diff options
| -rw-r--r-- | documentation/poky-ref-manual/bsp.xml | 246 |
1 files changed, 127 insertions, 119 deletions
diff --git a/documentation/poky-ref-manual/bsp.xml b/documentation/poky-ref-manual/bsp.xml index acb9f38e19..7cd18b61e3 100644 --- a/documentation/poky-ref-manual/bsp.xml +++ b/documentation/poky-ref-manual/bsp.xml @@ -1,53 +1,60 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<chapter id='bsp'> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<chapter id="bsp"> <title>Board Support Packages (BSP) - Developers Guide</title> <para> - A Board Support Package (BSP) is a collection of information which together + A Board Support Package (BSP) is a collection of information that defines how to support a particular hardware device, set of devices, or - hardware platform. It will include information about the hardware features + hardware platform. + The BSP includes information about the hardware features present on the device and kernel configuration information along with any - additional hardware drivers required. It will also list any additional software + additional hardware drivers required. + The BSP also lists any additional software components required in addition to a generic Linux software stack for both essential and optional platform features. </para> <para> The intent of this document is to define a structure for these components - so that BSPs follow a commonly understood layout, allowing them to be - provided in a common form that everyone understands. It also allows end-users - to become familiar with one common format and encourages standardisation + so that BSPs follow a commonly understood layout. + Providing a common form allows end-users to understand and become familiar + with the layout. + A common form also encourages standardization of software support of hardware. </para> <para> The proposed format does have elements that are specific to the Poky and - OpenEmbedded build systems. It is intended that this information can be - used by other systems besides Poky/OpenEmbedded and that it will be simple - to extract information and convert to other formats if required. The format - described can be directly accepted as a layer by Poky using its standard - layers mechanism, but it is important to recognise that the BSP captures all + OpenEmbedded build systems. + It is intended that this information can be + used by other systems besides Poky and OpenEmbedded and thatspecified it will be simple + to extract information and convert it to other formats if required. + Poky, through its standard slyers mechanism, can directly accept The format + described as a layer. + The BSP captures all the hardware specific details in one place in a standard format, which is useful for any person wishing to use the hardware platform regardless of - the build system in use. + the build system being used. </para> <para> The BSP specification does not include a build system or other tools - - it is concerned with the hardware specific components only. At the end - distribution point the BSP may be shipped combined with a build system - and other tools, but it is important to maintain the distinction that these - are separate components which may just be combined in certain end products. + it is concerned with the hardware-specific components only. + At the end + distribution point you can shipt the BSP combined with a build system + and other tools. + However, it is important to maintain the distinction that these + are separate components that happen to be combined in certain end products. </para> - <section id='bsp-filelayout'> + <section id="bsp-filelayout"> <title>Example Filesystem Layout</title> <para> - The BSP consists of a file structure inside a base directory, meta-bsp in this example, where "bsp" is a placeholder for the machine or platform name. Examples of some files that it could contain are: + The BSP consists of a file structure inside a base directory, meta-bsp in this example, + where "bsp" is a placeholder for the machine or platform name. + Examples of some files that it could contain are: </para> <para> @@ -76,15 +83,18 @@ meta-bsp/prebuilds/ </section> - <section id='bsp-filelayout-binary'> + <section id="bsp-filelayout-binary"> <title>Prebuilt User Binaries (meta-bsp/binary/*)</title> <para> This optional area contains useful prebuilt kernels and userspace filesystem - images appropriate to the target system. Users could use these to get a system - running and quickly get started on development tasks. The exact types of binaries + images appropriate to the target system. + Users could use these to get a system + running and quickly get started on development tasks. + The exact types of binaries present will be highly hardware-dependent but a README file should be present - explaining how to use them with the target hardware. If prebuilt binaries are + explaining how to use them with the target hardware. + If prebuilt binaries are present, source code to meet licensing requirements must also be provided in some form. </para> @@ -95,9 +105,10 @@ meta-bsp/prebuilds/ <title>Layer Configuration (meta-bsp/conf/layer.conf)</title> <para> - This file identifies the structure as a Poky layer. This file identifies the - contents of the layer and contains information about how Poky should use - it. In general it will most likely be a standard boilerplate file consisting of: + This file identifies the structure as a Poky layer by identifying the + contents of the layer and containing information about how Poky should use + it. + Generally, a standard boilerplate file consisting of the following works. </para> <para> @@ -106,7 +117,7 @@ meta-bsp/prebuilds/ BBPATH := "${BBPATH}${LAYERDIR}" # We have a recipes directory containing .bb and .bbappend files, add to BBFILES -BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb ${LAYERDIR}/recipes/*/*.bbappend" +BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ ${LAYERDIR}/recipes/*/*.bbappend" BBFILE_COLLECTIONS += "bsp" BBFILE_PATTERN_bsp := "^${LAYERDIR}/" @@ -115,47 +126,45 @@ BBFILE_PRIORITY_bsp = "5" </para> <para> - which simply makes bitbake aware of the recipes and conf directories. - </para> - - <para> - This file is required for recognition of the BSP by Poky. + This file simply makes bitbake aware of the recipes and conf directories and is required + for recognition of the BSP by Poky. </para> </section> - <section id='bsp-filelayout-machine'> + <section id="bsp-filelayout-machine"> <title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title> <para> The machine files bind together all the information contained elsewhere - in the BSP into a format that Poky/OpenEmbedded can understand. If - the BSP supports multiple machines, multiple machine configuration files - can be present. These filenames correspond to the values users set the - MACHINE variable to. + in the BSP into a format that Poky/OpenEmbedded can understand. + If the BSP supports multiple machines, multiple machine configuration files + can be present. + These filenames correspond to the values to which users have set the MACHINE variable. </para> <para> - These files would define things like which kernel package to use - (PREFERRED_PROVIDER of virtual/kernel), which hardware drivers to + These files define things such as what kernel package to use + (PREFERRED_PROVIDER of virtual/kernel), what hardware drivers to include in different types of images, any special software components that are needed, any bootloader information, and also any special image format requirements. </para> <para> - At least one machine file is required for a Poky BSP layer but more than one may be present. + At least one machine file is required for a Poky BSP layer. + However, you can supply more than one file. </para> </section> - <section id='bsp-filelayout-tune'> - <title>Hardware Optimisation Options (meta-bsp/conf/machine/include/tune-*.inc)</title> + <section id="bsp-filelayout-tune"> + <title>Hardware Optimization Options (meta-bsp/conf/machine/include/tune-*.inc)</title> <para> These are shared hardware "tuning" definitions and are commonly used to - pass specific optimisation flags to the compiler. An example is - tune-atom.inc: + pass specific optimization flags to the compiler. + An example is tune-atom.inc: </para> <para> <programlisting> @@ -164,40 +173,42 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" </programlisting> </para> <para> - which defines a new package architecture called "core2" and uses the - optimization flags specified, which are carefully chosen to give best - performance on atom cpus. + This example defines a new package architecture called "core2" and uses the + specified optimization flags, which are carefully chosen to give best + performance on atom processors. </para> <para> The tune file would be included by the machine definition and can be - contained in the BSP or reference one from the standard core set of + contained in the BSP or referenced from one of the standard core set of files included with Poky itself. </para> <para> - These files are optional for a Poky BSP layer. + Both the base package architecuture file and the tune file are optional for a Poky BSP layer. </para> </section> + <section id='bsp-filelayout-kernel'> <title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title> <para> These files make up the definition of a kernel to use with this - hardware. In this case it is a complete self-contained kernel with its own + hardware. + In this case it is a complete self-contained kernel with its own configuration and patches but kernels can be shared between many - machines as well. Taking some specific example files: - </para> - <para> + machines as well. + Following is an example: <programlisting> meta-bsp/packages/linux/linux-bsp_2.6.50.bb </programlisting> + This example file is the core kernel recipe that details from where to get the kernel + source. + All standard source code locations are supported so this could + be a release tarball, some git repository, or source included in + the directory within the BSP itself. </para> <para> - which is the core kernel recipe which firstly details where to get the kernel - source from. All standard source code locations are supported so this could - be a release tarball, some git repository, or source included in - the directory within the BSP itself. It then contains information about which - patches to apply and how to configure and build it. It can reuse the main - Poky kernel build class, so the definitions here can remain very simple. + 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. </para> <para> <programlisting> @@ -205,7 +216,7 @@ linux-bsp-2.6.50/*.patch </programlisting> </para> <para> - which are patches which may be applied against the base kernel, wherever + The above example file contains patches you can apply against the base kernel, wherever they may have been obtained from. </para> <para> @@ -214,11 +225,11 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp </programlisting> </para> <para> - which is the configuration information to use to configure the kernel. + Finally, this last example file contains configuration information to use to configure the kernel. </para> <para> - Examples of kernel recipes are available in Poky itself. These files are - optional since a kernel from Poky itself could be selected, although it + Examples of kernel recipes are available in Poky itself. + These files are optional since a kernel from Poky itself could be selected, although it would be unusual not to have a kernel configuration. </para> </section> @@ -227,11 +238,19 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp <title>Other Software (meta-bsp/packages/*)</title> <para> - This area includes other pieces of software which the hardware may need for best - operation. These are just examples of the kind of things that may be - encountered. These are standard .bb file recipes in the usual Poky format, - so for examples, see standard Poky recipes. The source can be included directly, - referred to in source control systems or release tarballs of external software projects. + This section describes other pieces of software that the hardware might need for best + operation. + These are examples of the kinds of things that you could encounter. + The examples used in this section are standard <filename>.bb</filename> file recipes in the + usual Poky format. + You can include the source directly by referring to it in the source control system or + the released tarballs of external software projects. + You only need to provide these types of files if the platform requires them. + </para> + <para> + The following file is a bootloader recipe that can be used to generate a new + bootloader binary. + Sometimes these files are included in the final image format and are needed to reflash hardware. </para> <para> <programlisting> @@ -239,9 +258,9 @@ meta-bsp/packages/bootloader/bootloader_0.1.bb </programlisting> </para> <para> - Some kind of bootloader recipe which may be used to generate a new - bootloader binary. Sometimes these are included in the final image - format and needed to reflash hardware. + These next two files are examples of a hardware driver and a hardware daemon that might need + to be included in images to make the hardware useful. + Although the example uses "modem" there may be other components needed, such as firmware. </para> <para> <programlisting> @@ -250,72 +269,62 @@ meta-bsp/packages/modem/modem-daemon_0.1.bb </programlisting> </para> <para> - These are examples of a hardware driver and also a hardware daemon which - may need to be included in images to make the hardware useful. "modem" - is one example but there may be other components needed like firmware. + Sometimes the device needs an image in a very specific format so that the update + mechanism can accept and reflash it. + Recipes to build the tools needed to do this can be included with the BSP. + Following is an example. </para> <para> <programlisting> meta-bsp/packages/image-creator/image-creator-native_0.1.bb </programlisting> </para> + </section> + + <section id='bs-filelayout-bbappend'> + <title>Append BSP-Specific Information to Existing Recipes</title> <para> - Sometimes the device will need an image in a very specific format for - its update mechanism to accept and reflash with it. Recipes to build the - tools needed to do this can be included with the BSP. + 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, which is where + 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 + pointercal recipe and files into your layer, and then add the single file for your machine. </para> <para> - These files only need be provided if the platform requires them. + With the <filename>.bbappend</filename> extension, however, your work becomes much easier. + It allows you to easily merge BSP-specific information with the original recipe. + Whenever bitbake finds any <filename>.bbappend</filename> files, they will be + included after bitbake loads the associated <filename>.bb</filename> but before any finalize + or anonymous methods run. + This allows the BSP layer to do whatever it might want to do to customize the original recipe. </para> - </section> - - <section id='bs-filelayout-bbappend'> - <title>Append BSP specific information to existing recipes</title> - <para> - Say you have a recipe like pointercal which has machine-specific information in it, - and then you have your new BSP code in a layer. Before the .bbappend extension was - introduced, you'd have to copy the whole pointercal recipe and files into your layer, - and then add the single file for your machine, which is ugly. - - .bbappend makes the above work much easier, to allow BSP-specific information to be merged - with the original recipe easily. When bitbake finds any X.bbappend files, they will be - included after bitbake loads X.bb but before finalise or anonymous methods run. - This allows the BSP layer to poke around and do whatever it might want to customise - the original recipe. - - If your recipe needs to reference extra files it can use the FILESEXTRAPATH variable - to specify their location. The example below shows extra files contained in a folder - called ${PN} (the package name). + If your recipe needs to reference extra files it can use the FILESEXTRAPATH variable + to specify their location. + The example below shows extra files contained in a folder called ${PN} (the package name). </para> - <programlisting> FILESEXTRAPATHS := "${THISDIR}/${PN}" </programlisting> - <para> - Then the BSP could add machine-specific config files in layer directory, which will be - added by bitbake. You can look at meta-emenlow/packages/formfactor as an example. + This technique allows the BSP to add machine-specific configuration files to the layer directory, + which will be picked up by bitbake. + For an example see <filename>meta-emenlow/packages/formfactor</filename>. </para> </section> - <section id='bsp-filelayout-prebuilds'> + <section id="bsp-filelayout-prebuilds"> <title>Prebuild Data (meta-bsp/prebuilds/*)</title> - - <para> - The location can contain a precompiled representation of the source code - contained elsewhere in the BSP layer. It can be processed and used by - Poky to provide much faster build times, assuming a compatible configuration is used. - </para> - <para> - These files are optional. + This location can contain precompiled representations of the source code + contained elsewhere in the BSP layer. + Assuming a compatible configuration is used, Poky can process and use these optional precompiled + representations to provide much faster build times. </para> - </section> <section id='bsp-click-through-licensing'> - <title>BSP 'Click-through' Licensing Procedure</title> + <title>BSP 'Click-Through' Licensing Procedure</title> <note><para> This section is here as a description of how click-through licensing is expected to work, and is @@ -367,10 +376,9 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}" <para> Get a license key (or keys) for the encumbered BSP - by - visiting <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink> - and give the web form there the name of the BSP - and your e-mail address. + by visiting + <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink> + and give the web form there the name of the BSP and your e-mail address. </para> <programlisting> |