diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index a2453326d9..1b5f0f5b2a 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -75,7 +75,7 @@ Some layers function as a layer to hold other BSP layers. - An example of this type of layers is the meta-intel layer. + An example of this type of layer is the meta-intel layer. The meta-intel layer contains over 10 individual BSP layers. @@ -121,6 +121,15 @@ are separate components that happen to be combined in certain end products. + + 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 + "Released BSP Requirements" + section. + + 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 @@ -644,6 +653,193 @@ +
+ Requirements and Recommendations for Released BSPs + + + Certain requirements exist for a released BSP to be considered + compliant with the Yocto Project. + Additionally, a single recommendation also exists. + This section describes the requirements and recommendation for + released BSPs. + + +
+ Released BSP Requirements + + + Before looking at BSP requirements, you should consider the following: + + The requirements here assume the base Yocto Project requirements + for the BSP layer are already met. + For example, requirements for working with the + oe-core and standard toolchain layers. + The requirements in this section apply regardless of how you + ultimately package a BSP. + You should consult the packaging and distribution guidelines for your + specific release process. + For an example of packaging and distribution requirements, see the + Third + Party BSP Release Process wiki page. + The requirements for the BSP as it is made available to a developer + are completely independent of the released form of the BSP. + For example, the BSP metadata can be contained within a Git repository + and could have a directory structure completely different from what appears + in the officially released BSP layer. + No requirement stipulates that specific packages or package + modifications exist in the BSP layer, beyond the requirements for general + compliance with the Yocto Project. + For example, no requirement exists dictating that a specific kernel or + kernel version be used in a given BSP. + + + + + Following are the requirements for a released BSP that conforms to the + Yocto Project: + + Layer Name: + The BSP must have a layer name that follows the Yocto + Project standards. + For information on BSP layer names, see the + "BSP Layers" section. + + File System Layout: + In general, the filesystem layout for the BSP layer + should use the same directory names + as listed in recipes.txt. + You can find recipes.txt in the + meta directory of the + Yocto + Project Files, or in the OpenEmbedded Core Layer + (openembedded-core) found at + . + + In particular, you should place recipes + (.bb files) and recipe + modifications (.bbappend files) into + recipes-* subdirectories by functional area + as outlined in recipes.txt. + If none of the categories fits a particular recipe, you can + make up your own recipe-* subdirectory. + Within any particular recipes-* category, the layout + should match what is found in the OpenEmbedded Core + Git repository (openembedded-core) + or the Yocto Project Files (poky). + In other words, make sure you place related files in appropriately + related recipes-* subdirectories specific to the + recipe's function, or within a subdirectory containing a set of closely-related + recipes. + The recipes themselves should follow the general guidelines + for recipes used in the Yocto Project found in the + Yocto + Recipe and Patch Style Guide. + License File: + You must include a license file in the + meta-<bsp_name> directory. + This license covers the BSP metadata as a whole. + You must specify which license to use since there is no + default license if one is not specified. + README File: + You must include a README file in the + meta-<bsp_name> directory. + At a minimum, the README file should + contain the following: + + A brief description about the hardware the BSP + targets. + A list of all the dependencies a + on which a BSP layer depends. + These dependencies are typically a list of required layers needed + to build the BSP. + However, the dependencies should also contain information regarding + any other dependencies the BSP might have. + Any required special licensing information. + For example, this information includes information on + special variables needed to satisfy a EULA, + or instructions on information needed to build or distribute + binaries built from the BSP metadata. + The name and contact information for the + BSP layer maintainer. + This is the person to whom patches and questions should + be sent. + Instructions on how to build the BSP using the BSP + layer. + Instructions on how to boot the BSP build from + the BSP layer. + Instructions on how to boot the binary images + contained in the /binary directory, + if present. + Information on any known bugs or issues that users + should know about when either building or booting the BSP + binaries. + + README.sources File: + You must include a README.sources in the + meta-<bsp_name> directory. + This file specifies exactly where you can find the sources used to + generate the binary images contained in the + /binary directory, if present. + Layer Configuration File: + You must include a conf/layer.conf in the + meta-<bsp_name> directory. + This file identifies the meta-<bsp_name> + BSP layer as a layer to the build system. + Machine Configuration File: + You must include a conf/machine/<bsp_name>.conf + in the meta-<bsp_name> directory. + This configuration file defines a machine target that can be built + using the BSP layer. + Multiple machine configuration files define variations of machine + configurations that are supported by the BSP. + If a BSP supports more multiple machine variations, you need to + adequately describe each variation in the BSP + README file. + Do not use multiple machine configuration files to describe disparate + hardware. + Multiple machine configuration files should describe very similar targets. + If you do have very different targets, you should create a separate + BSP. + It is completely possible for a developer to structure the + working repository as a conglomeration of unrelated BSP + files, and to possibly generate specifically targeted 'release' BSPs + from that directory using scripts or some other mechanism. + Such considerations are outside the scope of this document. + + + +
+ +
+ Released BSP Recommendations + + + One recommendation for BSP releases is that they 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. + +
+
+
Customizing a Recipe for a BSP @@ -760,7 +956,7 @@ 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 whitelisted + 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. @@ -931,7 +1127,7 @@ Now that you know where these two commands reside and how to access information on them, you should find it relatively straightforward to discover the commands - necessary to create a BSP and perform basic kernel maintainence on that BSP using + necessary to create a BSP and perform basic kernel maintenance on that BSP using the tools. The next sections provide a concrete starting point to expand on a few points that might not be immediately obvious or that could use further explanation. @@ -990,7 +1186,7 @@ In every other way, this architecture is representative of how creating a BSP for a 'real' machine would work. The reason the example uses this architecture is because it is an emulated architecture - and can easily be followed without requireing actual hardware. + and can easily be followed without requiring actual hardware. @@ -1059,7 +1255,7 @@ If you enter 'n', the script prompts you to further enter the kernel you do want to use (e.g. 3.0, 3.2_preempt-rt, etc.). Next, the script asks whether you would like to have a new - branch created especially for your BSPin the local + branch created especially for your BSP in the local Linux Yocto Kernel Git repository . If not, then the script re-uses an existing branch.