sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

documentation/bsp-guide/bsp.xml: General edits. 

1. Edited to incorporate new file system naming structure per Saul Wold.  This
   is the version I am sending him and Tom Z. to review.

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>

Conflicts:

	documentation/bsp-guide/bsp.xml

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
This commit is contained in:
Scott Rifenbark 2010-12-13 16:21:12 -08:00 committed by Saul Wold
parent e7f5bc2504
commit 27c117141f
1 changed files with 87 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -55,27 +55,37 @@
<title>Example Filesystem Layout</title> <title>Example Filesystem Layout</title>
<para> <para>
The BSP consists of a file structure inside a base directory, meta-bsp in this example, The BSP consists of a file structure inside a base directory, which uses the following
where "bsp" is a placeholder for the machine or platform name. naming convention:
Examples of some files that it could contain are: <literallayout class='monospaced'>
meta-&lt;bsp_name&gt;
</literallayout>
"bsp_name" is a placeholder for the machine or platform name.
Here are some example base directory names:
<literallayout class='monospaced'>
meta-Emenlow
meta-intel_n450
meta-oaktrail
</literallayout>
</para> </para>
<para> <para>
The file structure inside the base directory takes on the following form:
<programlisting> <programlisting>
meta-bsp/ meta-&lt;bsp_name&gt;/
meta-bsp/binary/zImage meta-&lt;bsp_name&gt;/binary/zImage
meta-bsp/binary/poky-image-minimal.directdisk meta-&lt;bsp_name&gt;/binary/poky-image-minimal.directdisk
meta-bsp/conf/layer.conf meta-&lt;bsp_name&gt;/conf/layer.conf
meta-bsp/conf/machine/*.conf meta-&lt;bsp_name&gt;/conf/machine/*.conf
meta-bsp/conf/machine/include/tune-*.inc meta-&lt;bsp_name&gt;/conf/machine/include/tune-*.inc
meta-bsp/packages/bootloader/bootloader_0.1.bb meta-&lt;bsp_name&gt;/recipes-kernel/bootloader/bootloader_0.1.bb
meta-bsp/packages/linux/linux-bsp-2.6.50/*.patch meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-bsp-2.6.50/*.patch
meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-bsp-2.6.50/defconfig-bsp
meta-bsp/packages/linux/linux-bsp_2.6.50.bb meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-bsp_2.6.50.bb
meta-bsp/packages/modem/modem-driver_0.1.bb meta-&lt;bsp_name&gt;/recipes-&lt;bsp_name&gt;/modem/modem-driver_0.1.bb
meta-bsp/packages/modem/modem-daemon_0.1.bb meta-&lt;bsp_name&gt;/recipes-&lt;bsp_name&gt;/modem/modem-daemon_0.1.bb
meta-bsp/packages/image-creator/image-creator-native_0.1.bb meta-&lt;bsp_name&gt;/recipes-&lt;bsp_name&gt;/image-creator/image-creator-native_0.1.bb
meta-bsp/prebuilds/ meta-&lt;bsp_name&gt;/prebuilds/
</programlisting> </programlisting>
</para> </para>
@ -86,32 +96,29 @@ meta-bsp/prebuilds/
</section> </section>
<section id="bsp-filelayout-binary"> <section id="bsp-filelayout-binary">
<title>Prebuilt User Binaries (meta-bsp/binary/*)</title> <title>Pre-built User Binaries (meta-&lt;bsp_name&gt;/binary/*)</title>
<para> <para>
This optional area contains useful prebuilt kernels and userspace filesystem This optional area contains useful pre-built kernels and userspace filesystem
images appropriate to the target system. images appropriate to the target system.
Users could use these to get a system You can use these kernels and images to get a system running and quickly get started
running and quickly get started on development tasks. on development tasks.
The exact types of binaries The exact types of binaries present are highly hardware-dependent.
present are highly hardware-dependent. However, a README file should be present that explains how to use the kernels and
However, a README file should be present images with the target hardware.
that explains how to use them with the target hardware. If pre-built binaries are present, source code to meet licensing requirements must also
If prebuilt binaries are be provided in some form.
present, source code to meet licensing requirements must also be provided in
some form.
</para> </para>
</section> </section>
<section id='bsp-filelayout-layer'> <section id='bsp-filelayout-layer'>
<title>Layer Configuration (meta-bsp/conf/layer.conf)</title> <title>Layer Configuration (meta-&lt;bsp_name&gt;/conf/layer.conf)</title>
<para> <para>
This file identifies the structure as a Poky layer, identifies the This file identifies the structure as a Poky layer, identifies the
contents of the layer and contains information about how Poky should use contents of the layer, and contains information about how Poky should use
it. it.
Generally, a standard boilerplate file consisting of the following works. Generally, a standard boilerplate file such as the following works:
</para> </para>
<para> <para>
@ -129,26 +136,25 @@ BBFILE_PRIORITY_bsp = "5"
</para> </para>
<para> <para>
This file simply makes bitbake aware of the recipes and conf directories and is required This file simply makes BitBake aware of the recipes and configuration directories.
for recognition of the BSP by Poky. This file must exist so that Poky can recognize the BSP.
</para> </para>
</section> </section>
<section id="bsp-filelayout-machine"> <section id="bsp-filelayout-machine">
<title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title> <title>Hardware Configuration Options (meta-&lt;bsp_name&gt;/conf/machine/*.conf)</title>
<para> <para>
The machine files bind together all the information contained elsewhere The machine files bind together all the information contained elsewhere
in the BSP into a format that Poky/OpenEmbedded can understand. in the BSP into a format that Poky can understand.
If the BSP supports multiple machines, multiple machine configuration files If the BSP supports multiple machines, multiple machine configuration files
can be present. can be present.
These filenames correspond to the values to which users have set the MACHINE variable. These filenames correspond to the values to which users have set the MACHINE variable.
</para> </para>
<para> <para>
These files define things such as what kernel package to use These files define things such as the kernel package to use
(PREFERRED_PROVIDER of virtual/kernel), what hardware drivers to (PREFERRED_PROVIDER of virtual/kernel), the hardware drivers to
include in different types of images, any special software components include in different types of images, any special software components
that are needed, any bootloader information, and also any special image that are needed, any bootloader information, and also any special image
format requirements. format requirements.
@ -158,22 +164,21 @@ BBFILE_PRIORITY_bsp = "5"
At least one machine file is required for a Poky BSP layer. At least one machine file is required for a Poky BSP layer.
However, you can supply more than one file. However, you can supply more than one file.
</para> </para>
</section> </section>
<section id="bsp-filelayout-tune"> <section id="bsp-filelayout-tune">
<title>Hardware Optimization Options (meta-bsp/conf/machine/include/tune-*.inc)</title> <title>Hardware Optimization Options (meta-&lt;bsp_name&gt;/conf/machine/include/tune-*.inc)</title>
<para> <para>
These are shared hardware "tuning" definitions and are commonly used to These files are shared hardware "tuning" definitions and are commonly used to
pass specific optimization flags to the compiler. pass specific optimization flags to the compiler.
An example is tune-atom.inc: An example is <filename>tune-atom.inc</filename>:
</para> </para>
<para> <para>
<programlisting> <programlisting>
BASE_PACKAGE_ARCH = "core2" BASE_PACKAGE_ARCH = "core2"
TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
</programlisting> </programlisting>
</para> </para>
<para> <para>
This example defines a new package architecture called "core2" and uses the This example defines a new package architecture called "core2" and uses the
@ -191,59 +196,58 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
</section> </section>
<section id='bsp-filelayout-kernel'> <section id='bsp-filelayout-kernel'>
<title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title> <title>Linux Kernel Configuration (meta-&lt;bsp_name&gt;/recipes-kernel/linux/*)</title>
<para> <para>
These files make up the definition of a kernel to use with this These files make up the definition of a kernel to use with this hardware.
hardware.
In this case, it is a complete self-contained kernel with its own In this case, it is a complete self-contained kernel with its own
configuration and patches. configuration and patches.
However, kernels can be shared between many machines as well. However, kernels can be shared between many machines as well.
Following is an example: Following is an example:
<programlisting> <programlisting>
meta-bsp/packages/linux/linux-bsp_2.6.50.bb meta-Emenlow/recipes-kernel/linux/linux-bsp_2.6.50.bb
</programlisting> </programlisting>
This example file is the core kernel recipe that details from where to get the kernel This example file is the core kernel recipe that details from where to get the kernel
source. source.
All standard source code locations are supported so this could All standard source code locations are supported.
be a release tarball, some git repository, or source included in Consequently, the source could be a release tarball, a git repository, or source included in
the directory within the BSP itself. the directory within the BSP itself.
</para> </para>
<para> <para>
The file then contains information about what patches to apply and how to configure and build them. The file then contains information about what patches to apply and how to configure and build them.
It can reuse the main Poky kernel build class, so the definitions here can remain very simple. Because the file can reuse the main Poky kernel build class, the definitions here can
remain very simple.
</para> </para>
<para> <para>
<programlisting> <programlisting>
linux-bsp-2.6.50/*.patch linux-bsp-2.6.50/*.patch
</programlisting> </programlisting>
</para> </para>
<para> <para>
The above example file contains patches you can apply against the base kernel, from wherever The above example file contains patches you can apply against the base kernel, from wherever
they may have been obtained. they may have been obtained.
</para> </para>
<para> <para>
<programlisting> <programlisting>
meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp meta-Emenlow/recipes-kernel/linux/linux-bsp-2.6.50/defconfig-bsp
</programlisting> </programlisting>
</para> </para>
<para> <para>
Finally, this last example file contains kernel configuration information. Finally, this last example file contains kernel configuration information.
</para> </para>
<para> <para>
Examples of kernel recipes are available in Poky itself. Examples of kernel recipes are available in Poky itself, and thus, make these files optional.
These files are optional since a kernel from Poky could be selected, although it However, it would be unusual not to have a kernel configuration.
would be unusual not to have a kernel configuration.
</para> </para>
</section> </section>
<section id='bsp-filelayout-packages'> <section id='bsp-filelayout-packages'>
<title>Other Software (meta-bsp/packages/*)</title> <title>Other Software (meta-&lt;bsp_name&gt;/recipes-kernel/*)</title>
<para> <para>
This section describes other pieces of software that the hardware might need for best This section describes other pieces of software that the hardware might need for best
operation. operation.
This section shows examples of the kinds of things that you could encounter. Examples show some of the things you could encounter.
The examples are standard <filename>.bb</filename> file recipes in the The examples are standard <filename>.bb</filename> file recipes in the
usual Poky format. usual Poky format.
You can include the source directly by referring to it in the source control system or You can include the source directly by referring to it in the source control system or
@ -257,7 +261,7 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
</para> </para>
<para> <para>
<programlisting> <programlisting>
meta-bsp/packages/bootloader/bootloader_0.1.bb meta-Emenlow/recipes-kernel/bootloader/bootloader_0.1.bb
</programlisting> </programlisting>
</para> </para>
<para> <para>
@ -267,8 +271,8 @@ meta-bsp/packages/bootloader/bootloader_0.1.bb
</para> </para>
<para> <para>
<programlisting> <programlisting>
meta-bsp/packages/modem/modem-driver_0.1.bb meta-Emenlow/recipes-Emenlow/modem/modem-driver_0.1.bb
meta-bsp/packages/modem/modem-daemon_0.1.bb meta-Emenlow/recipes-Emenlow/modem/modem-daemon_0.1.bb
</programlisting> </programlisting>
</para> </para>
<para> <para>
@ -279,7 +283,7 @@ meta-bsp/packages/modem/modem-daemon_0.1.bb
</para> </para>
<para> <para>
<programlisting> <programlisting>
meta-bsp/packages/image-creator/image-creator-native_0.1.bb meta-Emenlow/recipes-Emenlow/image-creator/image-creator-native_0.1.bb
</programlisting> </programlisting>
</para> </para>
</section> </section>
@ -287,7 +291,7 @@ meta-bsp/packages/image-creator/image-creator-native_0.1.bb
<section id='bs-filelayout-bbappend'> <section id='bs-filelayout-bbappend'>
<title>Append BSP-Specific Information to Existing Recipes</title> <title>Append BSP-Specific Information to Existing Recipes</title>
<para> <para>
Suppose you have a recipe such as 'pointercal' that requires machine-specific information. Suppose you have a recipe such as "pointercal" that requires machine-specific information.
At the same time, you have your new BSP code nicely partitioned into a layer through which At the same time, you have your new BSP code nicely partitioned into a layer through which
you would also like to specify any machine-specific information associated with your new machine. you would also like to specify any machine-specific information associated with your new machine.
Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole Before the <filename>.bbappend</filename> extension was introduced, you would have to copy the whole
@ -296,9 +300,9 @@ meta-bsp/packages/image-creator/image-creator-native_0.1.bb
<para> <para>
With the <filename>.bbappend</filename> extension, however, your work becomes much easier. With the <filename>.bbappend</filename> extension, however, your work becomes much easier.
This extension allows you to easily merge BSP-specific information with the original recipe. This extension allows you to easily merge BSP-specific information with the original recipe.
Whenever bitbake finds any <filename>.bbappend</filename> files they will be Whenever BitBake finds any <filename>.bbappend</filename> files BitBake will include them after
included after bitbake loads the associated <filename>.bb</filename> but before any finalize it loads the associated <filename>.bb</filename> file but before any finalize
or anonymous methods run. or anonymous methods are run.
This allows the BSP layer to do whatever it might want to do to customize the original recipe. This allows the BSP layer to do whatever it might want to do to customize the original recipe.
</para> </para>
<para> <para>
@ -311,17 +315,17 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
</programlisting> </programlisting>
<para> <para>
This technique allows the BSP to add machine-specific configuration files to the layer directory, This technique allows the BSP to add machine-specific configuration files to the layer directory,
which will be picked up by bitbake. which will be picked up by BitBake.
For an example see <filename>meta-emenlow/packages/formfactor</filename>. For an example see <filename>meta-emenlow/packages/formfactor</filename>.
</para> </para>
</section> </section>
<section id="bsp-filelayout-prebuilds"> <section id="bsp-filelayout-prebuilds">
<title>Prebuild Data (meta-bsp/prebuilds/*)</title> <title>Pre-build Data (meta-&lt;bsp_name&gt;/prebuilds/*)</title>
<para> <para>
This location can contain precompiled representations of the source code This location can contain precompiled representations of the source code
contained elsewhere in the BSP layer. contained elsewhere in the BSP layer.
Assuming a compatible configuration is used, Poky can process and use these optional precompiled Assuming a compatible configuration is used, Poky can process and use these optional pre-compiled
representations to provide much faster build times. representations to provide much faster build times.
</para> </para>
</section> </section>
@ -354,24 +358,18 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
<para> <para>
For cases where you can substitute something and still maintain functionality, the Poky website will make For cases where you can substitute something and still maintain functionality, the Poky website will make
available a 'de-featured' BSP completely free of available a 'de-featured' BSP completely free of the encumbered IP.
the encumbered IP. In that case you can use the substitution directly and without any further licensing requirements.
In that case you can use the substitution directly and without If present, this fully 'de-featured' BSP will be named meta-&lt;bsp_name&gt; (i.e. the
any further licensing requirements.
If present, this
fully 'de-featured' BSP will be named meta-bsp (i.e. the
normal default naming convention). normal default naming convention).
If available, this is the simplest the most preferred option. If available, this is the simplest the most preferred option.
This, of course, assumes the resulting functionality meets requirements. This, of course, assumes the resulting functionality meets requirements.
</para> </para>
<para> <para>
If however, a non-encumbered version is unavailable or If however, a non-encumbered version is unavailable or the 'free' version would provide unsuitable
the 'free' version would provide unsuitable functionality or quality, an encumbered version can be used.
functionality or quality, an encumbered version can be Encumbered versions of a BSP are given names of the form meta-&lt;bsp_name&gt;-nonfree.
used.
Encumbered versions of a BSP are given names of
the form meta-bsp-nonfree.
</para> </para>
<para> <para>
@ -381,11 +379,10 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
</para> </para>
<orderedlist> <orderedlist>
<listitem> <listitem>
<para> <para>
Get a license key (or keys) for the encumbered BSP Get a license key (or keys) for the encumbered BSP by visiting
by visiting
<ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink> <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink>
and give the name of the BSP and your e-mail address in the web form. and give the name of the BSP and your e-mail address in the web form.
</para> </para>
@ -427,7 +424,7 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
applicable license must be present in <filename>local.conf</filename> or applicable license must be present in <filename>local.conf</filename> or
supplied on the command-line. supplied on the command-line.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Do nothing - build as you normally would. Do nothing - build as you normally would.
@ -465,7 +462,7 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
non-free BSPs. non-free BSPs.
Those images are likewise available at Those images are likewise available at
<ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>. <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
</para> </para>
</section> </section>
</chapter> </chapter>