From d4a3a121ed17f0a80ad4336bc0461927cd79bfe6 Mon Sep 17 00:00:00 2001 From: "rpjday@crashcourse.ca" Date: Sun, 23 Feb 2020 16:56:42 -0500 Subject: BSP Guide: numerous tweaks/grammar/wording/clarification (From yocto-docs rev: 3a87e5900b603f124ce7f63fd072415762f63212) Signed-off-by: Robert P. J. Day Signed-off-by: Richard Purdie --- documentation/bsp-guide/bsp.xml | 89 ++++++++++++++++++++++++----------------- 1 file changed, 52 insertions(+), 37 deletions(-) diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index e76dd57e77..96c0455f67 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -19,7 +19,7 @@ - This guide presents information about BSP Layers, defines a structure for components + This guide presents information about BSP layers, defines a structure for components so that BSPs follow a commonly understood layout, discusses how to customize a recipe for a BSP, addresses BSP licensing, and provides information that shows you how to create a @@ -34,7 +34,7 @@ A BSP consists of a file structure inside a base directory. Collectively, you can think of the base directory, its file structure, - and the contents as a BSP Layer. + and the contents as a BSP layer. Although not a strict requirement, BSP layers in the Yocto Project use the following well-established naming convention: @@ -69,9 +69,9 @@ Each repository is a BSP layer supported by the Yocto Project (e.g. meta-raspberrypi and meta-intel). - Each of these layers is a repository unto itself and clicking on a - layer reveals information that includes two links from which you can choose - to set up a clone of the layer's repository on your local host system. + Each of these layers is a repository unto itself and clicking on + the layer name displays two URLs from which you can + clone the layer's repository to your local system. Here is an example that clones the Raspberry Pi BSP layer: $ git clone git://git.yoctoproject.org/meta-raspberrypi @@ -83,12 +83,13 @@ meta-yocto-bsp layer is part of the shipped poky repository. The meta-yocto-bsp layer maintains several - BSPs such as the Beaglebone, EdgeRouter, and generic versions of + "reference" BSPs including the ARM-based Beaglebone, MIPS-based + EdgeRouter, and generic versions of both 32-bit and 64-bit IA machines. - For information on the BSP development workflow, see the + For information on typical BSP development workflow, see the "Developing a Board Support Package (BSP)" section. For more information on how to set up a local copy of source files @@ -98,12 +99,12 @@ - The layer's base directory + The BSP layer's base directory (meta-bsp_root_name) - is the root directory of the BSP Layer. + is the root directory of that Layer. This directory is what you add to the BBLAYERS - variable in the conf/bblayers.conf file found in the + variable in the conf/bblayers.conf file found in your Build Directory, which is established after you run the OpenEmbedded build environment setup script (i.e. @@ -153,6 +154,20 @@ layer. The meta-openembedded layer contains many meta-* layers. + In cases like this, you need to include the names of the actual + layers you want to work with, such as: + + BBLAYERS ?= " \ + /usr/local/src/yocto/meta \ + /usr/local/src/yocto/meta-poky \ + /usr/local/src/yocto/meta-yocto-bsp \ + /usr/local/src/yocto/meta-mylayer \ + .../meta-openembedded/meta-oe \ + .../meta-openembedded/meta-perl \ + .../meta-openembedded/meta-networking \ + " + + and so on. @@ -351,25 +366,24 @@ layer combined with a build system and other tools. Realize that it is important to maintain the distinction that the BSP layer, a build system, and tools are - separate components that could to be combined in + separate components that could 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 + Before looking at the recommended form for the directory structure + inside a BSP layer, you should be aware that some requirements do exist in order for a BSP layer to - be considered compliant with the Yocto Project. + 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. + Below is the typical directory structure for a BSP layer. While this basic form represents the standard, - realize that the actual file structures for specific + realize that the actual layout for individual BSPs could differ. meta-bsp_root_name/ @@ -567,7 +581,7 @@ for the BSP. The type or types of files here can vary depending on the licensing requirements. - For example, in the Raspberry Pi BSP all licensing + For example, in the Raspberry Pi BSP, all licensing requirements are handled with the COPYING.MIT file. @@ -802,7 +816,7 @@ Source Directory. For example, many tune-* files (e.g. tune-arm1136jf-s.inc, - tun-1586-nlp.inc, and so forth) + tune-1586-nlp.inc, and so forth) reside in the poky/meta/conf/machine/include directory. @@ -834,7 +848,7 @@ This optional directory contains miscellaneous recipe files for the BSP. Most notably would be the formfactor files. - For example, in the Raspberry Pi BSP there is the + For example, in the Raspberry Pi BSP, there is the formfactor_0.0.bbappend file, which is an append file used to augment the recipe that starts the build. @@ -901,7 +915,7 @@ The *.bb files would be a developer-supplied kernel recipe. This area of the BSP hierarchy can contain both these - types of files, although in practice, it is likely that + types of files although, in practice, it is likely that you would have one or the other. @@ -976,7 +990,7 @@ Developing a Board Support Package (BSP) - This section contains the high-level procedure you can + This section describes the high-level procedure you can follow to create a BSP. Although not required for BSP creation, the meta-intel repository, which @@ -1298,7 +1312,7 @@ (openembedded-core) or the Source Directory (poky). In other words, make sure you place related - files in appropriately related + files in appropriately-related recipes-* subdirectories specific to the recipe's function, or within a subdirectory containing a set of closely-related @@ -1315,7 +1329,7 @@ directory. This license covers the BSP Metadata as a whole. You must specify which license to use since no - default license exists when one not specified. + default license exists when one is not specified. See the COPYING.MIT file for the Raspberry Pi BSP in the @@ -1338,12 +1352,10 @@ file should contain the following: - A brief description about the hardware the BSP - targets. + A brief description of the target hardware. - A list of all the dependencies - on which a BSP layer depends. + A list of all the dependencies of the BSP. These dependencies are typically a list of required layers needed to build the BSP. @@ -1606,7 +1618,7 @@ BSP Licensing Considerations - In some cases, a BSP contains separately licensed + 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 @@ -1619,7 +1631,7 @@ - You could find that some separately licensed components + 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 @@ -1627,7 +1639,7 @@ 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 + 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 @@ -1740,7 +1752,7 @@ The bitbake-layers create-layer script automates creating a BSP layer. - What makes a layer a "BSP layer", is the presence of a machine + What makes a layer a "BSP layer" is the presence of at least one machine configuration file. Additionally, a BSP layer usually has a kernel recipe or an append file that leverages off an existing kernel recipe. @@ -1864,11 +1876,14 @@ - Machine configuration files exist in the + One or more machine configuration files exist in the bsp_layer/conf/machine/ directory of the layer: - bsp_layer/conf/machine/machine.conf + bsp_layer/conf/machine/machine1.conf + bsp_layer/conf/machine/machine2.conf + bsp_layer/conf/machine/machine3.conf + ... more ... For example, the machine configuration file for the BeagleBone and BeagleBone Black development boards @@ -1919,8 +1934,8 @@ IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" The variables used to configure the machine define - machine-specific properties. - For example, machine-dependent packages, machine + machine-specific properties; + for example, machine-dependent packages, machine tunings, the type of kernel to build, and U-Boot configurations. @@ -1931,7 +1946,7 @@ machine configuration file for the BeagleBone development boards. Realize that much more can be defined as part of - a machines configuration file. + a machine's configuration file. In general, you can learn about related variables that this example does not have by locating the variables in the -- cgit v1.2.3-54-g00ecf