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.