[yocto] [PATCH v2] yocto-docs: kernel-dev, Aesthetic/formatting/clarification fixes
Robert P. J. Day
rpjday at crashcourse.ca
Thu Feb 23 09:44:51 PST 2017
A variety of tweaks to kernel-dev manual, section
kernel-dev-common.xml, which include:
* adding extra text in places to clarify possibly ambiguous content
* some formatting changes related to font and overly long lines
* update some old version numbers that don't even exist anymore
Signed-off-by: Robert P. J. Day <rpjday at crashcourse.ca>
---
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index a9aafd3..cb186c9 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -25,10 +25,10 @@
If you are going to be modifying kernel recipes, it is recommended
that you create and prepare your own layer in which to do your
work.
- Your layer contains its own
+ Your layer would typically contain its own
<ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
append files
- (<filename>.bbappend</filename>) and provides a convenient
+ (<filename>.bbappend</filename>) and would provide a convenient
mechanism to create your own recipe files
(<filename>.bb</filename>).
For details on how to create and work with layers, see the following
@@ -59,9 +59,9 @@
<para>
Modifying an existing recipe can consist of the following:
<itemizedlist>
- <listitem><para>Creating the append file</para></listitem>
- <listitem><para>Applying patches</para></listitem>
- <listitem><para>Changing the configuration</para></listitem>
+ <listitem><para>Creating an append file</para></listitem>
+ <listitem><para>Applying some local patches</para></listitem>
+ <listitem><para>Changing the kernel configuration</para></listitem>
</itemizedlist>
</para>
@@ -81,14 +81,14 @@
<para>
You create this file in your custom layer.
- You also name it accordingly based on the linux-yocto recipe
- you are using.
+ You also name it accordingly based on the version of the
+ linux-yocto recipe you are modifying.
For example, if you are modifying the
- <filename>meta/recipes-kernel/linux/linux-yocto_3.19.bb</filename>
- recipe, the append file will typically be located as follows
- within your custom layer:
+ <filename>meta/recipes-kernel/linux/linux-yocto_4.4.bb</filename>
+ recipe, the corresponding append file will typically be located
+ as follows within your custom layer:
<literallayout class='monospaced'>
- <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_3.19.bbappend
+ <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_4.4.bbappend
</literallayout>
The append file should initially extend the
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
@@ -133,12 +133,14 @@
<para>
For example, you can apply a three-patch series by adding the
- following lines to your linux-yocto
- <filename>.bbappend</filename> file in your layer:
+ following lines to the linux-yocto
+ <filename>.bbappend</filename> file in your custom layer:
<literallayout class='monospaced'>
- SRC_URI += "file://0001-first-change.patch"
- SRC_URI += "file://0002-second-change.patch"
- SRC_URI += "file://0003-third-change.patch"
+ SRC_URI += " \
+ file://0001-first-change.patch \
+ file://0002-second-change.patch \
+ file://0003-third-change.patch \
+ "
</literallayout>
The next time you run BitBake to build the Linux kernel,
BitBake detects the change in the recipe and fetches and
@@ -158,11 +160,12 @@
<para>
You can make wholesale or incremental changes to the final
<filename>.config</filename> file used for the eventual
- Linux kernel configuration by including a
- <filename>defconfig</filename> file and by specifying
+ Linux kernel configuration by including a local
+ <filename>defconfig</filename> file, as well as by specifying
configuration fragments in the
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- to be applied to that file.
+ to be applied to the configuration defined by that
+ <filename>defconfig</filename> file.
</para>
<para>
@@ -204,10 +207,10 @@
<para>
Generally speaking, the preferred approach is to determine the
- incremental change you want to make and add that as a
- configuration fragment.
- For example, if you want to add support for a basic serial
- console, create a file named <filename>8250.cfg</filename> in
+ incremental changes you want to make and add each of those changes
+ using a separate configuration fragment.
+ For example, if you want to add support for a basic (8250 UART-based) serial
+ console, create a file named, for example, <filename>8250.cfg</filename> in
the <filename>${PN}</filename> directory with the following
content (without indentation):
<literallayout class='monospaced'>
@@ -219,7 +222,7 @@
CONFIG_SERIAL_CORE=y
CONFIG_SERIAL_CORE_CONSOLE=y
</literallayout>
- Next, include this configuration fragment and extend the
+ Next, include this configuration fragment and (as before) extend the
<filename>FILESPATH</filename> variable in your
<filename>.bbappend</filename> file:
<literallayout class='monospaced'>
@@ -231,6 +234,17 @@
new configuration before building the kernel.
</para>
+ <note>
+ Depending on the kernel config fragment you are adding, it might not be
+ necessary to specify every single setting related to what you want.
+ For instance, in the above example, once you select
+ <varname>CONFIG_SERIAL_8250=y</varname>, some of the subsequent config
+ settings might be set based on default values in the kernel's
+ corresponding <varname>Kconfig</varname>
+ file. However, some developers prefer to list everything related to
+ the selected feature for the sake of completeness and clarity.
+ </note>
+
<para>
For a detailed example showing how to configure the kernel,
see the
@@ -270,7 +284,7 @@
edit the recipe that builds your kernel so that it has the
following command form:
<literallayout class='monospaced'>
- KBUILD_DEFCONFIG_KMACHINE ?= <replaceable>defconfig_file</replaceable>
+ KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
</literallayout>
You need to append the variable with
<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
More information about the yocto
mailing list