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: - - meta-bsp_name/README.sources - - + README.sources File - - 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. - - + + 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. + +
- 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: - - meta-bsp_name/recipes-bsp/* - - + Miscellaneous BSP-Specific Recipe Files - - 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: - + + 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: + 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: - - meta-bsp_name/recipes-graphics/* - - + Display Support Files - - 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. - + + 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. +
- Linux Kernel Configuration - - You can find these files in the BSP Layer at: - - meta-bsp_name/recipes-kernel/linux/linux-yocto*.bbappend - - + Linux Kernel Configuration - - 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: - + + You can find these files in the BSP Layer at: + + meta-bsp_name/recipes-kernel/linux/linux-yocto*.bbappend + + + + + These files append machine-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 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). + + + + 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. - - - - 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. - - - - 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. + + + 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 +
+ Overview - include standard.scc - include mybsp-hw.scc - - + + 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. + - - 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. - + + 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 - - 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: - + 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. + + + + 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. + + + + + 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. + + + + 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. + + + + 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 + + +
+ +
+ Example + + + 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 cfg/timer/rtc.scc - include features/leds/leds.scc - include features/spi/spidev.scc - include features/i2c/i2cdev.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 + # Earlyprintk and port debug requires 8250 + kconf hardware cfg/8250.cfg - kconf hardware minnow.cfg - kconf hardware minnow-dev.cfg - - + kconf hardware minnow.cfg + kconf hardware minnow-dev.cfg + + - - 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: - + + 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 + define KMACHINE minnow + define KTYPE standard + define KARCH i386 - include ktypes/standard + include ktypes/standard - include minnow.scc + 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 + # 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 + # 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 + # 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 hardware enablements for the BSP that is common to all - kernel types. - Using this command significantly reduces duplication. - + # 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. + +