diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml')
| -rw-r--r-- | import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml | 392 |
1 files changed, 262 insertions, 130 deletions
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml index 6bb0cf6fd0..f5fd183fd0 100644 --- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml +++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml @@ -7,82 +7,144 @@ <section id='tree-construction'> <title>Tree Construction</title> + <para> - This section describes construction of the Yocto Project kernel source repositories - as accomplished by the Yocto Project team to create kernel repositories. - These kernel repositories are found under the heading "Yocto Linux Kernel" at + This section describes construction of the Yocto Project kernel + source repositories as accomplished by the Yocto Project team to + create Yocto Linux kernel repositories. + These kernel repositories are found under the heading "Yocto Linux + Kernel" at <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink> - and can be shipped as part of a Yocto Project release. - The team creates these repositories by - compiling and executing the set of feature descriptions for every BSP - and feature in the product. + and are shipped as part of a Yocto Project release. + The team creates these repositories by compiling and executing the + set of feature descriptions for every BSP and feature in the + product. Those feature descriptions list all necessary patches, - configuration, branching, tagging and feature divisions found in a kernel. - Thus, the Yocto Project kernel repository (or tree) is built. + configurations, branches, tags, and feature divisions found in a + Yocto Linux kernel. + Thus, the Yocto Project Linux kernel repository (or tree) and + accompanying Metadata in the + <filename>yocto-kernel-cache</filename> are built. </para> + <para> - The existence of this tree allows you to access and clone a particular - Yocto Project kernel repository and use it to build images based on their configurations - and features. + The existence of these repositories allow you to access and clone a + particular Yocto Project Linux kernel repository and use it to + build images based on their configurations and features. </para> + <para> - You can find the files used to describe all the valid features and BSPs - in the Yocto Project kernel in any clone of the Yocto Project kernel source repository - Git tree. - For example, the following command clones the Yocto Project baseline kernel that - branched off of <filename>linux.org</filename> version 3.19: + You can find the files used to describe all the valid features and + BSPs in the Yocto Project Linux kernel in any clone of the Yocto + Project Linux kernel source repository and + <filename>yocto-kernel-cache</filename> Git trees. + For example, the following commands clone the Yocto Project + baseline Linux kernel that branches off + <filename>linux.org</filename> version 4.12 and the + <filename>yocto-kernel-cache</filename>, which contains stores of + kernel Metadata: <literallayout class='monospaced'> - $ git clone git://git.yoctoproject.org/linux-yocto-3.19 + $ git clone git://git.yoctoproject.org/linux-yocto-4.12 + $ git clone git://git.yoctoproject.org/linux-kernel-cache </literallayout> - For another example of how to set up a local Git repository of the Yocto Project - kernel files, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted - item in the Yocto Project Development Manual. + For more information on how to set up a local Git repository of + the Yocto Project Linux kernel files, see the + "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>" + section. </para> + <para> - Once you have cloned the kernel Git repository on your local machine, you can - switch to the <filename>meta</filename> branch within the repository. - Here is an example that assumes the local Git repository for the kernel is in - a top-level directory named <filename>linux-yocto-3.19</filename>: + Once you have cloned the kernel Git repository and the + cache of Metadata on your local machine, you can discover the + branches that are available in the repository using the following + Git command: + <literallayout class='monospaced'> + $ git branch -a + </literallayout> + Checking out a branch allows you to work with a particular + Yocto Linux kernel. + For example, the following commands check out the + "standard/beagleboard" branch of the Yocto Linux kernel repository + and the "yocto-4.12" branch of the + <filename>yocto-kernel-cache</filename> repository: <literallayout class='monospaced'> - $ cd linux-yocto-3.19 - $ git checkout -b meta origin/meta + $ cd ~/linux-yocto-4.12 + $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard + $ cd ~/linux-kernel-cache + $ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12 </literallayout> - Once you have checked out and switched to the <filename>meta</filename> branch, - you can see a snapshot of all the kernel configuration and feature descriptions that are - used to build that particular kernel repository. - These descriptions are in the form of <filename>.scc</filename> files. + <note> + Branches in the <filename>yocto-kernel-cache</filename> + repository correspond to Yocto Linux kernel versions + (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth). + </note> + Once you have checked out and switched to appropriate branches, + you can see a snapshot of all the kernel source files used to + used to build that particular Yocto Linux kernel for a + particular board. </para> + <para> - You should realize, however, that browsing your local kernel repository - for feature descriptions and patches is not an effective way to determine what is in a - particular kernel branch. - Instead, you should use Git directly to discover the changes in a branch. - Using Git is an efficient and flexible way to inspect changes to the kernel. + To see the features and configurations for a particular Yocto + Linux kernel, you need to examine the + <filename>yocto-kernel-cache</filename> Git repository. + As mentioned, branches in the + <filename>yocto-kernel-cache</filename> repository correspond to + Yocto Linux kernel versions (e.g. <filename>yocto-4.12</filename>). + Branches contain descriptions in the form of + <filename>.scc</filename> and <filename>.cfg</filename> files. + </para> + + <para> + You should realize, however, that browsing your local + <filename>yocto-kernel-cache</filename> repository for feature + descriptions and patches is not an effective way to determine what + is in a particular kernel branch. + Instead, you should use Git directly to discover the changes in + a branch. + Using Git is an efficient and flexible way to inspect changes to + the kernel. <note> - Ground up reconstruction of the complete kernel tree is an action only taken by the - Yocto Project team during an active development cycle. - When you create a clone of the kernel Git repository, you are simply making it - efficiently available for building and development. + Ground up reconstruction of the complete kernel tree is an + action only taken by the Yocto Project team during an active + development cycle. + When you create a clone of the kernel Git repository, you are + simply making it efficiently available for building and + development. </note> </para> + <para> - The following steps describe what happens when the Yocto Project Team constructs - the Yocto Project kernel source Git repository (or tree) found at + The following steps describe what happens when the Yocto Project + Team constructs the Yocto Project kernel source Git repository + (or tree) found at <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the introduction of a new top-level kernel feature or BSP. - These are the actions that effectively create the tree - that includes the new feature, patch or BSP: + These are the actions that effectively provide the Metadata + and create the tree that includes the new feature, patch or BSP: <orderedlist> - <listitem><para>A top-level kernel feature is passed to the kernel build subsystem. - Normally, this feature is a BSP for a particular kernel type.</para></listitem> - <listitem><para>The file that describes the top-level feature is located by searching - these system directories: + <listitem><para> + <emphasis>Pass Feature to Build Subsystem:</emphasis> + A top-level kernel feature is passed to the kernel build + subsystem. + Normally, this feature is a BSP for a particular kernel + type. + </para></listitem> + <listitem><para> + <emphasis>Locate Feature:</emphasis> + The file that describes the top-level feature is located + by searching these system directories: <itemizedlist> - <listitem><para>The in-tree kernel-cache directories, which are located - in <filename>meta/cfg/kernel-cache</filename></para></listitem> - <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements - found in recipes</para></listitem> + <listitem><para> + The in-tree kernel-cache directories, which are + located in the + <filename>yocto-kernel-cache</filename> + repository + </para></listitem> + <listitem><para> + Areas pointed to by <filename>SRC_URI</filename> + statements found in kernel recipes + </para></listitem> </itemizedlist> For a typical build, the target of the search is a feature description in an <filename>.scc</filename> file @@ -91,41 +153,96 @@ <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc </literallayout> </para></listitem> - <listitem><para>Once located, the feature description is either compiled into a simple script - of actions, or into an existing equivalent script that is already part of the - shipped kernel.</para></listitem> - <listitem><para>Extra features are appended to the top-level feature description. + <listitem><para> + <emphasis>Expand Feature:</emphasis> + Once located, the feature description is either expanded + into a simple script of actions, or into an existing + equivalent script that is already part of the shipped + kernel. + </para></listitem> + <listitem><para> + <emphasis>Append Extra Features:</emphasis> + Extra features are appended to the top-level feature + description. These features can come from the <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> - variable in recipes.</para></listitem> - <listitem><para>Each extra feature is located, compiled and appended to the script - as described in step three.</para></listitem> - <listitem><para>The script is executed to produce a series of <filename>meta-*</filename> - directories. - These directories are descriptions of all the branches, tags, patches and configurations that - need to be applied to the base Git repository to completely create the - source (build) branch for the new BSP or feature.</para></listitem> - <listitem><para>The base repository is cloned, and the actions - listed in the <filename>meta-*</filename> directories are applied to the - tree.</para></listitem> - <listitem><para>The Git repository is left with the desired branch checked out and any - required branching, patching and tagging has been performed.</para></listitem> + variable in recipes. + </para></listitem> + <listitem><para> + <emphasis>Locate, Expand, and Append Each Feature:</emphasis> + Each extra feature is located, expanded and appended to + the script as described in step three. + </para></listitem> + <listitem><para> + <emphasis>Execute the Script:</emphasis> + The script is executed to produce files + <filename>.scc</filename> and <filename>.cfg</filename> + files in appropriate directories of the + <filename>yocto-kernel-cache</filename> repository. + These files are descriptions of all the branches, tags, + patches and configurations that need to be applied to the + base Git repository to completely create the + source (build) branch for the new BSP or feature. + </para></listitem> + <listitem><para> + <emphasis>Clone Base Repository:</emphasis> + The base repository is cloned, and the actions + listed in the <filename>yocto-kernel-cache</filename> + directories are applied to the tree. + </para></listitem> + <listitem><para> + <emphasis>Perform Cleanup:</emphasis> + The Git repositories are left with the desired branches + checked out and any required branching, patching and + tagging has been performed. + </para></listitem> </orderedlist> </para> + <para> - The kernel tree is now ready for developer consumption to be locally cloned, - configured, and built into a Yocto Project kernel specific to some target hardware. - <note><para>The generated <filename>meta-*</filename> directories add to the kernel - as shipped with the Yocto Project release. - Any add-ons and configuration data are applied to the end of an existing branch. - The full repository generation that is found in the - official Yocto Project kernel repositories at - <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink> - is the combination of all supported boards and configurations.</para> - <para>The technique the Yocto Project team uses is flexible and allows for seamless - blending of an immutable history with additional patches specific to a - deployment. - Any additions to the kernel become an integrated part of the branches.</para> + The kernel tree and cache are ready for developer consumption to + be locally cloned, configured, and built into a Yocto Project + kernel specific to some target hardware. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + The generated <filename>yocto-kernel-cache</filename> + repository adds to the kernel as shipped with the Yocto + Project release. + Any add-ons and configuration data are applied to the + end of an existing branch. + The full repository generation that is found in the + official Yocto Project kernel repositories at + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink> + is the combination of all supported boards and + configurations. + </para></listitem> + <listitem><para> + The technique the Yocto Project team uses is flexible + and allows for seamless blending of an immutable + history with additional patches specific to a + deployment. + Any additions to the kernel become an integrated part + of the branches. + </para></listitem> + <listitem><para> + The full kernel tree that you see on + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> is + generated through repeating the above steps for all + valid BSPs. + The end result is a branched, clean history tree that + makes up the kernel for a given release. + You can see the script (<filename>kgit-scc</filename>) + responsible for this in the + <ulink url='&YOCTO_GIT_URL;/cgit.cgi/yocto-kernel-tools/tree/tools'><filename>yocto-kernel-tools</filename></ulink> + repository. + </para></listitem> + <listitem><para> + The steps used to construct the full kernel tree are + the same steps that BitBake uses when it builds a + kernel image. + </para></listitem> + </itemizedlist> </note> </para> </section> @@ -133,85 +250,100 @@ <section id='build-strategy'> <title>Build Strategy</title> -<!-- <para> - <emphasis>AR - Darren Hart:</emphasis> Some parts of this section - need to be in the - "<link linkend='using-an-iterative-development-process'>Using an Iterative Development Process</link>" - section. - Darren needs to figure out which parts and identify them. - </para> ---> - - <para> - Once a local Git repository of the Yocto Project kernel exists on a development system, - you can consider the compilation phase of kernel development - building a kernel image. - Some prerequisites exist that are validated by the build process before compilation - starts: + Once you have cloned a Yocto Linux kernel repository and the + cache repository (<filename>yocto-kernel-cache</filename>) onto + your development system, you can consider the compilation phase + of kernel development, which is building a kernel image. + Some prerequisites exist that are validated by the build process + before compilation starts: </para> <itemizedlist> - <listitem><para>The - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points - to the kernel Git repository.</para></listitem> - <listitem><para>A BSP build branch exists. - This branch has the following form: + <listitem><para> + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + points to the kernel Git repository. + </para></listitem> + <listitem><para> + A BSP build branch with Metadata exists in the + <filename>yocto-kernel-cache</filename> repository. + The branch is based on the Yocto Linux kernel version and + has configurations and features grouped under the + <filename>yocto-kernel-cache/bsp</filename> directory. + For example, features and configurations for the + BeagleBone Board assuming a + <filename>linux-yocto_4.12</filename> kernel reside in the + following area of the <filename>yocto-kernel-cache</filename> + repository: <literallayout class='monospaced'> - <replaceable>kernel_type</replaceable>/<replaceable>bsp_name</replaceable> - </literallayout></para></listitem> + yocto-kernel-cache/bsp/beaglebone + </literallayout> + <note> + In the previous example, the "yocto-4.12" branch is + checked out in the <filename>yocto-kernel-cache</filename> + repository. + </note> + </para></listitem> </itemizedlist> <para> - The OpenEmbedded build system makes sure these conditions exist before attempting compilation. + The OpenEmbedded build system makes sure these conditions exist + before attempting compilation. Other means, however, do exist, such as as bootstrapping a BSP. </para> <para> Before building a kernel, the build process verifies the tree and configures the kernel by processing all of the - configuration "fragments" specified by feature descriptions in the <filename>.scc</filename> - files. - As the features are compiled, associated kernel configuration fragments are noted - and recorded in the <filename>meta-*</filename> series of directories in their compilation order. - The fragments are migrated, pre-processed and passed to the Linux Kernel - Configuration subsystem (<filename>lkc</filename>) as raw input in the form - of a <filename>.config</filename> file. - The <filename>lkc</filename> uses its own internal dependency constraints to do the final - processing of that information and generates the final <filename>.config</filename> file - that is used during compilation. + configuration "fragments" specified by feature descriptions + in the <filename>.scc</filename> files. + As the features are compiled, associated kernel configuration + fragments are noted and recorded in the series of directories + in their compilation order. + The fragments are migrated, pre-processed and passed to the + Linux Kernel Configuration subsystem (<filename>lkc</filename>) as + raw input in the form of a <filename>.config</filename> file. + The <filename>lkc</filename> uses its own internal dependency + constraints to do the final processing of that information and + generates the final <filename>.config</filename> file that is used + during compilation. </para> <para> - Using the board's architecture and other relevant values from the board's template, - kernel compilation is started and a kernel image is produced. + Using the board's architecture and other relevant values from + the board's template, kernel compilation is started and a kernel + image is produced. </para> <para> The other thing that you notice once you configure a kernel is that - the build process generates a build tree that is separate from your kernel's local Git - source repository tree. + the build process generates a build tree that is separate from + your kernel's local Git source repository tree. This build tree has a name that uses the following form, where - <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one - of the Yocto Project supported kernel types (e.g. "standard"): + <filename>${MACHINE}</filename> is the metadata name of the + machine (BSP) and "kernel_type" is one of the Yocto Project + supported kernel types (e.g. "standard"): <literallayout class='monospaced'> linux-${MACHINE}-<replaceable>kernel_type</replaceable>-build </literallayout> </para> <para> - The existing support in the <filename>kernel.org</filename> tree achieves this - default functionality. + The existing support in the <filename>kernel.org</filename> tree + achieves this default functionality. </para> <para> - This behavior means that all the generated files for a particular machine or BSP are now in - the build tree directory. - The files include the final <filename>.config</filename> file, all the <filename>.o</filename> - files, the <filename>.a</filename> files, and so forth. + This behavior means that all the generated files for a particular + machine or BSP are now in the build tree directory. + The files include the final <filename>.config</filename> file, + all the <filename>.o</filename> files, the <filename>.a</filename> + files, and so forth. Since each machine or BSP has its own separate - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> - in its own separate branch - of the Git repository, you can easily switch between different builds. + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + in its own separate branch of the Git repository, you can easily + switch between different builds. </para> </section> </appendix> |