From 31d594802f4b3fb18ee64bc23427c9af8468b724 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 18 Aug 2011 16:00:16 -0700 Subject: documentation/bsp-guide/bsp.xml: General updates I added a parallel textual construct at the beginning of each section that details a directory in the Yocto Project file's structure. I did not like starting these sections with a literallayout string. (From yocto-docs rev: 5dde476f0c02d655217f3fa863522e8b7df57cda) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/bsp-guide/bsp.xml | 388 ++++++++++++++++------------------------ 1 file changed, 159 insertions(+), 229 deletions(-) (limited to 'documentation') diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index c7f9f87d4b..492a7956d2 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -3,7 +3,7 @@ - Board Support Packages (BSP) - Developers Guide + Board Support Packages (BSP) - Developer's Guide A Board Support Package (BSP) is a collection of information that @@ -27,12 +27,12 @@ of software support of hardware. - + The information here does not provide an example of how to create a BSP. For information on how to create a BSP, see the Yocto Project Development Manual or the wiki page. - + The proposed format does have elements that are specific to the Yocto Project and @@ -81,8 +81,11 @@ The base directory (meta-<bsp_name>) is the root of the BSP layer. - This root is what you add to the BBLAYERS variable in build/conf/bblayers.conf - so that the build system recognizes the BSP definition and from it can build an image. + This root is what you add to the BBLAYERS + variable in the build/conf/bblayers.conf file found in the + Yocto Project file's build directory. + Adding the root allows the Yocto Project build system to recognize the BSP + definition and from it build an image. Here is an example: BBLAYERS = " \ @@ -94,6 +97,9 @@ For more detailed information on layers, see the BitBake Layers section of the Yocto Project Reference Manual. + You can also see the detailed examples in the appendices of + + The Yocto Project Development Manual. @@ -101,41 +107,41 @@ While you can use this basic form for the standard, realize that the actual structures for specific BSPs could differ. - -meta-<bsp_name>/ -meta-<bsp_name>/<bsp_license_file> -meta-<bsp_name>/README -meta-<bsp_name>/binary/<bootable_images> -meta-<bsp_name>/conf/layer.conf -meta-<bsp_name>/conf/machine/*.conf -meta-<bsp_name>/recipes-bsp/* -meta-<bsp_name>/recipes-graphics/* -meta-<bsp_name>/recipes-kernel/linux/linux-yocto_git.bbappend - - - - - Below is an example of the crownbay BSP: - - -meta-crownbay/COPYING.MIT -meta-crownbay/README -meta-crownbay/binary/.gitignore -meta-crownbay/conf/layer.conf -meta-crownbay/conf/machine/crownbay.conf -meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig -meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xcorg.conf -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin/.gitignore -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin_1.7.99.2.bb -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/crosscompile.patch -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/fix_open_max_preprocessor_error.patch -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/macro_tweak.patch -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/nodolt.patch -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd_1.7.99.2.bb -meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend - + + meta-<bsp_name>/ + meta-<bsp_name>/<bsp_license_file> + meta-<bsp_name>/README + meta-<bsp_name>/binary/<bootable_images> + meta-<bsp_name>/conf/layer.conf + meta-<bsp_name>/conf/machine/*.conf + meta-<bsp_name>/recipes-bsp/* + meta-<bsp_name>/recipes-graphics/* + meta-<bsp_name>/recipes-kernel/linux/linux-yocto_git.bbappend + + + + + Below is an example of the Crownbay BSP: + + + meta-crownbay/COPYING.MIT + meta-crownbay/README + meta-crownbay/binary/.gitignore + meta-crownbay/conf/layer.conf + meta-crownbay/conf/machine/crownbay.conf + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig + meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xcorg.conf + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin/.gitignore + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin_1.7.99.2.bb + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/crosscompile.patch + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/fix_open_max_preprocessor_error.patch + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/macro_tweak.patch + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/nodolt.patch + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd_1.7.99.2.bb + meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend + @@ -144,14 +150,18 @@ meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend
License Files - -meta-<bsp_name>/<bsp_license_file> - + + + You can find these files in the Yocto Project file's directory structure at: + + meta-<bsp_name>/<bsp_license_file> + + These optional files satisfy licensing requirements for the BSP. The type or types of files here can vary depending on the licensing requirements. - For example, in the crownbay BSP all licensing requirements are handled with the + For example, in the Crownbay BSP all licensing requirements are handled with the COPYING.MIT file. @@ -163,9 +173,12 @@ meta-<bsp_name>/<bsp_license_file>
README File - -meta-<bsp_name>/README - + + You can find these files in the Yocto Project file's directory structure at: + + meta-<bsp_name>/README + + This file provides information on how to boot the live images that are optionally @@ -182,9 +195,12 @@ meta-<bsp_name>/README
Pre-built User Binaries - -meta-<bsp_name>/binary/<bootable_images> - + + You can find these files in the Yocto Project file's directory structure at: + + meta-<bsp_name>/binary/<bootable_images> + + This optional area contains useful pre-built kernels and user-space filesystem @@ -206,9 +222,12 @@ meta-<bsp_name>/binary/<bootable_images>
Layer Configuration File - -meta-<bsp_name>/conf/layer.conf - + + You can find these files in the Yocto Project file's directory structure at: + + meta-<bsp_name>/conf/layer.conf + + This file identifies the structure as a Yocto Project layer, identifies the @@ -219,18 +238,18 @@ meta-<bsp_name>/conf/layer.conf - -# We have a conf directory, add to BBPATH -BBPATH := "${BBPATH}:${LAYERDIR}" + + # We have a conf directory, add to BBPATH + BBPATH := "${BBPATH}:${LAYERDIR}" -# We have a recipes directory containing .bb and .bbappend files, add to BBFILES -BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ - ${LAYERDIR}/recipes/*/*.bbappend" + # We have a recipes directory containing .bb and .bbappend files, add to BBFILES + BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ + ${LAYERDIR}/recipes/*/*.bbappend" -BBFILE_COLLECTIONS += "bsp" -BBFILE_PATTERN_bsp := "^${LAYERDIR}/" -BBFILE_PRIORITY_bsp = "5" - + BBFILE_COLLECTIONS += "bsp" + BBFILE_PATTERN_bsp := "^${LAYERDIR}/" + BBFILE_PRIORITY_bsp = "5" + @@ -241,9 +260,12 @@ BBFILE_PRIORITY_bsp = "5"
Hardware Configuration Options - -meta-<bsp_name>/conf/machine/*.conf - + + You can find these files in the Yocto Project file's directory structure at: + + meta-<bsp_name>/conf/machine/*.conf + + The machine files bind together all the information contained elsewhere @@ -272,10 +294,10 @@ meta-<bsp_name>/conf/machine/*.conf An example is tune-atom.inc: - -BASE_PACKAGE_ARCH = "core2" -TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" - + + BASE_PACKAGE_ARCH = "core2" + TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" + This example defines a new package architecture called "core2" and uses the @@ -294,19 +316,22 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
Miscellaneous Recipe Files - -meta-<bsp_name>/recipes-bsp/* - + + You can find these files in the Yocto Project file's directory structure at: + + meta-<bsp_name>/recipes-bsp/* + + This optional directory contains miscellaneous recipe files for the BSP. Most notably would be the formfactor files. - For example, in the crownbay BSP there is a machconfig file and a + For example, in the Crownbay BSP there is a machconfig file and a formfactor_0.0.bbappend file: - -meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig -meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend - + + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig + meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend + @@ -317,34 +342,40 @@ meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
Display Support Files - -meta-<bsp_name>/recipes-graphics/* - + + You can find these files in the Yocto Project file's directory structure at: + + meta-<bsp_name>/recipes-graphics/* + + This optional directory contains recipes for the BSP if it has special requirements for graphics support. All files that are needed for the BSP to support a display are kept here. - For example, in the crownbay BSP several display support files exist: - -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xcorg.conf -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin/.gitignore -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin_1.7.99.2.bb -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/crosscompile.patch -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/fix_open_max_preprocessor_error.patch -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/macro_tweak.patch -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/nodolt.patch -meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd_1.7.99.2.bb - + For example, in the Crownbay BSP several display support files exist: + + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xcorg.conf + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin/.gitignore + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin_1.7.99.2.bb + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/crosscompile.patch + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/fix_open_max_preprocessor_error.patch + eta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/macro_tweak.patch + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/nodolt.patch + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd_1.7.99.2.bb +
Linux Kernel Configuration - -meta-<bsp_name>/recipes-kernel/linux/linux-yocto_git.bbappend - + + You can find these files in the Yocto Project file's directory structure at: + + meta-<bsp_name>/recipes-kernel/linux/linux-yocto_git.bbappend + + This file appends your specific changes to the kernel you are using. @@ -362,25 +393,25 @@ meta-<bsp_name>/recipes-kernel/linux/linux-yocto_git.bbappend which is the preferred kernel to use for developing a new BSP using the Yocto Project. In other words, you have selected the kernel in your <bsp_name>.conf file by adding the following statement: - -PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" - + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + You would use the linux-yocto_git.bbappend file to append specific BSP settings to the kernel, thus configuring the kernel for your particular BSP. - Now take a look at the existing "crownbay" BSP. + Now take a look at the existing Crownbay BSP. The append file used is: - -meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend - + + meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend + The file contains the following: - -FILESEXTRAPATHS := "${THISDIR}/${PN}" -COMPATIBLE_MACHINE_crownbay = "crownbay" -KMACHINE_crownbay = "yocto/standard/crownbay" - - This append file adds "crownbay" as a compatible machine, + + FILESEXTRAPATHS := "${THISDIR}/${PN}" + COMPATIBLE_MACHINE_crownbay = "crownbay" + KMACHINE_crownbay = "yocto/standard/crownbay" + + This append file adds Crownbay as a compatible machine, and additionally sets a Yocto Kernel-specific variable that identifies the name of the BSP branch to use in the Git repository to find configuration information. @@ -402,9 +433,9 @@ KMACHINE_crownbay = "yocto/standard/crownbay" /linux-yocto and then added a SRC_URI statement such as the following to the append file, those configuration options will be picked up and applied when the kernel is built. - -SRC_URI += "file://defconfig" - + + SRC_URI += "file://defconfig" + As mentioned earlier, you can group related configurations into multiple files and @@ -412,18 +443,19 @@ SRC_URI += "file://defconfig" For example, you could group separate configurations specifically for Ethernet and graphics into their own files and add those by using a SRC_URI statement like the following in your append file: - -SRC_URI += "file://defconfig \ + + SRC_URI += "file://defconfig \ file://eth.cfg \ file://gfx.cfg" - + The FILESEXTRAPATHS variable is in boilerplate form here in order to make it easy to do that. It basically allows those configuration files to be found by the build process. - + + Other methods exist to accomplish grouping and defining configuration options. For example, you could directly add configuration options to the Yocto kernel meta branch for your BSP. @@ -432,116 +464,26 @@ SRC_URI += "file://defconfig \ For information on how to add these configurations directly, see the "Yocto Project Kernel Architecture and Use Manual" on the Yocto Project website - Documentation Page - - + Documentation Page + In general, however, the Yocto Project maintainers take care of moving the SRC_URI-specified configuration options to the meta branch. Not only is it easier for BSP developers to not have to worry about putting those configurations in the branch, but having the maintainers do it allows them to apply 'global' knowledge about the kinds of common configuration options multiple BSPs in the tree are typically using. - This allows for promotion of common configurations into common features. - -
- -
BSP 'Click-Through' Licensing Procedure - This section describes how + This section describes how click-through licensing is expected to work. Currently, this functionality is not yet implemented. - + In some cases, a BSP contains separately licensed IP @@ -595,19 +537,6 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}" through a web form. - - After agreeing to any applicable license terms, the BSP key(s) will be immediately sent to the address @@ -615,9 +544,9 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}" environment variables when building the image: - - $ BSPKEY_<keydomain>=<key> bitbake core-image-sato - + + $ BSPKEY_<keydomain>=<key> bitbake core-image-sato + These steps allow the encumbered image to be built @@ -627,7 +556,8 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}" Equivalently and probably more conveniently, a line for each key can instead be put into the user's - local.conf file. + local.conf file found in the Yocto Project file's + build directory. -- cgit v1.2.3-54-g00ecf