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>

1 files changed, 450 insertions, 0 deletions

diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 8567c2602f..e4a113a3f2 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -754,4 +754,454 @@
                 You must eventually rebuild the image if you want to remove this restriction.
             </note> 
         </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 &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
+                        [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
+                
+                            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 &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
+                        [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
+                            
+                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>