diff options
Diffstat (limited to 'documentation/kernel-dev/common.rst')
-rw-r--r-- | documentation/kernel-dev/common.rst | 795 |
1 files changed, 316 insertions, 479 deletions
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst index 58adcc9b70..fda41694dc 100644 --- a/documentation/kernel-dev/common.rst +++ b/documentation/kernel-dev/common.rst | |||
@@ -52,12 +52,11 @@ image and ready to make modifications as described in the | |||
52 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | 52 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" |
53 | section: | 53 | section: |
54 | 54 | ||
55 | 1. *Initialize the BitBake Environment:* Before building an extensible | 55 | #. *Initialize the BitBake Environment:* |
56 | SDK, you need to initialize the BitBake build environment by sourcing | 56 | you need to initialize the BitBake build environment by sourcing |
57 | the build environment script (i.e. :ref:`structure-core-script`): | 57 | the build environment script (i.e. :ref:`structure-core-script`):: |
58 | :: | ||
59 | 58 | ||
60 | $ cd ~/poky | 59 | $ cd poky |
61 | $ source oe-init-build-env | 60 | $ source oe-init-build-env |
62 | 61 | ||
63 | .. note:: | 62 | .. note:: |
@@ -67,34 +66,28 @@ section: | |||
67 | (i.e. ``poky``) have been cloned using Git and the local repository is named | 66 | (i.e. ``poky``) have been cloned using Git and the local repository is named |
68 | "poky". | 67 | "poky". |
69 | 68 | ||
70 | 2. *Prepare Your local.conf File:* By default, the | 69 | #. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable |
71 | :term:`MACHINE` variable is set to | 70 | is set to "qemux86-64", which is fine if you are building for the QEMU |
72 | "qemux86-64", which is fine if you are building for the QEMU emulator | 71 | emulator in 64-bit mode. However, if you are not, you need to set the |
73 | in 64-bit mode. However, if you are not, you need to set the | 72 | :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file |
74 | ``MACHINE`` variable appropriately in your ``conf/local.conf`` file | 73 | found in the :term:`Build Directory` (i.e. ``poky/build`` in this example). |
75 | found in the | ||
76 | :term:`Build Directory` (i.e. | ||
77 | ``~/poky/build`` in this example). | ||
78 | 74 | ||
79 | Also, since you are preparing to work on the kernel image, you need | 75 | Also, since you are preparing to work on the kernel image, you need |
80 | to set the | 76 | to set the :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable to include |
81 | :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` | 77 | kernel modules. |
82 | variable to include kernel modules. | ||
83 | 78 | ||
84 | In this example we wish to build for qemux86 so we must set the | 79 | In this example we wish to build for qemux86 so we must set the |
85 | ``MACHINE`` variable to "qemux86" and also add the "kernel-modules". | 80 | :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules". |
86 | As described we do this by appending to ``conf/local.conf``: | 81 | As described we do this by appending to ``conf/local.conf``:: |
87 | :: | ||
88 | 82 | ||
89 | MACHINE = "qemux86" | 83 | MACHINE = "qemux86" |
90 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" | 84 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" |
91 | 85 | ||
92 | 3. *Create a Layer for Patches:* You need to create a layer to hold | 86 | #. *Create a Layer for Patches:* You need to create a layer to hold |
93 | patches created for the kernel image. You can use the | 87 | patches created for the kernel image. You can use the |
94 | ``bitbake-layers create-layer`` command as follows: | 88 | ``bitbake-layers create-layer`` command as follows:: |
95 | :: | ||
96 | 89 | ||
97 | $ cd ~/poky/build | 90 | $ cd poky/build |
98 | $ bitbake-layers create-layer ../../meta-mylayer | 91 | $ bitbake-layers create-layer ../../meta-mylayer |
99 | NOTE: Starting bitbake server... | 92 | NOTE: Starting bitbake server... |
100 | Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' | 93 | Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' |
@@ -104,92 +97,29 @@ section: | |||
104 | 97 | ||
105 | For background information on working with common and BSP layers, | 98 | For background information on working with common and BSP layers, |
106 | see the | 99 | see the |
107 | ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 100 | ":ref:`dev-manual/layers:understanding and creating layers`" |
108 | section in the Yocto Project Development Tasks Manual and the | 101 | section in the Yocto Project Development Tasks Manual and the |
109 | ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board | 102 | ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board |
110 | Support (BSP) Developer's Guide, respectively. For information on how to | 103 | Support (BSP) Developer's Guide, respectively. For information on how to |
111 | use the ``bitbake-layers create-layer`` command to quickly set up a layer, | 104 | use the ``bitbake-layers create-layer`` command to quickly set up a layer, |
112 | see the | 105 | see the |
113 | ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" | 106 | ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" |
114 | section in the Yocto Project Development Tasks Manual. | 107 | section in the Yocto Project Development Tasks Manual. |
115 | 108 | ||
116 | 4. *Inform the BitBake Build Environment About Your Layer:* As directed | 109 | #. *Inform the BitBake Build Environment About Your Layer:* As directed |
117 | when you created your layer, you need to add the layer to the | 110 | when you created your layer, you need to add the layer to the |
118 | :term:`BBLAYERS` variable in the | 111 | :term:`BBLAYERS` variable in the |
119 | ``bblayers.conf`` file as follows: | 112 | ``bblayers.conf`` file as follows:: |
120 | :: | ||
121 | 113 | ||
122 | $ cd ~/poky/build | 114 | $ cd poky/build |
123 | $ bitbake-layers add-layer ../../meta-mylayer | 115 | $ bitbake-layers add-layer ../../meta-mylayer |
124 | NOTE: Starting bitbake server... | 116 | NOTE: Starting bitbake server... |
125 | $ | 117 | $ |
126 | 118 | ||
127 | 5. *Build the Extensible SDK:* Use BitBake to build the extensible SDK | 119 | #. *Build the Clean Image:* The final step in preparing to work on the |
128 | specifically for use with images to be run using QEMU: | 120 | kernel is to build an initial image using ``bitbake``:: |
129 | :: | ||
130 | |||
131 | $ cd ~/poky/build | ||
132 | $ bitbake core-image-minimal -c populate_sdk_ext | ||
133 | |||
134 | Once | ||
135 | the build finishes, you can find the SDK installer file (i.e. | ||
136 | ``*.sh`` file) in the following directory: | ||
137 | :: | ||
138 | |||
139 | ~/poky/build/tmp/deploy/sdk | ||
140 | |||
141 | For this example, the installer file is named | ||
142 | ``poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh``. | ||
143 | |||
144 | 6. *Install the Extensible SDK:* Use the following command to install | ||
145 | the SDK. For this example, install the SDK in the default | ||
146 | ``~/poky_sdk`` directory: | ||
147 | :: | ||
148 | |||
149 | $ cd ~/poky/build/tmp/deploy/sdk | ||
150 | $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh | ||
151 | Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO; | ||
152 | ============================================================================ | ||
153 | Enter target directory for SDK (default: ~/poky_sdk): | ||
154 | You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y | ||
155 | Extracting SDK......................................done | ||
156 | Setting it up... | ||
157 | Extracting buildtools... | ||
158 | Preparing build system... | ||
159 | Parsing recipes: 100% |#################################################################| Time: 0:00:52 | ||
160 | Initializing tasks: 100% |############## ###############################################| Time: 0:00:04 | ||
161 | Checking sstate mirror object availability: 100% |######################################| Time: 0:00:00 | ||
162 | Parsing recipes: 100% |#################################################################| Time: 0:00:33 | ||
163 | Initializing tasks: 100% |##############################################################| Time: 0:00:00 | ||
164 | done | ||
165 | SDK has been successfully set up and is ready to be used. | ||
166 | Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. | ||
167 | $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux | ||
168 | |||
169 | |||
170 | 7. *Set Up a New Terminal to Work With the Extensible SDK:* You must set | ||
171 | up a new terminal to work with the SDK. You cannot use the same | ||
172 | BitBake shell used to build the installer. | ||
173 | |||
174 | After opening a new shell, run the SDK environment setup script as | ||
175 | directed by the output from installing the SDK: | ||
176 | :: | ||
177 | |||
178 | $ source ~/poky_sdk/environment-setup-i586-poky-linux | ||
179 | "SDK environment now set up; additionally you may now run devtool to perform development tasks. | ||
180 | Run devtool --help for further details. | ||
181 | |||
182 | .. note:: | ||
183 | |||
184 | If you get a warning about attempting to use the extensible SDK in | ||
185 | an environment set up to run BitBake, you did not use a new shell. | ||
186 | |||
187 | 8. *Build the Clean Image:* The final step in preparing to work on the | ||
188 | kernel is to build an initial image using ``devtool`` in the new | ||
189 | terminal you just set up and initialized for SDK work: | ||
190 | :: | ||
191 | 121 | ||
192 | $ devtool build-image | 122 | $ bitbake core-image-minimal |
193 | Parsing recipes: 100% |##########################################| Time: 0:00:05 | 123 | Parsing recipes: 100% |##########################################| Time: 0:00:05 |
194 | Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors. | 124 | Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors. |
195 | WARNING: No packages to add, building image core-image-minimal unmodified | 125 | WARNING: No packages to add, building image core-image-minimal unmodified |
@@ -201,7 +131,6 @@ section: | |||
201 | NOTE: Executing SetScene Tasks | 131 | NOTE: Executing SetScene Tasks |
202 | NOTE: Executing RunQueue Tasks | 132 | NOTE: Executing RunQueue Tasks |
203 | NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded. | 133 | NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded. |
204 | NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86 | ||
205 | 134 | ||
206 | If you were | 135 | If you were |
207 | building for actual hardware and not for emulation, you could flash | 136 | building for actual hardware and not for emulation, you could flash |
@@ -211,7 +140,7 @@ section: | |||
211 | Wiki page. | 140 | Wiki page. |
212 | 141 | ||
213 | At this point you have set up to start making modifications to the | 142 | At this point you have set up to start making modifications to the |
214 | kernel by using the extensible SDK. For a continued example, see the | 143 | kernel. For a continued example, see the |
215 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | 144 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" |
216 | section. | 145 | section. |
217 | 146 | ||
@@ -229,7 +158,7 @@ this procedure leaves you ready to make modifications to the kernel | |||
229 | source as described in the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" | 158 | source as described in the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" |
230 | section: | 159 | section: |
231 | 160 | ||
232 | 1. *Initialize the BitBake Environment:* Before you can do anything | 161 | #. *Initialize the BitBake Environment:* Before you can do anything |
233 | using BitBake, you need to initialize the BitBake build environment | 162 | using BitBake, you need to initialize the BitBake build environment |
234 | by sourcing the build environment script (i.e. | 163 | by sourcing the build environment script (i.e. |
235 | :ref:`structure-core-script`). | 164 | :ref:`structure-core-script`). |
@@ -237,10 +166,9 @@ section: | |||
237 | checked out for ``poky`` is the Yocto Project &DISTRO_NAME; branch. If | 166 | checked out for ``poky`` is the Yocto Project &DISTRO_NAME; branch. If |
238 | you need to checkout out the &DISTRO_NAME; branch, see the | 167 | you need to checkout out the &DISTRO_NAME; branch, see the |
239 | ":ref:`dev-manual/start:checking out by branch in poky`" | 168 | ":ref:`dev-manual/start:checking out by branch in poky`" |
240 | section in the Yocto Project Development Tasks Manual. | 169 | section in the Yocto Project Development Tasks Manual:: |
241 | :: | ||
242 | 170 | ||
243 | $ cd ~/poky | 171 | $ cd poky |
244 | $ git branch | 172 | $ git branch |
245 | master | 173 | master |
246 | * &DISTRO_NAME_NO_CAP; | 174 | * &DISTRO_NAME_NO_CAP; |
@@ -253,14 +181,11 @@ section: | |||
253 | (i.e. ``poky``) have been cloned using Git and the local repository is named | 181 | (i.e. ``poky``) have been cloned using Git and the local repository is named |
254 | "poky". | 182 | "poky". |
255 | 183 | ||
256 | 2. *Prepare Your local.conf File:* By default, the | 184 | #. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable is |
257 | :term:`MACHINE` variable is set to | 185 | set to "qemux86-64", which is fine if you are building for the QEMU emulator |
258 | "qemux86-64", which is fine if you are building for the QEMU emulator | 186 | in 64-bit mode. However, if you are not, you need to set the :term:`MACHINE` |
259 | in 64-bit mode. However, if you are not, you need to set the | 187 | variable appropriately in your ``conf/local.conf`` file found in the |
260 | ``MACHINE`` variable appropriately in your ``conf/local.conf`` file | 188 | :term:`Build Directory` (i.e. ``poky/build`` in this example). |
261 | found in the | ||
262 | :term:`Build Directory` (i.e. | ||
263 | ``~/poky/build`` in this example). | ||
264 | 189 | ||
265 | Also, since you are preparing to work on the kernel image, you need | 190 | Also, since you are preparing to work on the kernel image, you need |
266 | to set the | 191 | to set the |
@@ -268,19 +193,17 @@ section: | |||
268 | variable to include kernel modules. | 193 | variable to include kernel modules. |
269 | 194 | ||
270 | In this example we wish to build for qemux86 so we must set the | 195 | In this example we wish to build for qemux86 so we must set the |
271 | ``MACHINE`` variable to "qemux86" and also add the "kernel-modules". | 196 | :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules". |
272 | As described we do this by appending to ``conf/local.conf``: | 197 | As described we do this by appending to ``conf/local.conf``:: |
273 | :: | ||
274 | 198 | ||
275 | MACHINE = "qemux86" | 199 | MACHINE = "qemux86" |
276 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" | 200 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" |
277 | 201 | ||
278 | 3. *Create a Layer for Patches:* You need to create a layer to hold | 202 | #. *Create a Layer for Patches:* You need to create a layer to hold |
279 | patches created for the kernel image. You can use the | 203 | patches created for the kernel image. You can use the |
280 | ``bitbake-layers create-layer`` command as follows: | 204 | ``bitbake-layers create-layer`` command as follows:: |
281 | :: | ||
282 | 205 | ||
283 | $ cd ~/poky/build | 206 | $ cd poky/build |
284 | $ bitbake-layers create-layer ../../meta-mylayer | 207 | $ bitbake-layers create-layer ../../meta-mylayer |
285 | NOTE: Starting bitbake server... | 208 | NOTE: Starting bitbake server... |
286 | Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' | 209 | Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' |
@@ -289,27 +212,26 @@ section: | |||
289 | 212 | ||
290 | For background information on working with common and BSP layers, | 213 | For background information on working with common and BSP layers, |
291 | see the | 214 | see the |
292 | ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 215 | ":ref:`dev-manual/layers:understanding and creating layers`" |
293 | section in the Yocto Project Development Tasks Manual and the | 216 | section in the Yocto Project Development Tasks Manual and the |
294 | ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board | 217 | ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board |
295 | Support (BSP) Developer's Guide, respectively. For information on how to | 218 | Support (BSP) Developer's Guide, respectively. For information on how to |
296 | use the ``bitbake-layers create-layer`` command to quickly set up a layer, | 219 | use the ``bitbake-layers create-layer`` command to quickly set up a layer, |
297 | see the | 220 | see the |
298 | ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" | 221 | ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" |
299 | section in the Yocto Project Development Tasks Manual. | 222 | section in the Yocto Project Development Tasks Manual. |
300 | 223 | ||
301 | 4. *Inform the BitBake Build Environment About Your Layer:* As directed | 224 | #. *Inform the BitBake Build Environment About Your Layer:* As directed |
302 | when you created your layer, you need to add the layer to the | 225 | when you created your layer, you need to add the layer to the |
303 | :term:`BBLAYERS` variable in the | 226 | :term:`BBLAYERS` variable in the |
304 | ``bblayers.conf`` file as follows: | 227 | ``bblayers.conf`` file as follows:: |
305 | :: | ||
306 | 228 | ||
307 | $ cd ~/poky/build | 229 | $ cd poky/build |
308 | $ bitbake-layers add-layer ../../meta-mylayer | 230 | $ bitbake-layers add-layer ../../meta-mylayer |
309 | NOTE: Starting bitbake server ... | 231 | NOTE: Starting bitbake server ... |
310 | $ | 232 | $ |
311 | 233 | ||
312 | 5. *Create a Local Copy of the Kernel Git Repository:* You can find Git | 234 | #. *Create a Local Copy of the Kernel Git Repository:* You can find Git |
313 | repositories of supported Yocto Project kernels organized under | 235 | repositories of supported Yocto Project kernels organized under |
314 | "Yocto Linux Kernel" in the Yocto Project Source Repositories at | 236 | "Yocto Linux Kernel" in the Yocto Project Source Repositories at |
315 | :yocto_git:`/`. | 237 | :yocto_git:`/`. |
@@ -321,16 +243,7 @@ section: | |||
321 | ``standard/base`` branch. | 243 | ``standard/base`` branch. |
322 | 244 | ||
323 | The following commands show how to create a local copy of the | 245 | The following commands show how to create a local copy of the |
324 | ``linux-yocto-4.12`` kernel and be in the ``standard/base`` branch. | 246 | ``linux-yocto-4.12`` kernel and be in the ``standard/base`` branch:: |
325 | |||
326 | .. note:: | ||
327 | |||
328 | The ``linux-yocto-4.12`` kernel can be used with the Yocto Project 2.4 | ||
329 | release and forward. | ||
330 | You cannot use the ``linux-yocto-4.12`` kernel with releases prior to | ||
331 | Yocto Project 2.4. | ||
332 | |||
333 | :: | ||
334 | 247 | ||
335 | $ cd ~ | 248 | $ cd ~ |
336 | $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base | 249 | $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base |
@@ -342,7 +255,14 @@ section: | |||
342 | Resolving deltas: 100% (5152604/5152604), done. Checking connectivity... done. | 255 | Resolving deltas: 100% (5152604/5152604), done. Checking connectivity... done. |
343 | Checking out files: 100% (59846/59846), done. | 256 | Checking out files: 100% (59846/59846), done. |
344 | 257 | ||
345 | 6. *Create a Local Copy of the Kernel Cache Git Repository:* For | 258 | .. note:: |
259 | |||
260 | The ``linux-yocto-4.12`` kernel can be used with the Yocto Project 2.4 | ||
261 | release and forward. | ||
262 | You cannot use the ``linux-yocto-4.12`` kernel with releases prior to | ||
263 | Yocto Project 2.4. | ||
264 | |||
265 | #. *Create a Local Copy of the Kernel Cache Git Repository:* For | ||
346 | simplicity, it is recommended that you create your copy of the kernel | 266 | simplicity, it is recommended that you create your copy of the kernel |
347 | cache Git repository outside of the | 267 | cache Git repository outside of the |
348 | :term:`Source Directory`, which is | 268 | :term:`Source Directory`, which is |
@@ -350,8 +270,7 @@ section: | |||
350 | the ``yocto-4.12`` branch. | 270 | the ``yocto-4.12`` branch. |
351 | 271 | ||
352 | The following commands show how to create a local copy of the | 272 | The following commands show how to create a local copy of the |
353 | ``yocto-kernel-cache`` and be in the ``yocto-4.12`` branch: | 273 | ``yocto-kernel-cache`` and switch to the ``yocto-4.12`` branch:: |
354 | :: | ||
355 | 274 | ||
356 | $ cd ~ | 275 | $ cd ~ |
357 | $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12 | 276 | $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12 |
@@ -365,8 +284,7 @@ section: | |||
365 | 284 | ||
366 | At this point, you are ready to start making modifications to the kernel | 285 | At this point, you are ready to start making modifications to the kernel |
367 | using traditional kernel development steps. For a continued example, see | 286 | using traditional kernel development steps. For a continued example, see |
368 | the "`Using Traditional Kernel Development to Patch the | 287 | the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" |
369 | Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__" | ||
370 | section. | 288 | section. |
371 | 289 | ||
372 | Creating and Preparing a Layer | 290 | Creating and Preparing a Layer |
@@ -378,7 +296,7 @@ layer contains its own :term:`BitBake` | |||
378 | append files (``.bbappend``) and provides a convenient mechanism to | 296 | append files (``.bbappend``) and provides a convenient mechanism to |
379 | create your own recipe files (``.bb``) as well as store and use kernel | 297 | create your own recipe files (``.bb``) as well as store and use kernel |
380 | patch files. For background information on working with layers, see the | 298 | patch files. For background information on working with layers, see the |
381 | ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 299 | ":ref:`dev-manual/layers:understanding and creating layers`" |
382 | section in the Yocto Project Development Tasks Manual. | 300 | section in the Yocto Project Development Tasks Manual. |
383 | 301 | ||
384 | .. note:: | 302 | .. note:: |
@@ -386,7 +304,7 @@ section in the Yocto Project Development Tasks Manual. | |||
386 | The Yocto Project comes with many tools that simplify tasks you need | 304 | The Yocto Project comes with many tools that simplify tasks you need |
387 | to perform. One such tool is the ``bitbake-layers create-layer`` | 305 | to perform. One such tool is the ``bitbake-layers create-layer`` |
388 | command, which simplifies creating a new layer. See the | 306 | command, which simplifies creating a new layer. See the |
389 | ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" | 307 | ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" |
390 | section in the Yocto Project Development Tasks Manual for | 308 | section in the Yocto Project Development Tasks Manual for |
391 | information on how to use this script to quick set up a new layer. | 309 | information on how to use this script to quick set up a new layer. |
392 | 310 | ||
@@ -395,24 +313,17 @@ following section describes how to create a layer without the aid of | |||
395 | tools. These steps assume creation of a layer named ``mylayer`` in your | 313 | tools. These steps assume creation of a layer named ``mylayer`` in your |
396 | home directory: | 314 | home directory: |
397 | 315 | ||
398 | 1. *Create Structure*: Create the layer's structure: | 316 | #. *Create Structure*: Create the layer's structure:: |
399 | :: | ||
400 | 317 | ||
401 | $ cd $HOME | 318 | $ mkdir -p meta-mylayer/conf meta-mylayer/recipes-kernel/linux/linux-yocto |
402 | $ mkdir meta-mylayer | ||
403 | $ mkdir meta-mylayer/conf | ||
404 | $ mkdir meta-mylayer/recipes-kernel | ||
405 | $ mkdir meta-mylayer/recipes-kernel/linux | ||
406 | $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto | ||
407 | 319 | ||
408 | The ``conf`` directory holds your configuration files, while the | 320 | The ``conf`` directory holds your configuration files, while the |
409 | ``recipes-kernel`` directory holds your append file and eventual | 321 | ``recipes-kernel`` directory holds your append file and eventual |
410 | patch files. | 322 | patch files. |
411 | 323 | ||
412 | 2. *Create the Layer Configuration File*: Move to the | 324 | #. *Create the Layer Configuration File*: Move to the |
413 | ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as | 325 | ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as |
414 | follows: | 326 | follows:: |
415 | :: | ||
416 | 327 | ||
417 | # We have a conf and classes directory, add to BBPATH | 328 | # We have a conf and classes directory, add to BBPATH |
418 | BBPATH .= ":${LAYERDIR}" | 329 | BBPATH .= ":${LAYERDIR}" |
@@ -427,23 +338,22 @@ home directory: | |||
427 | 338 | ||
428 | Notice ``mylayer`` as part of the last three statements. | 339 | Notice ``mylayer`` as part of the last three statements. |
429 | 340 | ||
430 | 3. *Create the Kernel Recipe Append File*: Move to the | 341 | #. *Create the Kernel Recipe Append File*: Move to the |
431 | ``meta-mylayer/recipes-kernel/linux`` directory and create the | 342 | ``meta-mylayer/recipes-kernel/linux`` directory and create the |
432 | kernel's append file. This example uses the ``linux-yocto-4.12`` | 343 | kernel's append file. This example uses the ``linux-yocto-4.12`` |
433 | kernel. Thus, the name of the append file is | 344 | kernel. Thus, the name of the append file is |
434 | ``linux-yocto_4.12.bbappend``: | 345 | ``linux-yocto_4.12.bbappend``:: |
435 | :: | ||
436 | 346 | ||
437 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 347 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
438 | 348 | ||
439 | SRC_URI_append = " file://patch-file-one.patch" | 349 | SRC_URI += "file://patch-file-one.patch" |
440 | SRC_URI_append = " file://patch-file-two.patch" | 350 | SRC_URI += "file://patch-file-two.patch" |
441 | SRC_URI_append = " file://patch-file-three.patch" | 351 | SRC_URI += "file://patch-file-three.patch" |
442 | 352 | ||
443 | The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements | 353 | The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements |
444 | enable the OpenEmbedded build system to find patch files. For more | 354 | enable the OpenEmbedded build system to find patch files. For more |
445 | information on using append files, see the | 355 | information on using append files, see the |
446 | ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`" | 356 | ":ref:`dev-manual/layers:appending other layers metadata with your layer`" |
447 | section in the Yocto Project Development Tasks Manual. | 357 | section in the Yocto Project Development Tasks Manual. |
448 | 358 | ||
449 | Modifying an Existing Recipe | 359 | Modifying an Existing Recipe |
@@ -464,8 +374,8 @@ Modifying an existing recipe can consist of the following: | |||
464 | - :ref:`kernel-dev/common:changing the configuration` | 374 | - :ref:`kernel-dev/common:changing the configuration` |
465 | 375 | ||
466 | Before modifying an existing recipe, be sure that you have created a | 376 | Before modifying an existing recipe, be sure that you have created a |
467 | minimal, custom layer from which you can work. See the "`Creating and | 377 | minimal, custom layer from which you can work. See the |
468 | Preparing a Layer <#creating-and-preparing-a-layer>`__" section for | 378 | ":ref:`kernel-dev/common:creating and preparing a layer`" section for |
469 | information. | 379 | information. |
470 | 380 | ||
471 | Creating the Append File | 381 | Creating the Append File |
@@ -473,29 +383,27 @@ Creating the Append File | |||
473 | 383 | ||
474 | You create this file in your custom layer. You also name it accordingly | 384 | You create this file in your custom layer. You also name it accordingly |
475 | based on the linux-yocto recipe you are using. For example, if you are | 385 | based on the linux-yocto recipe you are using. For example, if you are |
476 | modifying the ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe, | 386 | modifying the ``meta/recipes-kernel/linux/linux-yocto_6.1.bb`` recipe, |
477 | the append file will typically be located as follows within your custom | 387 | the append file will typically be located as follows within your custom |
478 | layer: | 388 | layer: |
479 | 389 | ||
480 | .. code-block:: none | 390 | .. code-block:: none |
481 | 391 | ||
482 | your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend | 392 | your-layer/recipes-kernel/linux/linux-yocto_6.1.bbappend |
483 | 393 | ||
484 | The append file should initially extend the | 394 | The append file should initially extend the |
485 | :term:`FILESPATH` search path by | 395 | :term:`FILESPATH` search path by |
486 | prepending the directory that contains your files to the | 396 | prepending the directory that contains your files to the |
487 | :term:`FILESEXTRAPATHS` | 397 | :term:`FILESEXTRAPATHS` |
488 | variable as follows: | 398 | variable as follows:: |
489 | :: | ||
490 | 399 | ||
491 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 400 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
492 | 401 | ||
493 | The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}`` | 402 | The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}`` |
494 | expands to "linux-yocto" in the current directory for this example. If | 403 | expands to "linux-yocto" in the current directory for this example. If |
495 | you add any new files that modify the kernel recipe and you have | 404 | you add any new files that modify the kernel recipe and you have |
496 | extended ``FILESPATH`` as described above, you must place the files in | 405 | extended :term:`FILESPATH` as described above, you must place the files in |
497 | your layer in the following area: | 406 | your layer in the following area:: |
498 | :: | ||
499 | 407 | ||
500 | your-layer/recipes-kernel/linux/linux-yocto/ | 408 | your-layer/recipes-kernel/linux/linux-yocto/ |
501 | 409 | ||
@@ -509,36 +417,31 @@ As an example, consider the following append file used by the BSPs in | |||
509 | 417 | ||
510 | .. code-block:: none | 418 | .. code-block:: none |
511 | 419 | ||
512 | meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend | 420 | meta-yocto-bsp/recipes-kernel/linux/linux-yocto_6.1.bbappend |
513 | 421 | ||
514 | The following listing shows the file. Be aware that the actual commit ID | 422 | Here are the contents of this file. Be aware that the actual commit ID |
515 | strings in this example listing might be different than the actual | 423 | strings in this example listing might be different than the actual |
516 | strings in the file from the ``meta-yocto-bsp`` layer upstream. | 424 | strings in the file from the ``meta-yocto-bsp`` layer upstream:: |
517 | :: | ||
518 | |||
519 | KBRANCH_genericx86 = "standard/base" | ||
520 | KBRANCH_genericx86-64 = "standard/base" | ||
521 | 425 | ||
522 | KMACHINE_genericx86 ?= "common-pc" | 426 | KBRANCH:genericx86 = "v6.1/standard/base" |
523 | KMACHINE_genericx86-64 ?= "common-pc-64" | 427 | KBRANCH:genericx86-64 = "v6.1/standard/base" |
524 | KBRANCH_edgerouter = "standard/edgerouter" | 428 | KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone" |
525 | KBRANCH_beaglebone = "standard/beaglebone" | ||
526 | 429 | ||
527 | SRCREV_machine_genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19" | 430 | KMACHINE:genericx86 ?= "common-pc" |
528 | SRCREV_machine_genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19" | 431 | KMACHINE:genericx86-64 ?= "common-pc-64" |
529 | SRCREV_machine_edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d" | 432 | KMACHINE:beaglebone-yocto ?= "beaglebone" |
530 | SRCREV_machine_beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d" | ||
531 | 433 | ||
434 | SRCREV_machine:genericx86 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86" | ||
435 | SRCREV_machine:genericx86-64 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86" | ||
436 | SRCREV_machine:beaglebone-yocto ?= "423e1996694b61fbfc8ec3bf062fc6461d64fde1" | ||
532 | 437 | ||
533 | COMPATIBLE_MACHINE_genericx86 = "genericx86" | 438 | COMPATIBLE_MACHINE:genericx86 = "genericx86" |
534 | COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" | 439 | COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64" |
535 | COMPATIBLE_MACHINE_edgerouter = "edgerouter" | 440 | COMPATIBLE_MACHINE:beaglebone-yocto = "beaglebone-yocto" |
536 | COMPATIBLE_MACHINE_beaglebone = "beaglebone" | ||
537 | 441 | ||
538 | LINUX_VERSION_genericx86 = "4.12.7" | 442 | LINUX_VERSION:genericx86 = "6.1.30" |
539 | LINUX_VERSION_genericx86-64 = "4.12.7" | 443 | LINUX_VERSION:genericx86-64 = "6.1.30" |
540 | LINUX_VERSION_edgerouter = "4.12.10" | 444 | LINUX_VERSION:beaglebone-yocto = "6.1.20" |
541 | LINUX_VERSION_beaglebone = "4.12.10" | ||
542 | 445 | ||
543 | This append file | 446 | This append file |
544 | contains statements used to support several BSPs that ship with the | 447 | contains statements used to support several BSPs that ship with the |
@@ -573,19 +476,17 @@ the append file. | |||
573 | 476 | ||
574 | For example, suppose you had some configuration options in a file called | 477 | For example, suppose you had some configuration options in a file called |
575 | ``network_configs.cfg``. You can place that file inside a directory | 478 | ``network_configs.cfg``. You can place that file inside a directory |
576 | named ``linux-yocto`` and then add a ``SRC_URI`` statement such as the | 479 | named ``linux-yocto`` and then add a :term:`SRC_URI` statement such as the |
577 | following to the append file. When the OpenEmbedded build system builds | 480 | following to the append file. When the OpenEmbedded build system builds |
578 | the kernel, the configuration options are picked up and applied. | 481 | the kernel, the configuration options are picked up and applied:: |
579 | :: | ||
580 | 482 | ||
581 | SRC_URI += "file://network_configs.cfg" | 483 | SRC_URI += "file://network_configs.cfg" |
582 | 484 | ||
583 | To group related configurations into multiple files, you perform a | 485 | To group related configurations into multiple files, you perform a |
584 | similar procedure. Here is an example that groups separate | 486 | similar procedure. Here is an example that groups separate |
585 | configurations specifically for Ethernet and graphics into their own | 487 | configurations specifically for Ethernet and graphics into their own |
586 | files and adds the configurations by using a ``SRC_URI`` statement like | 488 | files and adds the configurations by using a :term:`SRC_URI` statement like |
587 | the following in your append file: | 489 | the following in your append file:: |
588 | :: | ||
589 | 490 | ||
590 | SRC_URI += "file://myconfig.cfg \ | 491 | SRC_URI += "file://myconfig.cfg \ |
591 | file://eth.cfg \ | 492 | file://eth.cfg \ |
@@ -599,7 +500,7 @@ recipe is processed. | |||
599 | 500 | ||
600 | .. note:: | 501 | .. note:: |
601 | 502 | ||
602 | Other methods exist to accomplish grouping and defining configuration | 503 | There are other ways of grouping and defining configuration |
603 | options. For example, if you are working with a local clone of the | 504 | options. For example, if you are working with a local clone of the |
604 | kernel repository, you could checkout the kernel's ``meta`` branch, | 505 | kernel repository, you could checkout the kernel's ``meta`` branch, |
605 | make your changes, and then push the changes to the local bare clone | 506 | make your changes, and then push the changes to the local bare clone |
@@ -609,9 +510,9 @@ recipe is processed. | |||
609 | added to the Yocto Project. | 510 | added to the Yocto Project. |
610 | 511 | ||
611 | In general, however, the Yocto Project maintainers take care of | 512 | In general, however, the Yocto Project maintainers take care of |
612 | moving the ``SRC_URI``-specified configuration options to the | 513 | moving the :term:`SRC_URI`-specified configuration options to the |
613 | kernel's ``meta`` branch. Not only is it easier for BSP developers to | 514 | kernel's ``meta`` branch. Not only is it easier for BSP developers |
614 | not have to worry about putting those configurations in the branch, | 515 | not to have to put those configurations in the branch, |
615 | but having the maintainers do it allows them to apply 'global' | 516 | but having the maintainers do it allows them to apply 'global' |
616 | knowledge about the kinds of common configuration options multiple | 517 | knowledge about the kinds of common configuration options multiple |
617 | BSPs in the tree are typically using. This allows for promotion of | 518 | BSPs in the tree are typically using. This allows for promotion of |
@@ -629,8 +530,7 @@ reference them in :term:`SRC_URI` | |||
629 | statements. | 530 | statements. |
630 | 531 | ||
631 | For example, you can apply a three-patch series by adding the following | 532 | For example, you can apply a three-patch series by adding the following |
632 | lines to your linux-yocto ``.bbappend`` file in your layer: | 533 | lines to your linux-yocto ``.bbappend`` file in your layer:: |
633 | :: | ||
634 | 534 | ||
635 | SRC_URI += "file://0001-first-change.patch" | 535 | SRC_URI += "file://0001-first-change.patch" |
636 | SRC_URI += "file://0002-second-change.patch" | 536 | SRC_URI += "file://0002-second-change.patch" |
@@ -660,19 +560,27 @@ If you have a complete, working Linux kernel ``.config`` file you want | |||
660 | to use for the configuration, as before, copy that file to the | 560 | to use for the configuration, as before, copy that file to the |
661 | appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux`` | 561 | appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux`` |
662 | directory, and rename the copied file to "defconfig". Then, add the | 562 | directory, and rename the copied file to "defconfig". Then, add the |
663 | following lines to the linux-yocto ``.bbappend`` file in your layer: | 563 | following lines to the linux-yocto ``.bbappend`` file in your layer:: |
664 | :: | ||
665 | 564 | ||
666 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 565 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
667 | SRC_URI += "file://defconfig" | 566 | SRC_URI += "file://defconfig" |
668 | 567 | ||
669 | The ``SRC_URI`` tells the build system how to search | 568 | The :term:`SRC_URI` tells the build system how to search |
670 | for the file, while the | 569 | for the file, while the |
671 | :term:`FILESEXTRAPATHS` | 570 | :term:`FILESEXTRAPATHS` |
672 | extends the :term:`FILESPATH` | 571 | extends the :term:`FILESPATH` |
673 | variable (search directories) to include the ``${PN}`` directory you | 572 | variable (search directories) to include the ``${PN}`` directory you |
674 | created to hold the configuration changes. | 573 | created to hold the configuration changes. |
675 | 574 | ||
575 | You can also use a regular ``defconfig`` file, as generated by the | ||
576 | :ref:`ref-tasks-savedefconfig` | ||
577 | task instead of a complete ``.config`` file. This only specifies the | ||
578 | non-default configuration values. You need to additionally set | ||
579 | :term:`KCONFIG_MODE` | ||
580 | in the linux-yocto ``.bbappend`` file in your layer:: | ||
581 | |||
582 | KCONFIG_MODE = "alldefconfig" | ||
583 | |||
676 | .. note:: | 584 | .. note:: |
677 | 585 | ||
678 | The build system applies the configurations from the ``defconfig`` | 586 | The build system applies the configurations from the ``defconfig`` |
@@ -687,8 +595,7 @@ Generally speaking, the preferred approach is to determine the | |||
687 | incremental change you want to make and add that as a configuration | 595 | incremental change you want to make and add that as a configuration |
688 | fragment. For example, if you want to add support for a basic serial | 596 | fragment. For example, if you want to add support for a basic serial |
689 | console, create a file named ``8250.cfg`` in the ``${PN}`` directory | 597 | console, create a file named ``8250.cfg`` in the ``${PN}`` directory |
690 | with the following content (without indentation): | 598 | with the following content (without indentation):: |
691 | :: | ||
692 | 599 | ||
693 | CONFIG_SERIAL_8250=y | 600 | CONFIG_SERIAL_8250=y |
694 | CONFIG_SERIAL_8250_CONSOLE=y | 601 | CONFIG_SERIAL_8250_CONSOLE=y |
@@ -699,11 +606,10 @@ with the following content (without indentation): | |||
699 | CONFIG_SERIAL_CORE_CONSOLE=y | 606 | CONFIG_SERIAL_CORE_CONSOLE=y |
700 | 607 | ||
701 | Next, include this | 608 | Next, include this |
702 | configuration fragment and extend the ``FILESPATH`` variable in your | 609 | configuration fragment and extend the :term:`FILESPATH` variable in your |
703 | ``.bbappend`` file: | 610 | ``.bbappend`` file:: |
704 | :: | ||
705 | 611 | ||
706 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 612 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
707 | SRC_URI += "file://8250.cfg" | 613 | SRC_URI += "file://8250.cfg" |
708 | 614 | ||
709 | The next time you run BitBake to build the | 615 | The next time you run BitBake to build the |
@@ -711,7 +617,7 @@ Linux kernel, BitBake detects the change in the recipe and fetches and | |||
711 | applies the new configuration before building the kernel. | 617 | applies the new configuration before building the kernel. |
712 | 618 | ||
713 | For a detailed example showing how to configure the kernel, see the | 619 | For a detailed example showing how to configure the kernel, see the |
714 | "`Configuring the Kernel <#configuring-the-kernel>`__" section. | 620 | ":ref:`kernel-dev/common:configuring the kernel`" section. |
715 | 621 | ||
716 | Using an "In-Tree" ``defconfig`` File | 622 | Using an "In-Tree" ``defconfig`` File |
717 | -------------------------------------- | 623 | -------------------------------------- |
@@ -720,8 +626,7 @@ It might be desirable to have kernel configuration fragment support | |||
720 | through a ``defconfig`` file that is pulled from the kernel source tree | 626 | through a ``defconfig`` file that is pulled from the kernel source tree |
721 | for the configured machine. By default, the OpenEmbedded build system | 627 | for the configured machine. By default, the OpenEmbedded build system |
722 | looks for ``defconfig`` files in the layer used for Metadata, which is | 628 | looks for ``defconfig`` files in the layer used for Metadata, which is |
723 | "out-of-tree", and then configures them using the following: | 629 | "out-of-tree", and then configures them using the following:: |
724 | :: | ||
725 | 630 | ||
726 | SRC_URI += "file://defconfig" | 631 | SRC_URI += "file://defconfig" |
727 | 632 | ||
@@ -734,26 +639,24 @@ append files, you can direct the OpenEmbedded build system to use a | |||
734 | ``defconfig`` file that is "in-tree". | 639 | ``defconfig`` file that is "in-tree". |
735 | 640 | ||
736 | To specify an "in-tree" ``defconfig`` file, use the following statement | 641 | To specify an "in-tree" ``defconfig`` file, use the following statement |
737 | form: | 642 | form:: |
738 | :: | ||
739 | 643 | ||
740 | KBUILD_DEFCONFIG_KMACHINE ?= "defconfig_file" | 644 | KBUILD_DEFCONFIG:<machine> ?= "defconfig_file" |
741 | 645 | ||
742 | Here is an example | 646 | Here is an example that assigns the :term:`KBUILD_DEFCONFIG` variable utilizing |
743 | that assigns the ``KBUILD_DEFCONFIG`` variable based on "raspberrypi2" | 647 | an override for the "raspberrypi2" :term:`MACHINE` and provides the path to the |
744 | and provides the path to the "in-tree" ``defconfig`` file to be used for | 648 | "in-tree" ``defconfig`` file to be used for a Raspberry Pi 2, which is based on |
745 | a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset: | 649 | the Broadcom 2708/2709 chipset:: |
746 | :: | ||
747 | 650 | ||
748 | KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig" | 651 | KBUILD_DEFCONFIG:raspberrypi2 ?= "bcm2709_defconfig" |
749 | 652 | ||
750 | Aside from modifying your kernel recipe and providing your own | 653 | Aside from modifying your kernel recipe and providing your own |
751 | ``defconfig`` file, you need to be sure no files or statements set | 654 | ``defconfig`` file, you need to be sure no files or statements set |
752 | ``SRC_URI`` to use a ``defconfig`` other than your "in-tree" file (e.g. | 655 | :term:`SRC_URI` to use a ``defconfig`` other than your "in-tree" file (e.g. |
753 | a kernel's ``linux-``\ `machine`\ ``.inc`` file). In other words, if the | 656 | a kernel's ``linux-``\ `machine`\ ``.inc`` file). In other words, if the |
754 | build system detects a statement that identifies an "out-of-tree" | 657 | build system detects a statement that identifies an "out-of-tree" |
755 | ``defconfig`` file, that statement will override your | 658 | ``defconfig`` file, that statement will override your |
756 | ``KBUILD_DEFCONFIG`` variable. | 659 | :term:`KBUILD_DEFCONFIG` variable. |
757 | 660 | ||
758 | See the | 661 | See the |
759 | :term:`KBUILD_DEFCONFIG` | 662 | :term:`KBUILD_DEFCONFIG` |
@@ -763,7 +666,7 @@ Using ``devtool`` to Patch the Kernel | |||
763 | ===================================== | 666 | ===================================== |
764 | 667 | ||
765 | The steps in this procedure show you how you can patch the kernel using | 668 | The steps in this procedure show you how you can patch the kernel using |
766 | the extensible SDK and ``devtool``. | 669 | ``devtool``. |
767 | 670 | ||
768 | .. note:: | 671 | .. note:: |
769 | 672 | ||
@@ -784,9 +687,8 @@ modified image causes the added messages to appear on the emulator's | |||
784 | console. The example is a continuation of the setup procedure found in | 687 | console. The example is a continuation of the setup procedure found in |
785 | the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Section. | 688 | the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Section. |
786 | 689 | ||
787 | 1. *Check Out the Kernel Source Files:* First you must use ``devtool`` | 690 | #. *Check Out the Kernel Source Files:* First you must use ``devtool`` |
788 | to checkout the kernel source code in its workspace. Be sure you are | 691 | to checkout the kernel source code in its workspace. |
789 | in the terminal set up to do work with the extensible SDK. | ||
790 | 692 | ||
791 | .. note:: | 693 | .. note:: |
792 | 694 | ||
@@ -794,15 +696,14 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se | |||
794 | ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" | 696 | ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" |
795 | section for more information. | 697 | section for more information. |
796 | 698 | ||
797 | Use the following ``devtool`` command to check out the code: | 699 | Use the following ``devtool`` command to check out the code:: |
798 | :: | ||
799 | 700 | ||
800 | $ devtool modify linux-yocto | 701 | $ devtool modify linux-yocto |
801 | 702 | ||
802 | .. note:: | 703 | .. note:: |
803 | 704 | ||
804 | During the checkout operation, a bug exists that could cause | 705 | During the checkout operation, there is a bug that could cause |
805 | errors such as the following to appear: | 706 | errors such as the following: |
806 | 707 | ||
807 | .. code-block:: none | 708 | .. code-block:: none |
808 | 709 | ||
@@ -814,21 +715,19 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se | |||
814 | You can safely ignore these messages. The source code is correctly | 715 | You can safely ignore these messages. The source code is correctly |
815 | checked out. | 716 | checked out. |
816 | 717 | ||
817 | 2. *Edit the Source Files* Follow these steps to make some simple | 718 | #. *Edit the Source Files* Follow these steps to make some simple |
818 | changes to the source files: | 719 | changes to the source files: |
819 | 720 | ||
820 | 1. *Change the working directory*: In the previous step, the output | 721 | #. *Change the working directory*: In the previous step, the output |
821 | noted where you can find the source files (e.g. | 722 | noted where you can find the source files (e.g. |
822 | ``~/poky_sdk/workspace/sources/linux-yocto``). Change to where the | 723 | ``poky_sdk/workspace/sources/linux-yocto``). Change to where the |
823 | kernel source code is before making your edits to the | 724 | kernel source code is before making your edits to the |
824 | ``calibrate.c`` file: | 725 | ``calibrate.c`` file:: |
825 | :: | ||
826 | 726 | ||
827 | $ cd ~/poky_sdk/workspace/sources/linux-yocto | 727 | $ cd poky_sdk/workspace/sources/linux-yocto |
828 | 728 | ||
829 | 2. *Edit the source file*: Edit the ``init/calibrate.c`` file to have | 729 | #. *Edit the source file*: Edit the ``init/calibrate.c`` file to have |
830 | the following changes: | 730 | the following changes:: |
831 | :: | ||
832 | 731 | ||
833 | void calibrate_delay(void) | 732 | void calibrate_delay(void) |
834 | { | 733 | { |
@@ -847,15 +746,17 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se | |||
847 | . | 746 | . |
848 | . | 747 | . |
849 | 748 | ||
850 | 3. *Build the Updated Kernel Source:* To build the updated kernel | 749 | #. *Build the Updated Kernel Source:* To build the updated kernel |
851 | source, use ``devtool``: | 750 | source, use ``devtool``:: |
852 | :: | ||
853 | 751 | ||
854 | $ devtool build linux-yocto | 752 | $ devtool build linux-yocto |
855 | 753 | ||
856 | 4. *Create the Image With the New Kernel:* Use the | 754 | #. *Create the Image With the New Kernel:* Use the |
857 | ``devtool build-image`` command to create a new image that has the | 755 | ``devtool build-image`` command to create a new image that has the |
858 | new kernel. | 756 | new kernel:: |
757 | |||
758 | $ cd ~ | ||
759 | $ devtool build-image core-image-minimal | ||
859 | 760 | ||
860 | .. note:: | 761 | .. note:: |
861 | 762 | ||
@@ -865,21 +766,15 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se | |||
865 | :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>` | 766 | :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>` |
866 | Wiki Page. | 767 | Wiki Page. |
867 | 768 | ||
868 | :: | 769 | #. *Test the New Image:* For this example, you can run the new image |
869 | |||
870 | $ cd ~ | ||
871 | $ devtool build-image core-image-minimal | ||
872 | |||
873 | 5. *Test the New Image:* For this example, you can run the new image | ||
874 | using QEMU to verify your changes: | 770 | using QEMU to verify your changes: |
875 | 771 | ||
876 | 1. *Boot the image*: Boot the modified image in the QEMU emulator | 772 | #. *Boot the image*: Boot the modified image in the QEMU emulator |
877 | using this command: | 773 | using this command:: |
878 | :: | ||
879 | 774 | ||
880 | $ runqemu qemux86 | 775 | $ runqemu qemux86 |
881 | 776 | ||
882 | 2. *Verify the changes*: Log into the machine using ``root`` with no | 777 | #. *Verify the changes*: Log into the machine using ``root`` with no |
883 | password and then use the following shell command to scroll | 778 | password and then use the following shell command to scroll |
884 | through the console's boot output. | 779 | through the console's boot output. |
885 | 780 | ||
@@ -891,21 +786,18 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se | |||
891 | the results of your ``printk`` statements as part of the output | 786 | the results of your ``printk`` statements as part of the output |
892 | when you scroll down the console window. | 787 | when you scroll down the console window. |
893 | 788 | ||
894 | 6. *Stage and commit your changes*: Within your eSDK terminal, change | 789 | #. *Stage and commit your changes*: Change |
895 | your working directory to where you modified the ``calibrate.c`` file | 790 | your working directory to where you modified the ``calibrate.c`` file |
896 | and use these Git commands to stage and commit your changes: | 791 | and use these Git commands to stage and commit your changes:: |
897 | :: | ||
898 | 792 | ||
899 | $ cd ~/poky_sdk/workspace/sources/linux-yocto | 793 | $ cd poky_sdk/workspace/sources/linux-yocto |
900 | $ git status | 794 | $ git status |
901 | $ git add init/calibrate.c | 795 | $ git add init/calibrate.c |
902 | $ git commit -m "calibrate: Add printk example" | 796 | $ git commit -m "calibrate: Add printk example" |
903 | 797 | ||
904 | 7. *Export the Patches and Create an Append File:* To export your | 798 | #. *Export the Patches and Create an Append File:* To export your |
905 | commits as patches and create a ``.bbappend`` file, use the following | 799 | commits as patches and create a ``.bbappend`` file, use the following |
906 | command in the terminal used to work with the extensible SDK. This | 800 | command. This example uses the previously established layer named ``meta-mylayer``:: |
907 | example uses the previously established layer named ``meta-mylayer``. | ||
908 | :: | ||
909 | 801 | ||
910 | $ devtool finish linux-yocto ~/meta-mylayer | 802 | $ devtool finish linux-yocto ~/meta-mylayer |
911 | 803 | ||
@@ -919,22 +811,20 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se | |||
919 | finishes, the patches and the ``.bbappend`` file are located in the | 811 | finishes, the patches and the ``.bbappend`` file are located in the |
920 | ``~/meta-mylayer/recipes-kernel/linux`` directory. | 812 | ``~/meta-mylayer/recipes-kernel/linux`` directory. |
921 | 813 | ||
922 | 8. *Build the Image With Your Modified Kernel:* You can now build an | 814 | #. *Build the Image With Your Modified Kernel:* You can now build an |
923 | image that includes your kernel patches. Execute the following | 815 | image that includes your kernel patches. Execute the following |
924 | command from your | 816 | command from your :term:`Build Directory` in the terminal |
925 | :term:`Build Directory` in the terminal | 817 | set up to run BitBake:: |
926 | set up to run BitBake: | ||
927 | :: | ||
928 | 818 | ||
929 | $ cd ~/poky/build | 819 | $ cd poky/build |
930 | $ bitbake core-image-minimal | 820 | $ bitbake core-image-minimal |
931 | 821 | ||
932 | Using Traditional Kernel Development to Patch the Kernel | 822 | Using Traditional Kernel Development to Patch the Kernel |
933 | ======================================================== | 823 | ======================================================== |
934 | 824 | ||
935 | The steps in this procedure show you how you can patch the kernel using | 825 | The steps in this procedure show you how you can patch the kernel using |
936 | traditional kernel development (i.e. not using ``devtool`` and the | 826 | traditional kernel development (i.e. not using ``devtool`` |
937 | extensible SDK as described in the | 827 | as described in the |
938 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | 828 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" |
939 | section). | 829 | section). |
940 | 830 | ||
@@ -955,28 +845,25 @@ emulator console output at boot time through ``printk`` statements in | |||
955 | the kernel's ``calibrate.c`` source code file. Applying the patch and | 845 | the kernel's ``calibrate.c`` source code file. Applying the patch and |
956 | booting the modified image causes the added messages to appear on the | 846 | booting the modified image causes the added messages to appear on the |
957 | emulator's console. The example is a continuation of the setup procedure | 847 | emulator's console. The example is a continuation of the setup procedure |
958 | found in the "`Getting Ready for Traditional Kernel | 848 | found in the |
959 | Development <#getting-ready-for-traditional-kernel-development>`__" | 849 | ":ref:`kernel-dev/common:getting ready for traditional kernel development`" |
960 | Section. | 850 | Section. |
961 | 851 | ||
962 | 1. *Edit the Source Files* Prior to this step, you should have used Git | 852 | #. *Edit the Source Files* Prior to this step, you should have used Git |
963 | to create a local copy of the repository for your kernel. Assuming | 853 | to create a local copy of the repository for your kernel. Assuming |
964 | you created the repository as directed in the "`Getting Ready for | 854 | you created the repository as directed in the |
965 | Traditional Kernel | 855 | ":ref:`kernel-dev/common:getting ready for traditional kernel development`" |
966 | Development <#getting-ready-for-traditional-kernel-development>`__" | ||
967 | section, use the following commands to edit the ``calibrate.c`` file: | 856 | section, use the following commands to edit the ``calibrate.c`` file: |
968 | 857 | ||
969 | 1. *Change the working directory*: You need to locate the source | 858 | #. *Change the working directory*: You need to locate the source |
970 | files in the local copy of the kernel Git repository. Change to | 859 | files in the local copy of the kernel Git repository. Change to |
971 | where the kernel source code is before making your edits to the | 860 | where the kernel source code is before making your edits to the |
972 | ``calibrate.c`` file: | 861 | ``calibrate.c`` file:: |
973 | :: | ||
974 | 862 | ||
975 | $ cd ~/linux-yocto-4.12/init | 863 | $ cd ~/linux-yocto-4.12/init |
976 | 864 | ||
977 | 2. *Edit the source file*: Edit the ``calibrate.c`` file to have the | 865 | #. *Edit the source file*: Edit the ``calibrate.c`` file to have the |
978 | following changes: | 866 | following changes:: |
979 | :: | ||
980 | 867 | ||
981 | void calibrate_delay(void) | 868 | void calibrate_delay(void) |
982 | { | 869 | { |
@@ -995,9 +882,8 @@ Section. | |||
995 | . | 882 | . |
996 | . | 883 | . |
997 | 884 | ||
998 | 2. *Stage and Commit Your Changes:* Use standard Git commands to stage | 885 | #. *Stage and Commit Your Changes:* Use standard Git commands to stage |
999 | and commit the changes you just made: | 886 | and commit the changes you just made:: |
1000 | :: | ||
1001 | 887 | ||
1002 | $ git add calibrate.c | 888 | $ git add calibrate.c |
1003 | $ git commit -m "calibrate.c - Added some printk statements" | 889 | $ git commit -m "calibrate.c - Added some printk statements" |
@@ -1006,24 +892,22 @@ Section. | |||
1006 | stage and commit your changes, the OpenEmbedded Build System will not | 892 | stage and commit your changes, the OpenEmbedded Build System will not |
1007 | pick up the changes. | 893 | pick up the changes. |
1008 | 894 | ||
1009 | 3. *Update Your local.conf File to Point to Your Source Files:* In | 895 | #. *Update Your local.conf File to Point to Your Source Files:* In |
1010 | addition to your ``local.conf`` file specifying to use | 896 | addition to your ``local.conf`` file specifying to use |
1011 | "kernel-modules" and the "qemux86" machine, it must also point to the | 897 | "kernel-modules" and the "qemux86" machine, it must also point to the |
1012 | updated kernel source files. Add | 898 | updated kernel source files. Add |
1013 | :term:`SRC_URI` and | 899 | :term:`SRC_URI` and |
1014 | :term:`SRCREV` statements similar | 900 | :term:`SRCREV` statements similar |
1015 | to the following to your ``local.conf``: | 901 | to the following to your ``local.conf``:: |
1016 | :: | ||
1017 | 902 | ||
1018 | $ cd ~/poky/build/conf | 903 | $ cd poky/build/conf |
1019 | 904 | ||
1020 | Add the following to the ``local.conf``: | 905 | Add the following to the ``local.conf``:: |
1021 | :: | ||
1022 | 906 | ||
1023 | SRC_URI_pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \ | 907 | SRC_URI:pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \ |
1024 | git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" | 908 | git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" |
1025 | SRCREV_meta_qemux86 = "${AUTOREV}" | 909 | SRCREV_meta:qemux86 = "${AUTOREV}" |
1026 | SRCREV_machine_qemux86 = "${AUTOREV}" | 910 | SRCREV_machine:qemux86 = "${AUTOREV}" |
1027 | 911 | ||
1028 | .. note:: | 912 | .. note:: |
1029 | 913 | ||
@@ -1032,23 +916,21 @@ Section. | |||
1032 | be sure to specify the correct branch and machine types. For this | 916 | be sure to specify the correct branch and machine types. For this |
1033 | example, the branch is ``standard/base`` and the machine is ``qemux86``. | 917 | example, the branch is ``standard/base`` and the machine is ``qemux86``. |
1034 | 918 | ||
1035 | 4. *Build the Image:* With the source modified, your changes staged and | 919 | #. *Build the Image:* With the source modified, your changes staged and |
1036 | committed, and the ``local.conf`` file pointing to the kernel files, | 920 | committed, and the ``local.conf`` file pointing to the kernel files, |
1037 | you can now use BitBake to build the image: | 921 | you can now use BitBake to build the image:: |
1038 | :: | ||
1039 | 922 | ||
1040 | $ cd ~/poky/build | 923 | $ cd poky/build |
1041 | $ bitbake core-image-minimal | 924 | $ bitbake core-image-minimal |
1042 | 925 | ||
1043 | 5. *Boot the image*: Boot the modified image in the QEMU emulator using | 926 | #. *Boot the image*: Boot the modified image in the QEMU emulator using |
1044 | this command. When prompted to login to the QEMU console, use "root" | 927 | this command. When prompted to login to the QEMU console, use "root" |
1045 | with no password: | 928 | with no password:: |
1046 | :: | ||
1047 | 929 | ||
1048 | $ cd ~/poky/build | 930 | $ cd poky/build |
1049 | $ runqemu qemux86 | 931 | $ runqemu qemux86 |
1050 | 932 | ||
1051 | 6. *Look for Your Changes:* As QEMU booted, you might have seen your | 933 | #. *Look for Your Changes:* As QEMU booted, you might have seen your |
1052 | changes rapidly scroll by. If not, use these commands to see your | 934 | changes rapidly scroll by. If not, use these commands to see your |
1053 | changes: | 935 | changes: |
1054 | 936 | ||
@@ -1060,55 +942,49 @@ Section. | |||
1060 | ``printk`` statements as part of the output when you scroll down the | 942 | ``printk`` statements as part of the output when you scroll down the |
1061 | console window. | 943 | console window. |
1062 | 944 | ||
1063 | 7. *Generate the Patch File:* Once you are sure that your patch works | 945 | #. *Generate the Patch File:* Once you are sure that your patch works |
1064 | correctly, you can generate a ``*.patch`` file in the kernel source | 946 | correctly, you can generate a ``*.patch`` file in the kernel source |
1065 | repository: | 947 | repository:: |
1066 | :: | ||
1067 | 948 | ||
1068 | $ cd ~/linux-yocto-4.12/init | 949 | $ cd ~/linux-yocto-4.12/init |
1069 | $ git format-patch -1 | 950 | $ git format-patch -1 |
1070 | 0001-calibrate.c-Added-some-printk-statements.patch | 951 | 0001-calibrate.c-Added-some-printk-statements.patch |
1071 | 952 | ||
1072 | 8. *Move the Patch File to Your Layer:* In order for subsequent builds | 953 | #. *Move the Patch File to Your Layer:* In order for subsequent builds |
1073 | to pick up patches, you need to move the patch file you created in | 954 | to pick up patches, you need to move the patch file you created in |
1074 | the previous step to your layer ``meta-mylayer``. For this example, | 955 | the previous step to your layer ``meta-mylayer``. For this example, |
1075 | the layer created earlier is located in your home directory as | 956 | the layer created earlier is located in your home directory as |
1076 | ``meta-mylayer``. When the layer was created using the | 957 | ``meta-mylayer``. When the layer was created using the |
1077 | ``yocto-create`` script, no additional hierarchy was created to | 958 | ``yocto-create`` script, no additional hierarchy was created to |
1078 | support patches. Before moving the patch file, you need to add | 959 | support patches. Before moving the patch file, you need to add |
1079 | additional structure to your layer using the following commands: | 960 | additional structure to your layer using the following commands:: |
1080 | :: | ||
1081 | 961 | ||
1082 | $ cd ~/meta-mylayer | 962 | $ cd ~/meta-mylayer |
1083 | $ mkdir recipes-kernel | 963 | $ mkdir -p recipes-kernel recipes-kernel/linux/linux-yocto |
1084 | $ mkdir recipes-kernel/linux | ||
1085 | $ mkdir recipes-kernel/linux/linux-yocto | ||
1086 | 964 | ||
1087 | Once you have created this | 965 | Once you have created this |
1088 | hierarchy in your layer, you can move the patch file using the | 966 | hierarchy in your layer, you can move the patch file using the |
1089 | following command: | 967 | following command:: |
1090 | :: | ||
1091 | 968 | ||
1092 | $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto | 969 | $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto |
1093 | 970 | ||
1094 | 9. *Create the Append File:* Finally, you need to create the | 971 | #. *Create the Append File:* Finally, you need to create the |
1095 | ``linux-yocto_4.12.bbappend`` file and insert statements that allow | 972 | ``linux-yocto_4.12.bbappend`` file and insert statements that allow |
1096 | the OpenEmbedded build system to find the patch. The append file | 973 | the OpenEmbedded build system to find the patch. The append file |
1097 | needs to be in your layer's ``recipes-kernel/linux`` directory and it | 974 | needs to be in your layer's ``recipes-kernel/linux`` directory and it |
1098 | must be named ``linux-yocto_4.12.bbappend`` and have the following | 975 | must be named ``linux-yocto_4.12.bbappend`` and have the following |
1099 | contents: | 976 | contents:: |
1100 | :: | ||
1101 | 977 | ||
1102 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 978 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
1103 | SRC_URI_append = "file://0001-calibrate.c-Added-some-printk-statements.patch" | 979 | SRC_URI += "file://0001-calibrate.c-Added-some-printk-statements.patch" |
1104 | 980 | ||
1105 | The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements | 981 | The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements |
1106 | enable the OpenEmbedded build system to find the patch file. | 982 | enable the OpenEmbedded build system to find the patch file. |
1107 | 983 | ||
1108 | For more information on append files and patches, see the "`Creating | 984 | For more information on append files and patches, see the |
1109 | the Append File <#creating-the-append-file>`__" and "`Applying | 985 | ":ref:`kernel-dev/common:creating the append file`" and |
1110 | Patches <#applying-patches>`__" sections. You can also see the | 986 | ":ref:`kernel-dev/common:applying patches`" sections. You can also see the |
1111 | ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`" | 987 | ":ref:`dev-manual/layers:appending other layers metadata with your layer`" |
1112 | section in the Yocto Project Development Tasks Manual. | 988 | section in the Yocto Project Development Tasks Manual. |
1113 | 989 | ||
1114 | .. note:: | 990 | .. note:: |
@@ -1116,11 +992,10 @@ Section. | |||
1116 | To build ``core-image-minimal`` again and see the effects of your patch, | 992 | To build ``core-image-minimal`` again and see the effects of your patch, |
1117 | you can essentially eliminate the temporary source files saved in | 993 | you can essentially eliminate the temporary source files saved in |
1118 | ``poky/build/tmp/work/...`` and residual effects of the build by entering | 994 | ``poky/build/tmp/work/...`` and residual effects of the build by entering |
1119 | the following sequence of commands: | 995 | the following sequence of commands:: |
1120 | :: | ||
1121 | 996 | ||
1122 | $ cd ~/poky/build | 997 | $ cd poky/build |
1123 | $ bitbake -c cleanall yocto-linux | 998 | $ bitbake -c cleanall linux-yocto |
1124 | $ bitbake core-image-minimal -c cleanall | 999 | $ bitbake core-image-minimal -c cleanall |
1125 | $ bitbake core-image-minimal | 1000 | $ bitbake core-image-minimal |
1126 | $ runqemu qemux86 | 1001 | $ runqemu qemux86 |
@@ -1141,8 +1016,8 @@ configuration fragments, and how to interactively modify your | |||
1141 | ``.config`` file to create the leanest kernel configuration file | 1016 | ``.config`` file to create the leanest kernel configuration file |
1142 | possible. | 1017 | possible. |
1143 | 1018 | ||
1144 | For more information on kernel configuration, see the "`Changing the | 1019 | For more information on kernel configuration, see the |
1145 | Configuration <#changing-the-configuration>`__" section. | 1020 | ":ref:`kernel-dev/common:changing the configuration`" section. |
1146 | 1021 | ||
1147 | Using ``menuconfig`` | 1022 | Using ``menuconfig`` |
1148 | --------------------- | 1023 | --------------------- |
@@ -1150,21 +1025,19 @@ Using ``menuconfig`` | |||
1150 | The easiest way to define kernel configurations is to set them through | 1025 | The easiest way to define kernel configurations is to set them through |
1151 | the ``menuconfig`` tool. This tool provides an interactive method with | 1026 | the ``menuconfig`` tool. This tool provides an interactive method with |
1152 | which to set kernel configurations. For general information on | 1027 | which to set kernel configurations. For general information on |
1153 | ``menuconfig``, see https://en.wikipedia.org/wiki/Menuconfig. | 1028 | ``menuconfig``, see :wikipedia:`Menuconfig`. |
1154 | 1029 | ||
1155 | To use the ``menuconfig`` tool in the Yocto Project development | 1030 | To use the ``menuconfig`` tool in the Yocto Project development |
1156 | environment, you must do the following: | 1031 | environment, you must do the following: |
1157 | 1032 | ||
1158 | - Because you launch ``menuconfig`` using BitBake, you must be sure to | 1033 | - Because you launch ``menuconfig`` using BitBake, you must be sure to |
1159 | set up your environment by running the | 1034 | set up your environment by running the :ref:`structure-core-script` script |
1160 | :ref:`structure-core-script` script found in | 1035 | found in the :term:`Build Directory`. |
1161 | the :term:`Build Directory`. | ||
1162 | 1036 | ||
1163 | - You must be sure of the state of your build's configuration in the | 1037 | - You must be sure of the state of your build's configuration in the |
1164 | :term:`Source Directory`. | 1038 | :term:`Source Directory`. |
1165 | 1039 | ||
1166 | - Your build host must have the following two packages installed: | 1040 | - Your build host must have the following two packages installed:: |
1167 | :: | ||
1168 | 1041 | ||
1169 | libncurses5-dev | 1042 | libncurses5-dev |
1170 | libtinfo-dev | 1043 | libtinfo-dev |
@@ -1172,8 +1045,7 @@ environment, you must do the following: | |||
1172 | The following commands initialize the BitBake environment, run the | 1045 | The following commands initialize the BitBake environment, run the |
1173 | :ref:`ref-tasks-kernel_configme` | 1046 | :ref:`ref-tasks-kernel_configme` |
1174 | task, and launch ``menuconfig``. These commands assume the Source | 1047 | task, and launch ``menuconfig``. These commands assume the Source |
1175 | Directory's top-level folder is ``~/poky``: | 1048 | Directory's top-level folder is ``poky``:: |
1176 | :: | ||
1177 | 1049 | ||
1178 | $ cd poky | 1050 | $ cd poky |
1179 | $ source oe-init-build-env | 1051 | $ source oe-init-build-env |
@@ -1201,7 +1073,7 @@ Consider an example that configures the "CONFIG_SMP" setting for the | |||
1201 | .. note:: | 1073 | .. note:: |
1202 | 1074 | ||
1203 | The OpenEmbedded build system recognizes this kernel as ``linux-yocto`` | 1075 | The OpenEmbedded build system recognizes this kernel as ``linux-yocto`` |
1204 | through Metadata (e.g. :term:`PREFERRED_VERSION`\ ``_linux-yocto ?= "12.4%"``). | 1076 | through Metadata (e.g. :term:`PREFERRED_VERSION`\ ``_linux-yocto ?= "4.12%"``). |
1205 | 1077 | ||
1206 | Once ``menuconfig`` launches, use the interface to navigate through the | 1078 | Once ``menuconfig`` launches, use the interface to navigate through the |
1207 | selections to find the configuration settings in which you are | 1079 | selections to find the configuration settings in which you are |
@@ -1212,10 +1084,10 @@ can find the option under "Processor Type and Features". To deselect | |||
1212 | Multi-Processing Support" and enter "N" to clear the asterisk. When you | 1084 | Multi-Processing Support" and enter "N" to clear the asterisk. When you |
1213 | are finished, exit out and save the change. | 1085 | are finished, exit out and save the change. |
1214 | 1086 | ||
1215 | Saving the selections updates the ``.config`` configuration file. This | 1087 | Saving the selections updates the ``.config`` configuration file. This is the |
1216 | is the file that the OpenEmbedded build system uses to configure the | 1088 | file that the OpenEmbedded build system uses to configure the kernel during |
1217 | kernel during the build. You can find and examine this file in the Build | 1089 | the build. You can find and examine this file in the :term:`Build Directory` |
1218 | Directory in ``tmp/work/``. The actual ``.config`` is located in the | 1090 | in ``tmp/work/``. The actual ``.config`` is located in the |
1219 | area where the specific kernel is built. For example, if you were | 1091 | area where the specific kernel is built. For example, if you were |
1220 | building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel | 1092 | building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel |
1221 | and you were building a QEMU image targeted for ``x86`` architecture, | 1093 | and you were building a QEMU image targeted for ``x86`` architecture, |
@@ -1235,8 +1107,7 @@ the ``.config`` file would be: | |||
1235 | 1107 | ||
1236 | Within the ``.config`` file, you can see the kernel settings. For | 1108 | Within the ``.config`` file, you can see the kernel settings. For |
1237 | example, the following entry shows that symmetric multi-processor | 1109 | example, the following entry shows that symmetric multi-processor |
1238 | support is not set: | 1110 | support is not set:: |
1239 | :: | ||
1240 | 1111 | ||
1241 | # CONFIG_SMP is not set | 1112 | # CONFIG_SMP is not set |
1242 | 1113 | ||
@@ -1277,10 +1148,9 @@ your layer's ``recipes-kernel/linux`` directory, and rename the copied | |||
1277 | file to "defconfig" (e.g. | 1148 | file to "defconfig" (e.g. |
1278 | ``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then, | 1149 | ``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then, |
1279 | add the following lines to the linux-yocto ``.bbappend`` file in your | 1150 | add the following lines to the linux-yocto ``.bbappend`` file in your |
1280 | layer: | 1151 | layer:: |
1281 | :: | ||
1282 | 1152 | ||
1283 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 1153 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
1284 | SRC_URI += "file://defconfig" | 1154 | SRC_URI += "file://defconfig" |
1285 | 1155 | ||
1286 | The :term:`SRC_URI` tells the build system how to search for the file, while the | 1156 | The :term:`SRC_URI` tells the build system how to search for the file, while the |
@@ -1298,8 +1168,8 @@ created to hold the configuration changes. | |||
1298 | applies these on top of and after applying the existing ``defconfig`` file | 1168 | applies these on top of and after applying the existing ``defconfig`` file |
1299 | configurations. | 1169 | configurations. |
1300 | 1170 | ||
1301 | For more information on configuring the kernel, see the "`Changing the | 1171 | For more information on configuring the kernel, see the |
1302 | Configuration <#changing-the-configuration>`__" section. | 1172 | ":ref:`kernel-dev/common:changing the configuration`" section. |
1303 | 1173 | ||
1304 | Creating Configuration Fragments | 1174 | Creating Configuration Fragments |
1305 | -------------------------------- | 1175 | -------------------------------- |
@@ -1326,8 +1196,7 @@ appear in the ``.config`` file, which is in the :term:`Build Directory`. | |||
1326 | It is simple to create a configuration fragment. One method is to use | 1196 | It is simple to create a configuration fragment. One method is to use |
1327 | shell commands. For example, issuing the following from the shell | 1197 | shell commands. For example, issuing the following from the shell |
1328 | creates a configuration fragment file named ``my_smp.cfg`` that enables | 1198 | creates a configuration fragment file named ``my_smp.cfg`` that enables |
1329 | multi-processor support within the kernel: | 1199 | multi-processor support within the kernel:: |
1330 | :: | ||
1331 | 1200 | ||
1332 | $ echo "CONFIG_SMP=y" >> my_smp.cfg | 1201 | $ echo "CONFIG_SMP=y" >> my_smp.cfg |
1333 | 1202 | ||
@@ -1344,34 +1213,31 @@ saved, and one freshly created using the ``menuconfig`` tool. | |||
1344 | To create a configuration fragment using this method, follow these | 1213 | To create a configuration fragment using this method, follow these |
1345 | steps: | 1214 | steps: |
1346 | 1215 | ||
1347 | 1. *Complete a Build Through Kernel Configuration:* Complete a build at | 1216 | #. *Complete a Build Through Kernel Configuration:* Complete a build at |
1348 | least through the kernel configuration task as follows: | 1217 | least through the kernel configuration task as follows:: |
1349 | :: | ||
1350 | 1218 | ||
1351 | $ bitbake linux-yocto -c kernel_configme -f | 1219 | $ bitbake linux-yocto -c kernel_configme -f |
1352 | 1220 | ||
1353 | This step ensures that you create a | 1221 | This step ensures that you create a |
1354 | ``.config`` file from a known state. Because situations exist where | 1222 | ``.config`` file from a known state. Because there are situations where |
1355 | your build state might become unknown, it is best to run this task | 1223 | your build state might become unknown, it is best to run this task |
1356 | prior to starting ``menuconfig``. | 1224 | prior to starting ``menuconfig``. |
1357 | 1225 | ||
1358 | 2. *Launch menuconfig:* Run the ``menuconfig`` command: | 1226 | #. *Launch menuconfig:* Run the ``menuconfig`` command:: |
1359 | :: | ||
1360 | 1227 | ||
1361 | $ bitbake linux-yocto -c menuconfig | 1228 | $ bitbake linux-yocto -c menuconfig |
1362 | 1229 | ||
1363 | 3. *Create the Configuration Fragment:* Run the ``diffconfig`` command | 1230 | #. *Create the Configuration Fragment:* Run the ``diffconfig`` command |
1364 | to prepare a configuration fragment. The resulting file | 1231 | to prepare a configuration fragment. The resulting file |
1365 | ``fragment.cfg`` is placed in the | 1232 | ``fragment.cfg`` is placed in the |
1366 | ``${``\ :term:`WORKDIR`\ ``}`` | 1233 | ``${``\ :term:`WORKDIR`\ ``}`` |
1367 | directory: | 1234 | directory:: |
1368 | :: | ||
1369 | 1235 | ||
1370 | $ bitbake linux-yocto -c diffconfig | 1236 | $ bitbake linux-yocto -c diffconfig |
1371 | 1237 | ||
1372 | The ``diffconfig`` command creates a file that is a list of Linux kernel | 1238 | The ``diffconfig`` command creates a file that is a list of Linux kernel |
1373 | ``CONFIG_`` assignments. See the "`Changing the | 1239 | ``CONFIG_`` assignments. See the |
1374 | Configuration <#changing-the-configuration>`__" section for additional | 1240 | ":ref:`kernel-dev/common:changing the configuration`" section for additional |
1375 | information on how to use the output as a configuration fragment. | 1241 | information on how to use the output as a configuration fragment. |
1376 | 1242 | ||
1377 | .. note:: | 1243 | .. note:: |
@@ -1390,18 +1256,16 @@ options in a file called ``myconfig.cfg``. If you put that file inside a | |||
1390 | directory named ``linux-yocto`` that resides in the same directory as | 1256 | directory named ``linux-yocto`` that resides in the same directory as |
1391 | the kernel's append file within your layer and then add the following | 1257 | the kernel's append file within your layer and then add the following |
1392 | statements to the kernel's append file, those configuration options will | 1258 | statements to the kernel's append file, those configuration options will |
1393 | be picked up and applied when the kernel is built: | 1259 | be picked up and applied when the kernel is built:: |
1394 | :: | ||
1395 | 1260 | ||
1396 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 1261 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
1397 | SRC_URI += "file://myconfig.cfg" | 1262 | SRC_URI += "file://myconfig.cfg" |
1398 | 1263 | ||
1399 | As mentioned earlier, you can group related configurations into multiple | 1264 | As mentioned earlier, you can group related configurations into multiple |
1400 | files and name them all in the ``SRC_URI`` statement as well. For | 1265 | files and name them all in the :term:`SRC_URI` statement as well. For |
1401 | example, you could group separate configurations specifically for | 1266 | example, you could group separate configurations specifically for |
1402 | Ethernet and graphics into their own files and add those by using a | 1267 | Ethernet and graphics into their own files and add those by using a |
1403 | ``SRC_URI`` statement like the following in your append file: | 1268 | :term:`SRC_URI` statement like the following in your append file:: |
1404 | :: | ||
1405 | 1269 | ||
1406 | SRC_URI += "file://myconfig.cfg \ | 1270 | SRC_URI += "file://myconfig.cfg \ |
1407 | file://eth.cfg \ | 1271 | file://eth.cfg \ |
@@ -1412,8 +1276,7 @@ Validating Configuration | |||
1412 | 1276 | ||
1413 | You can use the | 1277 | You can use the |
1414 | :ref:`ref-tasks-kernel_configcheck` | 1278 | :ref:`ref-tasks-kernel_configcheck` |
1415 | task to provide configuration validation: | 1279 | task to provide configuration validation:: |
1416 | :: | ||
1417 | 1280 | ||
1418 | $ bitbake linux-yocto -c kernel_configcheck -f | 1281 | $ bitbake linux-yocto -c kernel_configcheck -f |
1419 | 1282 | ||
@@ -1426,7 +1289,7 @@ In order to run this task, you must have an existing ``.config`` file. | |||
1426 | See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" section for | 1289 | See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" section for |
1427 | information on how to create a configuration file. | 1290 | information on how to create a configuration file. |
1428 | 1291 | ||
1429 | Following is sample output from the ``do_kernel_configcheck`` task: | 1292 | Here is sample output from the :ref:`ref-tasks-kernel_configcheck` task: |
1430 | 1293 | ||
1431 | .. code-block:: none | 1294 | .. code-block:: none |
1432 | 1295 | ||
@@ -1506,12 +1369,12 @@ possible by reading the output of the kernel configuration fragment | |||
1506 | audit, noting any issues, making changes to correct the issues, and then | 1369 | audit, noting any issues, making changes to correct the issues, and then |
1507 | repeating. | 1370 | repeating. |
1508 | 1371 | ||
1509 | As part of the kernel build process, the ``do_kernel_configcheck`` task | 1372 | As part of the kernel build process, the :ref:`ref-tasks-kernel_configcheck` task |
1510 | runs. This task validates the kernel configuration by checking the final | 1373 | runs. This task validates the kernel configuration by checking the final |
1511 | ``.config`` file against the input files. During the check, the task | 1374 | ``.config`` file against the input files. During the check, the task |
1512 | produces warning messages for the following issues: | 1375 | produces warning messages for the following issues: |
1513 | 1376 | ||
1514 | - Requested options that did not make the final ``.config`` file. | 1377 | - Requested options that did not make it into the final ``.config`` file. |
1515 | 1378 | ||
1516 | - Configuration items that appear twice in the same configuration | 1379 | - Configuration items that appear twice in the same configuration |
1517 | fragment. | 1380 | fragment. |
@@ -1535,19 +1398,18 @@ configuration. | |||
1535 | 1398 | ||
1536 | To streamline the configuration, do the following: | 1399 | To streamline the configuration, do the following: |
1537 | 1400 | ||
1538 | 1. *Use a Working Configuration:* Start with a full configuration that | 1401 | #. *Use a Working Configuration:* Start with a full configuration that |
1539 | you know works. Be sure the configuration builds and boots | 1402 | you know works. Be sure the configuration builds and boots |
1540 | successfully. Use this configuration file as your baseline. | 1403 | successfully. Use this configuration file as your baseline. |
1541 | 1404 | ||
1542 | 2. *Run Configure and Check Tasks:* Separately run the | 1405 | #. *Run Configure and Check Tasks:* Separately run the |
1543 | ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks: | 1406 | :ref:`ref-tasks-kernel_configme` and :ref:`ref-tasks-kernel_configcheck` tasks:: |
1544 | :: | ||
1545 | 1407 | ||
1546 | $ bitbake linux-yocto -c kernel_configme -f | 1408 | $ bitbake linux-yocto -c kernel_configme -f |
1547 | $ bitbake linux-yocto -c kernel_configcheck -f | 1409 | $ bitbake linux-yocto -c kernel_configcheck -f |
1548 | 1410 | ||
1549 | 3. *Process the Results:* Take the resulting list of files from the | 1411 | #. *Process the Results:* Take the resulting list of files from the |
1550 | ``do_kernel_configcheck`` task warnings and do the following: | 1412 | :ref:`ref-tasks-kernel_configcheck` task warnings and do the following: |
1551 | 1413 | ||
1552 | - Drop values that are redefined in the fragment but do not change | 1414 | - Drop values that are redefined in the fragment but do not change |
1553 | the final ``.config`` file. | 1415 | the final ``.config`` file. |
@@ -1559,9 +1421,9 @@ To streamline the configuration, do the following: | |||
1559 | 1421 | ||
1560 | - Remove repeated and invalid options. | 1422 | - Remove repeated and invalid options. |
1561 | 1423 | ||
1562 | 4. *Re-Run Configure and Check Tasks:* After you have worked through the | 1424 | #. *Re-Run Configure and Check Tasks:* After you have worked through the |
1563 | output of the kernel configuration audit, you can re-run the | 1425 | output of the kernel configuration audit, you can re-run the |
1564 | ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks to see the | 1426 | :ref:`ref-tasks-kernel_configme` and :ref:`ref-tasks-kernel_configcheck` tasks to see the |
1565 | results of your changes. If you have more issues, you can deal with | 1427 | results of your changes. If you have more issues, you can deal with |
1566 | them as described in the previous step. | 1428 | them as described in the previous step. |
1567 | 1429 | ||
@@ -1575,8 +1437,7 @@ Expanding Variables | |||
1575 | Sometimes it is helpful to determine what a variable expands to during a | 1437 | Sometimes it is helpful to determine what a variable expands to during a |
1576 | build. You can examine the values of variables by examining the | 1438 | build. You can examine the values of variables by examining the |
1577 | output of the ``bitbake -e`` command. The output is long and is more | 1439 | output of the ``bitbake -e`` command. The output is long and is more |
1578 | easily managed in a text file, which allows for easy searches: | 1440 | easily managed in a text file, which allows for easy searches:: |
1579 | :: | ||
1580 | 1441 | ||
1581 | $ bitbake -e virtual/kernel > some_text_file | 1442 | $ bitbake -e virtual/kernel > some_text_file |
1582 | 1443 | ||
@@ -1588,25 +1449,23 @@ Working with a "Dirty" Kernel Version String | |||
1588 | ============================================ | 1449 | ============================================ |
1589 | 1450 | ||
1590 | If you build a kernel image and the version string has a "+" or a | 1451 | If you build a kernel image and the version string has a "+" or a |
1591 | "-dirty" at the end, uncommitted modifications exist in the kernel's | 1452 | "-dirty" at the end, it means there are uncommitted modifications in the kernel's |
1592 | source directory. Follow these steps to clean up the version string: | 1453 | source directory. Follow these steps to clean up the version string: |
1593 | 1454 | ||
1594 | 1. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned | 1455 | #. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned |
1595 | Git repository (source directory) and use the following Git command | 1456 | Git repository (source directory) and use the following Git command |
1596 | to list the files that have been changed, added, or removed: | 1457 | to list the files that have been changed, added, or removed:: |
1597 | :: | ||
1598 | 1458 | ||
1599 | $ git status | 1459 | $ git status |
1600 | 1460 | ||
1601 | 2. *Commit the Changes:* You should commit those changes to the kernel | 1461 | #. *Commit the Changes:* You should commit those changes to the kernel |
1602 | source tree regardless of whether or not you will save, export, or | 1462 | source tree regardless of whether or not you will save, export, or |
1603 | use the changes: | 1463 | use the changes:: |
1604 | :: | ||
1605 | 1464 | ||
1606 | $ git add | 1465 | $ git add |
1607 | $ git commit -s -a -m "getting rid of -dirty" | 1466 | $ git commit -s -a -m "getting rid of -dirty" |
1608 | 1467 | ||
1609 | 3. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the | 1468 | #. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the |
1610 | kernel. | 1469 | kernel. |
1611 | 1470 | ||
1612 | Depending on your particular kernel development workflow, the | 1471 | Depending on your particular kernel development workflow, the |
@@ -1614,9 +1473,8 @@ source directory. Follow these steps to clean up the version string: | |||
1614 | on building the kernel image when using ``devtool``, see the | 1473 | on building the kernel image when using ``devtool``, see the |
1615 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | 1474 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" |
1616 | section. For | 1475 | section. For |
1617 | information on building the kernel image when using Bitbake, see the | 1476 | information on building the kernel image when using BitBake, see the |
1618 | "`Using Traditional Kernel Development to Patch the | 1477 | ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" |
1619 | Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__" | ||
1620 | section. | 1478 | section. |
1621 | 1479 | ||
1622 | Working With Your Own Sources | 1480 | Working With Your Own Sources |
@@ -1633,34 +1491,30 @@ Maintaining format compatibility facilitates converging with linux-yocto | |||
1633 | on a future, mutually-supported kernel version. | 1491 | on a future, mutually-supported kernel version. |
1634 | 1492 | ||
1635 | To help you use your own sources, the Yocto Project provides a | 1493 | To help you use your own sources, the Yocto Project provides a |
1636 | linux-yocto custom recipe (``linux-yocto-custom.bb``) that uses | 1494 | linux-yocto custom recipe that uses ``kernel.org`` sources and |
1637 | ``kernel.org`` sources and the Yocto Project Linux kernel tools for | 1495 | the Yocto Project Linux kernel tools for managing kernel Metadata. |
1638 | managing kernel Metadata. You can find this recipe in the ``poky`` Git | 1496 | You can find this recipe in the ``poky`` Git repository: |
1639 | repository of the Yocto Project :yocto_git:`Source Repository <>` | 1497 | :yocto_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb |
1640 | at: | 1498 | </poky/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`. |
1641 | :: | ||
1642 | |||
1643 | poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb | ||
1644 | 1499 | ||
1645 | Here are some basic steps you can use to work with your own sources: | 1500 | Here are some basic steps you can use to work with your own sources: |
1646 | 1501 | ||
1647 | 1. *Create a Copy of the Kernel Recipe:* Copy the | 1502 | #. *Create a Copy of the Kernel Recipe:* Copy the |
1648 | ``linux-yocto-custom.bb`` recipe to your layer and give it a | 1503 | ``linux-yocto-custom.bb`` recipe to your layer and give it a |
1649 | meaningful name. The name should include the version of the Yocto | 1504 | meaningful name. The name should include the version of the Yocto |
1650 | Linux kernel you are using (e.g. ``linux-yocto-myproject_4.12.bb``, | 1505 | Linux kernel you are using (e.g. ``linux-yocto-myproject_4.12.bb``, |
1651 | where "4.12" is the base version of the Linux kernel with which you | 1506 | where "4.12" is the base version of the Linux kernel with which you |
1652 | would be working). | 1507 | would be working). |
1653 | 1508 | ||
1654 | 2. *Create a Directory for Your Patches:* In the same directory inside | 1509 | #. *Create a Directory for Your Patches:* In the same directory inside |
1655 | your layer, create a matching directory to store your patches and | 1510 | your layer, create a matching directory to store your patches and |
1656 | configuration files (e.g. ``linux-yocto-myproject``). | 1511 | configuration files (e.g. ``linux-yocto-myproject``). |
1657 | 1512 | ||
1658 | 3. *Ensure You Have Configurations:* Make sure you have either a | 1513 | #. *Ensure You Have Configurations:* Make sure you have either a |
1659 | ``defconfig`` file or configuration fragment files in your layer. | 1514 | ``defconfig`` file or configuration fragment files in your layer. |
1660 | When you use the ``linux-yocto-custom.bb`` recipe, you must specify a | 1515 | When you use the ``linux-yocto-custom.bb`` recipe, you must specify a |
1661 | configuration. If you do not have a ``defconfig`` file, you can run | 1516 | configuration. If you do not have a ``defconfig`` file, you can run |
1662 | the following: | 1517 | the following:: |
1663 | :: | ||
1664 | 1518 | ||
1665 | $ make defconfig | 1519 | $ make defconfig |
1666 | 1520 | ||
@@ -1672,7 +1526,7 @@ Here are some basic steps you can use to work with your own sources: | |||
1672 | 1526 | ||
1673 | Running the ``make defconfig`` command results in the default | 1527 | Running the ``make defconfig`` command results in the default |
1674 | configuration for your architecture as defined by your kernel. | 1528 | configuration for your architecture as defined by your kernel. |
1675 | However, no guarantee exists that this configuration is valid for | 1529 | However, there is no guarantee that this configuration is valid for |
1676 | your use case, or that your board will even boot. This is | 1530 | your use case, or that your board will even boot. This is |
1677 | particularly true for non-x86 architectures. | 1531 | particularly true for non-x86 architectures. |
1678 | 1532 | ||
@@ -1681,15 +1535,15 @@ Here are some basic steps you can use to work with your own sources: | |||
1681 | ``arch/arm/configs`` and use the one that is the best starting point | 1535 | ``arch/arm/configs`` and use the one that is the best starting point |
1682 | for your board). | 1536 | for your board). |
1683 | 1537 | ||
1684 | 4. *Edit the Recipe:* Edit the following variables in your recipe as | 1538 | #. *Edit the Recipe:* Edit the following variables in your recipe as |
1685 | appropriate for your project: | 1539 | appropriate for your project: |
1686 | 1540 | ||
1687 | - :term:`SRC_URI`: The | 1541 | - :term:`SRC_URI`: The |
1688 | ``SRC_URI`` should specify a Git repository that uses one of the | 1542 | :term:`SRC_URI` should specify a Git repository that uses one of the |
1689 | supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``, | 1543 | supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``, |
1690 | and so forth). The ``SRC_URI`` variable should also specify either | 1544 | and so forth). The :term:`SRC_URI` variable should also specify either |
1691 | a ``defconfig`` file or some configuration fragment files. The | 1545 | a ``defconfig`` file or some configuration fragment files. The |
1692 | skeleton recipe provides an example ``SRC_URI`` as a syntax | 1546 | skeleton recipe provides an example :term:`SRC_URI` as a syntax |
1693 | reference. | 1547 | reference. |
1694 | 1548 | ||
1695 | - :term:`LINUX_VERSION`: | 1549 | - :term:`LINUX_VERSION`: |
@@ -1707,17 +1561,16 @@ Here are some basic steps you can use to work with your own sources: | |||
1707 | indicate to the OpenEmbedded build system that the recipe has | 1561 | indicate to the OpenEmbedded build system that the recipe has |
1708 | changed. | 1562 | changed. |
1709 | 1563 | ||
1710 | - :term:`PV`: The default ``PV`` | 1564 | - :term:`PV`: The default :term:`PV` |
1711 | assignment is typically adequate. It combines the | 1565 | assignment is typically adequate. It combines the |
1712 | ``LINUX_VERSION`` with the Source Control Manager (SCM) revision | 1566 | :term:`LINUX_VERSION` with the Source Control Manager (SCM) revision |
1713 | as derived from the :term:`SRCPV` | 1567 | as derived from the :term:`SRCPV` |
1714 | variable. The combined results are a string with the following | 1568 | variable. The combined results are a string with the following |
1715 | form: | 1569 | form:: |
1716 | :: | ||
1717 | 1570 | ||
1718 | 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 | 1571 | 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 |
1719 | 1572 | ||
1720 | While lengthy, the extra verbosity in ``PV`` helps ensure you are | 1573 | While lengthy, the extra verbosity in :term:`PV` helps ensure you are |
1721 | using the exact sources from which you intend to build. | 1574 | using the exact sources from which you intend to build. |
1722 | 1575 | ||
1723 | - :term:`COMPATIBLE_MACHINE`: | 1576 | - :term:`COMPATIBLE_MACHINE`: |
@@ -1727,15 +1580,15 @@ Here are some basic steps you can use to work with your own sources: | |||
1727 | triggers an explicit build failure. You must change it to match a | 1580 | triggers an explicit build failure. You must change it to match a |
1728 | list of the machines that your new recipe supports. For example, | 1581 | list of the machines that your new recipe supports. For example, |
1729 | to support the ``qemux86`` and ``qemux86-64`` machines, use the | 1582 | to support the ``qemux86`` and ``qemux86-64`` machines, use the |
1730 | following form: | 1583 | following form:: |
1731 | :: | ||
1732 | 1584 | ||
1733 | COMPATIBLE_MACHINE = "qemux86|qemux86-64" | 1585 | COMPATIBLE_MACHINE = "qemux86|qemux86-64" |
1734 | 1586 | ||
1735 | 5. *Customize Your Recipe as Needed:* Provide further customizations to | 1587 | #. *Customize Your Recipe as Needed:* Provide further customizations to |
1736 | your recipe as needed just as you would customize an existing | 1588 | your recipe as needed just as you would customize an existing |
1737 | linux-yocto recipe. See the "`Modifying an Existing | 1589 | linux-yocto recipe. See the |
1738 | Recipe <#modifying-an-existing-recipe>`__" section for information. | 1590 | ":ref:`ref-manual/devtool-reference:modifying an existing recipe`" section |
1591 | for information. | ||
1739 | 1592 | ||
1740 | Working with Out-of-Tree Modules | 1593 | Working with Out-of-Tree Modules |
1741 | ================================ | 1594 | ================================ |
@@ -1787,11 +1640,9 @@ Linux kernel sources, if you need an external kernel module, the | |||
1787 | create your own out-of-tree Linux kernel module recipe. | 1640 | create your own out-of-tree Linux kernel module recipe. |
1788 | 1641 | ||
1789 | This template recipe is located in the ``poky`` Git repository of the | 1642 | This template recipe is located in the ``poky`` Git repository of the |
1790 | Yocto Project :yocto_git:`Source Repository <>` at: | 1643 | Yocto Project: |
1791 | 1644 | :yocto_git:`meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb | |
1792 | .. code-block:: none | 1645 | </poky/tree/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb>`. |
1793 | |||
1794 | poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb | ||
1795 | 1646 | ||
1796 | To get started, copy this recipe to your layer and give it a meaningful | 1647 | To get started, copy this recipe to your layer and give it a meaningful |
1797 | name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new | 1648 | name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new |
@@ -1810,29 +1661,26 @@ Typically, you will need to set the following variables: | |||
1810 | 1661 | ||
1811 | Depending on the build system used by the module sources, you might need | 1662 | Depending on the build system used by the module sources, you might need |
1812 | to make some adjustments. For example, a typical module ``Makefile`` | 1663 | to make some adjustments. For example, a typical module ``Makefile`` |
1813 | looks much like the one provided with the ``hello-mod`` template: | 1664 | looks much like the one provided with the ``hello-mod`` template:: |
1814 | :: | ||
1815 | 1665 | ||
1816 | obj-m := hello.o | 1666 | obj-m := hello.o |
1817 | 1667 | ||
1818 | SRC := $(shell pwd) | 1668 | SRC := $(shell pwd) |
1819 | 1669 | ||
1820 | all: | 1670 | all: |
1821 | $(MAKE) -C $(KERNEL_SRC) M=$(SRC) | 1671 | $(MAKE) -C $(KERNEL_SRC) M=$(SRC) |
1822 | 1672 | ||
1823 | modules_install: | 1673 | modules_install: |
1824 | $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install | 1674 | $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install |
1825 | ... | 1675 | ... |
1826 | 1676 | ||
1827 | The important point to note here is the :term:`KERNEL_SRC` variable. The | 1677 | The important point to note here is the :term:`KERNEL_SRC` variable. The |
1828 | :ref:`module <ref-classes-module>` class sets this variable and the | 1678 | :ref:`ref-classes-module` class sets this variable and the :term:`KERNEL_PATH` |
1829 | :term:`KERNEL_PATH` variable to | 1679 | variable to ``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build |
1830 | ``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build | 1680 | information to build modules. If your module ``Makefile`` uses a different |
1831 | information to build modules. If your module ``Makefile`` uses a | 1681 | variable, you might want to override the :ref:`ref-tasks-compile` step, or |
1832 | different variable, you might want to override the | ||
1833 | :ref:`ref-tasks-compile` step, or | ||
1834 | create a patch to the ``Makefile`` to work with the more typical | 1682 | create a patch to the ``Makefile`` to work with the more typical |
1835 | ``KERNEL_SRC`` or ``KERNEL_PATH`` variables. | 1683 | :term:`KERNEL_SRC` or :term:`KERNEL_PATH` variables. |
1836 | 1684 | ||
1837 | After you have prepared your recipe, you will likely want to include the | 1685 | After you have prepared your recipe, you will likely want to include the |
1838 | module in your images. To do this, see the documentation for the | 1686 | module in your images. To do this, see the documentation for the |
@@ -1848,8 +1696,7 @@ them appropriately for your machine configuration file: | |||
1848 | - :term:`MACHINE_EXTRA_RRECOMMENDS` | 1696 | - :term:`MACHINE_EXTRA_RRECOMMENDS` |
1849 | 1697 | ||
1850 | Modules are often not required for boot and can be excluded from certain | 1698 | Modules are often not required for boot and can be excluded from certain |
1851 | build configurations. The following allows for the most flexibility: | 1699 | build configurations. The following allows for the most flexibility:: |
1852 | :: | ||
1853 | 1700 | ||
1854 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" | 1701 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" |
1855 | 1702 | ||
@@ -1873,7 +1720,7 @@ tree. Using Git is an efficient way to see what has changed in the tree. | |||
1873 | What Changed in a Kernel? | 1720 | What Changed in a Kernel? |
1874 | ------------------------- | 1721 | ------------------------- |
1875 | 1722 | ||
1876 | Following are a few examples that show how to use Git commands to | 1723 | Here are a few examples that show how to use Git commands to |
1877 | examine changes. These examples are by no means the only way to see | 1724 | examine changes. These examples are by no means the only way to see |
1878 | changes. | 1725 | changes. |
1879 | 1726 | ||
@@ -1893,31 +1740,26 @@ Here is an example that looks at what has changed in the ``emenlow`` | |||
1893 | branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the | 1740 | branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the |
1894 | commit associated with the ``standard/base`` branch, while the upper | 1741 | commit associated with the ``standard/base`` branch, while the upper |
1895 | commit range is the commit associated with the ``standard/emenlow`` | 1742 | commit range is the commit associated with the ``standard/emenlow`` |
1896 | branch. | 1743 | branch:: |
1897 | :: | ||
1898 | 1744 | ||
1899 | $ git whatchanged origin/standard/base..origin/standard/emenlow | 1745 | $ git whatchanged origin/standard/base..origin/standard/emenlow |
1900 | 1746 | ||
1901 | To see short, one line summaries of changes use the ``git log`` command: | 1747 | To see short, one line summaries of changes use the ``git log`` command:: |
1902 | :: | ||
1903 | 1748 | ||
1904 | $ git log --oneline origin/standard/base..origin/standard/emenlow | 1749 | $ git log --oneline origin/standard/base..origin/standard/emenlow |
1905 | 1750 | ||
1906 | Use this command to see code differences for the changes: | 1751 | Use this command to see code differences for the changes:: |
1907 | :: | ||
1908 | 1752 | ||
1909 | $ git diff origin/standard/base..origin/standard/emenlow | 1753 | $ git diff origin/standard/base..origin/standard/emenlow |
1910 | 1754 | ||
1911 | Use this command to see the commit log messages and the text | 1755 | Use this command to see the commit log messages and the text |
1912 | differences: | 1756 | differences:: |
1913 | :: | ||
1914 | 1757 | ||
1915 | $ git show origin/standard/base..origin/standard/emenlow | 1758 | $ git show origin/standard/base..origin/standard/emenlow |
1916 | 1759 | ||
1917 | Use this command to create individual patches for each change. Here is | 1760 | Use this command to create individual patches for each change. Here is |
1918 | an example that that creates patch files for each commit and places them | 1761 | an example that creates patch files for each commit and places them |
1919 | in your ``Documents`` directory: | 1762 | in your ``Documents`` directory:: |
1920 | :: | ||
1921 | 1763 | ||
1922 | $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow | 1764 | $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow |
1923 | 1765 | ||
@@ -1926,15 +1768,13 @@ Showing a Particular Feature or Branch Change | |||
1926 | 1768 | ||
1927 | Tags in the Yocto Project kernel tree divide changes for significant | 1769 | Tags in the Yocto Project kernel tree divide changes for significant |
1928 | features or branches. The ``git show`` tag command shows changes based | 1770 | features or branches. The ``git show`` tag command shows changes based |
1929 | on a tag. Here is an example that shows ``systemtap`` changes: | 1771 | on a tag. Here is an example that shows ``systemtap`` changes:: |
1930 | :: | ||
1931 | 1772 | ||
1932 | $ git show systemtap | 1773 | $ git show systemtap |
1933 | 1774 | ||
1934 | You can use the ``git branch --contains`` tag command to | 1775 | You can use the ``git branch --contains`` tag command to |
1935 | show the branches that contain a particular feature. This command shows | 1776 | show the branches that contain a particular feature. This command shows |
1936 | the branches that contain the ``systemtap`` feature: | 1777 | the branches that contain the ``systemtap`` feature:: |
1937 | :: | ||
1938 | 1778 | ||
1939 | $ git branch --contains systemtap | 1779 | $ git branch --contains systemtap |
1940 | 1780 | ||
@@ -1952,31 +1792,31 @@ build stops. Kernel features are the last elements processed for | |||
1952 | configuring and patching the kernel. Therefore, adding features in this | 1792 | configuring and patching the kernel. Therefore, adding features in this |
1953 | manner is a way to enforce specific features are present and enabled | 1793 | manner is a way to enforce specific features are present and enabled |
1954 | without needing to do a full audit of any other layer's additions to the | 1794 | without needing to do a full audit of any other layer's additions to the |
1955 | ``SRC_URI`` statement. | 1795 | :term:`SRC_URI` statement. |
1956 | 1796 | ||
1957 | You add a kernel feature by providing the feature as part of the | 1797 | You add a kernel feature by providing the feature as part of the |
1958 | ``KERNEL_FEATURES`` variable and by providing the path to the feature's | 1798 | :term:`KERNEL_FEATURES` variable and by providing the path to the feature's |
1959 | ``.scc`` file, which is relative to the root of the kernel Metadata. The | 1799 | ``.scc`` file, which is relative to the root of the kernel Metadata. The |
1960 | OpenEmbedded build system searches all forms of kernel Metadata on the | 1800 | OpenEmbedded build system searches all forms of kernel Metadata on the |
1961 | ``SRC_URI`` statement regardless of whether the Metadata is in the | 1801 | :term:`SRC_URI` statement regardless of whether the Metadata is in the |
1962 | "kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e. | 1802 | "kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e. |
1963 | part of the kernel recipe). See the | 1803 | part of the kernel recipe). See the |
1964 | ":ref:`kernel-dev/advanced:kernel metadata location`" section for | 1804 | ":ref:`kernel-dev/advanced:kernel metadata location`" section for |
1965 | additional information. | 1805 | additional information. |
1966 | 1806 | ||
1967 | When you specify the feature's ``.scc`` file on the ``SRC_URI`` | 1807 | When you specify the feature's ``.scc`` file on the :term:`SRC_URI` |
1968 | statement, the OpenEmbedded build system adds the directory of that | 1808 | statement, the OpenEmbedded build system adds the directory of that |
1969 | ``.scc`` file along with all its subdirectories to the kernel feature | 1809 | ``.scc`` file along with all its subdirectories to the kernel feature |
1970 | search path. Because subdirectories are searched, you can reference a | 1810 | search path. Because subdirectories are searched, you can reference a |
1971 | single ``.scc`` file in the ``SRC_URI`` statement to reference multiple | 1811 | single ``.scc`` file in the :term:`SRC_URI` statement to reference multiple |
1972 | kernel features. | 1812 | kernel features. |
1973 | 1813 | ||
1974 | Consider the following example that adds the "test.scc" feature to the | 1814 | Consider the following example that adds the "test.scc" feature to the |
1975 | build. | 1815 | build. |
1976 | 1816 | ||
1977 | 1. *Create the Feature File:* Create a ``.scc`` file and locate it just | 1817 | #. *Create the Feature File:* Create a ``.scc`` file and locate it just |
1978 | as you would any other patch file, ``.cfg`` file, or fetcher item you | 1818 | as you would any other patch file, ``.cfg`` file, or fetcher item you |
1979 | specify in the ``SRC_URI`` statement. | 1819 | specify in the :term:`SRC_URI` statement. |
1980 | 1820 | ||
1981 | .. note:: | 1821 | .. note:: |
1982 | 1822 | ||
@@ -1989,8 +1829,7 @@ build. | |||
1989 | searched during the build as potential feature directories. | 1829 | searched during the build as potential feature directories. |
1990 | 1830 | ||
1991 | Continuing with the example, suppose the "test.scc" feature you are | 1831 | Continuing with the example, suppose the "test.scc" feature you are |
1992 | adding has a ``test.scc`` file in the following directory: | 1832 | adding has a ``test.scc`` file in the following directory:: |
1993 | :: | ||
1994 | 1833 | ||
1995 | my_recipe | 1834 | my_recipe |
1996 | | | 1835 | | |
@@ -2003,21 +1842,19 @@ build. | |||
2003 | ``linux-yocto`` directory has both the feature ``test.scc`` file and | 1842 | ``linux-yocto`` directory has both the feature ``test.scc`` file and |
2004 | a similarly named configuration fragment file ``test.cfg``. | 1843 | a similarly named configuration fragment file ``test.cfg``. |
2005 | 1844 | ||
2006 | 2. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the | 1845 | #. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the |
2007 | recipe's ``SRC_URI`` statement: | 1846 | recipe's :term:`SRC_URI` statement:: |
2008 | :: | ||
2009 | 1847 | ||
2010 | SRC_URI_append = " file://test.scc" | 1848 | SRC_URI += "file://test.scc" |
2011 | 1849 | ||
2012 | The leading space before the path is important as the path is | 1850 | The leading space before the path is important as the path is |
2013 | appended to the existing path. | 1851 | appended to the existing path. |
2014 | 1852 | ||
2015 | 3. *Specify the Feature as a Kernel Feature:* Use the | 1853 | #. *Specify the Feature as a Kernel Feature:* Use the |
2016 | ``KERNEL_FEATURES`` statement to specify the feature as a kernel | 1854 | :term:`KERNEL_FEATURES` statement to specify the feature as a kernel |
2017 | feature: | 1855 | feature:: |
2018 | :: | ||
2019 | 1856 | ||
2020 | KERNEL_FEATURES_append = " test.scc" | 1857 | KERNEL_FEATURES += "test.scc" |
2021 | 1858 | ||
2022 | The OpenEmbedded build | 1859 | The OpenEmbedded build |
2023 | system processes the kernel feature when it builds the kernel. | 1860 | system processes the kernel feature when it builds the kernel. |