[yocto] [PATCH][yocto-docs] BSP Guide: Numerous aesthetic tweaks/clarifications
Robert P. J. Day
rpjday at crashcourse.ca
Fri Mar 24 07:26:15 PDT 2017
* Outside of a title, use "BSP layer", not "BSP Layer"
* Add details about YP reference boards.
* Minor grammatical clarification in places.
* Add <para> to even single paragraph notes for consistency.
Signed-off-by: Robert P. J. Day <rpjday at crashcourse.ca>
---
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 4d0ace0..63848ad 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -19,7 +19,7 @@
</para>
<para>
- This guide presents information about BSP Layers, defines a structure for components
+ This guide presents information about BSP layers, defines a structure for components
so that BSPs follow a commonly understood layout, discusses how to customize
a recipe for a BSP, addresses BSP licensing, and provides information that
shows you how to create and manage a
@@ -33,7 +33,7 @@
<para>
A BSP consists of a file structure inside a base directory.
Collectively, you can think of the base directory, its file structure,
- and the contents as a BSP Layer.
+ and the contents as a BSP layer.
Although not a strict requirement, layers in the Yocto Project use the
following well-established naming convention:
<literallayout class='monospaced'>
@@ -77,8 +77,9 @@
<filename>meta-yocto-bsp</filename> layer is part of the
shipped <filename>poky</filename> repository.
The <filename>meta-yocto-bsp</filename> layer maintains several
- BSPs such as the Beaglebone, EdgeRouter, and generic versions of
- both 32 and 64-bit IA machines.
+ Yocto Project "reference" BSPs such as the ARM-based Beaglebone,
+ MIPS-based Ubiquiti EdgeRouter, PowerPC-based MPC8315E-RDB,
+ and generic versions of both 32 and 64-bit IA machines.
</para>
<para>
@@ -94,7 +95,7 @@
<para>
The layer's base directory
(<filename>meta-<replaceable>bsp_name</replaceable></filename>)
- is the root of the BSP Layer.
+ is the root of the BSP layer.
This root is what you add to the
<ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
variable in the <filename>conf/bblayers.conf</filename> file found in the
@@ -179,7 +180,7 @@
</para>
<para>
- Before looking at the common form for the file structure inside a BSP Layer,
+ Before looking at the common form for the file structure inside a BSP layer,
you should be aware that some requirements do exist in order for a BSP to
be considered compliant with the Yocto Project.
For that list of requirements, see the
@@ -188,7 +189,7 @@
</para>
<para>
- Below is the common form for the file structure inside a BSP Layer.
+ Below is the common form for the file structure inside a BSP layer.
While you can use this basic form for the standard, realize that the actual structures
for specific BSPs could differ.
@@ -572,7 +573,8 @@
</para>
<para>
- To use an include file, you simply include them in the
+ To use an include file, you simply <filename>include</filename> or
+ <filename>require</filename> it in the
machine configuration file.
For example, the Raspberry Pi BSP
<filename>raspberrypi3.conf</filename> contains the
@@ -956,28 +958,28 @@
<listitem><para>Instructions on how to boot the BSP build from
the BSP layer.</para></listitem>
<listitem><para>Instructions on how to boot the binary images
- contained in the <filename>binary</filename> directory,
+ contained in the <filename>binary/</filename> directory,
if present.</para></listitem>
<listitem><para>Information on any known bugs or issues that users
should know about when either building or booting the BSP
binaries.</para></listitem>
</itemizedlist></para></listitem>
<listitem><para><emphasis>README.sources File:</emphasis>
- You must include a <filename>README.sources</filename> in the
- <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- This file specifies exactly where you can find the sources used to
- generate the binary images contained in the
- <filename>binary</filename> directory, if present.
+ If your BSP layer includes a <filename>binary/</filename> directory
+ with at least one binary image, then it must also include a top-level
+ <filename>README.sources</filename> file that explains exactly
+ where you can find the sources used to generate those binary images.
</para></listitem>
<listitem><para><emphasis>Layer Configuration File:</emphasis>
- You must include a <filename>conf/layer.conf</filename> in the
+ You must include a <filename>conf/layer.conf</filename> file in the
<filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
This file identifies the <filename>meta-<replaceable>bsp_name</replaceable></filename>
BSP layer as a layer to the build system.</para></listitem>
<listitem><para><emphasis>Machine Configuration File:</emphasis>
You must include one or more
- <filename>conf/machine/<replaceable>bsp_name</replaceable>.conf</filename>
- files in the <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
+ <filename>conf/machine/<replaceable>machine</replaceable>.conf</filename>
+ machine definition files in the
+ <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
These configuration files define machine targets that can be built
using the BSP layer.
Multiple machine configuration files define variations of machine
@@ -989,12 +991,22 @@
hardware.
If you do have very different targets, you should create separate
BSP layers for each target.
- <note>It is completely possible for a developer to structure the
- working repository as a conglomeration of unrelated BSP
- files, and to possibly generate BSPs targeted for release
- from that directory using scripts or some other mechanism
- (e.g. <filename>meta-yocto-bsp</filename> layer).
- Such considerations are outside the scope of this document.</note>
+ <note>
+ <para>
+ It is completely possible for a developer to structure the
+ working repository as a conglomeration of unrelated BSP
+ files, and to possibly generate BSPs targeted for release
+ from that directory using scripts or some other mechanism
+ (e.g. <filename>meta-yocto-bsp</filename> layer).
+ Such considerations are outside the scope of this document.
+ </para>
+ <para>
+ In any event, the <filename>meta-yocto-bsp</filename> layer should be
+ considered a special case as it defines the family of Yocto Project
+ reference boards, which necessarily cover the set of supported
+ architectures.
+ </para>
+ </note>
</para></listitem>
</itemizedlist>
</para>
@@ -1025,16 +1037,20 @@
purposes, you should put the images and artifacts within a
<filename>binary/</filename> subdirectory located in the
<filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- <note>If you do include a bootable image as part of the BSP and the image
- was built by software covered by the GPL or other open source licenses,
- it is your responsibility to understand
- and meet all licensing requirements, which could include distribution
- of source files.</note></para></listitem>
+ <note>
+ <para>
+ If you do include a bootable image as part of the BSP and the image
+ was built by software covered by the GPL or other open source licenses,
+ it is your responsibility to understand and meet all licensing
+ requirements, which could include distribution of source files.
+ </para>
+ </note>
+ </para></listitem>
<listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis>
Kernel recipes in the BSP should be based on a Yocto Linux kernel.
Basing your recipes on these kernels reduces the costs for maintaining
the BSP and increases its scalability.
- See the <filename>Yocto Linux Kernel</filename> category in the
+ See the "Yocto Linux Kernel" category in the
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
for these kernels.</para></listitem>
</itemizedlist>
@@ -1056,7 +1072,7 @@
section in the Yocto Project Development Manual.
</para></listitem>
<listitem><para>
- Ensure your directory structure in the BSP layer
+ Ensure that the directory structure in the BSP layer
that supports your machine is such that it can be found
by the build system.
See the example later in this section for more information.
@@ -1083,40 +1099,40 @@
<para>
Following is a specific example to help you better understand the process.
- Consider an example that customizes a recipe by adding
+ Consider an example that customizes a single recipe by adding
a BSP-specific configuration file named <filename>interfaces</filename> to the
- <filename>init-ifupdown_1.0.bb</filename> recipe for machine "xyz" where the
- BSP layer also supports several other machines.
+ <filename>init-ifupdown_1.0.bb</filename> recipe exclusively for machine "xyz",
+ where the BSP layer supports several other machines.
+ </para>
+ <para>
Do the following:
<orderedlist>
- <listitem><para>Edit the <filename>init-ifupdown_1.0.bbappend</filename> file so that it
- contains the following:
+ <listitem><para>In the <filename>meta-xyz/recipes-core/init-ifupdown/</filename>
+ directory, create the <filename>init-ifupdown_1.0.bbappend</filename> file
+ so that it contains the following:
<literallayout class='monospaced'>
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
</literallayout>
- The append file needs to be in the
- <filename>meta-xyz/recipes-core/init-ifupdown</filename> directory.
</para></listitem>
<listitem><para>Create and place the new <filename>interfaces</filename>
- configuration file in the BSP's layer here:
- <literallayout class='monospaced'>
- meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
- </literallayout>
+ configuration file in the BSP layer at
+ <filename>meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces</filename>.
<note>
+ <para>
If the <filename>meta-xyz</filename> layer did not support
- multiple machines, you would place the
+ multiple machines, or this customization applied to all of the
+ machines defined by this BSP layer, you could place the
<filename>interfaces</filename> configuration file in the
- layer here:
- <literallayout class='monospaced'>
- meta-xyz/recipes-core/init-ifupdown/files/interfaces
- </literallayout>
+ layer at
+ <filename>meta-xyz/recipes-core/init-ifupdown/files/interfaces</filename>.
+ </para>
</note>
The
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
variable in the append files extends the search path
the build system uses to find files during the build.
Consequently, for this example you need to have the
- <filename>files</filename> directory in the same location
+ <filename>files/</filename> directory in the same location
as your append file.</para></listitem>
</orderedlist>
</para>
@@ -1227,6 +1243,7 @@
</para>
<note>
+ <para>
Pre-compiled images are bundled with
a time-limited kernel that runs for a
predetermined amount of time (10 days) before it forces
@@ -1234,6 +1251,7 @@
This limitation is meant to discourage direct redistribution
of the image.
You must eventually rebuild the image if you want to remove this restriction.
+ </para>
</note>
</section>
@@ -1367,11 +1385,13 @@
necessary to create a BSP and perform basic kernel maintenance on that BSP using
the tools.
<note>
+ <para>
You can also use the <filename>yocto-layer</filename> tool to create
a "generic" layer.
For information on this tool, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>"
section in the Yocto Project Development Guide.
+ </para>
</note>
</para>
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
More information about the yocto
mailing list