diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 72b065dad3..1edbc049de 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -1425,39 +1425,55 @@
Released BSP Recommendations
- Following are recommendations for a released BSP that conforms to the
- Yocto Project:
+ Following are recommendations for released BSPs that
+ conform to the Yocto Project:
- Bootable Images:
- BSP releases
- can contain one or more bootable images.
- Including bootable images allows users to easily try out the BSP
- on their own hardware.
- In some cases, it might not be convenient to include a
- bootable image.
- In this case, you might want to make two versions of the
- BSP available: one that contains binary images, and one
- that does not.
- The version that does not contain bootable images avoids
- unnecessary download times for users not interested in the images.
-
- If you need to distribute a BSP and include bootable images or build kernel and
- filesystems meant to allow users to boot the BSP for evaluation
- purposes, you should put the images and artifacts within a
- binary/ subdirectory located in the
- meta-bsp_name directory.
- 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.
- Use a Yocto Linux Kernel:
- 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 Yocto Linux Kernel category in the
+
+ Bootable Images:
+ Released BSPs can contain one or more bootable
+ images.
+ Including bootable images allows users to easily
+ try out the BSP using their own hardware.
+
+ In some cases, it might not be convenient
+ to include a bootable image.
+ If so, you might want to make two versions of the
+ BSP available: one that contains binary images, and
+ one that does not.
+ The version that does not contain bootable images
+ avoids unnecessary download times for users not
+ interested in the images.
+
+ If you need to distribute a BSP and include
+ bootable images or build kernel and filesystems
+ meant to allow users to boot the BSP for evaluation
+ purposes, you should put the images and artifacts
+ within a
+ binary/ subdirectory located
+ in the
+ meta-bsp_name
+ directory.
+
+ 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.
+
+
+
+ Use a Yocto Linux Kernel:
+ 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 Yocto Linux Kernel
+ category in the
Source Repositories
- for these kernels.
+ for these kernels.
+
@@ -1467,78 +1483,94 @@
Customizing a Recipe for a BSP
- If you plan on customizing a recipe for a particular BSP, you need to do the
- following:
-
- Create a .bbappend
- file for the modified recipe.
- For information on using append files, see the
- "Using .bbappend Files in Your Layer"
- section in the Yocto Project Development Tasks Manual.
-
-
- Ensure your 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.
-
-
- Put the append file in a directory whose name matches
- the machine's name and is located in an appropriate
- sub-directory inside the BSP layer (i.e.
- recipes-bsp, recipes-graphics,
- recipes-core, and so forth).
-
- Place the BSP-specific files in the proper directory
- inside the BSP layer.
- How expansive the layer is affects where you must place these files.
- For example, if your layer supports several different machine types,
- you need to be sure your layer's directory structure includes hierarchy
- that separates the files out according to machine.
- If your layer does not support multiple machines, the layer would not
- have that additional hierarchy and the files would obviously not be
- able to reside in a machine-specific directory.
-
-
-
+ If you plan on customizing a recipe for a particular BSP,
+ you need to do the following:
+
+
+ Create a *.bbappend file for
+ the modified recipe.
+ For information on using append files, see the
+ "Using .bbappend Files in Your Layer"
+ section in the Yocto Project Development Tasks
+ Manual.
+
+
+ Ensure your directory structure in the BSP layer
+ that supports your machine is such that the
+ OpenEmbedded build system can find it.
+ See the example later in this section for more
+ information.
+
+
+ Put the append file in a directory whose name matches
+ the machine's name and is located in an appropriate
+ sub-directory inside the BSP layer (i.e.
+ recipes-bsp,
+ recipes-graphics,
+ recipes-core, and so forth).
+
+
+ Place the BSP-specific files in the proper
+ directory inside the BSP layer.
+ How expansive the layer is affects where you must
+ place these files.
+ For example, if your layer supports several
+ different machine types, you need to be sure your
+ layer's directory structure includes hierarchy
+ that separates the files according to machine.
+ If your layer does not support multiple machines,
+ the layer would not have that additional hierarchy
+ and the files would obviously not be able to reside
+ in a machine-specific directory.
+
+
+
-
- Following is a specific example to help you better understand the process.
- Consider an example that customizes a recipe by adding
- a BSP-specific configuration file named interfaces to the
- init-ifupdown_1.0.bb recipe for machine "xyz" where the
- BSP layer also supports several other machines.
- Do the following:
-
- Edit the init-ifupdown_1.0.bbappend file so that it
- contains the following:
-
+
+ Following is a specific example to help you better understand
+ the process.
+ This example customizes customizes a recipe by adding a
+ BSP-specific configuration file named
+ interfaces to the
+ init-ifupdown_1.0.bb recipe for machine
+ "xyz" where the BSP layer also supports several other
+ machines:
+
+
+ Edit the
+ init-ifupdown_1.0.bbappend file
+ so that it contains the following:
+
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
-
- The append file needs to be in the
- meta-xyz/recipes-core/init-ifupdown directory.
-
- Create and place the new interfaces
- configuration file in the BSP's layer here:
-
+
+ The append file needs to be in the
+ meta-xyz/recipes-core/init-ifupdown
+ directory.
+
+
+ Create and place the new
+ interfaces configuration file in
+ the BSP's layer here:
+
meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
-
-
- If the meta-xyz layer did not support
- multiple machines, you would place the
- interfaces configuration file in the
- layer here:
-
+
+
+ If the meta-xyz layer did
+ not support multiple machines, you would place
+ the interfaces configuration
+ file in the layer here:
+
meta-xyz/recipes-core/init-ifupdown/files/interfaces
-
-
- The
- FILESEXTRAPATHS
- 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
- files directory in the same location
- as your append file.
+
+
+ The
+ FILESEXTRAPATHS
+ 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
+ files directory in the same
+ location as your append file.
+
@@ -1547,115 +1579,131 @@
BSP Licensing Considerations
- 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 some kind of explicit End User License Agreement (EULA).
- Once the license is accepted, the OpenEmbedded build system can then build and
- include the corresponding component in the final BSP image.
- If the BSP is available as a pre-built image, you can download the image after
- agreeing to the license or EULA.
+ 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
+ some kind of explicit End User License Agreement (EULA).
+ Once you accept the license, the OpenEmbedded build system
+ can then build and include the corresponding component
+ in the final BSP image.
+ If the BSP is available as a pre-built image, you can
+ download the image after agreeing to the license or EULA.
- 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 non-functional.
- 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 component.
- Even for components essential to the system, you might find an unencumbered component
- that is not identical but will work as a less-capable version of the
- licensed version in the BSP recipe.
+ 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
+ non-functional.
+ 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
+ component.
+ Even for components essential to the system, you might
+ find an unencumbered component that is not identical but
+ will work as a less-capable version of the licensed version
+ in the BSP recipe.
- For cases where you can substitute a free component and still
- maintain the system's functionality, the "Downloads" page from the
- Yocto Project website's
- makes available de-featured BSPs
- that are completely free of any IP encumbrances.
+ For cases where you can substitute a free component and
+ still maintain the system's functionality, the "DOWNLOADS"
+ selection from the "SOFTWARE" tab on the
+ Yocto Project website
+ makes available de-featured BSPs that are completely free
+ of any IP encumbrances.
For these cases, you can use the substitution directly and
without any further licensing requirements.
- If present, these fully de-featured BSPs are named appropriately
- different as compared to the names of the respective
- encumbered BSPs.
- If available, these substitutions are your
- simplest and most preferred options.
- Use of these substitutions of course assumes the resulting functionality meets
- system requirements.
+ If present, these fully de-featured BSPs are named
+ appropriately different as compared to the names of their
+ respective encumbered BSPs.
+ If available, these substitutions are your simplest and
+ most preferred options.
+ Obviously, use of these substitutions assumes the resulting
+ functionality meets system requirements.
+
+ If however, a non-encumbered version is unavailable or
+ it provides unsuitable functionality or quality, you can
+ use an encumbered version.
+
- If however, a non-encumbered version is unavailable or
- it provides unsuitable functionality or quality, you can use an encumbered
- version.
-
-
-
- A couple different methods exist within the OpenEmbedded build system to
- satisfy the licensing requirements for an encumbered BSP.
+ A couple different methods exist within the OpenEmbedded
+ build system to satisfy the licensing requirements for an
+ encumbered BSP.
The following list describes them in order of preference:
- Use the
+
+ Use the
LICENSE_FLAGS
- variable to define the recipes that have commercial or other
- types of specially-licensed packages:
- For each of those recipes, you can
- specify a matching license string in a
+ Variable to Define the Recipes that Have Commercial
+ or Other Types of Specially-Licensed Packages:
+ For each of those recipes, you can specify a
+ matching license string in a
local.conf variable named
LICENSE_FLAGS_WHITELIST.
- Specifying the matching license string signifies that you agree to the license.
- Thus, the build system can build the corresponding recipe and include
- the component in the image.
+ Specifying the matching license string signifies
+ that you agree to the license.
+ Thus, the build system can build the corresponding
+ recipe and include the component in the image.
See the
"Enabling Commercially Licensed Recipes"
- section in the Yocto Project Concepts Manual for details on how
- to use these variables.
+ section in the Yocto Project Concepts Manual for
+ details on how to use these variables.
+
If you build as you normally would, without
specifying any recipes in the
- LICENSE_FLAGS_WHITELIST, the build stops and
- provides you with the list of recipes that you have
- tried to include in the image that need entries in
- the LICENSE_FLAGS_WHITELIST.
- Once you enter the appropriate license flags into the whitelist,
- restart the build to continue where it left off.
+ LICENSE_FLAGS_WHITELIST, the
+ build stops and provides you with the list of recipes
+ that you have tried to include in the image that
+ need entries in the
+ LICENSE_FLAGS_WHITELIST.
+ Once you enter the appropriate license flags into
+ the whitelist, restart the build to continue where
+ it left off.
During the build, the prompt will not appear again
since you have satisfied the requirement.
- Once the appropriate license flags are on the white list
- in the LICENSE_FLAGS_WHITELIST variable, you
- can build the encumbered image with no change at all
- to the normal build process.
- Get a pre-built version of the BSP:
- You can get this type of BSP by visiting the
- "Downloads" page of the
+
+ Once the appropriate license flags are on the
+ white list in the
+ LICENSE_FLAGS_WHITELIST variable,
+ you can build the encumbered image with no change
+ at all to the normal build process.
+
+
+ Get a Pre-Built Version of the BSP:
+ You can get this type of BSP by selecting the
+ "DOWNLOADS" item from the "SOFTWARE" tab on the
Yocto Project website.
- You can download BSP tarballs that contain proprietary components
- after agreeing to the licensing
- requirements of each of the individually encumbered
- packages as part of the download process.
- Obtaining the BSP this way allows you to access an encumbered
- image immediately after agreeing to the
+ You can download BSP tarballs that contain
+ proprietary components after agreeing to the
+ licensing requirements of each of the individually
+ encumbered packages as part of the download process.
+ Obtaining the BSP this way allows you to access an
+ encumbered image immediately after agreeing to the
click-through license agreements presented by the
website.
- Note that if you want to build the image
- yourself using the recipes contained within the BSP
- tarball, you will still need to create an
- appropriate LICENSE_FLAGS_WHITELIST to match the
- encumbered recipes in the BSP.
+ If you want to build the image yourself using
+ the recipes contained within the BSP tarball,
+ you will still need to create an appropriate
+ LICENSE_FLAGS_WHITELIST
+ to match the encumbered recipes in the BSP.
+
+
+ Pre-compiled images are bundled with a time-limited
+ kernel that runs for a predetermined amount of time
+ (10 days) before it forces the system to reboot.
+ This limitation is meant to discourage direct
+ redistribution of the image.
+ You must eventually rebuild the image if you want
+ to remove this restriction.
+
-
-
- Pre-compiled images are bundled with
- a time-limited kernel that runs for a
- predetermined amount of time (10 days) before it forces
- the system to reboot.
- This limitation is meant to discourage direct redistribution
- of the image.
- You must eventually rebuild the image if you want to remove this restriction.
-