documentation: dev-manual - edits to kernel section and compliance
* Edits to get the patching the kernel section more sane. * A tweak to the opening sentence of the compliance section to rid it of the split-infinitives. (From yocto-docs rev: 8e2ff293e85a602efd98aceb20da5a2ea5f2a34d) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
Richard Purdie
parent
4c35e5a983
commit
bd83f6a66f
|
|
@ -1626,7 +1626,7 @@
|
|||
</para>
|
||||
|
||||
<para>
|
||||
The example assumes a clean build exists for the <filename>x86qemu</filename>
|
||||
The example assumes a clean build exists for the <filename>qemux86</filename>
|
||||
machine in a Source Directory named <filename>poky</filename>.
|
||||
Furthermore, the <link linkend='build-directory'>Build Directory</link> is
|
||||
<filename>build</filename> and is located in <filename>poky</filename> and
|
||||
|
|
@ -1637,13 +1637,13 @@
|
|||
<title>Create a Layer for your Changes</title>
|
||||
|
||||
<para>
|
||||
The first step is to isolate your changes into a layer:
|
||||
The first step is to create a layer so you can isolate your changes:
|
||||
<literallayout class='monospaced'>
|
||||
$cd ~/poky
|
||||
$mkdir meta-mylayer
|
||||
</literallayout>
|
||||
Creating a directory that follows the Yocto Project layer naming
|
||||
conventions sets up the area for your changes.
|
||||
conventions sets up the layer for your changes.
|
||||
The layer is where you place your configuration files, append
|
||||
files, and patch files.
|
||||
To learn more about creating a layer and filling it with the
|
||||
|
|
@ -1657,26 +1657,24 @@
|
|||
|
||||
<para>
|
||||
Each time you build a kernel image, the kernel source code is fetched
|
||||
and unpacked into a temporary location in the <link linkend='build-directory'>Build Directory</link>.
|
||||
See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
|
||||
section for a description of where the OpenEmbedded build system places
|
||||
kernel source files during a build.
|
||||
Following is where machine-specific source code is temporarily stored
|
||||
during the build:
|
||||
and unpacked into the following directory:
|
||||
<literallayout class='monospaced'>
|
||||
${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
|
||||
${S}/linux
|
||||
</literallayout>
|
||||
See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
|
||||
section and the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable
|
||||
for more information about where source is kept during a build.
|
||||
For this example, the directory that
|
||||
holds the temporary source code is here:
|
||||
<literallayout class='monospaced'>
|
||||
~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3
|
||||
~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3/linux
|
||||
</literallayout>
|
||||
Within the <filename>linux</filename> directory, you find directories for
|
||||
the source.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For this example, we are going to patch the <filename>init/calibrate.c</filename> file
|
||||
For this example, we are going to patch the
|
||||
<filename>init/calibrate.c</filename> file
|
||||
by adding some simple console <filename>printk</filename> statements that we can
|
||||
see when we boot the image using QEMU.
|
||||
</para>
|
||||
|
|
@ -1686,39 +1684,31 @@
|
|||
<title>Creating the Patch</title>
|
||||
|
||||
<para>
|
||||
Two methods exist by which you can create the patch: Git workflow and Quilt workflow.
|
||||
Two methods exist by which you can create the patch:
|
||||
<link linkend='using-a-git-workflow'>Git workflow</link> and
|
||||
<link linkend='using-a-quilt-workflow'>Quilt workflow</link>.
|
||||
For kernel patches, the Git workflow is more appropriate.
|
||||
This section assumes the Git workflow.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To create the patch for the <filename>calibrate.c</filename>, follow steps
|
||||
3 through 12 outlined in the
|
||||
"<link linkend='using-a-git-workflow'>Using a Git Workflow</link>"
|
||||
section.
|
||||
For step 6 (Edit the Files), do the following:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Locate the <filename>void __cpuinit calibrate_delay(void)</filename>
|
||||
function:
|
||||
<literallayout class='monospaced'>
|
||||
void __cpuinit calibrate_delay(void)
|
||||
{
|
||||
unsigned long lpj;
|
||||
static bool printed;
|
||||
int this_cpu = smp_processor_id();
|
||||
|
||||
if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
|
||||
.
|
||||
.
|
||||
.
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Alter the code as follows:
|
||||
<literallayout class='monospaced'>
|
||||
This section assumes the Git workflow and shows the steps specific to
|
||||
this example.
|
||||
<orderedlist>
|
||||
<listitem><para><emphasis>Change the working directory</emphasis>:
|
||||
Change to where the kernel source code is before making
|
||||
your edits to the <filename>calibrate.c</filename> file:
|
||||
<literallayout class='monospaced'>
|
||||
$ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
|
||||
</literallayout>
|
||||
Because you are working in an established Git repository,
|
||||
you must be in this directory in order to commit your changes
|
||||
and create the patch file.
|
||||
<note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
|
||||
represent the version and revision for the
|
||||
<filename>linux-yocto</filename> recipe.
|
||||
</note></para></listitem>
|
||||
<listitem><para><emphasis>Edit the source file</emphasis>:
|
||||
Edit the <filename>init/calibrate.c</filename> file to have the
|
||||
following changes:
|
||||
<literallayout class='monospaced'>
|
||||
void __cpuinit calibrate_delay(void)
|
||||
{
|
||||
unsigned long lpj;
|
||||
|
|
@ -1735,44 +1725,49 @@
|
|||
.
|
||||
.
|
||||
.
|
||||
</literallayout>
|
||||
</literallayout></para></listitem>
|
||||
<listitem><para><emphasis>Stage and commit your changes</emphasis>:
|
||||
These Git commands list out the changed file, stage it, and then
|
||||
commit the files:
|
||||
<literallayout class='monospaced'>
|
||||
$ git status
|
||||
$ git add init/calibrate.c
|
||||
$ git commit
|
||||
</literallayout></para></listitem>
|
||||
<listitem><para><emphasis>Generate the patch file</emphasis>:
|
||||
This Git command creates the a patch file named
|
||||
<filename>0001-calibrate.c.patch</filename> in the current directory.
|
||||
<literallayout class='monospaced'>
|
||||
$ git format-patch HEAD~1
|
||||
</literallayout>
|
||||
<note>The name of the patch file is based on your commit summary
|
||||
line.</note>
|
||||
</para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='get-your-layer-setup-for-the-build'>
|
||||
<title>Get Your Layer Setup for the Build</title>
|
||||
|
||||
<para>
|
||||
At this point, you have a patch file in the kernel's source code directory.
|
||||
The patch file is named according to the commit's summary line and ends
|
||||
with <filename>.patch</filename>.
|
||||
For this example, it is named <filename>0001-calibrate.c.patch</filename>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You need to move the patch file to your layer next.
|
||||
The patch file needs to reside in the
|
||||
<filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename> directory.
|
||||
Create this directory path within your layer and move the patch file.
|
||||
This directory path mirrors that used by the main kernel recipe in
|
||||
the Source Directory (<filename>poky</filename>).
|
||||
<literallayout class='monospaced'>
|
||||
<para>These steps get your layer set up for the build:
|
||||
<orderedlist>
|
||||
<listitem><para><emphasis>Create additional structure</emphasis>:
|
||||
Create the additional layer structure:
|
||||
<literallayout class='monospaced'>
|
||||
$ cd ~/poky/meta-mylayer
|
||||
$ mkdir conf
|
||||
$ mkdir recipes-kernel
|
||||
$ mkdir recipes-kernel/linux
|
||||
$ mkdir recipes-kernel/linux/linux-yocto
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Next, you need to create a <filename>conf</filename> directory in your layer
|
||||
and within it create the <filename>layer.conf</filename> file.
|
||||
You can find information on this in the
|
||||
"<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
|
||||
section.
|
||||
Here is what your <filename>layer.conf</filename> should look like for this
|
||||
example:
|
||||
<literallayout class='monospaced'>
|
||||
</literallayout>
|
||||
The <filename>conf</filename> directory holds your configuration files, while the
|
||||
<filename>recipes-kernel</filename> directory holds your append file and
|
||||
your patch file.</para></listitem>
|
||||
<listitem><para><emphasis>Create the layer configuration file</emphasis>:
|
||||
Move to the <filename>meta-mylayer/conf</filename> directory and create
|
||||
the <filename>layer.conf</filename> file as follows:
|
||||
<literallayout class='monospaced'>
|
||||
# We have a conf and classes directory, add to BBPATH
|
||||
BBPATH := "${LAYERDIR}:${BBPATH}"
|
||||
|
||||
|
|
@ -1783,80 +1778,85 @@
|
|||
BBFILE_COLLECTIONS += "mylayer"
|
||||
BBFILE_PATTERN_mylayer := "^${LAYERDIR}/"
|
||||
BBFILE_PRIORITY_mylayer = "5"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Do the following to make sure the build parameters are set up for the example.
|
||||
Once you set up these build parameters, they do not have to change unless you
|
||||
change the target architecture of the machine you are building:
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
|
||||
<filename>local.conf</filename> file in the build directory defines the build's
|
||||
target architecture.
|
||||
By default, <filename>MACHINE</filename> is set to
|
||||
<filename>qemux86</filename>, which specifies a 32-bit
|
||||
<trademark class='registered'>Intel</trademark> Architecture
|
||||
target machine suitable for the QEMU emulator.
|
||||
In this example, <filename>MACHINE</filename> is correctly configured.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the
|
||||
<filename>local.conf</filename> file are two variables that can speed your
|
||||
build time if your host supports multi-core and multi-thread capabilities:
|
||||
<filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
|
||||
If the host system has multiple cores then you can optimize build time
|
||||
by setting both these variables to twice the number of
|
||||
cores.</para></listitem>
|
||||
<listitem><para><emphasis>Identify Your <filename>meta-mylayer</filename>
|
||||
Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
|
||||
<filename>bblayers.conf</filename> file found in the
|
||||
<filename>poky/build/conf</filename> directory needs to have the path to your local
|
||||
<filename>meta-mylayer</filename> layer.
|
||||
By default, the <filename>BBLAYERS</filename> variable contains paths to
|
||||
<filename>meta</filename>, <filename>meta-yocto</filename>, and
|
||||
<filename>meta-yocto-bsp</filename> in the
|
||||
<filename>poky</filename> Git repository.
|
||||
Add the path to your <filename>meta-mylayer</filename> location.
|
||||
Be sure to substitute your user information in the statement.
|
||||
Here is an example:
|
||||
<literallayout class='monospaced'>
|
||||
BBLAYERS = " \
|
||||
/home/scottrif/poky/meta \
|
||||
/home/scottrif/poky/meta-yocto \
|
||||
/home/scottrif/poky/meta-yocto-bsp \
|
||||
/home/scottrif/poky/meta-mylayer \
|
||||
"
|
||||
</literallayout></para></listitem>
|
||||
<listitem><para><emphasis>Create a bbappend File:</emphasis> You need to create
|
||||
an append file for the main 3.4 kernel recipe.
|
||||
Create the append file in the <filename>linux</filename> directory you
|
||||
created earlier within your layer.
|
||||
Assuming the patch file is named
|
||||
<filename>0001-documentation-calibrate.c.patch</filename>, your append
|
||||
file, which must be named <filename>linux-yocto_3.4.bbappend</filename>,
|
||||
has these statements:
|
||||
<literallayout class='monospaced'>
|
||||
</literallayout>
|
||||
Notice <filename>mylayer</filename> as part of the last three
|
||||
statements.</para></listitem>
|
||||
<listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
|
||||
Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
|
||||
the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
|
||||
<literallayout class='monospaced'>
|
||||
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
|
||||
|
||||
SRC_URI += "file://0001-documentation-calibrate.c.patch"
|
||||
SRC_URI += "file://0001-calibrate.c.patch"
|
||||
|
||||
PRINC := "${@int(PRINC) + 1}"
|
||||
</literallayout>
|
||||
The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename>
|
||||
statements ensure the OpenEmbedded build system picks up the patch file.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
</literallayout>
|
||||
The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename>
|
||||
statements enable the OpenEmbedded build system to find the patch file.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Put the patch file in your layer</emphasis>:
|
||||
Move the <filename>0001-calibrate.c.patch</filename> file to
|
||||
the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
|
||||
directory.</para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='building-and-booting-the-modified-qemu-kernel-image'>
|
||||
<title>Building and Booting the Modified QEMU Kernel Image</title>
|
||||
<section id='set-up-for-the-build'>
|
||||
<title>Set Up for the Build</title>
|
||||
|
||||
<para>
|
||||
Next, you need to build the modified image.
|
||||
Do the following:
|
||||
Do the following to make sure the build parameters are set up for the example.
|
||||
Once you set up these build parameters, they do not have to change unless you
|
||||
change the target architecture of the machine you are building:
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
|
||||
<filename>local.conf</filename> file in the build directory defines the build's
|
||||
target architecture.
|
||||
By default, <filename>MACHINE</filename> is set to
|
||||
<filename>qemux86</filename>, which specifies a 32-bit
|
||||
<trademark class='registered'>Intel</trademark> Architecture
|
||||
target machine suitable for the QEMU emulator.
|
||||
In this example, <filename>MACHINE</filename> is correctly configured.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the
|
||||
<filename>local.conf</filename> file are two variables that can speed your
|
||||
build time if your host supports multi-core and multi-thread capabilities:
|
||||
<filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
|
||||
If the host system has multiple cores then you can optimize build time
|
||||
by setting both these variables to twice the number of
|
||||
cores.</para></listitem>
|
||||
<listitem><para><emphasis>Identify Your <filename>meta-mylayer</filename>
|
||||
Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
|
||||
<filename>bblayers.conf</filename> file found in the
|
||||
<filename>poky/build/conf</filename> directory needs to have the path to your local
|
||||
<filename>meta-mylayer</filename> layer.
|
||||
By default, the <filename>BBLAYERS</filename> variable contains paths to
|
||||
<filename>meta</filename>, <filename>meta-yocto</filename>, and
|
||||
<filename>meta-yocto-bsp</filename> in the
|
||||
<filename>poky</filename> Git repository.
|
||||
Add the path to your <filename>meta-mylayer</filename> location.
|
||||
Be sure to substitute your user information in the statement:
|
||||
<literallayout class='monospaced'>
|
||||
BBLAYERS = " \
|
||||
/home/<user>/poky/meta \
|
||||
/home/<user>/poky/meta-yocto \
|
||||
/home/<user>/poky/meta-yocto-bsp \
|
||||
/home/<user>/poky/meta-mylayer \
|
||||
"
|
||||
</literallayout></para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='build-and-booting-the-modified-qemu-kernel-image'>
|
||||
<title>Build and Booting the Modified QEMU Kernel Image</title>
|
||||
|
||||
<para>
|
||||
The following steps build and boot your modified kernel image:
|
||||
<orderedlist>
|
||||
<listitem><para>Your environment should be set up since you previously sourced
|
||||
<listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
|
||||
Your environment should be set up since you previously sourced
|
||||
the <filename>&OE_INIT_FILE;</filename> script.
|
||||
If it isn't, source the script again from <filename>poky</filename>.
|
||||
<literallayout class='monospaced'>
|
||||
|
|
@ -1864,7 +1864,8 @@
|
|||
$ source &OE_INIT_FILE;
|
||||
</literallayout>
|
||||
</para></listitem>
|
||||
<listitem><para>Be sure old images are cleaned out by running the
|
||||
<listitem><para><emphasis>Clean up</emphasis>:
|
||||
Be sure old images are cleaned out by running the
|
||||
<filename>cleanall</filename> BitBake task as follows from your build directory:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake -c cleanall linux-yocto
|
||||
|
|
@ -1873,29 +1874,36 @@
|
|||
directory inside the build directory.
|
||||
Always use the BitBake <filename>cleanall</filename> task to clear
|
||||
out previous builds.</note></para></listitem>
|
||||
<listitem><para>Next, build the kernel image using this command:
|
||||
<listitem><para><emphasis>Build the image</emphasis>:
|
||||
Next, build the kernel image using this command:
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake -k linux-yocto
|
||||
</literallayout></para></listitem>
|
||||
<listitem><para>Finally, boot the modified image in the QEMU emulator
|
||||
</orderedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='verify-your-changes'>
|
||||
<title>Verify Your Changes</title>
|
||||
|
||||
<para>
|
||||
These steps boot the image and allow you to see the changes
|
||||
<orderedlist>
|
||||
<listitem><para><emphasis>Boot the image</emphasis>:
|
||||
Boot the modified image in the QEMU emulator
|
||||
using this command:
|
||||
<literallayout class='monospaced'>
|
||||
$ runqemu qemux86
|
||||
</literallayout></para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Log into the machine using <filename>root</filename> with no password and then
|
||||
use the following shell command to scroll through the console's boot output.
|
||||
<literallayout class='monospaced'>
|
||||
<listitem><para><emphasis>Verify the changes</emphasis>:
|
||||
Log into the machine using <filename>root</filename> with no password and then
|
||||
use the following shell command to scroll through the console's boot output.
|
||||
<literallayout class='monospaced'>
|
||||
# dmesg | less
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You should see the results of your <filename>printk</filename> statements
|
||||
as part of the output.
|
||||
</literallayout>
|
||||
You should see the results of your <filename>printk</filename> statements
|
||||
as part of the output.</para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
|
@ -2625,8 +2633,8 @@
|
|||
One of the concerns for a development organization using open source
|
||||
software is how to maintain compliance with various open source
|
||||
licensing during the lifecycle of the product.
|
||||
While this section is not meant to be legal advice or to
|
||||
comprehensively cover all scenarios, it is meant to
|
||||
While this section does not provide legal advice or
|
||||
comprehensively cover all scenarios, it does
|
||||
present methods that you can use to
|
||||
meet the compliance requirements during a software
|
||||
release.
|
||||
|
|
|
|||
|
|
@ -1688,10 +1688,12 @@ directory.</para></listitem>
|
|||
You need to be in the directory that has the temporary source code.
|
||||
That directory is defined by the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink>
|
||||
variable.
|
||||
For this discussion, assume that directory is <filename>linux</filename>.</para></listitem>
|
||||
<listitem><para><emphasis>Initialize a Git Repository:</emphasis>
|
||||
Use the <filename>git init</filename> command to initialize a new local repository
|
||||
variable.
|
||||
If you are working with a kernel, you need to be in the
|
||||
<filename>${S}/linux</filename> directory.</para></listitem>
|
||||
<listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis>
|
||||
If you are not already in a Git repository, use the
|
||||
<filename>git init</filename> command to initialize a new local repository
|
||||
that is based on the work directory:
|
||||
<literallayout class='monospaced'>
|
||||
$ git init
|
||||
|
|
@ -1730,11 +1732,6 @@ directory.</para></listitem>
|
|||
"<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
|
||||
section of the Yocto Project Quick Start.
|
||||
</note></para></listitem>
|
||||
<listitem><para><emphasis>Change Your Working Directory:</emphasis>
|
||||
After making your edits, move back to the directory from which you
|
||||
initialized the Git repository.
|
||||
Returning to this directory ensures you are using the correct branch when
|
||||
you go to commit your changes.</para></listitem>
|
||||
<listitem><para><emphasis>See the List of Files You Changed:</emphasis>
|
||||
Use the <filename>git status</filename> command to see what files you have actually edited.
|
||||
The ability to have Git track the files you have changed is an advantage that this
|
||||
|
|
@ -1749,7 +1746,7 @@ directory.</para></listitem>
|
|||
Again, for this discussion assume the files changed are in the <filename>linux</filename>
|
||||
directory:
|
||||
<literallayout class='monospaced'>
|
||||
$ git add linux/file1.c linux/file2.c linux/file3.c
|
||||
$ git add <somepath>/file1.c <somepath>/file2.c <somepath>/file3.c
|
||||
</literallayout></para></listitem>
|
||||
<listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
|
||||
Use the <filename>git commit</filename> command to commit the changes to the
|
||||
|
|
|
|||
Loading…
Reference in New Issue