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>