diff options
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-advanced.xml')
| -rw-r--r-- | documentation/kernel-dev/kernel-dev-advanced.xml | 227 |
1 files changed, 121 insertions, 106 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 4a6aeb7391..4fdb853f92 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -24,9 +24,9 @@ <title>Using Kernel Metadata in a Recipe</title> <para> - The kernel sources in the Yocto Project contain kernel Metadata, which is - located in the <filename>meta</filename> branches of the kernel source - Git repositories. + The kernel sources in the Yocto Project contain kernel Metadata, which + is located in the <filename>meta</filename> branches of the kernel + source Git repositories. This Metadata defines Board Support Packages (BSPs) that correspond to definitions in linux-yocto recipes for the same BSPs. A BSP consists of an aggregation of kernel policy and hardware-specific @@ -48,37 +48,44 @@ This variable is typically set to the same value as the <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable, which is used by - <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> - (e.g. "edgerouter" or "fri2"). + <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>. + However, in some cases, the variable might instead refer to the + underlying platform of the <filename>MACHINE</filename>. + </para> + + <para> Multiple BSPs can reuse the same <filename>KMACHINE</filename> name if they are built using the same BSP description. - The "fri2" and "fri2-noemgd" BSP combination - in the <filename>meta-intel</filename> + The "ep108-zynqmp" and "qemuzynqmp" BSP combination + in the <filename>meta-xilinx</filename> layer is a good example of two BSPs using the same - <filename>KMACHINE</filename> value (i.e. "fri2"). + <filename>KMACHINE</filename> value (i.e. "zynqmp"). See the <link linkend='bsp-descriptions'>BSP Descriptions</link> section for more information. </para> <para> + Every linux-yocto style recipe must also indicate the Linux kernel + source repository branch used to build the Linux kernel. + The <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> + variable must be set to indicate the branch. + <note> + You can use the <filename>KBRANCH</filename> value to define an + alternate branch typically with a machine override as shown here + from the <filename>meta-emenlow</filename> layer: + <literallayout class='monospaced'> + KBRANCH_emenlow-noemgd = "standard/base" + </literallayout> + </note> + </para> + + <para> The linux-yocto style recipes can optionally define the following variables: <literallayout class='monospaced'> - <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'>KBRANCH</ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink> - <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH_DEFAULT'>KBRANCH_DEFAULT</ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</ulink> </literallayout> - <filename>KBRANCH_DEFAULT</filename> defines the Linux kernel source - repository's default branch to use to build the Linux kernel. - The value is used as the default for <filename>KBRANCH</filename>, which - can define an alternate branch typically with a machine override as - follows: - <literallayout class='monospaced'> - KBRANCH_fri2 = "standard/fri2" - </literallayout> - Unless you specify otherwise, <filename>KBRANCH_DEFAULT</filename> - initializes to "master". </para> <para> @@ -94,7 +101,7 @@ build out the sources and configuration. The linux-yocto recipes define "standard", "tiny", and "preempt-rt" kernel types. - See the <link linkend='kernel-types'>Kernel Types</link> section + See the "<link linkend='kernel-types'>Kernel Types</link>" section for more information on kernel types. </para> @@ -109,11 +116,11 @@ the following: <literallayout class='monospaced'> WARNING: Can't find any BSP hardware or required configuration fragments. - WARNING: Looked at meta/cfg/broken/fri2-broken/hdw_frags.txt and - meta/cfg/broken/fri2-broken/required_frags.txt in directory: - meta/cfg/broken/fri2-broken + WARNING: Looked at meta/cfg/broken/emenlow-broken/hdw_frags.txt and + meta/cfg/broken/emenlow-broken/required_frags.txt in directory: + meta/cfg/broken/emenlow-broken </literallayout> - In this example, <filename>KMACHINE</filename> was set to "fri2-broken" + In this example, <filename>KMACHINE</filename> was set to "emenlow-broken" and <filename>LINUX_KERNEL_TYPE</filename> was set to "broken". </para> @@ -131,21 +138,22 @@ to include features (configuration fragments, patches, or both) that are not already included by the <filename>KMACHINE</filename> and <filename>LINUX_KERNEL_TYPE</filename> variable combination. - For example, to include a feature specified as "features/netfilter.scc", + For example, to include a feature specified as + "features/netfilter/netfilter.scc", specify: <literallayout class='monospaced'> - KERNEL_FEATURES += "features/netfilter.scc" + KERNEL_FEATURES += "features/netfilter/netfilter.scc" </literallayout> To include a feature called "cfg/sound.scc" just for the <filename>qemux86</filename> machine, specify: <literallayout class='monospaced'> - KERNEL_FEATURES_append_qemux86 = "cfg/sound.scc" + KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc" </literallayout> The value of the entries in <filename>KERNEL_FEATURES</filename> are dependent on their location within the kernel Metadata itself. - The examples here are taken from the - <filename>linux-yocto-3.4</filename> repository where "features" - and "cfg" are subdirectories within the + The examples here are taken from the <filename>meta</filename> + branch of the <filename>linux-yocto-3.19</filename> repository. + Within that branch, "features" and "cfg" are subdirectories of the <filename>meta/cfg/kernel-cache</filename> directory. For more information, see the "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" section. @@ -214,7 +222,7 @@ Here is an example that shows a trivial tree of kernel Metadata stored in recipe-space within a BSP layer: <literallayout class='monospaced'> - meta-my_bsp_layer/ + meta-<replaceable>my_bsp_layer</replaceable>/ `-- recipes-kernel `-- linux `-- linux-yocto @@ -370,7 +378,7 @@ of Metadata. The following Metadata file hierarchy is recommended: <literallayout class='monospaced'> - <base>/ + <replaceable>base</replaceable>/ bsp/ cfg/ features/ @@ -440,22 +448,27 @@ feature. This feature consists of one or more Linux kernel configuration parameters in a configuration fragment file - (<filename>.cfg</filename>) and an <filename>.scc</filename> file + (<filename>.cfg</filename>) and a <filename>.scc</filename> file that describes the fragment. </para> <para> The Symmetric Multi-Processing (SMP) fragment included in the - <filename>linux-yocto-3.4</filename> Git repository + <filename>linux-yocto-3.19</filename> Git repository consists of the following two files: <literallayout class='monospaced'> cfg/smp.scc: define KFEATURE_DESCRIPTION "Enable SMP" + define KFEATURE_COMPATIBILITY all + kconf hardware smp.cfg cfg/smp.cfg: CONFIG_SMP=y CONFIG_SCHED_SMT=y + # 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 </literallayout> You can find information on configuration fragment files in the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>" @@ -513,7 +526,7 @@ patch mypatch.patch patches/mypatch.patch: - <typical-patch> + <replaceable>typical-patch</replaceable> </literallayout> You can create the typical <filename>.patch</filename> file using <filename>diff -Nurp</filename> or @@ -582,7 +595,7 @@ </para> <para> - As an example, the <filename>linux-yocto-3.4</filename> + As an example, the <filename>linux-yocto-3.19</filename> tree defines three kernel types: "standard", "tiny", and "preempt-rt": <itemizedlist> @@ -669,15 +682,15 @@ 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: + Consider this simple BSP description that supports the + <replaceable>mybsp</replaceable> machine: <literallayout class='monospaced'> - mybsp.scc: - define KMACHINE mybsp + <replaceable>mybsp</replaceable>.scc: + define KMACHINE <replaceable>mybsp</replaceable> define KTYPE standard define KARCH i386 - kconf mybsp.cfg + kconf <replaceable>mybsp</replaceable>.cfg </literallayout> Every BSP description should define the <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, @@ -722,13 +735,13 @@ a single <filename>.cfg</filename> file. Consider the following: <literallayout class='monospaced'> - mybsp.scc: + <replaceable>mybsp</replaceable>.scc: define KMACHINE mybsp define KTYPE standard define KARCH i386 include standard.scc - include mybsp-hw.scc + include <replaceable>mybsp</replaceable>-hw.scc </literallayout> </para> @@ -736,8 +749,10 @@ In the above example, <filename>standard.scc</filename> aggregates all the configuration fragments, patches, and features that make up your standard kernel policy whereas - <filename>mybsp-hw.scc</filename> aggregates all those necessary - to support the hardware available on the "mybsp" machine. + <replaceable>mybsp</replaceable><filename>-hw.scc</filename> + aggregates all those necessary + to support the hardware available on the + <replaceable>mybsp</replaceable> machine. For information on how to break a complete <filename>.config</filename> file into the various configuration fragments, see the @@ -749,99 +764,98 @@ Many real-world examples are more complex. Like any other <filename>.scc</filename> file, BSP descriptions can aggregate features. - Consider the Fish River Island 2 (fri2) - BSP definition from the <filename>linux-yocto-3.4</filename> + Consider the Minnow BSP definition from the + <filename>linux-yocto-3.19</filename> Git repository: <literallayout class='monospaced'> - fri2.scc: - kconf hardware fri2.cfg - + minnow.scc: include cfg/x86.scc include features/eg20t/eg20t.scc include cfg/dmaengine.scc - include features/ericsson-3g/f5521gw.scc include features/power/intel.scc include cfg/efi.scc include features/usb/ehci-hcd.scc include features/usb/ohci-hcd.scc - include features/iwlwifi/iwlwifi.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 </literallayout> </para> <para> - The <filename>fri2.scc</filename> description file includes + The <filename>minnow.scc</filename> description file includes a hardware configuration fragment - (<filename>fri2.cfg</filename>) specific to the Fish River - Island 2 BSP as well as several more general configuration + (<filename>minnow.cfg</filename>) 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 - "fri2" description files for the supported kernel types + "minnow" description files for the supported kernel types (i.e. "standard", "preempt-rt", and "tiny"). - Consider the "fri2" description for the "standard" kernel + Consider the "minnow" description for the "standard" kernel type: <literallayout class='monospaced'> - fri2-standard.scc: - define KMACHINE fri2 + minnow-standard.scc: + define KMACHINE minnow define KTYPE standard define KARCH i386 - include ktypes/standard/standard.scc - branch fri2 - - git merge emgd-1.14 + include ktypes/standard - include fri2.scc + include minnow.scc - # Extra fri2 configs above the minimal defined in fri2.scc + # Extra minnow configs above the minimal defined in minnow.scc include cfg/efi-ext.scc - include features/drm-emgd/drm-emgd.scc - include cfg/vesafb.scc + include features/media/media-all.scc + include features/sound/snd_hda_intel.scc - # default policy for standard kernels + # 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 </literallayout> The <filename>include</filename> command midway through the file - includes the <filename>fri2.scc</filename> description that + includes the <filename>minnow.scc</filename> description that defines all hardware enablements for the BSP that is common to all kernel types. Using this command significantly reduces duplication. </para> <para> - This "fri2" standard description introduces a few more variables - and commands that are worth further discussion. - Notice the <filename>branch fri2</filename> command, which creates - a machine-specific branch into which source changes are applied. - With this branch set up, the <filename>git merge</filename> command - uses Git to merge in a feature branch named "emgd-1.14". - You could also handle this with the <filename>patch</filename> - command. - However, for commonly used features such as this, feature branches - are a convenient mechanism. - See the "<link linkend='feature-branches'>Feature Branches</link>" - section for more information. - </para> - - <para> - Now consider the "fri2" description for the "tiny" kernel type: + Now consider the "minnow" description for the "tiny" kernel type: <literallayout class='monospaced'> - fri2-tiny.scc: - define KMACHINE fri2 + minnow-tiny.scc: + define KMACHINE minnow define KTYPE tiny define KARCH i386 - include ktypes/tiny/tiny.scc - branch fri2 + include ktypes/tiny - include fri2.scc + include minnow.scc </literallayout> 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 "fri2" description file. + the system as defined in the base "minnow" description file. </para> <para> @@ -968,37 +982,38 @@ hierarchical branching system similar to what the linux-yocto Linux kernel repositories use: <literallayout class='monospaced'> - <common>/<kernel_type>/<machine> + <replaceable>common</replaceable>/<replaceable>kernel_type</replaceable>/<replaceable>machine</replaceable> </literallayout> </para> <para> If you had two kernel types, "standard" and "small" for - instance, and three machines, the branches in your + instance, three machines, and <replaceable>common</replaceable> + as <filename>mydir</filename>, the branches in your Git repository might look like this: <literallayout class='monospaced'> - common/base - common/standard/base - common/standard/machine_a - common/standard/machine_b - common/standard/machine_c - common/small/base - common/small/machine_a + mydir/base + mydir/standard/base + mydir/standard/machine_a + mydir/standard/machine_b + mydir/standard/machine_c + mydir/small/base + mydir/small/machine_a </literallayout> </para> <para> This organization can help clarify the branch relationships. - In this case, <filename>common/standard/machine_a</filename> - includes everything in <filename>common/base</filename> and - <filename>common/standard/base</filename>. + In this case, <filename>mydir/standard/machine_a</filename> + includes everything in <filename>mydir/base</filename> and + <filename>mydir/standard/base</filename>. The "standard" and "small" branches add sources specific to those kernel types that for whatever reason are not appropriate for the other branches. <note>The "base" branches are an artifact of the way Git manages its data internally on the filesystem: Git will not allow you - to use <filename>common/standard</filename> and - <filename>common/standard/machine_a</filename> because it + to use <filename>mydir/standard</filename> and + <filename>mydir/standard/machine_a</filename> because it would have to create a file and a directory named "standard". </note> </para> |