sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

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 2012-10-12 20:02:43 -07:00 committed by Richard Purdie
parent 4c35e5a983
commit bd83f6a66f
2 changed files with 173 additions and 168 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

324
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@ -1626,7 +1626,7 @@
</para> </para>
<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>. machine in a Source Directory named <filename>poky</filename>.
Furthermore, the <link linkend='build-directory'>Build Directory</link> is Furthermore, the <link linkend='build-directory'>Build Directory</link> is
<filename>build</filename> and is located in <filename>poky</filename> and <filename>build</filename> and is located in <filename>poky</filename> and
@ -1637,13 +1637,13 @@
<title>Create a Layer for your Changes</title> <title>Create a Layer for your Changes</title>
<para> <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'> <literallayout class='monospaced'>
$cd ~/poky $cd ~/poky
$mkdir meta-mylayer $mkdir meta-mylayer
</literallayout> </literallayout>
Creating a directory that follows the Yocto Project layer naming 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 The layer is where you place your configuration files, append
files, and patch files. files, and patch files.
To learn more about creating a layer and filling it with the To learn more about creating a layer and filling it with the
@ -1657,26 +1657,24 @@
<para> <para>
Each time you build a kernel image, the kernel source code is fetched 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>. and unpacked into the following directory:
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:
<literallayout class='monospaced'> <literallayout class='monospaced'>
${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} ${S}/linux
</literallayout> </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 For this example, the directory that
holds the temporary source code is here: holds the temporary source code is here:
<literallayout class='monospaced'> <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> </literallayout>
Within the <filename>linux</filename> directory, you find directories for
the source.
</para> </para>
<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 by adding some simple console <filename>printk</filename> statements that we can
see when we boot the image using QEMU. see when we boot the image using QEMU.
</para> </para>
@ -1686,39 +1684,31 @@
<title>Creating the Patch</title> <title>Creating the Patch</title>
<para> <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. For kernel patches, the Git workflow is more appropriate.
This section assumes the Git workflow. This section assumes the Git workflow and shows the steps specific to
</para> this example.
<orderedlist>
<para> <listitem><para><emphasis>Change the working directory</emphasis>:
To create the patch for the <filename>calibrate.c</filename>, follow steps Change to where the kernel source code is before making
3 through 12 outlined in the your edits to the <filename>calibrate.c</filename> file:
"<link linkend='using-a-git-workflow'>Using a Git Workflow</link>" <literallayout class='monospaced'>
section. $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
For step 6 (Edit the Files), do the following: </literallayout>
</para> Because you are working in an established Git repository,
you must be in this directory in order to commit your changes
<para> and create the patch file.
Locate the <filename>void __cpuinit calibrate_delay(void)</filename> <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
function: <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
<literallayout class='monospaced'> represent the version and revision for the
void __cpuinit calibrate_delay(void) <filename>linux-yocto</filename> recipe.
{ </note></para></listitem>
unsigned long lpj; <listitem><para><emphasis>Edit the source file</emphasis>:
static bool printed; Edit the <filename>init/calibrate.c</filename> file to have the
int this_cpu = smp_processor_id(); following changes:
<literallayout class='monospaced'>
if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
.
.
.
</literallayout>
</para>
<para>
Alter the code as follows:
<literallayout class='monospaced'>
void __cpuinit calibrate_delay(void) void __cpuinit calibrate_delay(void)
{ {
unsigned long lpj; 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> </para>
</section> </section>
<section id='get-your-layer-setup-for-the-build'> <section id='get-your-layer-setup-for-the-build'>
<title>Get Your Layer Setup for the Build</title> <title>Get Your Layer Setup for the Build</title>
<para> <para>These steps get your layer set up for the build:
At this point, you have a patch file in the kernel's source code directory. <orderedlist>
The patch file is named according to the commit's summary line and ends <listitem><para><emphasis>Create additional structure</emphasis>:
with <filename>.patch</filename>. Create the additional layer structure:
For this example, it is named <filename>0001-calibrate.c.patch</filename>. <literallayout class='monospaced'>
</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'>
$ cd ~/poky/meta-mylayer $ cd ~/poky/meta-mylayer
$ mkdir conf
$ mkdir recipes-kernel $ mkdir recipes-kernel
$ mkdir recipes-kernel/linux $ mkdir recipes-kernel/linux
$ mkdir recipes-kernel/linux/linux-yocto $ mkdir recipes-kernel/linux/linux-yocto
</literallayout> </literallayout>
</para> The <filename>conf</filename> directory holds your configuration files, while the
<filename>recipes-kernel</filename> directory holds your append file and
<para> your patch file.</para></listitem>
Next, you need to create a <filename>conf</filename> directory in your layer <listitem><para><emphasis>Create the layer configuration file</emphasis>:
and within it create the <filename>layer.conf</filename> file. Move to the <filename>meta-mylayer/conf</filename> directory and create
You can find information on this in the the <filename>layer.conf</filename> file as follows:
"<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>" <literallayout class='monospaced'>
section.
Here is what your <filename>layer.conf</filename> should look like for this
example:
<literallayout class='monospaced'>
# We have a conf and classes directory, add to BBPATH # We have a conf and classes directory, add to BBPATH
BBPATH := "${LAYERDIR}:${BBPATH}" BBPATH := "${LAYERDIR}:${BBPATH}"
@ -1783,80 +1778,85 @@
BBFILE_COLLECTIONS += "mylayer" BBFILE_COLLECTIONS += "mylayer"
BBFILE_PATTERN_mylayer := "^${LAYERDIR}/" BBFILE_PATTERN_mylayer := "^${LAYERDIR}/"
BBFILE_PRIORITY_mylayer = "5" BBFILE_PRIORITY_mylayer = "5"
</literallayout> </literallayout>
</para> Notice <filename>mylayer</filename> as part of the last three
statements.</para></listitem>
<para> <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
Do the following to make sure the build parameters are set up for the example. Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
Once you set up these build parameters, they do not have to change unless you the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
change the target architecture of the machine you are building: <literallayout class='monospaced'>
<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'>
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://0001-documentation-calibrate.c.patch" SRC_URI += "file://0001-calibrate.c.patch"
PRINC := "${@int(PRINC) + 1}" PRINC := "${@int(PRINC) + 1}"
</literallayout> </literallayout>
The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename> The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename>
statements ensure the OpenEmbedded build system picks up the patch file. statements enable the OpenEmbedded build system to find the patch file.
</para></listitem> </para></listitem>
</itemizedlist> <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
</para> Move the <filename>0001-calibrate.c.patch</filename> file to
</section> 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'> <section id='set-up-for-the-build'>
<title>Building and Booting the Modified QEMU Kernel Image</title> <title>Set Up for the Build</title>
<para> <para>
Next, you need to build the modified image. Do the following to make sure the build parameters are set up for the example.
Do the following: 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/&lt;user&gt;/poky/meta \
/home/&lt;user&gt;/poky/meta-yocto \
/home/&lt;user&gt;/poky/meta-yocto-bsp \
/home/&lt;user&gt;/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> <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. the <filename>&OE_INIT_FILE;</filename> script.
If it isn't, source the script again from <filename>poky</filename>. If it isn't, source the script again from <filename>poky</filename>.
<literallayout class='monospaced'> <literallayout class='monospaced'>
@ -1864,7 +1864,8 @@
$ source &OE_INIT_FILE; $ source &OE_INIT_FILE;
</literallayout> </literallayout>
</para></listitem> </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: <filename>cleanall</filename> BitBake task as follows from your build directory:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ bitbake -c cleanall linux-yocto $ bitbake -c cleanall linux-yocto
@ -1873,29 +1874,36 @@
directory inside the build directory. directory inside the build directory.
Always use the BitBake <filename>cleanall</filename> task to clear Always use the BitBake <filename>cleanall</filename> task to clear
out previous builds.</note></para></listitem> 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'> <literallayout class='monospaced'>
$ bitbake -k linux-yocto $ bitbake -k linux-yocto
</literallayout></para></listitem> </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: using this command:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ runqemu qemux86 $ runqemu qemux86
</literallayout></para></listitem> </literallayout></para></listitem>
</orderedlist> <listitem><para><emphasis>Verify the changes</emphasis>:
</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.
<para> <literallayout class='monospaced'>
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 # dmesg | less
</literallayout> </literallayout>
</para> You should see the results of your <filename>printk</filename> statements
as part of the output.</para></listitem>
<para> </orderedlist>
You should see the results of your <filename>printk</filename> statements
as part of the output.
</para> </para>
</section> </section>
</section> </section>
@ -2625,8 +2633,8 @@
One of the concerns for a development organization using open source One of the concerns for a development organization using open source
software is how to maintain compliance with various open source software is how to maintain compliance with various open source
licensing during the lifecycle of the product. licensing during the lifecycle of the product.
While this section is not meant to be legal advice or to While this section does not provide legal advice or
comprehensively cover all scenarios, it is meant to comprehensively cover all scenarios, it does
present methods that you can use to present methods that you can use to
meet the compliance requirements during a software meet the compliance requirements during a software
release. release.

17
documentation/dev-manual/dev-manual-model.xml
View File

@ -1688,10 +1688,12 @@ directory.</para></listitem>
You need to be in the directory that has the temporary source code. You need to be in the directory that has the temporary source code.
That directory is defined by the That directory is defined by the
<ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink>
variable. variable.
For this discussion, assume that directory is <filename>linux</filename>.</para></listitem> If you are working with a kernel, you need to be in the
<listitem><para><emphasis>Initialize a Git Repository:</emphasis> <filename>${S}/linux</filename> directory.</para></listitem>
Use the <filename>git init</filename> command to initialize a new local repository <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: that is based on the work directory:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ git init $ git init
@ -1730,11 +1732,6 @@ directory.</para></listitem>
"<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
section of the Yocto Project Quick Start. section of the Yocto Project Quick Start.
</note></para></listitem> </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> <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. 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 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> Again, for this discussion assume the files changed are in the <filename>linux</filename>
directory: directory:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ git add linux/file1.c linux/file2.c linux/file3.c $ git add &lt;somepath&gt;/file1.c &lt;somepath&gt;/file2.c &lt;somepath&gt;/file3.c
</literallayout></para></listitem> </literallayout></para></listitem>
<listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis> <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 Use the <filename>git commit</filename> command to commit the changes to the