diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index 45905f8b6b..72b065dad3 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -1171,175 +1171,251 @@ Requirements and Recommendations for Released BSPs - Certain requirements exist for a released BSP to be considered - compliant with the Yocto Project. + Certain requirements exist for a released BSP to be + considered compliant with the Yocto Project. Additionally, recommendations also exist. - This section describes the requirements and recommendations for - released BSPs. + This section describes the requirements and + recommendations for released BSPs.
Released BSP Requirements - Before looking at BSP requirements, you should consider the following: + Before looking at BSP requirements, you should consider + the following: - The requirements here assume the BSP layer is a well-formed, "legal" - layer that can be added to the Yocto Project. - For guidelines on creating a layer that meets these base requirements, see the - "BSP Layers" and the - "Understanding - and Creating Layers" in the Yocto Project Development Tasks Manual. + + The requirements here assume the BSP layer + is a well-formed, "legal" layer that can be + added to the Yocto Project. + For guidelines on creating a layer that meets + these base requirements, see the + "BSP Layers" + section in this manual and the + "Understanding and Creating Layers"" + section in the Yocto Project Development Tasks + Manual. - The requirements in this section apply regardless of how you - 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 + + The requirements in this section apply + regardless of how you 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 + + 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. - It is not required that specific packages or package - modifications exist in the BSP layer, beyond the requirements for general + + It is not required 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. + 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 conform to the - Yocto Project: + Following are the requirements for a released BSP + that conform to the Yocto Project: - Layer Name: - The BSP must have a layer name that follows the Yocto - Project standards. + + 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: - When possible, use the same directory names in your - BSP layer as listed in the recipes.txt file. - 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 you cannot find a category in recipes.txt - to fit a particular recipe, you can make up your own - recipes-* subdirectory. - You can find recipes.txt in the - meta directory of the - Source Directory, + + File System Layout: + When possible, use the same directory names + in your BSP layer as listed in the + recipes.txt file, which + is found in poky/meta + directory of the + Source Directory or in the OpenEmbedded Core Layer - (openembedded-core) found at + (openembedded-core) at . - Within any particular recipes-* category, the layout - should match what is found in the OpenEmbedded Core - Git repository (openembedded-core) + + You should place recipes + (*.bb files) and recipe + modifications (*.bbappend + files) into recipes-* + subdirectories by functional area as outlined + in recipes.txt. + If you cannot find a category in + recipes.txt to fit a + particular recipe, you can make up your own + recipes-* subdirectory. + + + Within any particular + recipes-* category, the + layout should match what is found in the + OpenEmbedded Core Git repository + (openembedded-core) or the Source Directory (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 + 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 + The recipes themselves should follow the general + guidelines for recipes used in the Yocto Project + found in the "OpenEmbedded Style Guide". - License File: + + License File: You must include a license file in the - meta-bsp_name directory. + 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. + You must specify which license to use since no + default license exists when one not specified. See the COPYING.MIT file for the Raspberry Pi BSP in the - meta-raspberrypi BSP layer as an example. + meta-raspberrypi BSP layer + as an example. - README File: - You must include a README file in the - meta-bsp_name directory. + + README File: + You must include a README + file in the + meta-bsp_name + directory. See the README - file for the Raspberry Pi BSP in the meta-raspberrypi BSP layer + file for the Raspberry Pi BSP in the + meta-raspberrypi BSP layer as an example. - At a minimum, the README file should - contain the following: + + 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 - 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. - For information on how to find the right person, see the - "Submitting a Change to the Yocto Project" - section in the Yocto Project Development Tasks Manual. + + A brief description about the hardware the BSP + targets. - 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. + + A list of all the dependencies + 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. + For information on how to find the right + person, see the + "Submitting a Change to the Yocto Project" + section in the Yocto Project Development + Tasks Manual. + + + 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. + + - 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: + + README.sources File: + If you BSP contains binary images in the + binary directory, you must + include a README.sources + file in the + meta-bsp_name + directory. + This file specifies exactly where you can find + the sources used to generate the binary images. + + + Layer Configuration File: + You must include a + conf/layer.conf file 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 one or more - conf/machine/bsp_name.conf - files in the meta-bsp_name directory. - These configuration files define machine targets 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 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. - If you do have very different targets, you should create separate - BSP layers for each target. - It is completely possible for a developer to structure the - working repository as a conglomeration of unrelated BSP - files, and to possibly generate BSPs targeted for release - from that directory using scripts or some other mechanism - (e.g. meta-yocto-bsp layer). - Such considerations are outside the scope of this document. + conf/machine/bsp_name.conf + files in the + meta-bsp_name + directory. + These configuration files define machine targets + that can be built using the BSP layer. + Multiple machine configuration files define + variations of machine configurations that the + BSP supports. + If a BSP supports 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. + If you do have very different targets, you should + create separate BSP layers for each target. + + It is completely possible for a developer to + structure the working repository as a + conglomeration of unrelated BSP files, and to + possibly generate BSPs targeted for release + from that directory using scripts or some + other mechanism + (e.g. meta-yocto-bsp layer). + Such considerations are outside the scope of + this document. +