Transcript: creating one generic Atom BSP from another

Note: Though much of this page is still valid and can be useful in many cases, it should be noted that there are now tools that can help with the task of creating new BSPs and managing kernel patches and configuration settings for those BSPs, which you may want to consider first. Detailed documentation and walk-throughs using those tools are available at the following pages:
* Yocto BSP Tools Documentation
* Transcript: Using the Yocto BSP tools to manage kernel patches and config items
* Transcript: Using the Yocto BSP tools to create a qemu BSP
* Transcript: Using the Yocto BSP tools to create a meta-intel BSP.
Starting from scratch, we'll take a relatively generic Atom-based BSP and create another Atom-based BSP from that, that stands a good chance of booting and even booting into graphics, to serve as a starting point for a new BSP.
First set up poky:
 trz@elmorro:/usr/local/test/yocto$ git init
 Initialized empty Git repository in /usr/local/test/yocto/.git/
 trz@elmorro:/usr/local/test/yocto$ git remote add poky git://git.yoctoproject.org/poky.git
 trz@elmorro:/usr/local/test/yocto$ git remote update
 Fetching poky
 remote: Counting objects: 106111, done.
 remote: Compressing objects: 100% (36106/36106), done.
 remote: Total 106111 (delta 72275), reused 99193 (delta 66808)
 Receiving objects: 100% (106111/106111), 69.51 MiB | 518 KiB/s, done.
 Resolving deltas: 100% (72275/72275), done.
 From git://git.yoctoproject.org/poky
 * [new branch] 1.1_M1 -> poky/1.1_M1
 * [new branch] 1.1_M2 -> poky/1.1_M2
 * [new branch] bernard -> poky/bernard
 * [new branch] blinky -> poky/blinky
 * [new branch] clyde -> poky/clyde
 * [new branch] elroy -> poky/elroy
 * [new branch] green -> poky/green
 * [new branch] laverne -> poky/laverne
 * [new branch] master -> poky/master
 * [new branch] pinky -> poky/pinky
 * [new branch] purple -> poky/purple
 * [new tag] 1.1_M1.final -> 1.1_M1.final
 * [new tag] 1.1_M2.rc1 -> 1.1_M2.rc1
 * [new tag] bernard-5.0.1 -> bernard-5.0.1
 * [new tag] pinky-3.1.2 -> pinky-3.1.2
 From git://git.yoctoproject.org/poky
 * [new tag] 1.1_M1.rc1 -> 1.1_M1.rc1
 * [new tag] 1.1_M1.rc2 -> 1.1_M1.rc2
 * [new tag] bernard-1.0rc1 -> bernard-1.0rc1
 * [new tag] bernard-5.0 -> bernard-5.0
 * [new tag] bernard-5.0-alpha -> bernard-5.0-alpha
 * [new tag] bernard-5.0rc1 -> bernard-5.0rc1
 * [new tag] bernard-5.0rc2 -> bernard-5.0rc2
 * [new tag] laverne-4.0 -> laverne-4.0
 * [new tag] laverne-4.0.1 -> laverne-4.0.1
 * [new tag] m4 -> m4
 * [new tag] purple-3.2 -> purple-3.2
 * [new tag] purple-3.2.1 -> purple-3.2.1
 
 trz@elmorro:/usr/local/test/yocto$ git checkout -b bernard0 poky/bernard
 Branch bernard0 set up to track remote branch bernard from poky.
 Switched to a new branch 'bernard0'
 trz@elmorro:/usr/local/test/yocto$ git checkout -f
Now check out meta-intel:
 trz@elmorro:/usr/local/test/yocto$ mkdir meta-intel
 trz@elmorro:/usr/local/test/yocto$ cd meta-intel
 trz@elmorro:/usr/local/test/yocto/meta-intel$ git init
 Initialized empty Git repository in /usr/local/test/yocto/meta-intel/.git/
 
 trz@elmorro:/usr/local/test/yocto/meta-intel$ git remote add meta-intel git://git.yoctoproject.org/meta-intel.git
 trz@elmorro:/usr/local/test/yocto/meta-intel$ git remote update
 Fetching meta-intel
 remote: Counting objects: 1240, done.
 remote: Compressing objects: 100% (1008/1008), done.
 remote: Total 1240 (delta 513), reused 85 (delta 27)
 Receiving objects: 100% (1240/1240), 1.55 MiB | 510 KiB/s, done.
 Resolving deltas: 100% (513/513), done.
 From git://git.yoctoproject.org/meta-intel
 * [new branch] 1.1_M1 -> meta-intel/1.1_M1
 * [new branch] 1.1_M2 -> meta-intel/1.1_M2
 * [new branch] bernard -> meta-intel/bernard
 * [new branch] dvhart/n450 -> meta-intel/dvhart/n450
 * [new branch] laverne -> meta-intel/laverne
 * [new branch] master -> meta-intel/master
 
 trz@elmorro:/usr/local/test/yocto/meta-intel$ git checkout -b bernard0 meta-intel/bernard
 Branch bernard0 set up to track remote branch bernard from meta-intel.
 Switched to a new branch 'bernard0'
 trz@elmorro:/usr/local/test/yocto/meta-intel$ git checkout -f
The crownbay-noemgd is the closest thing we have to generic for Atom-based BSPs, so let's start with that:
 trz@elmorro:/usr/local/test/yocto/meta-intel$ cp -a meta-crownbay/ meta-mymachine
We want to get rid of anything crownbay, but keep and rename anything crownbay-noemgd. So:
 trz@elmorro:/usr/local/test/yocto/meta-intel$ rm meta-mymachine/conf/machine/crownbay.conf
 trz@elmorro:/usr/local/test/yocto/meta-intel$ mv meta-mymachine/conf/machine/crownbay-noemgd.conf meta-mymachine/conf/machine/mymachine.conf
Next, let's look at mymachine.conf and see which, if any, changes we need there. Aside from the obvious comment changes (lines starting with '#'), there's nothing to change except for the SRCREV lines at the end, which basically tell the recipe which kernel commits to use.
First, we need to figure out which kernel we're using. For our bernard checkout, we see from the line in the mymachine.conf we copied that it's linux-yocto-stable:
 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto-stable"
At the bottom of mymachine.conf, we see:
 SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= "56fe215d3f1a2cc3a5a26482ac9809ba44495695"
 SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= "e1f85a470934a0cf6abde5d95533e74501822c6b"
 
 SRCREV_machine_pn-linux-yocto-stable_crownbay-noemgd ?= "56fe215d3f1a2cc3a5a26482ac9809ba44495695"
 SRCREV_meta_pn-linux-yocto-stable_crownbay-noemgd ?= "e1f85a470934a0cf6abde5d95533e74501822c6b"
Since we're only interested in linux-yocto-stable, we can remove the linux-yocto SRCREVS, but we need to update the SRCREVs for linux-yocto-stable. So we'll change the linux-yocto-stable lines above to point to the machine and meta branches we'll use for our new BSP.
For the initial version of the BSP, we'll use the "atom-pc-standard" machine branch, since we don't yet have our own, which is something to do in future iterations (not covered by this transcript - see the other tutorials for further steps).
We can find the atom-pc-standard commit id to use by looking in the linux-yocto-2.6.34 kernel repo at http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-2.6.34/commit/?h=atom-pc-standard for the machine branch and http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-2.6.34/commit/?h=wrs_meta for the meta branch (note that branch names have changed in later repos e.g. linux-yocto, so keep that in mind if upgrading your kernel later. So the final SRCREVS for our new kernel are:
 SRCREV_machine_pn-linux-yocto-stable_mymachine ?= "72ca49ab08b8eb475cec82a10049503602325791"
 SRCREV_meta_pn-linux-yocto-stable_mymachine ?= "ec26387cb168e9e0976999b528b5a9dd62e3157a"
You also need to edit the meta-intel/meta-mymachine/conf/layer.conf to remove the crownbay lines and change the crownbay-noemgd lines from:
 BBFILE_COLLECTIONS_crownbay-noemgd += "crownbay-noemgd"
 BBFILE_PATTERN_crownbay-noemgd := "^${LAYERDIR}/"
 BBFILE_PRIORITY_crownbay-noemgd = "6"
to:
 BBFILE_COLLECTIONS_mymachine += "mymachine"
 BBFILE_PATTERN_mymachine := "^${LAYERDIR}/"
 BBFILE_PRIORITY_mymachine = "6"
Next, moving to recipes-bsp, we need to remove the crownbay formfactor and rename the crownbay-noemgd formfactor to mymachine:
 trz@elmorro:/usr/local/test/yocto/meta-intel$ rm -rf meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay
 trz@elmorro:/usr/local/test/yocto/meta-intel$ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine
Next, moving to recipes-graphics, remove anything with emgd in it - that's for crownbay and we don't care about it.
 trz@elmorro:/usr/local/test/yocto/meta-intel$ rm -rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-emgd*
We also need to remove the crownbay xorg.conf and rename the crownbay-noemgd xorg.conf:
 trz@elmorro:/usr/local/test/yocto/meta-intel$ rm -rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay
 trz@elmorro:/usr/local/test/yocto/meta-intel$ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine
This will leave us with a VESA xconfig.
Next, moving to recipes-kernel, we need to make a couple changes to meta-intel/meta-mymachine/recipes-kernel/linux/linux-yocto-stable_git.bbappend. Again, remove the crownbay lines and change the crownbay-noemgd lines from:
 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
 KMACHINE_crownbay-noemgd = "crownbay"
to
 COMPATIBLE_MACHINE_mymachine = "mymachine"
 KMACHINE_mymachine = "mymachine"
Finally, don't forget to update the top-level README to reflect the capabilities of your new BSP.
You should now be able to build and boot a live image. Before running the bitbake command, however, be sure to source the environment setup script:
 trz@elmorro:/usr/local/test/yocto$ source poky-init-build-env yocto-build
 trz@elmorro:/usr/local/test/yocto/yocto-build$ bitbake poky-image-sato-live
If it doesn't build, you typed in something wrong.
If it doesn't boot, you have work to do that no transcript will help you with.
And remember, this transcript was based on bernard, which for this BSP was based on the 2.6.34 'stable' kernel. You probably don't want to base a new BSP on 2.6.34. The BSP this transcript was based on switched to 2.6.34 soon after bernard, so you should be able to look at later version of it or other BSPs for hints on how to switch to a more recent kernel. This BSP was chosen because the -noemgd branch was the most generic otherwise, and choosing something else would have caused more confusion than the simple text editing done here.
You might be further ahead to try a more recent 'milestone' branch of 1.1 to base your new BSP on, which would give you a more up-to-date system, but we used the bernard branch instead because that's more stable.