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: + 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. + + + + The following listings show the build.scc + file and part of the + modpost-mask-trivial-warnings.patch file: - patches/mypatch.scc: - patch mypatch.patch + 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 - patches/mypatch.patch: - typical-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" + - As an example, the linux-yocto-3.19 - tree defines three kernel types: "standard", - "tiny", and "preempt-rt": + 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. + + + + + 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.