Yocto BSP Tools Documentation

Note: This documentation is the same as the documentation submitted to the Yocto BSP Developer's Guide. It's here temporarily as a convenience until that document has been officially published.

Using the Yocto BSP Tools

The Yocto Project includes a couple of tools that enable you to create a BSP from scratch (yocto- bsp) and do basic configuration and maintenance of the kernel (yocto-kernel) without ever looking at a Yocto metadata file.

The following sections describe each of those tools in detail, but there are some features common to both that will be useful to describe before delving into the details of either.

First, a word about how the tools are structured. Designed to have a 'git-like' command interface, each tool is structured as a set of sub-commands under a 'top-level' command. The top-level command (yocto-bsp or yocto-kernel) itself does nothing but invoke or provide help on the sub-commands it supports.

Secondly, since the tools themselves live in the scripts/ subdirectory, in order to use them, you need to 'source' the environment just as you would when invoking a build:

$ source oe-init-build-env [build_dir]

With that in mind, the most immediately useful function to describe is the built-in help system common to both tools.

The built-in help system makes it easy to drill down at any time and remind oneself of the syntax required for any specific command.

Simply entering the name of the command, or the command along with 'help' will display a list of the available sub-commands. For example:

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

Similarly, entering just the name of a sub-command will show the detailed usage for that sub- command:

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

With the knowledge that there are two commands, yocto-bsp and yocto-kernel, and a built-in help system available for each, it should be relatively straightforward to discover the commands necessary to create a BSP and do basic kernel maintainence of that BSP using the tools. The following sections are provided, however, in order to serve as a concrete starting point and to expand on a few points that may not be immediately obvious or that could use further explanation.

Creating a new BSP using yocto-bsp

yocto-bsp is a Yocto script that allows you to create a new Yocto BSP for any architecture supported Yocto, as well as qemu versions of the same. The default mode of operation when invoked from the command-line is to prompt the user for information needed to generate the BSP. For the current set of BSPs, the user is prompted for various important parameters such as which kernel to use, which branch of that kernel to use (or re-use), whether or not to use X, and if so, which drivers to use,

whether to turn on SMP, whether the BSP has a keyboard, touchscreen, or anything that happens to be configurable and has an associated input prompt.

The yocto-bsp create sub-command is the sub-command you use to create a new BSP. It requires you to specify a particular architecture to base the BSP on. You can use the yocto-bsp list karch sub-command to list the architectures available for BSP creation:

Assuming you've sourced the environment, you can invoke the yocto-bsp create command to create the BSP. The example below uses 'myarm' as the machine name, and tells it to use the 'qemu' architecture (the specific qemu machine architecture to use will be prompted for). You can use the 'yocto-bsp list karch' command to list the aviailable architectures for BSP creation:

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

For the example output below, we'll use the 'qemu' architecture, which is a special architecture that is the only one of the supported architectures that will prompt you further for a 'real' architecture. In every other way, it's representative of how creating a BSP for a 'real' machine would work; the reason we're using it here as an example is that since it's an emulated architecture, it's easy for readers to try out themselves without having any special hardware requirements.

The 'yocto-bsp create' command for the qemu architecture will display the following prompts along the way to gather the input required for BSP generation. Each prompt asks for input, but has a default value [in brackets]. If you press 'enter' (or any invalid value), the default value will automatically be used.

In the case of the qemu architecture, the first prompt asks which emulated architecture to use. In this example, we'll use the 'arm' qemu architecture.

It then asks if the default kernel (3.2) is ok, and we press enter, essentially telling it 'yes'. If we had entered 'n', we would have been prompted to choose a different kernel from a list of available kernels (3.0, 3.2_preempt-rt, etc).

Once we've selected the kernel, the next prompt asks whether we'd like to have a new branch in the Yocto kernel git repository created especially for this BSP, or whether we'll just re-use an existing branch. If we say 'yes', which is the default, the BSP code generated will create a new branch specifically for the BSP rather than a common shared branch; this is the branch that any patches we add later would be committed. The reason creating a new branch is the default is that typically new BSPs do require BSP-specific patches and so the BSP tool assumes that most of time a new branch will be required. Note that in the current implementation it doesn't actually matter, since the generated BSPs assume that patches and configuration live in recipe-space, which is something that can be done with or without a dedicated branch. The BSP that's generated, however, will be different, and this difference will become significant once 'publish' functionality is implemented.

Regardless of which choice we made in the previous step, we're then given the opportunity to select a particular machine branch to base our new BSP-specific machine branch on (or re-use if we elected not to create a new branch). Because we're generating an arm BSP, we choose #3 at that prompt to select the arm-versatile branch. The rest of the prompts are routine, and once all the questions have been completed, the BSP is generated along with a message telling you so. The output of the complete session is shown below:

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)

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

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

Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.2...
Please choose a machine branch to base this BSP on: [default: standard/default/arm-versatile-926ejs]
	1) base
	2) standard/base
 	3) standard/default/arm-versatile-926ejs
 	4) standard/default/base
	5) standard/default/beagleboard
	6) standard/default/cedartrail
	7) standard/default/common-pc-64/base
	8) standard/default/common-pc-64/jasperforest
  	9) standard/default/common-pc-64/romley
	10) standard/default/common-pc-64/sugarbay
	11) standard/default/common-pc/atom-pc
	12) standard/default/common-pc/base
	13) standard/default/crownbay
	14) standard/default/emenlow
	15) standard/default/fishriver
	16) standard/default/fri2
	17) standard/default/fsl-mpc8315e-rdb
	18) standard/default/mti-malta32-be
	19) standard/default/mti-malta32-le
	20) standard/default/preempt-rt
	21) standard/default/qemu-ppc32
	22) standard/default/routerstationpro
	23) standard/preempt-rt/base
	24) standard/preempt-rt/qemu-ppc32
	25) standard/preempt-rt/routerstationpro
	26) standard/tiny

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

Now that we have our BSP created, we need to add it to our bblayers.conf. This of course is required in order to build the BSP, but it's also required in order for the yocto-kernel tool to be able to find the layer and other metadata it needs to operate on.

BBLAYERS = " \
   /usr/local/src/yocto/meta \
   /usr/local/src/yocto/meta-yocto \
   /usr/local/src/yocto/meta-myarm \
   "

Managing Kernel Patches and Config Items with yocto-kernel

Assuming we've created a Yocto BSP layer using yocto-bsp and added it to our BBLAYERS, we can now use the yocto-kernel command to add patches and config items to the BSP's kernel. yocto- kernel is a Yocto script that allows you to add, remove, and list patches and kernel config settings to a Yocto BSP's kernel .bbappend file. The easiest way to see exactly what sub-commands are available using yocto-kernel is again to make use of the built-in help:

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

Usage: 

 Modify and list Yocto BSP kernel config items and patches.

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

 The most commonly used 'yocto-kernel' commands are:
   config list       List the modifiable set of bare kernel config options for a BSP
   config add        Add or modify bare kernel config options for a BSP
   config rm         Remove bare kernel config options from a BSP
   patch list        List the patches associated with a BSP
   patch add         Patch the Yocto kernel for a BSP
   patch rm          Remove patches from a BSP

 See 'yocto-kernel 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

The yocto-kernel patch add sub-command allows us to add a patch to a BSP. The following commands add a couple of patches to the 'myarm' BSP:

$ yocto-kernel patch add myarm ~/test.patch
Added patches:
   test.patch

$ yocto-kernel patch add myarm ~/yocto-testmod.patch
Added patches:
   yocto-testmod.patch

Note that though we added patches one by one above, we could also add multiple patches at the same time if we wanted to.

We can verify that the patches were added by using the yocto-kernel patch list sub-command:

$ yocto-kernel patch list myarm
The current set of machine-specific patches for myarm is:
   1) test.patch
   2) yocto-testmod.patch

We can also use yocto-kernel to remove a patch using the yocto-kernel patch rm sub-command:

$ yocto-kernel patch rm myarm
Specify the patches to remove:
   1) test.patch
   2) yocto-testmod.patch
1
Removed patches:
   test.patch

Again using yocto-kernel patch list we can verify that it was in fact removed:

$ yocto-kernel patch list myarm
The current set of machine-specific patches for myarm is:
   1) yocto-testmod.patch

In a completely similar way, we can use the yocto-kernel config add sub-command to add one or more kernel config item settings to a BSP. The following commands add a couple of config items to the 'myarm' BSP:

$ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y
Added items:
   CONFIG_MISC_DEVICES=y

$ yocto-kernel config add myarm KCONFIG_YOCTO_TESTMOD=y
Added items:
   CONFIG_YOCTO_TESTMOD=y

Note that though we added config items one by one above, we could also add multiple configuration settings at the same time if we wanted to.

Finally, we can list the config items now associated with the BSP and see the config items we added along with some others.

$ yocto-kernel config list myarm
The current set of machine-specific kernel config items for myarm is:
   1) CONFIG_MISC_DEVICES=y
   2) CONFIG_YOCTO_TESTMOD=y

Similarly, we can remove one or more config items using yocto-kernel config rm in a manner completely analogous to yocto-kernel patch rm.