View source for BKM: starting a new BSP

This is a practical 'quick start' on creating a new BSP.  For detailed background and instructions on how to to formally do this, please see the BSP Developer's Guide [http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html] and the Kernel Manual [http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html].  This document is essentially a pragmatic distillation of those documents but oriented toward the mechanics of quickly getting the initial BSP infrastructure in place for a minimally functional new BSP.

Mostly it's a straightforward exercise:
* copy a meta-* subdirectory representing the metadata of the BSP
* add it as a layer and configure the build system to use it
* add or tweak the machine configuration and recipes in the layer to get things working
* create a specialized branch for the BSP in the kernel and add kernel metadata to customize it for the BSP

The final step above (dealing with the kernel) is actually the most time-consuming and least straightforward aspect of not only creating the initial BSP, but of maintaining it going forward, so much of this document will be dedicated to addressing that aspect of BSP creation/maintenance.

=== Starting Out ===

As mentioned in the BSP Developer's Guide, the easiest way to start a new BSP is to base it on a similar already-existing working BSP.  For this guide, we'll essentially go through the steps used to create the BSP for the Fish River Island, which exists in its current form as meta-fishriver in the meta-intel repository.

For this particular BSP, a bit of background on the base hardware and its relationship with some similar Intel hardware, the Crown Bay platform, will be useful when describing how the fishriver BSP was created.  For the purposes of this guide, the relevant components of the Crown Bay platform that we care about are the 'EG20T platform controller hub' (Topcliff) which provides 'platform' components such as USB hardware and a gigabit ethernet adapter, etc, and the processor, which in the case of the Crown Bay platform, is the E660 Atom 'Tunnel Creek' processor with on-board graphics.  The Fish River Island I is also based on the Topcliff, but instead of a Tunnel Creek processor, it uses a Z530 Atom 'eMenlow' processor.  The Fish River Island II will make use of the Tunnel Creek processor instead of the eMenlow; the relevant aspect of this last fact relative to BSP development relates to the on-board graphics of these chips, in that both the Crown Bay and Fish River Island II BSPs can use the same configuration of the Intel EMGD graphics driver support to drive the video subsystems, whereas the Fish River Island I uses a simpler graphics setup based on VESA graphics.

So, from the perspective of the BSP developer, the important facts are:

* both the Crown Bay and Fish River Island I/II use the EG20T and can share support for this
* both the Crown Bay and Fish River Island II use the same graphics configuration and can share support for EMGD
* the Fish River Island I uses different graphics from the Crown Bay, so can't share anything with respect to graphics

Since this guide only really covers the Fish River Island I, we won't go into any more detail on anything related to the Fish River Island II - in addition to the above similarities, it adds a set of additional components to justify its existence as a separate BSP - adding that is left as an exercise for the reader ;-)

Before we start, we need to do a basic checkout of the Yocto sources.  For this example, we'll assume you've done so by following the instructions in the following tutorial, 'Transcript: from git checkout to meta-intel BSP' [https://wiki.yoctoproject.org/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP], but only up to and including the step starting with 'Now check out the meta-intel repo into the top-level Yocto repo dir'.

So the first step for the Fish River BSP would be to take a look at what's already available in meta-intel, and use one of the existing BSPs as a starting point.  Here's a list of the current set of BSPs available in the meta-intel repository:

 trz@copacabana:~/yocto/dev/meta-intel$ ls -al
 total 52
 drwxr-xr-x 11 trz trz 4096 2011-06-24 17:39 .
 drwxr-xr-x 13 trz trz 4096 2011-06-24 17:38 ..
 drwxr-xr-x  5 trz trz 4096 2011-06-24 17:39 common
 drwxr-xr-x  8 trz trz 4096 2011-06-24 17:39 .git
 -rw-r--r--  1 trz trz 1854 2011-06-24 17:39 MAINTAINERS
 drwxr-xr-x  8 trz trz 4096 2011-06-24 17:39 meta-crownbay
 drwxr-xr-x 10 trz trz 4096 2011-06-24 17:39 meta-emenlow
 drwxr-xr-x  8 trz trz 4096 2011-06-24 17:39 meta-jasperforest
 drwxr-xr-x  8 trz trz 4096 2011-06-24 17:39 meta-n450
 drwxr-xr-x  8 trz trz 4096 2011-06-24 17:39 meta-sugarbay
 -rw-r--r--  1 trz trz   71 2011-06-24 17:39 README

For us, since we already know the answer, the obvious starting point is the meta-crownbay BSP.  Here's a listing of the files contained in the meta-crownbay 'layer':

 trz@copacabana:~/yocto/dev/meta-intel/meta-crownbay$ find .
 .
 ./conf
 ./conf/machine
 ./conf/machine/crownbay.conf
 ./conf/machine/crownbay-noemgd.conf
 ./conf/layer.conf
 ./recipes-kernel
 ./recipes-kernel/linux
 ./recipes-kernel/linux/linux-yocto_2.6.37.bbappend
 ./recipes-kernel/linux/linux-yocto_2.6.34.bbappend
 ./recipes-core
 ./recipes-core/tasks
 ./recipes-core/tasks/task-core-tools.bbappend
 ./README
 ./recipes-bsp
 ./recipes-bsp/formfactor
 ./recipes-bsp/formfactor/formfactor
 ./recipes-bsp/formfactor/formfactor/crownbay
 ./recipes-bsp/formfactor/formfactor/crownbay/machconfig
 ./recipes-bsp/formfactor/formfactor/crownbay-noemgd
 ./recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig
 ./recipes-bsp/formfactor/formfactor_0.0.bbappend
 ./recipes-graphics
 ./recipes-graphics/xorg-xserver
 ./recipes-graphics/xorg-xserver/xserver-xf86-config
 ./recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay
 ./recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf
 ./recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd
 ./recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd/xorg.conf
 ./recipes-graphics/xorg-xserver/emgd-driver-bin-1.6
 ./recipes-graphics/xorg-xserver/emgd-driver-bin-1.6/.gitignore
 ./recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin
 ./recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin/.gitignore
 ./recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
 ./recipes-graphics/xorg-xserver/emgd-driver-bin_1.6.bb
 ./README.sources
 ./binary
 ./binary/.gitignore
 ./COPYING.MIT

Since meta-crownbay is the most similar BSP to the new BSP we want to create, we'll simply copy the contents of meta-crownbay into a new directory for our BSP, meta-fishriver, and rework the contents into something useful for our new BSP. 

 trz@copacabana:~/yocto/dev/meta-intel$ cp -a meta-crownbay meta-fishriver
 delete what we don't want, rename what we do, etc

 trz@copacabana:~/yocto/dev/meta-intel/meta-fishriver$ find .
 .
 ./conf
 ./conf/machine
 ./conf/machine/fishriver.conf
 ./conf/layer.conf
 ./recipes-kernel
 ./recipes-kernel/linux
 ./recipes-kernel/linux/linux-yocto_2.6.37.bbappend
 ./recipes-kernel/linux/linux-yocto_2.6.34.bbappend
 ./recipes-core
 ./recipes-core/tasks
 ./recipes-core/tasks/task-core-tools.bbappend
 ./README
 ./recipes-bsp
 ./recipes-bsp/formfactor
 ./recipes-bsp/formfactor/formfactor
 ./recipes-bsp/formfactor/formfactor/fishriver
 ./recipes-bsp/formfactor/formfactor/fishriver/machconfig
 ./recipes-bsp/formfactor/formfactor_0.0.bbappend
 ./recipes-graphics
 ./recipes-graphics/xorg-xserver
 ./recipes-graphics/xorg-xserver/xserver-xf86-config
 ./recipes-graphics/xorg-xserver/xserver-xf86-config/fishriver
 ./recipes-graphics/xorg-xserver/xserver-xf86-config/fishriver/xorg.conf
 ./recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
 ./README.sources
 ./binary
 ./binary/.gitignore
 ./COPYING.MIT

Note the branches 'yocto/standard/crownbay' and 'yocto/emgd' in the linux-yocto-2.6.37 repo:

 trz@copacabana:~/yocto/linux-yocto-2.6.37.git$ git branch -a
 * master
   meta
   yocto/base
   yocto/eg20t
   yocto/emgd
   yocto/gma500
   yocto/standard/arm-versatile-926ejs
   yocto/standard/base
   yocto/standard/beagleboard
   yocto/standard/common-pc-64/base
   yocto/standard/common-pc-64/jasperforest
   yocto/standard/common-pc-64/romley
   yocto/standard/common-pc-64/sugarbay
   yocto/standard/common-pc/atom-pc
   yocto/standard/common-pc/base
   yocto/standard/crownbay
   yocto/standard/emenlow
   yocto/standard/fishriver
   yocto/standard/fsl-mpc8315e-rdb
   yocto/standard/mti-malta32-be
   yocto/standard/mti-malta32-le
   yocto/standard/preempt-rt/base
   yocto/standard/preempt-rt/common-pc
   yocto/standard/preempt-rt/common-pc-64
   yocto/standard/qemu-ppc32
   yocto/standard/routerstationpro