From ed0d609c7c40ad638f634a5e1822ab3bcc4e6681 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 27 Mar 2017 09:17:08 -0700 Subject: bsp-guide, kernel-dev: Updates to how kernel metadata is found Fixes [YOCTO #10946] There was insufficient information in the combination of the BSP Guide and the Kernel Development Manual on just how to locate and use kernel metadata. * bsp-guide - Removed the detailed append file example for the kernel recipe. This is moved now to the chapter in the kernel manual that describes append files. * kernel-dev - Placed the example from the BSP Guide into the section that describes kernel append files. Cleaned up some terminology issues throughout chapter 3. Added information about how BitBake picks up kernel metadata when the metadata is in a hierarchical directory and not just a simple *.scc file. (From yocto-docs rev: 1048acb7127e77ca9c1f524a208fe25344fcb57c) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/bsp-guide/bsp.xml | 638 ++++++++++------------- documentation/kernel-dev/kernel-dev-advanced.xml | 390 ++++++++------ documentation/kernel-dev/kernel-dev-common.xml | 149 +++++- 3 files changed, 635 insertions(+), 542 deletions(-) (limited to 'documentation') diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index 4d0ace0484..cb9940c77a 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -352,135 +352,139 @@
- License Files + License Files - - You can find these files in the BSP Layer at: - + + You can find these files in the BSP Layer 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 Raspberry Pi BSP all licensing requirements are handled with the - COPYING.MIT 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 Raspberry Pi BSP all licensing requirements are handled with the + COPYING.MIT file. + - - Licensing files can be MIT, BSD, GPLv*, and so forth. - These files are recommended for the BSP but are optional and totally up to the BSP developer. - + + Licensing files can be MIT, BSD, GPLv*, and so forth. + These files are recommended for the BSP but are optional and totally up to the BSP developer. +
- README File - - You can find this file in the BSP Layer at: - + README File + + + You can find this file in the BSP Layer at: + meta-bsp_name/README - - + + - - This file provides information on how to boot the live images that are optionally - included in the binary/ directory. - The README file also provides special information needed for - building the image. - + + This file provides information on how to boot the live images that are optionally + included in the binary/ directory. + The README file also provides special information needed for + building the image. + - - At a minimum, the README file must - contain a list of dependencies, such as the names of - any other layers on which the BSP depends and the name of - the BSP maintainer with his or her contact information. - + + At a minimum, the README file must + contain a list of dependencies, such as the names of + any other layers on which the BSP depends and the name of + the BSP maintainer with his or her contact information. +
- README.sources File - - You can find this file in the BSP Layer at: - + README.sources File + + + You can find this file in the BSP Layer at: + meta-bsp_name/README.sources - - + + - - This file provides information on where to locate the BSP - source files used to build the images (if any) that reside in - meta-bsp_name/binary. - Images in the binary would be images - released with the BSP. - The information in the README.sources - file also helps you find the - Metadata - used to generate the images that ship with the BSP. - - If the BSP's binary directory is - missing or the directory has no images, an existing - README.sources file is - meaningless. - - + + This file provides information on where to locate the BSP + source files used to build the images (if any) that reside in + meta-bsp_name/binary. + Images in the binary would be images + released with the BSP. + The information in the README.sources + file also helps you find the + Metadata + used to generate the images that ship with the BSP. + + If the BSP's binary directory is + missing or the directory has no images, an existing + README.sources file is + meaningless. + +
- Pre-built User Binaries - - You can find these files in the BSP Layer at: - + Pre-built User Binaries + + + You can find these files in the BSP Layer at: + meta-bsp_name/binary/bootable_images - - + + - - This optional area contains useful pre-built kernels and - user-space filesystem images released with the BSP that are - appropriate to the target system. - This directory typically contains graphical (e.g. Sato) and - minimal live images when the BSP tarball has been created and - made available in the - Yocto Project website. - You can use these kernels and images to get a system running - and quickly get started on development tasks. - + + This optional area contains useful pre-built kernels and + user-space filesystem images released with the BSP that are + appropriate to the target system. + This directory typically contains graphical (e.g. Sato) and + minimal live images when the BSP tarball has been created and + made available in the + Yocto Project website. + You can use these kernels and images to get a system running + and quickly get started on development tasks. + - - The exact types of binaries present are highly - hardware-dependent. - The README file should be present in the - BSP Layer and it will explain how to use the images with the - target hardware. - Additionally, the README.sources file - should be present to locate the sources used to build the - images and provide information on the Metadata. - + + The exact types of binaries present are highly + hardware-dependent. + The README file should be present in the + BSP Layer and it will explain how to use the images with the + target hardware. + Additionally, the README.sources file + should be present to locate the sources used to build the + images and provide information on the Metadata. +
- Layer Configuration File - - You can find this file in the BSP Layer at: - + Layer Configuration File + + + You can find this file in the BSP Layer at: + meta-bsp_name/conf/layer.conf - - + + - - The conf/layer.conf file identifies the file structure as a - layer, identifies the - contents of the layer, and contains information about how the build - system should use it. - Generally, a standard boilerplate file such as the following works. - In the following example, you would replace "bsp" and - "_bsp" with the actual name - of the BSP (i.e. bsp_name from the example template). - + + The conf/layer.conf file identifies the file structure as a + layer, identifies the + contents of the layer, and contains information about how the build + system should use it. + Generally, a standard boilerplate file such as the following works. + In the following example, you would replace "bsp" and + "_bsp" with the actual name + of the BSP (i.e. bsp_name from the example template). + - - + + # We have a conf and classes directory, add to BBPATH BBPATH .= ":${LAYERDIR}" @@ -493,13 +497,13 @@ BBFILE_PRIORITY_bsp = "6" LAYERDEPENDS_bsp = "intel" - - + + - - To illustrate the string substitutions, here are the corresponding statements - from the Raspberry Pi conf/layer.conf file: - + + To illustrate the string substitutions, here are the corresponding statements + from the Raspberry Pi conf/layer.conf file: + # We have a conf and classes directory, append to BBPATH BBPATH .= ":${LAYERDIR}" @@ -513,316 +517,196 @@ # Additional license directories. LICENSE_PATH += "${LAYERDIR}/files/custom-licenses" - - + + - - This file simply makes - BitBake - aware of the recipes and configuration directories. - The file must exist so that the OpenEmbedded build system can recognize the BSP. - + + This file simply makes + BitBake + aware of the recipes and configuration directories. + The file must exist so that the OpenEmbedded build system can recognize the BSP. +
- Hardware Configuration Options - - You can find these files in the BSP Layer at: - + Hardware Configuration Options + + + You can find these files in the BSP Layer at: + meta-bsp_name/conf/machine/*.conf - - + + - - The machine files bind together all the information contained elsewhere - in the BSP into a format that the build system can understand. - If the BSP supports multiple machines, multiple machine configuration files - can be present. - These filenames correspond to the values to which users have set the - MACHINE variable. - + + The machine files bind together all the information contained elsewhere + in the BSP into a format that the build system can understand. + If the BSP supports multiple machines, multiple machine configuration files + can be present. + These filenames correspond to the values to which users have set the + MACHINE variable. + - - These files define things such as the kernel package to use - (PREFERRED_PROVIDER - of virtual/kernel), the hardware drivers to - include in different types of images, any special software components - that are needed, any bootloader information, and also any special image - format requirements. - + + These files define things such as the kernel package to use + (PREFERRED_PROVIDER + of virtual/kernel), the hardware drivers to + include in different types of images, any special software components + that are needed, any bootloader information, and also any special image + format requirements. + - - Each BSP Layer requires at least one machine file. - However, you can supply more than one file. - + + Each BSP Layer requires at least one machine file. + However, you can supply more than one file. + - - This configuration file could also include a hardware "tuning" - file that is commonly used to define the package architecture - and specify optimization flags, which are carefully chosen - to give best performance on a given processor. - + + This configuration file could also include a hardware "tuning" + file that is commonly used to define the package architecture + and specify optimization flags, which are carefully chosen + to give best performance on a given processor. + - - Tuning files are found in the meta/conf/machine/include - directory within the - Source Directory. - For example, the ia32-base.inc file resides in the - meta/conf/machine/include directory. - + + Tuning files are found in the meta/conf/machine/include + directory within the + Source Directory. + For example, the ia32-base.inc file resides in the + meta/conf/machine/include directory. + - - To use an include file, you simply include them in the - machine configuration file. - For example, the Raspberry Pi BSP - raspberrypi3.conf contains the - following statement: - + + To use an include file, you simply include them in the + machine configuration file. + For example, the Raspberry Pi BSP + raspberrypi3.conf contains the + following statement: + include conf/machine/raspberrypi2.conf - - + +
- Miscellaneous BSP-Specific Recipe Files - - You can find these files in the BSP Layer at: - + Miscellaneous BSP-Specific Recipe Files + + + You can find these files in the BSP Layer 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 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. - Furthermore, there are machine-specific settings used during - the build that are defined by the - machconfig file further down in the - directory. - Here is the machconfig - file for the Raspberry Pi BSP: - + + 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 + formfactor_0.0.bbappend file, which is an + append file used to augment the recipe that starts the build. + Furthermore, there are machine-specific settings used during + the build that are defined by the + machconfig file further down in the + directory. + Here is the machconfig + file for the Raspberry Pi BSP: + HAVE_TOUCHSCREEN=0 HAVE_KEYBOARD=1 DISPLAY_CAN_ROTATE=0 DISPLAY_ORIENTATION=0 DISPLAY_DPI=133 - - + + - - If a BSP does not have a formfactor entry, defaults are established according to - the formfactor configuration file that is installed by the main - formfactor recipe - meta/recipes-bsp/formfactor/formfactor_0.0.bb, - which is found in the - Source Directory. - + + If a BSP does not have a formfactor entry, defaults are established according to + the formfactor configuration file that is installed by the main + formfactor recipe + meta/recipes-bsp/formfactor/formfactor_0.0.bb, + which is found in the + Source Directory. +
- Display Support Files - - You can find these files in the BSP Layer at: - + Display Support Files + + + You can find these files in the BSP Layer 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. - + + 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. +
- Linux Kernel Configuration - - You can find these files in the BSP Layer at: - - meta-bsp_name/recipes-kernel/linux/linux-yocto*.bbappend - - - - - These files append your specific changes to the main kernel recipe you are using. - - - For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the - Source Directory - at meta/recipes-kernel/linux. - You can append your specific changes to the kernel recipe by using a - similarly named append file, which is located in the BSP Layer (e.g. - the meta-bsp_name/recipes-kernel/linux directory). - - - Suppose you are using the linux-yocto_4.4.bb recipe to build - the kernel. - In other words, you have selected the kernel in your - bsp_name.conf file by adding these types - of statements: - - PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" - PREFERRED_VERSION_linux-yocto ?= "4.4%" - - - When the preferred provider is assumed by default, the - PREFERRED_PROVIDER statement does not appear in the - bsp_name.conf file. - - You would use the linux-yocto_4.4.bbappend - file to append specific BSP settings to the kernel, thus - configuring the kernel for your particular BSP. - - - - As an example, consider the following append file - used by the BSPs in meta-yocto-bsp: - - meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend - - The following listing shows the file. - Be aware that the actual commit ID strings in this - example listing might be different than the actual strings - in the file from the meta-yocto-bsp - layer upstream. - - 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 = "standard/beaglebone" - KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb" - - SRCREV_machine_genericx86 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" - SRCREV_machine_genericx86-64 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" - SRCREV_machine_edgerouter ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" - SRCREV_machine_beaglebone ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" - SRCREV_machine_mpc8315e-rdb ?= "df00877ef9387b38b9601c82db57de2a1b23ce53" - - COMPATIBLE_MACHINE_genericx86 = "genericx86" - COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" - COMPATIBLE_MACHINE_edgerouter = "edgerouter" - COMPATIBLE_MACHINE_beaglebone = "beaglebone" - COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb" - - LINUX_VERSION_genericx86 = "4.4.3" - LINUX_VERSION_genericx86-64 = "4.4.3" - - This append file contains statements used to support - several BSPs that ship with the Yocto Project. - The file defines machines using the - COMPATIBLE_MACHINE - variable and uses the - KMACHINE - variable to ensure the machine name used by the OpenEmbedded - build system maps to the machine name used by the Linux Yocto - kernel. - The file also uses the optional - KBRANCH - variable to ensure the build process uses the - appropriate kernel branch. - - - - Although this particular example does not use it, the - KERNEL_FEATURES - variable could be used to enable features specific to - the kernel. - The append file points to specific commits in the - Source Directory - Git repository and the meta Git repository - branches to identify the exact kernel needed to build the - BSP. - - - - One thing missing in this particular BSP, which you will - typically need when developing a BSP, is the kernel configuration - file (.config) for your BSP. - When developing a BSP, you probably have a kernel configuration - file or a set of kernel configuration files that, when taken - together, define the kernel configuration for your BSP. - You can accomplish this definition by putting the configurations - in a file or a set of files inside a directory located at the - same level as your kernel's append file and having the same - name as the kernel's main recipe file. - With all these conditions met, simply reference those files in the - SRC_URI - statement in the append file. - + Linux Kernel Configuration - - For example, suppose you had some configuration options - in a file called network_configs.cfg. - You can place that file inside a directory named - linux-yocto and then add - a SRC_URI statement such as the - following to the append file. - When the OpenEmbedded build system builds the kernel, the - configuration options are picked up and applied. - - SRC_URI += "file://network_configs.cfg" - - + + You can find these files in the BSP Layer at: + + meta-bsp_name/recipes-kernel/linux/linux-yocto*.bbappend + + - - To group related configurations into multiple files, you - perform a similar procedure. - Here is an example that groups separate configurations - specifically for Ethernet and graphics into their own - files and adds the configurations by using a - SRC_URI statement like the following - in your append file: - - SRC_URI += "file://myconfig.cfg \ - file://eth.cfg \ - file://gfx.cfg" - - + + These files append machine-specific changes to the main + kernel recipe you are using. + - - Another variable you can use in your kernel recipe append - file is the - FILESEXTRAPATHS - variable. - When you use this statement, you are extending the locations - used by the OpenEmbedded system to look for files and - patches as the recipe is processed. - + + For your BSP, you typically want to use an existing Yocto + Project kernel recipe found in the + Source Directory + at meta/recipes-kernel/linux. + You can append machine-specific changes to the kernel recipe + by using a similarly named append file, which is located in + the BSP Layer for your target device (e.g. the + meta-bsp_name/recipes-kernel/linux directory). + - - Other methods exist to accomplish grouping and defining configuration options. - For example, if you are working with a local clone of the kernel repository, - you could checkout the kernel's meta branch, make your changes, - and then push the changes to the local bare clone of the kernel. - The result is that you directly add configuration options to the - meta branch for your BSP. - The configuration options will likely end up in that location anyway if the BSP gets - added to the Yocto Project. + Suppose you are using the linux-yocto_4.4.bb + recipe to build the kernel. + In other words, you have selected the kernel in your + bsp_name.conf + file by adding + PREFERRED_PROVIDER + and + PREFERRED_VERSION + statements as follows: + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "4.4%" + + + When the preferred provider is assumed by default, the + PREFERRED_PROVIDER + statement does not appear in the + bsp_name.conf file. + + You would use the linux-yocto_4.4.bbappend + file to append specific BSP settings to the kernel, thus + configuring the kernel for your particular BSP. - In general, however, the Yocto Project maintainers take care of moving the - SRC_URI-specified - configuration options to the kernel's 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. + You can find more information on what your append file + should contain in the + "Creating the Append File" + section in the Yocto Project Linux Kernel Development + Manual. -
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 1c1b6366db..434c01fafb 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -524,170 +524,219 @@ BSP Descriptions - BSP descriptions combine kernel types with hardware-specific - features. - The hardware-specific portion is typically defined - independently, and then aggregated with each supported kernel - type. - Consider this simple BSP description that supports the - mybsp machine: - - mybsp.scc: - define KMACHINE mybsp - define KTYPE standard - define KARCH i386 - - kconf mybsp.cfg - - Every BSP description should define the - KMACHINE, - KTYPE, - and KARCH - variables. - These variables allow the OpenEmbedded build system to identify - the description as meeting the criteria set by the recipe being - built. - This simple example supports the "mybsp" machine for the "standard" - kernel and the "i386" architecture. - - - - Be aware that a hard link between the - KTYPE variable and a kernel type - description file does not exist. - Thus, if you do not have kernel types defined in your kernel - Metadata, you only need to ensure that the kernel recipe's - LINUX_KERNEL_TYPE - variable and the KTYPE variable in the - BSP description file match. + BSP descriptions (i.e. *.scc files) + combine kernel types with hardware-specific features. + The hardware-specific Metadata is typically defined + independently in the BSP layer, and then aggregated with each + supported kernel type. - Future versions of the tooling make the specification of - KTYPE in the BSP optional. + For BSPs supported by the Yocto Project, the BSP description + files are located in the bsp directory + of the yocto-kernel-cache repository + organized under the "Yocto Linux Kernel" heading in the + Yocto Project Source Repositories. - If you did want to separate your kernel policy from your - hardware configuration, you could do so by specifying a kernel - type, such as "standard" and including that description file - in the BSP description file. - See the "Kernel Types" section - for more information. + This section provides a BSP description structural overview along + with aggregation concepts as well as a detailed example using + a BSP supported by the Yocto Project (i.e. Minnow Board). - - You might also have multiple hardware configurations that you - aggregate into a single hardware description file that you - could include in the BSP description file, rather than referencing - a single .cfg file. - Consider the following: - - mybsp.scc: - define KMACHINE mybsp - define KTYPE standard - define KARCH i386 - - include standard.scc - include mybsp-hw.scc - - +
+ Overview - - In the above example, standard.scc - aggregates all the configuration fragments, patches, and - features that make up your standard kernel policy whereas - mybsp-hw.scc - aggregates all those necessary - to support the hardware available on the - mybsp machine. - For information on how to break a complete - .config file into the various - configuration fragments, see the - "Generating Configuration Files" - section. - + + For simplicity, consider the following top-level BSP + description file. + Top-level BSP descriptions files employ both a structure + and naming convention for consistency. + The naming convention for the file is as follows: + + bsp_name-kernel_type.scc + + Here are some example top-level BSP filenames for the + Minnow Board BSP, which is supported by the Yocto Project: + + minnow-standard.scc + minnow-preempt-rt.scc + minnow-tiny.scc + + Each file uses the BSP name followed by the kernel type. + - - Many real-world examples are more complex. - Like any other .scc file, BSP - descriptions can aggregate features. - Consider the Minnow BSP definition from the - linux-yocto-3.19 - Git repository: - - minnow.scc: - include cfg/x86.scc - include features/eg20t/eg20t.scc - include cfg/dmaengine.scc - include features/power/intel.scc - include cfg/efi.scc - include features/usb/ehci-hcd.scc - include features/usb/ohci-hcd.scc - include features/usb/usb-gadgets.scc - include features/usb/touchscreen-composite.scc - include cfg/timer/hpet.scc - include cfg/timer/rtc.scc - include features/leds/leds.scc - include features/spi/spidev.scc - include features/i2c/i2cdev.scc - - # Earlyprintk and port debug requires 8250 - kconf hardware cfg/8250.cfg - - kconf hardware minnow.cfg - kconf hardware minnow-dev.cfg - - + + is simple BSP description file whose name has the + form + mybsp-standard + and supports the mybsp machine using + a standard kernel: + + define KMACHINE mybsp + define KTYPE standard + define KARCH i386 + + include ktypes/standard + + include mybsp.scc + + kconf hardware mybsp-extra.cfg + + Every top-level BSP description file should define the + KMACHINE, + KTYPE, + and KARCH + variables. + These variables allow the OpenEmbedded build system to identify + the description as meeting the criteria set by the recipe being + built. + This simple example supports the "mybsp" machine for the "standard" + kernel and the "i386" architecture. + - - The minnow.scc description file includes - a hardware configuration fragment - (minnow.cfg) specific to the Minnow - BSP as well as several more general configuration - fragments and features enabling hardware found on the - machine. - This description file is then included in each of the three - "minnow" description files for the supported kernel types - (i.e. "standard", "preempt-rt", and "tiny"). - Consider the "minnow" description for the "standard" kernel - type: - - minnow-standard.scc: - define KMACHINE minnow - define KTYPE standard - define KARCH i386 + + Be aware that a hard link between the + KTYPE variable and a kernel type description + file does not exist. + Thus, if you do not have kernel types defined in your kernel + Metadata, you only need to ensure that the kernel recipe's + LINUX_KERNEL_TYPE + variable and the KTYPE variable in the + BSP description file match. + + Future versions of the tooling make the specification of + KTYPE in the BSP optional. + + - include ktypes/standard + + To separate your kernel policy from your hardware configuration, + you include a kernel type (ktype), such as + "standard". + In the previous example, this is done using the following: + + include ktypes/standard + + In the previous example, ktypes/standard.scc + aggregates all the configuration fragments, patches, and + features that make up your standard kernel policy. + See the "Kernel Types" section + for more information. + - include minnow.scc + + To aggregate common configurations and features specific to the + kernel for mybsp, use the following: + + include mybsp.scc + + For information on how to break a complete + .config file into the various + configuration fragments, see the + "Generating Configuration Files" + section. + - # Extra minnow configs above the minimal defined in minnow.scc - include cfg/efi-ext.scc - include features/media/media-all.scc - include features/sound/snd_hda_intel.scc + + Finally, if you have any configurations specific to the + hardware that are not in a *.scc file, + you can include them as follows: + + kconf hardware mybsp-extra.cfg + + +
- # The following should really be in standard.scc - # USB live-image support - include cfg/usb-mass-storage.scc - include cfg/boot-live.scc +
+ Example - # Basic profiling - include features/latencytop/latencytop.scc - include features/profiling/profiling.scc + + Many real-world examples are more complex. + Like any other .scc file, BSP + descriptions can aggregate features. + Consider the Minnow BSP definition from the + linux-yocto-4.4 in the + Yocto Project + Source Repositories + (i.e. + yocto-kernel-cache/bsp/minnow): + + minnow.scc: + include cfg/x86.scc + include features/eg20t/eg20t.scc + include cfg/dmaengine.scc + include features/power/intel.scc + include cfg/efi.scc + include features/usb/ehci-hcd.scc + include features/usb/ohci-hcd.scc + include features/usb/usb-gadgets.scc + include features/usb/touchscreen-composite.scc + include cfg/timer/hpet.scc + include features/leds/leds.scc + include features/spi/spidev.scc + include features/i2c/i2cdev.scc + include features/mei/mei-txe.scc + + # Earlyprintk and port debug requires 8250 + kconf hardware cfg/8250.cfg + + kconf hardware minnow.cfg + kconf hardware minnow-dev.cfg + + - # Requested drivers that don't have an existing scc - kconf hardware minnow-drivers-extra.cfg - - The include command midway through the file - includes the minnow.scc description that - defines all hardware enablements for the BSP that is common to all - kernel types. - Using this command significantly reduces duplication. - + + The minnow.scc description file includes + a hardware configuration fragment + (minnow.cfg) specific to the Minnow + BSP as well as several more general configuration + fragments and features enabling hardware found on the + machine. + This minnow.scc description file is then + included in each of the three + "minnow" description files for the supported kernel types + (i.e. "standard", "preempt-rt", and "tiny"). + Consider the "minnow" description for the "standard" kernel + type: + + minnow-standard.scc: + define KMACHINE minnow + define KTYPE standard + define KARCH i386 + + include ktypes/standard + + include minnow.scc + + # Extra minnow configs above the minimal defined in minnow.scc + include cfg/efi-ext.scc + include features/media/media-all.scc + include features/sound/snd_hda_intel.scc + + # The following should really be in standard.scc + # USB live-image support + include cfg/usb-mass-storage.scc + include cfg/boot-live.scc + + # Basic profiling + include features/latencytop/latencytop.scc + include features/profiling/profiling.scc + + # Requested drivers that don't have an existing scc + kconf hardware minnow-drivers-extra.cfg + + The include command midway through the file + includes the minnow.scc description that + defines all enabled hardware for the BSP that is common to + all kernel types. + Using this command significantly reduces duplication. + - - Now consider the "minnow" description for the "tiny" kernel type: - + + Now consider the "minnow" description for the "tiny" kernel + type: + minnow-tiny.scc: define KMACHINE minnow define KTYPE tiny @@ -696,22 +745,24 @@ include ktypes/tiny include minnow.scc - - As you might expect, the "tiny" description includes quite a - bit less. - In fact, it includes only the minimal policy defined by the - "tiny" kernel type and the hardware-specific configuration required - for booting the machine along with the most basic functionality of - the system as defined in the base "minnow" description file. - + + As you might expect, the "tiny" description includes quite a + bit less. + In fact, it includes only the minimal policy defined by the + "tiny" kernel type and the hardware-specific configuration + required for booting the machine along with the most basic + functionality of the system as defined in the base "minnow" + description file. + - - Notice again the three critical variables: - KMACHINE, KTYPE, - and KARCH. - Of these variables, only the KTYPE has changed. - It is now set to "tiny". - + + Notice again the three critical variables: + KMACHINE, KTYPE, + and KARCH. + Of these variables, only the KTYPE has changed. + It is now set to "tiny". + +
@@ -795,6 +846,18 @@ value when changing the content of files not explicitly listed in the SRC_URI. + + + If the kernel Metadata is in a layer, you cannot simply list the + *.scc in the SRC_URI + statement. + You need to use the following form from your kernel append file: + + SRC_URI_append_myplatform = " \ + file://myplatform;type=kmeta;destsuffix=myplatform \ + " + +
@@ -817,7 +880,8 @@ ${KMETA}, in this context, is simply used to name the directory into which the Git fetcher places the Metadata. This behavior is no different than any multi-repository - SRC_URI statement used in a recipe. + SRC_URI statement used in a recipe (e.g. + see the previous section). diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml index a9aafd3c21..d49aa3ce17 100644 --- a/documentation/kernel-dev/kernel-dev-common.xml +++ b/documentation/kernel-dev/kernel-dev-common.xml @@ -84,11 +84,11 @@ You also name it accordingly based on the linux-yocto recipe you are using. For example, if you are modifying the - meta/recipes-kernel/linux/linux-yocto_3.19.bb + meta/recipes-kernel/linux/linux-yocto_4.4.bb recipe, the append file will typically be located as follows within your custom layer: - your-layer/recipes-kernel/linux/linux-yocto_3.19.bbappend + your-layer/recipes-kernel/linux/linux-yocto_4.4.bbappend The append file should initially extend the FILESPATH @@ -114,6 +114,151 @@ Yocto Project Board Support Package (BSP) Developer's Guide. + + + As an example, consider the following append file + used by the BSPs in meta-yocto-bsp: + + meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend + + The following listing shows the file. + Be aware that the actual commit ID strings in this + example listing might be different than the actual strings + in the file from the meta-yocto-bsp + layer upstream. + + 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 = "standard/beaglebone" + KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb" + + SRCREV_machine_genericx86 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2" + SRCREV_machine_genericx86-64 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2" + SRCREV_machine_edgerouter ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c" + SRCREV_machine_beaglebone ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c" + SRCREV_machine_mpc8315e-rdb ?= "06c0dbdcba374ca7f92a53d69292d6bb7bc9b0f3" + + COMPATIBLE_MACHINE_genericx86 = "genericx86" + COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" + COMPATIBLE_MACHINE_edgerouter = "edgerouter" + COMPATIBLE_MACHINE_beaglebone = "beaglebone" + COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb" + + LINUX_VERSION_genericx86 = "4.4.41" + LINUX_VERSION_genericx86-64 = "4.4.41" + LINUX_VERSION_edgerouter = "4.4.53" + LINUX_VERSION_beaglebone = "4.4.53" + LINUX_VERSION_mpc8315e-rdb = "4.4.53" + + This append file contains statements used to support + several BSPs that ship with the Yocto Project. + The file defines machines using the + COMPATIBLE_MACHINE + variable and uses the + KMACHINE + variable to ensure the machine name used by the OpenEmbedded + build system maps to the machine name used by the Linux Yocto + kernel. + The file also uses the optional + KBRANCH + variable to ensure the build process uses the + appropriate kernel branch. + + + + Although this particular example does not use it, the + KERNEL_FEATURES + variable could be used to enable features specific to + the kernel. + The append file points to specific commits in the + Source Directory + Git repository and the meta Git repository + branches to identify the exact kernel needed to build the + BSP. + + + + One thing missing in this particular BSP, which you will + typically need when developing a BSP, is the kernel configuration + file (.config) for your BSP. + When developing a BSP, you probably have a kernel configuration + file or a set of kernel configuration files that, when taken + together, define the kernel configuration for your BSP. + You can accomplish this definition by putting the configurations + in a file or a set of files inside a directory located at the + same level as your kernel's append file and having the same + name as the kernel's main recipe file. + With all these conditions met, simply reference those files in the + SRC_URI + statement in the append file. + + + + For example, suppose you had some configuration options + in a file called network_configs.cfg. + You can place that file inside a directory named + linux-yocto and then add + a SRC_URI statement such as the + following to the append file. + When the OpenEmbedded build system builds the kernel, the + configuration options are picked up and applied. + + SRC_URI += "file://network_configs.cfg" + + + + + To group related configurations into multiple files, you + perform a similar procedure. + Here is an example that groups separate configurations + specifically for Ethernet and graphics into their own + files and adds the configurations by using a + SRC_URI statement like the following + in your append file: + + SRC_URI += "file://myconfig.cfg \ + file://eth.cfg \ + file://gfx.cfg" + + + + + Another variable you can use in your kernel recipe append + file is the + FILESEXTRAPATHS + variable. + When you use this statement, you are extending the locations + used by the OpenEmbedded system to look for files and + patches as the recipe is processed. + + + + + Other methods exist to accomplish grouping and defining configuration options. + For example, if you are working with a local clone of the kernel repository, + you could checkout the kernel's meta branch, make your changes, + and then push the changes to the local bare clone of the kernel. + The result is that you directly add configuration options to the + meta branch for your BSP. + The configuration options will likely end up in that location anyway if the BSP gets + added to the Yocto Project. + + + + In general, however, the Yocto Project maintainers take care of moving the + SRC_URI-specified + configuration options to the kernel's 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. + +
-- cgit v1.2.3-54-g00ecf