Transcript: Using the Yocto BSP tools to create a qemu BSP

From Yocto Project
Jump to navigationJump to search

Here's a cut-and-paste shell session showing how to have the Yocto BSP tools create a new BSP from scratch. It starts with a fresh git checkout, then invokes yocto-bsp to create a new qemu-based ARM BSP, and finally builds a sato image and boots into a sato desktop in a qemu session (commands also shown for that).

Once you've successfully followed the steps in this transcript, you can use the result along with the 'yocto-kernel' BSP tool to add, remove, and list Yocto kernel patches and config items by following the steps outlined in the companion transcript Transcript: Using the Yocto BSP tools to manage kernel patches and config items

NOTE: this transcript was from a build done on a Ubuntu 11.10 system. Please see the 'Yocto Project Quickstart' for the packages required to be installed on the host system for building [1]

One thing to note with this example is that I'm checking out from poky/master.

trz@elmorro:/usr/local/dev$ mkdir Yocto
trz@elmorro:/usr/local/dev$ cd Yocto/
trz@elmorro:/usr/local/dev/Yocto$ git init
Initialized empty Git repository in /usr/local/dev/Yocto/.git/
trz@elmorro:/usr/local/dev/Yocto$ git remote add yocto git://git.yoctoproject.org/poky.git
trz@elmorro:/usr/local/dev/Yocto$ git remote update
Fetching yocto
remote: Counting objects: 154283, done.
remote: Compressing objects: 100% (42482/42482), done.
remote: Total 154283 (delta 109346), reused 152606 (delta 108055)
Receiving objects: 100% (154283/154283), 78.80 MiB | 80 KiB/s, done.
Resolving deltas: 100% (109346/109346), done.
From git://git.yoctoproject.org/poky
 * [new branch]      1.1_M1     -> yocto/1.1_M1
 * [new branch]      1.1_M2     -> yocto/1.1_M2
 * [new branch]      1.1_M3     -> yocto/1.1_M3
 * [new branch]      1.1_M4     -> yocto/1.1_M4
 * [new branch]      1.2_M1     -> yocto/1.2_M1
 * [new branch]      1.2_M2     -> yocto/1.2_M2
 * [new branch]      1.2_M3     -> yocto/1.2_M3
 * [new branch]      1.2_M4     -> yocto/1.2_M4
 * [new branch]      1.3_M1     -> yocto/1.3_M1
 * [new branch]      1.3_M2     -> yocto/1.3_M2
 * [new branch]      bernard    -> yocto/bernard
 * [new branch]      blinky     -> yocto/blinky
 * [new branch]      clyde      -> yocto/clyde
 * [new branch]      denzil     -> yocto/denzil
 * [new branch]      edison     -> yocto/edison
 * [new branch]      elroy      -> yocto/elroy
 * [new branch]      green      -> yocto/green
 * [new branch]      laverne    -> yocto/laverne
 * [new branch]      master     -> yocto/master
 * [new branch]      master-next -> yocto/master-next
 * [new branch]      pinky      -> yocto/pinky
 * [new branch]      purple     -> yocto/purple
 * [new tag]         1.1_M1.final -> 1.1_M1.final
 * [new tag]         1.1_M2.final -> 1.1_M2.final
 * [new tag]         1.1_M2.rc3 -> 1.1_M2.rc3
 * [new tag]         1.1_M3.final -> 1.1_M3.final
 * [new tag]         1.1_M3.rc3 -> 1.1_M3.rc3
 * [new tag]         1.2_M1.final -> 1.2_M1.final
 * [new tag]         1.2_M1.rc2 -> 1.2_M1.rc2
 * [new tag]         1.2_M2.final -> 1.2_M2.final
 * [new tag]         1.2_M2.rc1 -> 1.2_M2.rc1
 * [new tag]         1.2_M3.final -> 1.2_M3.final
 * [new tag]         1.2_M3.rc1 -> 1.2_M3.rc1
 * [new tag]         1.3_M1.final -> 1.3_M1.final
 * [new tag]         1.3_M1.rc1 -> 1.3_M1.rc1
 * [new tag]         1.3_M2.final -> 1.3_M2.final
 * [new tag]         bernard-5.0.2+docs -> bernard-5.0.2+docs
 * [new tag]         denzil-7.0.1 -> denzil-7.0.1
 * [new tag]         denzil-7.0.1_rc2 -> denzil-7.0.1_rc2
 * [new tag]         edison-6.0.2 -> edison-6.0.2
 * [new tag]         edison-6.0.2_rc1 -> edison-6.0.2_rc1
 * [new tag]         pinky-3.1.2 -> pinky-3.1.2

Now that we've cloned the Yocto repo, we need to source the environment in order to create or build a BSP:

trz@elmorro:/usr/local/dev/Yocto$ git checkout -b master0 yocto/master
Branch master0 set up to track remote branch master from yocto.
Switched to a new branch 'master0'

trz@elmorro:/usr/local/dev/Yocto$ source oe-init-build-env 
You had no conf/local.conf file. This configuration file has therefore been
created for you with some default values. You may wish to edit it to use a 
different MACHINE (target hardware) or enable parallel build options to take 
advantage of multiple cores for example. See the file for more information as 
common configuration options are commented.

The Yocto Project has extensive documentation about OE including a reference manual
which can be found at:
    http://yoctoproject.org/documentation

For more information about OpenEmbedded see their website:
    http://www.openembedded.org/

You had no conf/bblayers.conf file. The configuration file has been created for
you with some default values. To add additional metadata layers into your
configuration please add entries to this file.

The Yocto Project has extensive documentation about OE including a reference manual
which can be found at:
    http://yoctoproject.org/documentation

For more information about OpenEmbedded see their website:
    http://www.openembedded.org/



### Shell environment set up for builds. ###

You can now run 'bitbake <target>'

Common targets are:
    core-image-minimal
    core-image-sato
    meta-toolchain
    meta-toolchain-sdk
    adt-installer
    meta-ide-support 

You can also run generated qemu images with a command like 'runqemu qemux86'

We're now ready to generate a BSP using the 'yocto-bsp' tool. The 'yocto-bsp' tool will step through a series of questions about how the new BSP should be configured. The Yocto BSP tools all have extensive help and usage screens built in, which can be easily displayed at any time to remind yourself of the command syntax and descriptions of what the commands and sub-commands do. The tools have a git-like interface, meaning that there's a top-level command which essentially invokes multiple lower-level subcommands.

To display help for a top-level command, simply invoke the command without any parameters:

trz@elmorro:/usr/local/dev/Yocto/build$ yocto-bsp

Usage: 

 Create a customized Yocto BSP layer.

 usage: yocto-bsp [--version] [--help] COMMAND [ARGS]

 The most commonly used 'yocto-bsp' commands are:
    create            Create a new Yocto BSP
    list              List available values for options and BSP properties

 See 'yocto-bsp help COMMAND' for more information on a specific command.
 

Options:
  --version    show program's version number and exit
  -h, --help   show this help message and exit
  -D, --debug  output debug information

In order to create a new BSP, we'll want to use the 'yocto-bsp create' command.

To display usage help for a sub-command like 'yocto-bsp create', simply invoke it without any parameters:

trz@elmorro:/usr/local/dev/Yocto/build$ yocto-bsp create

Usage: 

 Create a new Yocto BSP

 usage: yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>]
            [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]

 This command creates a Yocto BSP based on the specified parameters.
 The new BSP will be a new Yocto BSP layer contained by default within
 the top-level directory specified as 'meta-bsp-name'.  The -o option
 can be used to place the BSP layer in a directory with a different
 name and location.

 The value of the 'karch' parameter determines the set of files that
 will be generated for the BSP, along with the specific set of
 'properties' that will be used to fill out the BSP-specific portions
 of the BSP.  The possible values for the 'karch' paramter can be
 listed via 'yocto-bsp list karch'. 


Options:
  -h, --help            show this help message and exit
  -o OUTDIR, --outdir=OUTDIR
                        name of BSP dir to create
  -i PROPERTIES_FILE, --infile=PROPERTIES_FILE
                        name of file containing the values for BSP properties
                        as a JSON file
  -c, --codedump        dump the generated code to bspgen.out

You can also get more extensive help for a sub-command by adding 'help' before the sub-command name:

trz@elmorro:/usr/local/dev/Yocto/build$ yocto-bsp help create

NAME
    yocto-bsp create - Create a new Yocto BSP

SYNOPSIS
    yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>]
        [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]

DESCRIPTION
    This command creates a Yocto BSP based on the specified
    parameters.  The new BSP will be a new Yocto BSP layer contained
    by default within the top-level directory specified as
    'meta-bsp-name'.  The -o option can be used to place the BSP layer
    in a directory with a different name and location. 

    The value of the 'karch' parameter determines the set of files
    that will be generated for the BSP, along with the specific set of
    'properties' that will be used to fill out the BSP-specific
    portions of the BSP.  The possible values for the 'karch' paramter
    can be listed via 'yocto-bsp list karch'.

    The BSP-specific properties that define the values that will be
    used to generate a particular BSP can be specified on the
    command-line using the -i option and supplying a JSON object
    consisting of the set of name:value pairs needed by the BSP. 

    If the -i option is not used, the user will be interactively
    prompted for each of the required property values, which will then
    be used as values for BSP generation.

    The set of properties available for a given architecture can be
    listed using the 'yocto-bsp list' command.

    Specifying -c causes the Python code generated and executed to
    create the BSP to be dumped to the 'bspgen.out' file in the
    current directory, and is useful for debugging.

    NOTE: Once created, you should add your new layer to your
    bblayers.conf file in order for it to be subsquently seen and
    modified by the yocto-kernel tool.

    NOTE for x86- and x86_64-based BSPs: The generated BSP assumes the
    presence of the of the meta-intel layer, so you should also have a
    meta-intel layer present and added to your bblayers.conf as well.

The other sub-command of 'yocto-bsp' is 'yocto-bsp list', which we can use to list all of the architectures we can create a BSP for:

trz@elmorro:/usr/local/dev/Yocto/build$ yocto-bsp list karch
Architectures available:
   arm
   powerpc
   i386
   mips
   x86_64
   qemu

For this BSP, we'll choose the 'qemu' architecture.

To create the BSP we'll invoke 'yocto-bsp create', but first let's change directories out of the 'build' directory (we could stay there, or use the -o option to generate the BSP somewhere else, but for this example we'll just cd into the Yocto dir and generate our BSP there).

We'll call our machine 'myqemuarm'; 'yocto-bsp create' will create our BSP layer in meta-myqemuarm in the current directory:

trz@elmorro:/usr/local/dev/Yocto/build$ cd ..
trz@elmorro:/usr/local/dev/Yocto$ yocto-bsp create myqemuarm qemu
 
Which qemu architecture would you like to use? [default: i386] 
 	1) i386    (32-bit) 
	2) x86_64  (64-bit)
	3) ARM     (32-bit)
	4) PowerPC (32-bit)
	5) MIPS    (32-bit)
 

For the 'qemu' architecture, we're given the choice of actual machine architecture. For this BSP, we'll choose ARM by typing in the number in the list labeled as 'ARM':

3
Would you like to use the default (3.4) kernel? (y/n) [default: y]

We're then asked whether we'd like to use the default kernel. If we type 'n' here, we're given a choice of kernels to use. For this BSP, we'll just take the default 3.4 kernel.

Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [y/n] [default: y]

For whichever kernel we choose, we're also asked whether we want the BSP to be associated with a machine branch dedicated to it and it alone. This would make sense if you plan to add machine-specific patches to your BSP. If not, it's more economical to just re-use a more generic branch and not worry about maintaining your own branch.

Note that regardless of which you choose, you can always add and modify BSP-specific kernel config items; that ability has nothing to do with the machine branches (unless of course you're talking about config items that would only exist if you added a corresponding kernel patch for them).

In the case of this BSP, we can reuse an existing branch that already has everything we need, so we'll answer 'n'.

Once we've done that, we're presented with a list of branches we can base the BSP on. For this BSP, we'll just choose the default:

Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.4.git...
Please choose a machine branch to base your new BSP branch on: [default: standard/arm-versatile-926ejs]
	1) standard/arm-versatile-926ejs
	2) standard/base
	3) standard/beagleboard
	4) standard/cedartrail
	5) standard/crownbay
	6) standard/emenlow
	7) standard/fishriver
	8) standard/fri2
	9) standard/fsl-mpc8315e-rdb
	10) standard/mti-malta32
	11) standard/mti-malta64
	12) standard/qemuppc
	13) standard/routerstationpro
	14) standard/sys940x

The rest of the values are straightforward, and for those we'll just take the defaults as well:

Do you need SMP support? (y/n) [default: y] 
Does your BSP have a touchscreen? (y/n) [default: n] 
Does your BSP have a keyboard? (y/n) [default: y] 

New qemu BSP created in meta-myqemuarm

The message states that a new BSP was created for us, and indeed it appears in our directory listing:

trz@elmorro:/usr/local/dev/Yocto$ ls -al
total 396
drwxrwxr-x 15 trz trz  4096 2012-08-09 00:33 .
drwxr-xr-x 42 trz trz  4096 2012-08-08 11:06 ..
drwxrwxr-x  6 trz trz  4096 2012-08-06 16:54 bitbake
drwxrwxr-x  9 trz trz  4096 2012-08-09 00:33 build
drwxrwxr-x 10 trz trz  4096 2012-08-06 16:54 documentation
drwxrwxr-x  8 trz trz  4096 2012-08-08 15:30 .git
-rw-rw-r--  1 trz trz   156 2012-08-06 16:54 .gitignore
-rw-rw-r--  1 trz trz   545 2012-08-06 16:54 LICENSE
drwxrwxr-x 20 trz trz  4096 2012-08-06 16:54 meta
drwxrwxr-x  4 trz trz  4096 2012-08-06 16:54 meta-hob
drwxrwxr-x 17 trz trz  4096 2012-08-06 16:54 meta-intel
drwxrwxr-x  8 trz trz  4096 2012-08-09 00:34 meta-myqemuarm
drwxrwxr-x  5 trz trz  4096 2012-08-06 16:54 meta-skeleton
drwxrwxr-x  9 trz trz  4096 2012-08-06 16:54 meta-yocto
-rwxrwxr-x  1 trz trz  1531 2012-08-06 16:54 oe-init-build-env
drwxrwxr-x  5 trz trz  4096 2012-08-06 16:54 poky-extras
-rw-rw-r--  1 trz trz  1365 2012-08-06 16:54 README
-rw-rw-r--  1 trz trz 17245 2012-08-06 16:54 README.hardware
drwxrwxr-x  8 trz trz  4096 2012-08-06 16:54 scripts

In order to build or use the other Yocto BSP tools such as 'yocto-kernel', you need to add the new BSP layer to BBLAYERS in bblayers.conf:

trz@elmorro:/usr/local/dev/Yocto$ emacs -nw build/conf/bblayers.conf

Change:

BBLAYERS ?= " \                                                                                
 /usr/local/dev/Yocto/meta \                                                                  
 /usr/local/dev/Yocto/meta-yocto \                                                            
 "

To:

BBLAYERS ?= " \                                                                                
 /usr/local/dev/Yocto/meta \                                                                  
 /usr/local/dev/Yocto/meta-yocto \                                                            
 /usr/local/dev/Yocto/meta-myqemuarm \                                                        
 "

You also need to edit local.conf set MACHINE to your new machine:

trz@elmorro:/usr/local/dev/Yocto$ emacs -nw build/conf/local.conf

Change:

# This sets the default machine to be qemux86 if no other machine is selected:                 
MACHINE ??= "qemux86"

To:

# This sets the default machine to be qemux86 if no other machine is selected:                 
MACHINE ??= "qemux86"
MACHINE ??= "myqemuarm"

You should also change anything else you need to in local.conf, such as BB_NUMER_THREADS values, etc. Once you've done that, you should be able to build and boot the sato image:

trz@elmorro:/usr/local/dev/Yocto$ cd build
trz@elmorro:/usr/local/dev/Yocto/build$ bitbake core-image-sato
Parsing recipes: 100% |##############################################################################################| Time: 00:00:21
Parsing of 835 .bb files complete (0 cached, 835 parsed). 1134 targets, 42 skipped, 0 masked, 0 errors.

Build Configuration:
BB_VERSION        = "1.15.3"
TARGET_ARCH       = "arm"
TARGET_OS         = "linux-gnueabi"
MACHINE           = "myqemuarm"
DISTRO            = "poky"
DISTRO_VERSION    = "1.2+snapshot-20120809"
TUNE_FEATURES     = "armv5 dsp thumb arm926ejs"
TARGET_FPU        = "soft"
meta              
meta-yocto        
meta-myqemuarm    = "master0:950dc77c33f9e6645e13196e9e28b82dfc72b2bb" 
NOTE: Running task 5314 of 5315 (ID: 7, /usr/local/dev/Yocto/meta/recipes-sato/images/core-image-sato.bb, do_rootfs)
NOTE: package core-image-sato-1.0-r0: task do_rootfs: Started
NOTE: package core-image-sato-1.0-r0: task do_rootfs: Succeeded
NOTE: Running noexec task 5315 of 5315 (ID: 10, /usr/local/dev/Yocto/meta/recipes-sato/images/core-image-sato.bb, do_build)
NOTE: Tasks Summary: Attempted 5315 tasks of which 1017 didn't need to be rerun and all succeeded. 
Summary: There were 16 WARNING messages shown.  

We had a successful build, and can now boot into a sato desktop:

trz@elmorro:/usr/local/dev/Yocto/build$ runqemu qemuarm tmp/deploy/images/zImage-myqemuarm.bin  tmp/deploy/images/core-image-sato-myqemuarm.ext3 

Continuing with the following parameters:
KERNEL: [tmp/deploy/images/zImage-myqemuarm.bin]
ROOTFS: [tmp/deploy/images/core-image-sato-myqemuarm.ext3]
FSTYPE: [ext3]
Setting up tap interface under sudo
Acquiring lockfile for tap0...
Starting distccd...
Running qemu-system-arm...
/usr/local/dev/Yocto/build/tmp/sysroots/x86_64-linux/usr/bin/qemu-system-arm -kernel tmp/deploy/images/zImage-myqemuarm.bin -net nic,vlan=0 -net  tap,vlan=0,ifname=tap0,script=no,downscript=no -M versatilepb -hda tmp/deploy/images/core-image-sato-myqemuarm.ext3 -no-reboot -show-cursor -usb -usbdevice wacom-tablet -no-reboot -m 128 --append "root=/dev/sda rw console=ttyAMA0,115200 console=tty ip=192.168.7.2::192.168.7.1:255.255.255.0 mem=128M highres=off "