summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-10-10 14:54:26 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-10-16 23:46:51 +0100
commit4c0e713b815031bcbc9fad7c20b0be87d91c58c1 (patch)
tree20d4ff2b5c9b7aa98b19df8c5381eb041117fb5b /documentation/kernel-dev
parent0b75283fa9b40e451923b6704d0be2b97f786c6e (diff)
downloadpoky-4c0e713b815031bcbc9fad7c20b0be87d91c58c1.tar.gz
kernel-dev: Applied review feedback
Various edits for review feedback on the manual in general. (From yocto-docs rev: 218061535b5bed326331d00eee6f514c81299238) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev')
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml221
-rw-r--r--documentation/kernel-dev/kernel-dev-concepts-appx.xml10
2 files changed, 61 insertions, 170 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index 3dd4cd88b6..17d89f7454 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -57,7 +57,7 @@
57 </para> 57 </para>
58 58
59 <section id='getting-ready-to-develop-using-devtool'> 59 <section id='getting-ready-to-develop-using-devtool'>
60 <title>Getting Ready to Develop using <filename>devtool</filename></title> 60 <title>Getting Ready to Develop Using <filename>devtool</filename></title>
61 61
62 <para> 62 <para>
63 Follow these steps to prepare to update the kernel image using 63 Follow these steps to prepare to update the kernel image using
@@ -129,15 +129,18 @@
129 Don't forget to add it to your BBLAYERS (for details see ../meta-mylayer/README). 129 Don't forget to add it to your BBLAYERS (for details see ../meta-mylayer/README).
130 </literallayout> 130 </literallayout>
131 <note> 131 <note>
132 For background information on working with layers, 132 For background information on working with
133 see the 133 common and BSP layers, see the
134 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" 134 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
135 section in the Yocto Project Development Manual. 135 section in the Yocto Project Development Manual
136 See the 136 and the
137 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
138 section in the Yocto Project Board Support (BSP)
139 Developer's Guide, respectively.
140 For information on how to use the
141 <filename>yocto-layer</filename> script, see the
137 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>" 142 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>"
138 section in the Yocto Project Development Manual for 143 section in the Yocto Project Development Manual.
139 details on how to use the
140 <filename>yocto-layer</filename> script.
141 </note> 144 </note>
142 </para></listitem> 145 </para></listitem>
143 <listitem><para> 146 <listitem><para>
@@ -350,15 +353,18 @@
350 Don't forget to add it to your BBLAYERS (for details see ../meta-mylayer/README). 353 Don't forget to add it to your BBLAYERS (for details see ../meta-mylayer/README).
351 </literallayout> 354 </literallayout>
352 <note> 355 <note>
353 For background information on working with layers, 356 For background information on working with
354 see the 357 common and BSP layers, see the
355 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" 358 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
356 section in the Yocto Project Development Manual. 359 section in the Yocto Project Development Manual
357 See the 360 and the
361 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
362 section in the Yocto Project Board Support (BSP)
363 Developer's Guide, respectively.
364 For information on how to use the
365 <filename>yocto-layer</filename> script, see the
358 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>" 366 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>"
359 section in the Yocto Project Development Manual for 367 section in the Yocto Project Development Manual.
360 details on how to use the
361 <filename>yocto-layer</filename> script.
362 </note> 368 </note>
363 </para></listitem> 369 </para></listitem>
364 <listitem><para> 370 <listitem><para>
@@ -815,7 +821,7 @@
815 <filename>devtool</filename>, see the 821 <filename>devtool</filename>, see the
816 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>" 822 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
817 and 823 and
818 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel'></link>" 824 "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
819 sections. 825 sections.
820 </para> 826 </para>
821 </section> 827 </section>
@@ -935,16 +941,17 @@
935 941
936 <para> 942 <para>
937 To specify an "in-tree" <filename>defconfig</filename> file, 943 To specify an "in-tree" <filename>defconfig</filename> file,
938 use the following 944 use the following statement form:
939 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG'><filename>KBUILD_DEFCONFIG</filename></ulink>
940 statement form in the append file for the kernel recipe:
941 <literallayout class='monospaced'> 945 <literallayout class='monospaced'>
942 KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable> 946 KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
943 </literallayout> 947 </literallayout>
944 You need to append the variable with 948 Here is an example that appends the
945 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> 949 <filename>KBUILD_DEFCONFIG</filename> variable with
946 and then supply the path to your "in-tree" 950 "common-pc" and provides the path to the "in-tree"
947 <filename>defconfig</filename> file. 951 <filename>defconfig</filename> file:
952 <literallayout class='monospaced'>
953 KBUILD_DEFCONFIG_common-pc ?= "/home/scottrif/configfiles/my_defconfig_file"
954 </literallayout>
948 </para> 955 </para>
949 956
950 <para> 957 <para>
@@ -990,14 +997,6 @@
990 to an existing kernel, changing or adding recipes to the kernel 997 to an existing kernel, changing or adding recipes to the kernel
991 that are needed to support specific hardware features, or even 998 that are needed to support specific hardware features, or even
992 altering the source code itself. 999 altering the source code itself.
993 <note>
994 You can also use the <filename>yocto-kernel</filename> script
995 found in the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
996 under <filename>scripts</filename> to manage kernel patches and configuration.
997 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
998 section in the Yocto Project Board Support Packages (BSP)
999 Developer's Guide for more information.
1000 </note>
1001 </para> 1000 </para>
1002 1001
1003 <para> 1002 <para>
@@ -1007,12 +1006,10 @@
1007 code file. 1006 code file.
1008 Applying the patch and booting the modified image causes the added 1007 Applying the patch and booting the modified image causes the added
1009 messages to appear on the emulator's console. 1008 messages to appear on the emulator's console.
1010 <note> 1009 The example is a continuation of the setup procedure found in
1011 The example is a continuation of the setup procedure found in 1010 the
1012 the 1011 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using <filename>devtool</filename></link>"
1013 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop using <filename>devtool</filename></link>" 1012 Section.
1014 Section.
1015 </note>
1016 <orderedlist> 1013 <orderedlist>
1017 <listitem><para> 1014 <listitem><para>
1018 <emphasis>Check Out the Kernel Source Files:</emphasis> 1015 <emphasis>Check Out the Kernel Source Files:</emphasis>
@@ -1161,7 +1158,7 @@
1161 <filename>meta-mylayer</filename>. 1158 <filename>meta-mylayer</filename>.
1162 <note> 1159 <note>
1163 See Step 3 of the 1160 See Step 3 of the
1164 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop using devtool</link>" 1161 "<link linkend='getting-ready-to-develop-using-devtool'>Getting Ready to Develop Using devtool</link>"
1165 section for information on setting up this layer. 1162 section for information on setting up this layer.
1166 </note> 1163 </note>
1167 <literallayout class='monospaced'> 1164 <literallayout class='monospaced'>
@@ -1212,31 +1209,31 @@
1212 to an existing kernel, changing or adding recipes to the kernel 1209 to an existing kernel, changing or adding recipes to the kernel
1213 that are needed to support specific hardware features, or even 1210 that are needed to support specific hardware features, or even
1214 altering the source code itself. 1211 altering the source code itself.
1215 <note>
1216 You can also use the <filename>yocto-kernel</filename> script
1217 found in the
1218 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
1219 under <filename>scripts</filename> to manage kernel patches
1220 and configuration.
1221 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
1222 section in the Yocto Project Board Support Packages (BSP)
1223 Developer's Guide for more information.
1224 </note>
1225 </para> 1212 </para>
1226 1213
1227 <para> 1214 <para>
1228 This example creates a simple patch by adding some QEMU emulator 1215 The example in this section creates a simple patch by adding some
1229 console output at boot time through <filename>printk</filename> 1216 QEMU emulator console output at boot time through
1230 statements in the kernel's <filename>calibrate.c</filename> source 1217 <filename>printk</filename> statements in the kernel's
1231 code file. 1218 <filename>calibrate.c</filename> source code file.
1232 Applying the patch and booting the modified image causes the added 1219 Applying the patch and booting the modified image causes the added
1233 messages to appear on the emulator's console. 1220 messages to appear on the emulator's console.
1234 <note> 1221 The example is a continuation of the setup procedure found in
1235 The example is a continuation of the setup procedure found in 1222 the
1236 the 1223 "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
1237 "<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>" 1224 Section.
1238 Section. 1225 </para>
1239 </note> 1226
1227 <para>
1228 Although this example uses Git and shell commands to generate the
1229 patch, you could use the <filename>yocto-kernel</filename> script
1230 found in the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
1231 under <filename>scripts</filename> to add and manage kernel
1232 patches and configuration.
1233 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
1234 section in the Yocto Project Board Support Packages (BSP)
1235 Developer's Guide for more information on the
1236 <filename>yocto-kernel</filename> script.
1240 <orderedlist> 1237 <orderedlist>
1241 <listitem><para> 1238 <listitem><para>
1242 <emphasis>Edit the Source Files</emphasis> 1239 <emphasis>Edit the Source Files</emphasis>
@@ -2115,114 +2112,6 @@
2115 </para> 2112 </para>
2116 </section> 2113 </section>
2117 2114
2118 <section id='iteratively-modifying-source-code'>
2119 <title>Iteratively Modifying Source Code</title>
2120
2121 <para>
2122 If you do not have existing patches or configuration files and
2123 you are using traditional kernel development methods,
2124 you can iteratively generate them from within the BitBake build
2125 environment as described within this section.
2126 During an iterative workflow, running a previously completed BitBake
2127 task causes BitBake to invalidate the tasks that follow the
2128 completed task in the build sequence.
2129 Invalidated tasks rebuild the next time you run the build using
2130 BitBake.
2131 </para>
2132
2133 <para>
2134 As you read this section, be sure to substitute the name
2135 of your Linux kernel recipe for the term
2136 "linux-yocto".
2137 </para>
2138
2139 <para>
2140 You can experiment with source code changes and create a
2141 simple patch without leaving the BitBake environment.
2142 To get started, be sure to complete a build at
2143 least through the kernel configuration task:
2144 <literallayout class='monospaced'>
2145 $ bitbake linux-yocto -c kernel_configme -f
2146 </literallayout>
2147 Taking this step ensures you have the sources prepared
2148 and the configuration completed.
2149 You can find the sources in the build directory within the
2150 <filename>source/</filename> directory, which is a symlink
2151 (i.e. <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}/source</filename>).
2152 The <filename>source/</filename> directory expands to
2153 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build/source</filename>.
2154 The directory pointed to by the
2155 <filename>source/</filename> symlink is also known as
2156 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink><filename>}</filename>.
2157 </para>
2158
2159 <para>
2160 You can edit the sources as you would any other Linux source
2161 tree.
2162 However, keep in mind that you will lose changes if you
2163 trigger the
2164 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
2165 task for the recipe.
2166 You can avoid triggering this task by not using BitBake to
2167 run the
2168 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>cleanall</filename></ulink>,
2169 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>cleansstate</filename></ulink>,
2170 or forced
2171 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>fetch</filename></ulink>
2172 commands.
2173 Also, do not modify the recipe itself while working
2174 with temporary changes or BitBake might run the
2175 <filename>fetch</filename> command depending on the
2176 changes to the recipe.
2177 </para>
2178
2179 <para>
2180 To test your temporary changes, instruct BitBake to run the
2181 <filename>compile</filename> again.
2182 The <filename>-f</filename> option forces the command to run
2183 even though BitBake might think it has already done so:
2184 <literallayout class='monospaced'>
2185 $ bitbake linux-yocto -c compile -f
2186 </literallayout>
2187 If the compile fails, you can update the sources and repeat
2188 the <filename>compile</filename>.
2189 Once compilation is successful, you can inspect and test
2190 the resulting build (i.e. kernel, modules, and so forth) from
2191 the following build directory:
2192 <literallayout class='monospaced'>
2193 ${WORKDIR}/linux-${PACKAGE_ARCH}-${LINUX_KERNEL_TYPE}-build
2194 </literallayout>
2195 Alternatively, you can run the <filename>deploy</filename>
2196 command to place the kernel image in the
2197 <filename>tmp/deploy/images</filename> directory:
2198 <literallayout class='monospaced'>
2199 $ bitbake linux-yocto -c deploy
2200 </literallayout>
2201 And, of course, you can perform the remaining installation and
2202 packaging steps by issuing:
2203 <literallayout class='monospaced'>
2204 $ bitbake linux-yocto
2205 </literallayout>
2206 </para>
2207
2208 <para>
2209 For rapid iterative development, the edit-compile-repeat loop
2210 described in this section is preferable to rebuilding the
2211 entire recipe because the installation and packaging tasks
2212 are very time consuming.
2213 </para>
2214
2215 <para>
2216 Once you are satisfied with your source code modifications,
2217 you can make them permanent by generating patches and
2218 applying them to the
2219 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2220 statement as described in the
2221 "<link linkend='applying-patches'>Applying Patches</link>"
2222 section.
2223 </para>
2224 </section>
2225
2226 <section id='working-with-your-own-sources'> 2115 <section id='working-with-your-own-sources'>
2227 <title>Working With Your Own Sources</title> 2116 <title>Working With Your Own Sources</title>
2228 2117
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index a7ce72b8ef..fbecc13875 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -129,10 +129,12 @@
129 the LTSI kernel is <filename>linux-yocto-4.1</filename>. 129 the LTSI kernel is <filename>linux-yocto-4.1</filename>.
130 </para></listitem> 130 </para></listitem>
131 <listitem><para> 131 <listitem><para>
132 <filename>linux-yocto-4.1</filename>, 132 For Yocto Project release 2.4, the LTSI kernel is
133 <filename>linux-yocto-4.4</filename>, and 133 <filename>linux-yocto-4.9</filename>
134 <filename>linux-yocto-4.9</filename> are all LTS 134 </para></listitem>
135 kernels. 135 <listitem><para>
136 <filename>linux-yocto-4.4</filename> is an LTS
137 kernel.
136 </para></listitem> 138 </para></listitem>
137 </itemizedlist> 139 </itemizedlist>
138 </note> 140 </note>