documentation/bsp-guide/bsp.xml: New section on using BSP tools.
Some documentation introducing and helping get people started with the Yocto BSP Tools (yocto-bsp and yocto-kernel). (From yocto-docs rev: 56a6db181f5cdf3c23daa021fe1e9ecb15843678) Signed-off-by: Tom Zanussi <tom.zanussi@intel.com> Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
parent
723c91297d
commit
0be0e3b350
|
@ -754,4 +754,454 @@
|
||||||
You must eventually rebuild the image if you want to remove this restriction.
|
You must eventually rebuild the image if you want to remove this restriction.
|
||||||
</note>
|
</note>
|
||||||
</section>
|
</section>
|
||||||
|
<section id='yocto-bsp-tools'>
|
||||||
|
<title>Using the Yocto BSP Tools</title>
|
||||||
|
<para>
|
||||||
|
The Yocto Project includes a couple of tools that enable
|
||||||
|
you to create a BSP from scratch
|
||||||
|
(<filename>yocto-bsp</filename>) and do basic
|
||||||
|
configuration and maintenance of the kernel
|
||||||
|
(<filename>yocto-kernel</filename>) without ever looking at
|
||||||
|
a Yocto metadata file.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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
|
||||||
|
(<filename>yocto-bsp</filename>
|
||||||
|
or <filename>yocto-kernel</filename>) itself does
|
||||||
|
nothing but invoke or provide help on the sub-commands
|
||||||
|
it supports.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Secondly, since the tools themselves live in
|
||||||
|
the <filename>scripts/</filename> subdirectory, in order
|
||||||
|
to use them, you need to 'source' the environment just
|
||||||
|
as you would when invoking a build:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ source oe-init-build-env [build_dir]
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
With that in mind, the most immediately useful function
|
||||||
|
to describe is the built-in help system common to both
|
||||||
|
tools.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Simply entering the name of the command, or the command
|
||||||
|
along with 'help' will display a list of the available
|
||||||
|
sub-commands. For example:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ yocto-bsp
|
||||||
|
$ yocto-bsp help
|
||||||
|
|
||||||
|
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
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Similarly, entering just the name of a sub-command will
|
||||||
|
show the detailed usage for that sub-command:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ 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.
|
||||||
|
|
||||||
|
...
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
For any sub-command, you can also use the word 'help'
|
||||||
|
just before the sub-command to get more extensive
|
||||||
|
documentation on the sub-command:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ 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.
|
||||||
|
|
||||||
|
...
|
||||||
|
|
||||||
|
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.
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
With the knowledge that there are two
|
||||||
|
commands, <filename>yocto-bsp</filename>
|
||||||
|
and <filename>yocto-kernel</filename> 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.
|
||||||
|
</para>
|
||||||
|
<section id='using-yocto-bsp'>
|
||||||
|
<title>Creating a new BSP using <filename>yocto-bsp</filename></title>
|
||||||
|
<para>
|
||||||
|
<filename>yocto-bsp</filename> 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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The <filename>yocto-bsp create</filename> 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 <filename>yocto-bsp
|
||||||
|
list karch</filename> sub-command to list the
|
||||||
|
architectures available for BSP creation:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Assuming you've sourced the environment, you can invoke
|
||||||
|
the <filename>yocto-bsp create</filename> 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:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ yocto-bsp list karch
|
||||||
|
Architectures available:
|
||||||
|
arm
|
||||||
|
powerpc
|
||||||
|
i386
|
||||||
|
mips
|
||||||
|
x86_64
|
||||||
|
qemu
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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).
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ yocto-bsp create myarm qemu
|
||||||
|
Which qemu architecture would you like to use? [default: x86]
|
||||||
|
1) common 32-bit x86
|
||||||
|
2) common 64-bit x86
|
||||||
|
3) common 32-bit ARM
|
||||||
|
4) common 32-bit PowerPC
|
||||||
|
5) common 32-bit MIPS
|
||||||
|
3
|
||||||
|
Would you like to use the default (3.2) kernel? (Y/n)
|
||||||
|
Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [Y/n]
|
||||||
|
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/common-pc]
|
||||||
|
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
|
||||||
|
3
|
||||||
|
Do you need SMP support? (Y/n)
|
||||||
|
Does your BSP have a touchscreen? (y/N)
|
||||||
|
Does your BSP have a keyboard? (Y/n)
|
||||||
|
New qemu BSP created in meta-myarm
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
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 <filename>yocto-kernel</filename> tool to be able to
|
||||||
|
find the layer and other metadata it needs to operate
|
||||||
|
on.
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
BBLAYERS = " \
|
||||||
|
/usr/local/src/yocto/meta \
|
||||||
|
/usr/local/src/yocto/meta-yocto \
|
||||||
|
/usr/local/src/yocto/meta-myarm \
|
||||||
|
"
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
<section id='using-yocto-kernel'>
|
||||||
|
<title>Managing Kernel Patches and Config Items
|
||||||
|
with <filename>yocto-kernel</filename></title>
|
||||||
|
<para>
|
||||||
|
Assuming we've created a Yocto BSP layer
|
||||||
|
using <filename>yocto-bsp</filename> and added it to our
|
||||||
|
BBLAYERS, we can now use
|
||||||
|
the <filename>yocto-kernel</filename> command to add
|
||||||
|
patches and config items to the BSP's
|
||||||
|
kernel. <filename>yocto-kernel</filename> 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 <filename>yocto-kernel</filename> is again to make
|
||||||
|
use of the built-in help:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ 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.
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The <filename>yocto-kernel patch add</filename>
|
||||||
|
sub-command allows us to add a patch to a BSP. The
|
||||||
|
following commands add a couple of patches to the
|
||||||
|
'myarm' BSP:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ yocto-kernel patch add myarm ~/test.patch
|
||||||
|
Added patches:
|
||||||
|
test.patch
|
||||||
|
|
||||||
|
$ yocto-kernel patch add myarm ~/yocto-testmod.patch
|
||||||
|
Added patches:
|
||||||
|
yocto-testmod.patch
|
||||||
|
</literallayout>
|
||||||
|
Note that though we added patches one by one above, we
|
||||||
|
could also add multiple patches at the same time if we
|
||||||
|
wanted to.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
We can verify that the patches were added by using
|
||||||
|
the <filename>yocto-kernel patch list</filename>
|
||||||
|
sub-command:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ yocto-kernel patch list myarm
|
||||||
|
The current set of machine-specific patches for myarm is:
|
||||||
|
1) test.patch
|
||||||
|
2) yocto-testmod.patch
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
We can also use <filename>yocto-kernel</filename> to
|
||||||
|
remove a patch using the <filename>yocto-kernel patch
|
||||||
|
rm</filename> sub-command:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ yocto-kernel patch rm myarm
|
||||||
|
Specify the patches to remove:
|
||||||
|
1) test.patch
|
||||||
|
2) yocto-testmod.patch
|
||||||
|
1
|
||||||
|
Removed patches:
|
||||||
|
test.patch
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Again using <filename>yocto-kernel patch list</filename>
|
||||||
|
we can verify that it was in fact removed:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ yocto-kernel patch list myarm
|
||||||
|
The current set of machine-specific patches for myarm is:
|
||||||
|
1) yocto-testmod.patch
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
In a completely similar way, we can use
|
||||||
|
the <filename>yocto-kernel config add</filename>
|
||||||
|
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:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ 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
|
||||||
|
</literallayout>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Finally, we can list the config items now associated
|
||||||
|
with the BSP and see the config items we added along
|
||||||
|
with some others.
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ 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
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Similarly, we can remove one or more config items using
|
||||||
|
<filename>yocto-kernel config rm</filename> in a manner
|
||||||
|
completely analogous to <filename>yocto-kernel patch
|
||||||
|
rm</filename>.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
Loading…
Reference in New Issue