mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-04-23 00:32:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

BSP Guide: numerous tweaks/grammar/wording/clarification

Browse Source 
(From yocto-docs rev: 3a87e5900b603f124ce7f63fd072415762f63212)

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
rpjday@crashcourse.ca
2020-02-23 16:56:42 -05:00
committed by Richard Purdie
parent 284af91476
commit d4a3a121ed
1 changed files with 52 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
documentation/bsp-guide/bsp.xml
View File

@@ -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 a
@@ -34,7 +34,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 <firstterm>BSP layer</firstterm>.
Although not a strict requirement, BSP layers in the Yocto Project
use the following well-established naming convention:
<literallayout class='monospaced'>
@@ -69,9 +69,9 @@
Each repository is a BSP layer supported by the Yocto Project
(e.g. <filename>meta-raspberrypi</filename> and
<filename>meta-intel</filename>).
Each of these layers is a repository unto itself and clicking on a
layer reveals information that includes two links from which you can choose
to set up a clone of the layer's repository on your local host system.
Each of these layers is a repository unto itself and clicking on
the layer name displays two URLs from which you can
clone the layer's repository to your local system.
Here is an example that clones the Raspberry Pi BSP layer:
<literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/meta-raspberrypi
@@ -83,12 +83,13 @@
<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
"reference" BSPs including the ARM-based Beaglebone, MIPS-based
EdgeRouter, and generic versions of
both 32-bit and 64-bit IA machines.
</para>
<para>
For information on the BSP development workflow, see the
For information on typical BSP development workflow, see the
"<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>"
section.
For more information on how to set up a local copy of source files
@@ -98,12 +99,12 @@
</para>
<para>
The layer's base directory
The BSP layer's base directory
(<filename>meta-<replaceable>bsp_root_name</replaceable></filename>)
is the root directory of the BSP Layer.
is the root directory of that Layer.
This directory 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
variable in the <filename>conf/bblayers.conf</filename> file found in your
<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
which is established after you run the OpenEmbedded build environment
setup script (i.e.
@@ -153,6 +154,20 @@
layer.
The <filename>meta-openembedded</filename> layer contains
many <filename>meta-*</filename> layers.
In cases like this, you need to include the names of the actual
layers you want to work with, such as:
<literallayout class='monospaced'>
BBLAYERS ?= " \
/usr/local/src/yocto/meta \
/usr/local/src/yocto/meta-poky \
/usr/local/src/yocto/meta-yocto-bsp \
/usr/local/src/yocto/meta-mylayer \
.../meta-openembedded/meta-oe \
.../meta-openembedded/meta-perl \
.../meta-openembedded/meta-networking \
"
</literallayout>
and so on.
</para>
<para>
@@ -351,25 +366,24 @@
layer combined with a build system and other tools.
Realize that it is important to maintain the distinction
that the BSP layer, a build system, and tools are
separate components that could to be combined in
separate components that could be combined in
certain end products.
</para>
<para>
Before looking at the common form for the file structure
inside a BSP Layer, you should be aware that some
Before looking at the recommended form for the directory structure
inside a BSP layer, you should be aware that some
requirements do exist in order for a BSP layer to
be considered compliant with the Yocto Project.
be considered <firstterm>compliant</firstterm> with the Yocto Project.
For that list of requirements, see the
"<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
section.
</para>
<para>
Below is the common form for the file structure
inside a BSP Layer.
Below is the typical directory structure for a BSP layer.
While this basic form represents the standard,
realize that the actual file structures for specific
realize that the actual layout for individual
BSPs could differ.
<literallayout class='monospaced'>
meta-<replaceable>bsp_root_name</replaceable>/
@@ -567,7 +581,7 @@
for the BSP.
The type or types of files here can vary depending
on the licensing requirements.
For example, in the Raspberry Pi BSP all licensing
For example, in the Raspberry Pi BSP, all licensing
requirements are handled with the
<filename>COPYING.MIT</filename> file.
</para>
@@ -802,7 +816,7 @@
<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
For example, many <filename>tune-*</filename> files
(e.g. <filename>tune-arm1136jf-s.inc</filename>,
<filename>tun-1586-nlp.inc</filename>, and so forth)
<filename>tune-1586-nlp.inc</filename>, and so forth)
reside in the
<filename>poky/meta/conf/machine/include</filename>
directory.
@@ -834,7 +848,7 @@
This optional directory contains miscellaneous recipe
files for the BSP.
Most notably would be the formfactor files.
For example, in the Raspberry Pi BSP there is the
For example, in the Raspberry Pi BSP, there is the
<filename>formfactor_0.0.bbappend</filename> file,
which is an append file used to augment the recipe
that starts the build.
@@ -901,7 +915,7 @@
The <filename>*.bb</filename> files would be a
developer-supplied kernel recipe.
This area of the BSP hierarchy can contain both these
types of files, although in practice, it is likely that
types of files although, in practice, it is likely that
you would have one or the other.
</para>
@@ -976,7 +990,7 @@
<title>Developing a Board Support Package (BSP)</title>
<para>
This section contains the high-level procedure you can
This section describes the high-level procedure you can
follow to create a BSP.
Although not required for BSP creation, the
<filename>meta-intel</filename> repository, which
@@ -1298,7 +1312,7 @@
(<filename>openembedded-core</filename>)
or the Source Directory (<filename>poky</filename>).
In other words, make sure you place related
files in appropriately related
files in appropriately-related
<filename>recipes-*</filename> subdirectories
specific to the recipe's function, or within
a subdirectory containing a set of closely-related
@@ -1315,7 +1329,7 @@
directory.
This license covers the BSP Metadata as a whole.
You must specify which license to use since no
default license exists when one not specified.
default license exists when one is not specified.
See the
<ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
file for the Raspberry Pi BSP in the
@@ -1338,12 +1352,10 @@
file should contain the following:
<itemizedlist>
<listitem><para>
A brief description about the hardware the BSP
targets.
A brief description of the target hardware.
</para></listitem>
<listitem><para>
A list of all the dependencies
on which a BSP layer depends.
A list of all the dependencies of the BSP.
These dependencies are typically a list
of required layers needed to build the
BSP.
@@ -1606,7 +1618,7 @@
<title>BSP Licensing Considerations</title>
<para>
In some cases, a BSP contains separately licensed
In some cases, a BSP contains separately-licensed
Intellectual Property (IP) for a component or components.
For these cases, you are required to accept the terms
of a commercial or other type of license that requires
@@ -1619,7 +1631,7 @@
</para>
<para>
You could find that some separately licensed components
You could find that some separately-licensed components
that are essential for normal operation of the system might
not have an unencumbered (or free) substitute.
Without these essential components, the system would be
@@ -1627,7 +1639,7 @@
Then again, you might find that other licensed components
that are simply 'good-to-have' or purely elective do have
an unencumbered, free replacement component that you can
use rather than agreeing to the separately licensed
use rather than agreeing to the separately-licensed
component.
Even for components essential to the system, you might
find an unencumbered component that is not identical but
@@ -1740,7 +1752,7 @@
<para>
The <filename>bitbake-layers create-layer</filename> script
automates creating a BSP layer.
What makes a layer a "BSP layer", is the presence of a machine
What makes a layer a "BSP layer" is the presence of at least one machine
configuration file.
Additionally, a BSP layer usually has a kernel recipe
or an append file that leverages off an existing kernel recipe.
@@ -1864,11 +1876,14 @@
</para>
<para>
Machine configuration files exist in the
One or more machine configuration files exist in the
<replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename>
directory of the layer:
<literallayout class='monospaced'>
<replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine</replaceable><filename>.conf</filename>
<replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine1</replaceable><filename>.conf</filename>
<replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine2</replaceable><filename>.conf</filename>
<replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine3</replaceable><filename>.conf</filename>
... more ...
</literallayout>
For example, the machine configuration file for the
<ulink url='http://beagleboard.org/bone'>BeagleBone and BeagleBone Black development boards</ulink>
@@ -1919,8 +1934,8 @@
IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb"
</literallayout>
The variables used to configure the machine define
machine-specific properties.
For example, machine-dependent packages, machine
machine-specific properties;
for example, machine-dependent packages, machine
tunings, the type of kernel to build, and
U-Boot configurations.
</para>
@@ -1931,7 +1946,7 @@
machine configuration file for the BeagleBone
development boards.
Realize that much more can be defined as part of
a machines configuration file.
a machine's configuration file.
In general, you can learn about related variables
that this example does not have by locating the
variables in the