From 429719213d9a6d9b825165b57d0b0ce0641564b5 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 28 Sep 2017 15:07:12 -0700 Subject: kernel-dev: Updates to "Kernel Metadata Syntax" section Scrubbed this section to bring it up to speed with more modern BSP examples and better explanation of the types of Metadata used. (From yocto-docs rev: ba009de68a3786f83d9c3c9debffa8b811479786) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/kernel-dev/kernel-dev-advanced.xml | 323 +++++++++++++++-------- 1 file changed, 219 insertions(+), 104 deletions(-) (limited to 'documentation/kernel-dev/kernel-dev-advanced.xml') diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 6618a7c906..380200a633 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -273,11 +273,13 @@ Paths used in kernel Metadata files are relative to - <base>, which is either + base, which is either FILESEXTRAPATHS if you are creating Metadata in recipe-space, - or yocto-kernel-cache/cfg if you are creating + or the top level of + yocto-kernel-cache + if you are creating Metadata outside of the recipe-space. @@ -294,12 +296,18 @@ - The Symmetric Multi-Processing (SMP) fragment included in the - linux-yocto-3.19 Git repository - consists of the following two files: + As an example, consider the Symmetric Multi-Processing (SMP) + fragment used with the linux-yocto-4.12 + kernel as defined outside of the recipe space (i.e. + yocto-kernel-cache). + This Metadata consists of two files: smp.scc + and smp.cfg. + You can find these files in the cfg directory + of the yocto-4.12 branch in the + yocto-kernel-cache Git repository: cfg/smp.scc: - define KFEATURE_DESCRIPTION "Enable SMP" + define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds" define KFEATURE_COMPATIBILITY all kconf hardware smp.cfg @@ -310,20 +318,27 @@ # Increase default NR_CPUS from 8 to 64 so that platform with # more than 8 processors can be all activated at boot time CONFIG_NR_CPUS=64 + # The following is nedded when setting NR_CPUS to something + # greater than 8 on x86 architectures, it should be automatically + # disregarded by Kconfig when using a different arch + CONFIG_X86_BIGSMP=y - You can find information on configuration fragment files in the + You can find general information on configuration fragment files in + the "Creating Configuration Fragments" section. + Within the smp.scc file, the KFEATURE_DESCRIPTION - provides a short description of the fragment. + statement provides a short description of the fragment. Higher level kernel tools use this description. - The kconf command is used to include the + Also within the smp.scc file, the + kconf command includes the actual configuration fragment in an .scc file, and the "hardware" keyword identifies the fragment as being hardware enabling, as opposed to general policy, @@ -355,26 +370,71 @@ Patch descriptions are very similar to configuration fragment descriptions, which are described in the previous section. However, instead of a .cfg file, these - descriptions work with source patches. + descriptions work with source patches (i.e. + .patch files). - A typical patch includes a description file and the patch itself: - - patches/mypatch.scc: - patch mypatch.patch + A typical patch includes a description file and the patch itself. + As an example, consider the build patches used with the + linux-yocto-4.12 kernel as defined outside of + the recipe space (i.e. yocto-kernel-cache). + This Metadata consists of several files: + build.scc and a set of + *.patch files. + You can find these files in the patches/build + directory of the yocto-4.12 branch in the + yocto-kernel-cache Git repository. + - patches/mypatch.patch: - typical-patch + + The following listings show the build.scc + file and part of the + modpost-mask-trivial-warnings.patch file: + + patches/build/build.scc: + patch arm-serialize-build-targets.patch + patch powerpc-serialize-image-targets.patch + patch kbuild-exclude-meta-directory-from-distclean-processi.patch + + # applied by kgit + # patch kbuild-add-meta-files-to-the-ignore-li.patch + + patch modpost-mask-trivial-warnings.patch + patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch + + patches/build/modpost-mask-trivial-warnings.patch: + From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001 + From: Paul Gortmaker <paul.gortmaker@windriver.com> + Date: Sun, 25 Jan 2009 17:58:09 -0500 + Subject: [PATCH] modpost: mask trivial warnings + + Newer HOSTCC will complain about various stdio fcns because + . + . + . + char *dump_write = NULL, *files_source = NULL; + int opt; + -- + 2.10.1 + + generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT) - You can create the typical .patch - file using diff -Nurp or - git format-patch. + The description file can include multiple patch statements where + each statement handles a single patch. + In the example build.scc file, five patch + statements exist for the five patches in the directory. - The description file can include multiple patch statements, - one per patch. + You can create a typical .patch file using + diff -Nurp or + git format-patch commands. + For information on how to create patches, see the + "Using devtool to Patch the Kernel" + and + "Using Traditional Kernel Development to Patch the Kernel" + sections. @@ -383,26 +443,23 @@ Features are complex kernel Metadata types that consist - of configuration fragments (kconf), patches - (patch), and possibly other feature - description files (include). - - - - Here is an example that shows a feature description file: + of configuration fragments, patches, and possibly other feature + description files. + As an example, consider the following generic listing: - features/myfeature.scc - define KFEATURE_DESCRIPTION "Enable myfeature" + features/myfeature.scc + define KFEATURE_DESCRIPTION "Enable myfeature" - patch 0001-myfeature-core.patch - patch 0002-myfeature-interface.patch + patch 0001-myfeature-core.patch + patch 0002-myfeature-interface.patch - include cfg/myfeature_dependency.scc - kconf non-hardware myfeature.cfg + include cfg/myfeature_dependency.scc + kconf non-hardware myfeature.cfg This example shows how the patch and kconf commands are used as well as - how an additional feature description file is included. + how an additional feature description file is included with + the include command. @@ -422,21 +479,47 @@ A kernel type defines a high-level kernel policy by aggregating non-hardware configuration fragments with - patches you want to use when building a Linux kernels of a - specific type. + patches you want to use when building a Linux kernel of a + specific type (e.g. a real-time kernel). Syntactically, kernel types are no different than features as described in the "Features" section. - The LINUX_KERNEL_TYPE variable in the kernel - recipe selects the kernel type. - See the "Using Kernel Metadata in a Recipe" - section for more information. + The + LINUX_KERNEL_TYPE + variable in the kernel recipe selects the kernel type. + For example, in the linux-yocto_4.12.bb + kernel recipe found in + poky/meta/recipes-kernel/linux, a + require + directive includes the + poky/meta/recipes-kernel/linux/linux-yocto.inc + file, which has the following statement that defines the default + kernel type: + + LINUX_KERNEL_TYPE ??= "standard" + + + + + Another example would be the real-time kernel (i.e. + linux-yocto-rt_4.12.bb). + This kernel recipe directly sets the kernel type as follows: + + LINUX_KERNEL_TYPE = "preempt-rt" + + + You can find kernel recipes in the + meta/recipes-kernel/linux directory of the + Source Directory + (e.g. poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb). + See the "Using Kernel Metadata in a Recipe" + section for more information. + - As an example, the linux-yocto-3.19 - tree defines three kernel types: "standard", - "tiny", and "preempt-rt": + Three kernel types ("standard", "tiny", and "preempt-rt") are + supported for Linux Yocto kernels: "standard": Includes the generic Linux kernel policy of the Yocto @@ -463,29 +546,40 @@ - The "standard" kernel type is defined by - standard.scc: + For any given kernel type, the Metadata is defined by the + .scc (e.g. standard.scc). + Here is a partial listing for the standard.scc + file, which is found in the ktypes/standard + directory of the yocto-kernel-cache Git + repository: # Include this kernel type fragment to get the standard features and # configuration values. - # Include all standard features - include standard-nocfg.scc + # Note: if only the features are desired, but not the configuration + # then this should be included as: + # include ktypes/standard/standard.scc nocfg + # if no chained configuration is desired, include it as: + # include ktypes/standard/standard.scc nocfg inherit + + + + include ktypes/base/base.scc + branch standard kconf non-hardware standard.cfg - # individual cfg block section - include cfg/fs/devtmpfs.scc - include cfg/fs/debugfs.scc - include cfg/fs/btrfs.scc - include cfg/fs/ext2.scc - include cfg/fs/ext3.scc - include cfg/fs/ext4.scc + include features/kgdb/kgdb.scc + . + . + . - include cfg/net/ipv6.scc - include cfg/net/ip_nf.scc include cfg/net/ip6_nf.scc include cfg/net/bridge.scc + + include cfg/systemd.scc + + include features/rfkill/rfkill.scc @@ -531,9 +625,9 @@ - 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). + This section overviews the BSP description structure, the + aggregation concepts, and presents a detailed example using + a BSP supported by the Yocto Project (i.e. BeagleBone Board).
@@ -541,7 +635,7 @@ For simplicity, consider the following top-level BSP - description file. + description files for the BeagleBone board. Top-level BSP descriptions files employ both a structure and naming convention for consistency. The naming convention for the file is as follows: @@ -549,31 +643,30 @@ 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: + BeagleBone Board BSP, which is supported by the Yocto Project: - minnow-standard.scc - minnow-preempt-rt.scc - minnow-tiny.scc + beaglebone-standard.scc + beaglebone-preempt-rt.scc Each file uses the BSP name followed by the kernel type. - is simple BSP description file whose name has the - form - mybsp-standard - and supports the mybsp machine using - a standard kernel: + Examine the beaglebone-standard.scc + file: - define KMACHINE mybsp + define KMACHINE beaglebone define KTYPE standard - define KARCH i386 + define KARCH arm - include ktypes/standard + include ktypes/standard/standard.scc + branch beaglebone - include mybsp.scc + include beaglebone.scc - kconf hardware mybsp-extra.cfg + # default policy for standard kernels + include features/latencytop/latencytop.scc + include features/profiling/profiling.scc Every top-level BSP description file should define the KMACHINE, @@ -583,19 +676,20 @@ 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. + This example supports the "beaglebone" machine for the + "standard" kernel and the "arm" 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 + KTYPE variable and a kernel type + description file does not exist. + Thus, if you do not have the kernel type defined in your kernel + Metadata as it is here, you only need to ensure that the LINUX_KERNEL_TYPE - variable and the KTYPE variable in the - BSP description file match. + variable in the kernel recipe and the + KTYPE variable in the BSP descriptionn + file match. Future versions of the tooling make the specification of KTYPE in the BSP optional. @@ -608,13 +702,12 @@ "standard". In the previous example, this is done using the following: - include ktypes/standard + include ktypes/standard/standard.scc - 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. + This file aggregates all the configuration fragments, patches, + and features that make up your standard kernel policy. + See the "Kernel Types" + section for more information. @@ -622,6 +715,10 @@ kernel for mybsp, use the following: include mybsp.scc + + You can see that in the BeagleBone example with the following: + + include beaglebone.scc For information on how to break a complete .config file into the various @@ -637,6 +734,23 @@ kconf hardware mybsp-extra.cfg + The BeagleBone example does not include these types of + configurations. + However, the Malta 32-bit board does ("mti-malta32"). + Here is the mti-malta32-le-standard.scc + file: + + define KMACHINE mti-malta32-le + define KMACHINE qemumipsel + define KTYPE standard + define KARCH mips + + include ktypes/standard/standard.scc + branch mti-malta32 + + include mti-malta32.scc + kconf hardware mti-malta32-le.cfg +
@@ -647,14 +761,15 @@ 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): + Consider the Minnow BSP definition given the + linux-yocto-4.4 branch of the + yocto-kernel-cache (i.e. + yocto-kernel-cache/bsp/minnow/minnow.scc): + + Although the Minnow Board BSP is unused, the Metadata + remains and is being used here just as an example. + - minnow.scc: include cfg/x86.scc include features/eg20t/eg20t.scc include cfg/dmaengine.scc @@ -690,9 +805,8 @@ "minnow" description files for the supported kernel types (i.e. "standard", "preempt-rt", and "tiny"). Consider the "minnow" description for the "standard" kernel - type: + type (i.e. minnow-standard.scc: - minnow-standard.scc: define KMACHINE minnow define KTYPE standard define KARCH i386 @@ -727,9 +841,8 @@ Now consider the "minnow" description for the "tiny" kernel - type: + type (i.e. minnow-tiny.scc: - minnow-tiny.scc: define KMACHINE minnow define KTYPE tiny define KARCH i386 @@ -749,10 +862,12 @@ Notice again the three critical variables: - KMACHINE, KTYPE, - and KARCH. - Of these variables, only the KTYPE has changed. - It is now set to "tiny". + KMACHINE, + KTYPE, + and + KARCH. + Of these variables, only KTYPE + has changed to specify the "tiny" kernel type. -- cgit v1.2.3-54-g00ecf