diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index f9455ed861..24bbeb6628 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -1746,25 +1746,20 @@ Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script - [INTRODUCE THE PROCEDURE AND LINK BACK TO BSP layer. - IF THERE IS A LAUNDRY LIST OF ITEMS THAT NEED DEFINITION OR GET SET - UP AS A RESULT OF THIS PROCEDURE, LIST THEM HERE.] - - [PARAMETER 1] - [PARAMETER 2] - [PARAMETER 3] - [PARAMETER 4] - [PARAMETER 5] - [PARAMETER 6] - [PARAMETER 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 + configuration file. + Additionally, a BSP layer usually has a kernel recipe + or an append file that leverages off an existing kernel recipe. + The primary requirement, however, is the machine configuration. - The following procedure creates a BSP layer: + Use these steps to create a BSP layer: - Create General Layer: + Create a General Layer: Use the bitbake-layers script with the create-layer subcommand to create a new general layer. @@ -1774,25 +1769,41 @@ section in the Yocto Project Development Tasks Manual. - Create a Machine Configuration File: - Create a conf/machine/>machine<.conf + Create a Layer Configuration File: + Every layer needs a layer configuration file. + This configuration file establishes locations for the + layer's recipes, priorities for the layer, and so forth. + You can find examples of layer.conf + files in the Yocto Project + Source Repositories. + To get examples of what you need in your configuration + file, locate a layer (e.g. "meta-ti") and examine the + file. - See meta-yocto-bsp/conf/machine for sample - >machine.conf< files. - Other samples exist from other vendors such as - meta-intel, meta-ti, - and meta-freescale that have more specific machine + + + Create a Machine Configuration File: + Create a conf/machine/bsp_root_name.conf + file. + See + meta-yocto-bsp/conf/machine + for sample + bsp_root_name.conf + files. + Other samples such as + meta-ti + and + meta-freescale + exist from other vendors that have more specific machine and tuning examples. Create a Kernel Recipe: Create a kernel recipe in recipes-kernel/linux - either using a linux-yocto kernel with a .bbappend - file or a new custom kernel recipe file (i.e. .bb - file). + by either using a kernel append file or a new custom kernel + recipe file (e.g. yocto-linux_4.12.bb). The BSP layers mentioned in the previous step also contain different kernel examples. - You can start with the linux-yocto or use a custom kernel. See the "Modifying an Existing Recipe" section in the Yocto Project Linux Kernel Development Manual @@ -1802,43 +1813,462 @@ - [THERE IS MORE INFORMATION THAT NEEDS TO BE FILLED IN HERE. THIS NEEDS TO - BE PROVIDED BY ENGINEERS.] + The remainder of this section provides a description of + the Yocto Project reference BSP for Beaglebone, which + resides in the + Container Layer + (i.e. + meta-yocto-bsp). - - The remainder of this section presents an example that uses - myarm as the machine name and qemu - as the machine architecture. - Of the available architectures, qemu is the only architecture - that causes the script to prompt you further for an actual architecture. - In every other way, this architecture is representative of how creating a BSP for - an actual machine would work. - The reason the example uses this architecture is because it is an emulated architecture - and can easily be followed without requiring actual hardware. - +
+ BSP Layer Configuration Example - - Following is a complete example: - - [INSERT EXAMPLE - NEED EXAMPLE] - - + + The layer's conf directory + contains the layer.conf + configuration file. + In this example, the + conf/layer.conf is the + following: + + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" - - Once the BSP Layer is created, you must add it to your - bblayers.conf file. - Here is an example: - - BBLAYERS = ? " \ - /usr/local/src/yocto/meta \ - /usr/local/src/yocto/meta-poky \ - /usr/local/src/yocto/meta-yocto-bsp \ - /usr/local/src/yocto/meta-myarm \ - " - - Adding the layer to this file allows the build system to build the BSP and - find the layer along with other Metadata it needs. - + # We have recipes-* directories, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "yoctobsp" + BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" + BBFILE_PRIORITY_yoctobsp = "5" + LAYERVERSION_yoctobsp = "4" + LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;" + + The variables used in this file configure the + layer. + A good way to learn about layer configuration + files is to examine various files for BSP from + the + Source Repositories. + + + + For a detailed description of this particular + layer configuration file, see + "step 3 + in the discussion that describes how to create + layers in the Yocto Project Development Tasks Manual. + +
+ +
+ BSP Machine Configuration Example + + + As mentioned earlier in this section, the existence + of a machine configuration file is what makes a + layer a BSP layer as compared to a general or + kernel layer. + + + + Machine configuration files exist in the + bsp_layer/conf/machine/ + directory of the layer: + + bsp_layer/conf/machine/machine.conf + + For example, the machine configuration file for the + BeagleBone and BeagleBone Black development boards + is located in the container layer + poky/meta-yocto-bsp/conf/machine + and is named beaglebone-yocto.conf: + + #@TYPE: Machine + #@NAME: Beaglebone-yocto machine + #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards + + PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg" + XSERVER ?= "xserver-xorg \ + xf86-video-modesetting \ + " + + MACHINE_EXTRA_RRECOMMENDS = " kernel-modules kernel-devicetree" + + EXTRA_IMAGEDEPENDS += "u-boot" + + DEFAULTTUNE ?= "cortexa8hf-neon" + include conf/machine/include/tune-cortexa8.inc + + IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap" + EXTRA_IMAGECMD_jffs2 = "-lnp " + WKS_FILE ?= "beaglebone-yocto.wks" + IMAGE_INSTALL_append = " kernel-devicetree kernel-image-zimage" + do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot" + + SERIAL_CONSOLE = "115200 ttyO0" + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "4.12%" + + KERNEL_IMAGETYPE = "zImage" + KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" + KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}" + + SPL_BINARY = "MLO" + UBOOT_SUFFIX = "img" + UBOOT_MACHINE = "am335x_boneblack_config" + UBOOT_ENTRYPOINT = "0x80008000" + UBOOT_LOADADDRESS = "0x80008000" + + MACHINE_FEATURES = "usbgadget usbhost vfat alsa" + + IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO" + + The variables used to configure the machine define + machine-specific properties. + For example, machine-dependent packages, machine + tunings, the type of kernel to build, and + U-Boot configurations. + + + + The following list provides some explanation + for the statements found in the example reference + machine configuration file for the BeagleBone + development boards. + Realize that much more can be defined as part of + a machines configuration file. + In general, you can learn about related variables + that this example does not have by locating the + variables in the + "Yocto Project Variables Glossary" + in the Yocto Project Reference Manual. + + + PREFERRED_PROVIDER_virtual/xserver: + The recipe that provides "virtual/xserver" when + more than one provider is found. + In this case, the recipe that provides + "virtual/xserver" is "xserver-xorg", which + exists in + poky/meta/recipes-graphics/xserver-xorg. + + + XSERVER: + The packages that should be installed to provide + an X server and drivers for the machine. + In this example, the "xserver-xorg" and + "xf86-video-modesetting" are installed. + + + MACHINE_EXTRA_RRECOMMENDS: + A list of machine-dependent packages + not essential for booting the image. + Thus, the build does not fail if the packages + do not exist. + However, the packages are required for a + fully-featured image. + Tip + Many MACHINE* variables + exist that help you configure a particular + piece of hardware. + + + + EXTRA_IMAGEDEPENDS: + Recipes to build that do not provide packages + for installing into the root filesystem + but building the image depends on the + recipes. + Sometimes a recipe is required to build + the final image but is not needed in the + root filesystem. + In this case, the U-Boot recipe must be + built for the image. + + + DEFAULTTUNE: + Machines use tunings to optimize machine, + CPU, and application performance. + These features, which are collectively known + as "tuning features", exist in the + OpenEmbedded Core (OE-Core) + layer (e.g. + poky/meta/conf/machine/include). + In this example, the default tunning file is + "cortexa8hf-neon". + + The include statement + that pulls in the + conf/machine/include/tune-cortexa8.inc + file provides many tuning possibilities. + + + + IMAGE_FSTYPES: + The formats the OpenEmbedded build system + uses during the build when creating the + root filesystem. + In this example, four types of images are + supported. + + + EXTRA_IMAGECMD: + Specifies additional options for image + creation commands. + In this example, the "-lnp " option is used + when creating the + JFFS2 + image. + + + WKS_FILE: + The location of the + Wic kickstart + file used by the OpenEmbedded build system to + create a partitioned image (image.wic). + + + IMAGE_INSTALL: + Specifies packages to install into an image + through the + image + class. + Recipes use the IMAGE_INSTALL + variable. + + + do_image_wic[depends]: + A task that is constructed during the build. + In this example, the task depends on specific tools + in order to create the sysroot when buiding a Wic + image. + + + SERIAL_CONSOLE: + Defines a serial console (TTY) to enable using + getty. + In this case, the baud rate is "115200" and the + device name is "ttyO0". + + + PREFERRED_PROVIDER_virtual/kernel: + Specifies the recipe that provides + "virtual/kernel" when more than one provider + is found. + In this case, the recipe that provides + "virtual/kernel" is "linux-yocto", which + exists in the layer's + recipes-kernel/linux directory. + + + PREFERRED_VERSION_linux-yocto: + Defines the version of the recipe used + to build the kernel, which is "4.12" in this + case. + + + KERNEL_IMAGETYPE: + The type of kernel to build for the device. + In this case, the OpenEmbedded build system + creates a "zImage" image type. + + + KERNEL_DEVICETREE: + The name of the generated Linux kernel device + tree (i.e. the .dtb) file. + All the device trees for the various BeagleBone + devices are included. + + + + KERNEL_EXTRA_ARGS: + Additional make + command-line arguments the OpenEmbedded build + system passes on when compiling the kernel. + In this example, "LOADADDR=${UBOOT_ENTRYPOINT}" + is passed as a command-line argument. + + + SPL_BINARY: + Defines the Secondary Program Loader (SPL) binary + type. + In this case, the SPL binary is set to + "MLO", which stands for Multimedia card LOader. + + + The BeagleBone development board requires a + MLO file in order to boot. + Consequently, the machine configuration needs to + define the SPL as an MLO type file and use it + as the Xloader. + + For more information on how the SPL variables + are used, see the + u-boot.inc + include file. + + + + + UBOOT_*: + Defines various U-Boot configurations needed + to build a U-Boot image. + In this example, a U-Boot image is required + to boot the BeagleBone device. + See the following variables for more information: + + + UBOOT_SUFFIX: + Points to the generated U-Boot extension. + + + UBOOT_MACHINE: + Specifies the value passed on the make command line when building a U-Boot image. + + + UBOOT_ENTRYPOINT: + Specifies the entry point for the U-Boot image. + + + UBOOT_LOADADDRESS: + Specifies the load address for the U-Boot image. + + + + + MACHINE_FEATURES: + Specifies the list of hardware features the + BeagleBone device is capable of supporting. + In this case, the device supports + "usbgadget usbhost vfat alsa". + + + IMAGE_BOOT_FILES: + Files installed into the device's boot partition + when preparing the image using the Wic tool + with the bootimg-partition + source plugin. + In this case, the "u-boot.${UBOOT_SUFFIX}" and + "MLO" files are installed. + + + +
+ +
+ BSP Kernel Recipe Example + + + The kernel recipe used to build the kernel image + for the BeagleBone device was established in the + machine configuration: + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "4.12%" + + The meta-yocto-bsp/recipes-kernel/linux + directory in the layer contains metadata used + to build the kernel. + In this case, a kernel append file is used to + override an established kernel recipe, which is + located in + + and named + linux-yocto_4.12.bb. + + + + Following is the contents of the append file: + + KBRANCH_genericx86 = "standard/base" + KBRANCH_genericx86-64 = "standard/base" + + KMACHINE_genericx86 ?= "common-pc" + KMACHINE_genericx86-64 ?= "common-pc-64" + KBRANCH_edgerouter = "standard/edgerouter" + KBRANCH_beaglebone-yocto = "standard/beaglebone" + KMACHINE_beaglebone-yocto = "beaglebone" + KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb" + + SRCREV_machine_genericx86 ?= "1c4ad569af3e23a77994235435040e322908687f" + SRCREV_machine_genericx86-64 ?= "1c4ad569af3e23a77994235435040e322908687f" + SRCREV_machine_edgerouter ?= "257f843ea367744620f1d92910afd2f454e31483" + SRCREV_machine_beaglebone-yocto ?= "257f843ea367744620f1d92910afd2f454e31483" + SRCREV_machine_mpc8315e-rdb ?= "014560874f9eb2a86138c9cc35046ff1720485e1" + + + COMPATIBLE_MACHINE_genericx86 = "genericx86" + COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" + COMPATIBLE_MACHINE_edgerouter = "edgerouter" + COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto" + COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb" + + LINUX_VERSION_genericx86 = "4.12.20" + LINUX_VERSION_genericx86-64 = "4.12.20" + LINUX_VERSION_edgerouter = "4.12.19" + LINUX_VERSION_beaglebone-yocto = "4.12.19" + LINUX_VERSION_mpc8315e-rdb = "4.12.19" + + This particular append file works for all the + machines that are part of the + meta-yocto-bsp container + layer. + The relevant statements are appended with + the "beaglebone-yocto" string. + The OpenEmbedded build system uses these + statements to override similar statements + in the kernel recipe: + + + KBRANCH: + Identifies the kernel branch that is validated, + patched, and configured during the build. + + + KMACHINE: + Identifies the machine name as known by the + kernel, which is sometimes a different name + than what is known by the OpenEmbedded build + system. + + + SRCREV: + Identifies the revision of the source code used + to build the image. + + + + COMPATIBLE_MACHINE: + A regular expression that resolves to one or + more target machines with which the recipe + is compatible. + + + LINUX_VERSION: + The Linux version from kernel.org used by + the OpenEmbedded build system to build the + kernel image. + + + +