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.
