diff options
-rw-r--r-- | documentation/dev-manual/dev-manual-model.xml | 249 |
1 files changed, 234 insertions, 15 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index 2404be8274..6324efa11f 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml | |||
@@ -84,13 +84,18 @@ | |||
84 | process and tools you need. | 84 | process and tools you need. |
85 | For information on how to get these files, see the | 85 | For information on how to get these files, see the |
86 | <xref linkend='getting-setup'>Getting Setup</xref> section in this manual.</para></listitem> | 86 | <xref linkend='getting-setup'>Getting Setup</xref> section in this manual.</para></listitem> |
87 | <listitem><para><emphasis>Establish a local copy of the base BSP files</emphasis>: Having | ||
88 | the BSP files on your system gives you access to the build | ||
89 | process and tools you need. | ||
90 | For information on how to get these files, see | ||
91 | <xref linkend='getting-setup'>Getting Setup</xref> earlier in this manual.</para></listitem> | ||
87 | <listitem><para><emphasis>Choose a Yocto Project-supported BSP as your base BSP</emphasis>: | 92 | <listitem><para><emphasis>Choose a Yocto Project-supported BSP as your base BSP</emphasis>: |
88 | The Yocto Project ships with several BSPs that support various hardware. | 93 | The Yocto Project ships with several BSPs that support various hardware. |
89 | It is best to base your new BSP on an existing BSP rather than create all the | 94 | It is best to base your new BSP on an existing BSP rather than create all the |
90 | recipes and configuration files from scratch. | 95 | recipes and configuration files from scratch. |
91 | While it is possible to create everything from scratch, basing your new BSP | 96 | While it is possible to create everything from scratch, basing your new BSP |
92 | on something that is close is much easier. | 97 | on something that is close is much easier. |
93 | Or, at a minimum, it gives you some structure with which to start.</para> | 98 | Or, at a minimum, it gives you some structure with which to start.</para> |
94 | <para>At this point you need to understand your target hardware well enough to determine which | 99 | <para>At this point you need to understand your target hardware well enough to determine which |
95 | existing BSP it most closely matches. | 100 | existing BSP it most closely matches. |
96 | Things to consider are your hardware’s on-board features such as CPU type and graphics support. | 101 | Things to consider are your hardware’s on-board features such as CPU type and graphics support. |
@@ -102,13 +107,8 @@ | |||
102 | <para>To see the supported BSPs, go to the Yocto Project | 107 | <para>To see the supported BSPs, go to the Yocto Project |
103 | <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click | 108 | <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click |
104 | on “BSP Downloads.”</para></listitem> | 109 | on “BSP Downloads.”</para></listitem> |
105 | <listitem><para><emphasis>Establish a local copy of the base BSP files</emphasis>: Having | ||
106 | the BSP files on your system gives you access to the build | ||
107 | process and tools you need. | ||
108 | For information on how to get these files, see | ||
109 | <xref linkend='getting-setup'>Getting Setup</xref> earlier in this manual.</para></listitem> | ||
110 | <listitem><para><emphasis>Create your own BSP layer</emphasis>: Layers are ideal for | 110 | <listitem><para><emphasis>Create your own BSP layer</emphasis>: Layers are ideal for |
111 | isolating and storing work for a given piece of hardware. | 111 | isolating and storing work for a given piece of hardware. |
112 | A layer is really just a location or area in which you place the recipes for your BSP. | 112 | A layer is really just a location or area in which you place the recipes for your BSP. |
113 | In fact, a BSP is, in itself, a special type of layer. | 113 | In fact, a BSP is, in itself, a special type of layer. |
114 | Consider an application as another example that illustrates a layer. | 114 | Consider an application as another example that illustrates a layer. |
@@ -119,8 +119,8 @@ | |||
119 | all the relevant information for the project that the Yocto Project build | 119 | all the relevant information for the project that the Yocto Project build |
120 | system knows about.</para> | 120 | system knows about.</para> |
121 | <note>The Yocto Project supports four BSPs that are part of the | 121 | <note>The Yocto Project supports four BSPs that are part of the |
122 | Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>, | 122 | Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>, |
123 | <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>. | 123 | <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>. |
124 | The recipes and configurations for these four BSPs are located and dispersed | 124 | The recipes and configurations for these four BSPs are located and dispersed |
125 | within local Yocto Project files. | 125 | within local Yocto Project files. |
126 | Consequently, they are not totally isolated in the spirit of layers unless you think | 126 | Consequently, they are not totally isolated in the spirit of layers unless you think |
@@ -129,7 +129,7 @@ | |||
129 | N450, and Sugar Bay are isolated.</note> | 129 | N450, and Sugar Bay are isolated.</note> |
130 | <para>When you set up a layer for a new BSP you should follow a standard layout. | 130 | <para>When you set up a layer for a new BSP you should follow a standard layout. |
131 | This layout is described in the | 131 | This layout is described in the |
132 | <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'> | 132 | <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'> |
133 | Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development | 133 | Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development |
134 | Guide. | 134 | Guide. |
135 | In the standard layout you will notice a suggested structure for recipes and | 135 | In the standard layout you will notice a suggested structure for recipes and |
@@ -137,13 +137,15 @@ | |||
137 | You can see the standard layout for the Crown Bay BSP in this example by examining the | 137 | You can see the standard layout for the Crown Bay BSP in this example by examining the |
138 | directory structure of the <filename>meta-crownbay</filename> layer inside the | 138 | directory structure of the <filename>meta-crownbay</filename> layer inside the |
139 | local Yocto Project files.</para></listitem> | 139 | local Yocto Project files.</para></listitem> |
140 | <listitem><para><emphasis>Make configuration and recipe changes to your new BSP | 140 | <listitem><para><emphasis>Make configuration changes to your new BSP |
141 | layer</emphasis>: The standard BSP layer structure organizes the files you need to edit in | 141 | layer</emphasis>: The standard BSP layer structure organizes the files you need to edit in |
142 | <filename>conf</filename> and several <filename>recipes-*</filename> within the | 142 | <filename>conf</filename> and several <filename>recipes-*</filename> within the |
143 | BSP layer.</para> | 143 | BSP layer. |
144 | <para>Configuration changes identify where your new layer is on the local system | 144 | Configuration changes identify where your new layer is on the local system |
145 | and identify which kernel you are going to use. | 145 | and identify which kernel you are going to use. |
146 | Recipe changes include altering recipes (<filename>.bb</filename> files), removing | 146 | </para></listitem> |
147 | <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe | ||
148 | changes include altering recipes (<filename>.bb</filename> files), removing | ||
147 | recipes you don't use, and adding new recipes that you need to support your hardware. | 149 | recipes you don't use, and adding new recipes that you need to support your hardware. |
148 | </para></listitem> | 150 | </para></listitem> |
149 | <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the | 151 | <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the |
@@ -225,8 +227,225 @@ | |||
225 | <title><anchor id='kernel-spot' />Modifying the Kernel</title> | 227 | <title><anchor id='kernel-spot' />Modifying the Kernel</title> |
226 | 228 | ||
227 | <para> | 229 | <para> |
228 | Text needed here. | 230 | Kernel modification involves changing the Linux Yocto kernel, which could involve changing |
231 | configuration variables as well as adding new kernel recipes. | ||
232 | Configuration changes can be added in the form of configuration fragments, while recipe | ||
233 | modification comes through the kernel's <filename>recipes-kernel</filename> area | ||
234 | in a kernel layer you create. | ||
235 | </para> | ||
236 | |||
237 | <para> | ||
238 | The remainder of this section presents a high-level overview of the Linux Yocto | ||
239 | kernel architecture and the steps to modify the Linux Yocto kernel. | ||
240 | For a complete discussion of the kernel, see the | ||
241 | <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'> | ||
242 | Yocto Project Kernel Architecture and Use Manual</ulink>. | ||
243 | You can reference <xref linkend='dev-manual-kernel-appendix'>Kernel Modification Example</xref> | ||
244 | for a detailed example that changes the configuration of a kernel. | ||
229 | </para> | 245 | </para> |
246 | |||
247 | <section id='kernel-overview'> | ||
248 | <title>Kernel Overview</title> | ||
249 | |||
250 | <para> | ||
251 | When one thinks of the source files for a kernel they usually think of a fixed structure | ||
252 | of files that contain kernel patches. | ||
253 | The Yocto Project, however, employs mechanisims that in a sense result in a kernel source | ||
254 | generator. | ||
255 | </para> | ||
256 | |||
257 | <para> | ||
258 | The Yocto Project uses the source code management (SCM) tool Git to manage and track Yocto | ||
259 | Project files. | ||
260 | Git employs branching strategies that effectively produce a tree-like structure whose | ||
261 | branches represent diversions from more general code. | ||
262 | For example, suppose two kernels are basically identical with the exception of a couple | ||
263 | different features in each. | ||
264 | In the Yocto Project source repositories managed by Git a main branch can contain the | ||
265 | common or shared | ||
266 | parts of the kernel source and two branches that diverge from that common branch can | ||
267 | each contain the features specific to the respective kernel. | ||
268 | The result is a managed tree whose "leaves" represent the end of a specific path that yields | ||
269 | a set of kernel source files necessary for a specific piece of hardware and its features. | ||
270 | </para> | ||
271 | |||
272 | <para> | ||
273 | A big advantage to this scheme is the sharing of common features by keeping them in | ||
274 | "larger" branches that are further up the tree. | ||
275 | This practice eliminates redundant storage of similar features shared among kernels. | ||
276 | </para> | ||
277 | |||
278 | <para> | ||
279 | When you build the kernel on your development system all files needed for the build | ||
280 | are taken from the Yocto Project source repositories pointed to by the | ||
281 | <filename>SRC_URI</filename> variable and gathered in a temporary work area | ||
282 | where they are subsequently used to create the unique kernel. | ||
283 | Thus, in a sense, the process constructs a local source tree specific to your | ||
284 | kernel to generate the new kernel image - a source generator if you will. | ||
285 | </para> | ||
286 | |||
287 | <para> | ||
288 | For a complete discussion of the Yocto Project kernel's architcture and its branching strategy, | ||
289 | see the <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'> | ||
290 | The Yocto Project Kernel Architecture and Use Manual</ulink>. | ||
291 | </para> | ||
292 | </section> | ||
293 | |||
294 | <section id='kernel-modification-workflow'> | ||
295 | <title>Kernel Modification Workflow</title> | ||
296 | |||
297 | <para> | ||
298 | This illustration and the following list summarizes the kernel modification general workflow. | ||
299 | </para> | ||
300 | |||
301 | <!-- <para> | ||
302 | <imagedata fileref="figures/bsp-dev-flow.png" width="6in" depth="8.5in" align="left" scale="100" /> | ||
303 | </para> --> | ||
304 | |||
305 | <para> | ||
306 | [WRITER'S NOTE: Need new flow illustration here] | ||
307 | </para> | ||
308 | |||
309 | <para> | ||
310 | <orderedlist> | ||
311 | <listitem><para><emphasis>Set up your host development system to support | ||
312 | development using the Yocto Project</emphasis>: See | ||
313 | <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'> | ||
314 | The Linux Distributions</ulink> section and | ||
315 | <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'> | ||
316 | The Packages</ulink> section both | ||
317 | in the Yocto Project Quick Start for requirements. | ||
318 | You will also need a release of Yocto Project installed on the host.</para></listitem> | ||
319 | <listitem><para><emphasis>Establish a local copy of the Yocto Project files on your | ||
320 | system</emphasis>: You need to have the Yocto Project files available on your host system. | ||
321 | Having the Yocto Project files on your system gives you access to the build | ||
322 | process and tools you need. | ||
323 | For information on how to get these files, see the bulleted item | ||
324 | <link linkend='local-yp-release'>Yocto Project Release</link> in | ||
325 | <xref linkend='getting-setup'>Getting Setup</xref> earlier in this manual. | ||
326 | </para></listitem> | ||
327 | <listitem><para><emphasis>Establish a local kernel layer by copying the | ||
328 | <filename>meta-skeleton</filename> layer</emphasis>: When you set up a kernel layer | ||
329 | for your changes you should follow a standard layout. | ||
330 | For kernel layers you can start with <filename>meta-skeleton</filename>, which | ||
331 | is a minimal, base kernel layer in the local Yocto Project files. | ||
332 | You can examine <filename>meta-skeleton</filename> | ||
333 | in the <filename>poky</filename> Git repository.</para> | ||
334 | <para>A layer is really just a location or area in which you place configuration | ||
335 | fragments and recipes that modify your kernel. | ||
336 | The layer, in this case, would be where all the recipes that define those dependencies | ||
337 | are kept. | ||
338 | The key point for a layer is that it is an isolated area that contains | ||
339 | all the relevant information for the project that the Yocto Project build | ||
340 | system knows about.</para> | ||
341 | <para></para></listitem> | ||
342 | <listitem><para><emphasis>Iteratively make kernel configuration changes | ||
343 | to your local kernel layer</emphasis>: Use <filename>menuconfig</filename> | ||
344 | to enable and disable the configurations to the Linux Yocto kernel. | ||
345 | Using <filename>menuconfig</filename> allows you to develop and test the | ||
346 | configuration changes you are making to the kernel.</para></listitem> | ||
347 | <listitem><para><emphasis>Iteratively make kernel recipe changes to your new kernel | ||
348 | layer</emphasis>: The standard layer structure organizes the files you need to edit in | ||
349 | <filename>conf</filename> and several <filename>recipes-*</filename> within the | ||
350 | layer. | ||
351 | Recipe changes include altering recipes (<filename>.bb</filename> files), removing | ||
352 | recipes you don't use, and adding new recipes that you need to support your hardware. | ||
353 | </para></listitem> | ||
354 | <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the | ||
355 | changes to your kernel layer there remains a few things | ||
356 | you need to do for the Yocto Project build system in order for it to create your image. | ||
357 | You need to get the build environment ready by sourcing an environment setup script | ||
358 | and you need to be sure two key configuration files are configured appropriately.</para> | ||
359 | <para>The entire process for building an image is overviewed in the | ||
360 | <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'> | ||
361 | Building an Image</ulink> section of the Yocto Project Quick Start. | ||
362 | You might want to reference this information.</para></listitem> | ||
363 | <listitem><para><emphasis>Build the image</emphasis>: The Yocto Project uses the BitBake | ||
364 | tool to build images based on the type of image | ||
365 | you want to create. | ||
366 | You can find more information on BitBake | ||
367 | <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para> | ||
368 | <para>The build process supports several types of images to satisfy different needs. | ||
369 | When you issue the BitBake command you provide a “top-level” recipe that essentially | ||
370 | starts the process off of building the type of image you want.</para> | ||
371 | <para>[WRITER'S NOTE: Consider moving this to the Poky Reference Manual.]</para> | ||
372 | <para>You can find these recipes in the <filename>meta/recipes-core/images</filename> and | ||
373 | <filename>meta/recipes-sato/images</filename> directories of your local Yocto Project | ||
374 | file structure (Git repository or extracted release tarball). | ||
375 | Although the recipe names are somewhat explanatory, here is a list that describes them: | ||
376 | <itemizedlist> | ||
377 | <listitem><para><emphasis>Base</emphasis> – A foundational basic image without support | ||
378 | for X that can be reasonably used for customization.</para></listitem> | ||
379 | <listitem><para><emphasis>Core</emphasis> – A foundational basic image with support for | ||
380 | X that can be reasonably used for customization.</para></listitem> | ||
381 | <listitem><para><emphasis>Direct Disk</emphasis> – An image that you can copy directory to | ||
382 | the disk of the target device.</para></listitem> | ||
383 | <listitem><para><emphasis>Live</emphasis> – An image you can run from a USB device or from | ||
384 | a CD without having to first install something.</para></listitem> | ||
385 | <listitem><para><emphasis>Minimal</emphasis> – A small image without a GUI. | ||
386 | This image is not much more than a kernel with a shell.</para></listitem> | ||
387 | <listitem><para><emphasis>Minimal Development</emphasis> – A Minimal image suitable for | ||
388 | development work.</para></listitem> | ||
389 | <listitem><para><emphasis>Minimal Direct Disk</emphasis> – A Minimal Direct | ||
390 | Disk image.</para></listitem> | ||
391 | <listitem><para><emphasis>Minimal RAM-based Initial Root Filesystem</emphasis> – | ||
392 | A minimal image | ||
393 | that has the <filename>initramfs</filename> as part of the kernel, which allows the | ||
394 | system to find the first “init” program more efficiently.</para></listitem> | ||
395 | <listitem><para><emphasis>Minimal Live</emphasis> – A Minimal Live image.</para></listitem> | ||
396 | <listitem><para><emphasis>Minimal MTD Utilities</emphasis> – A minimal image that has support | ||
397 | for the MTD utilities, which let the user interact with the MTD subsystem in | ||
398 | the kernel to perform operations on flash devices.</para></listitem> | ||
399 | <listitem><para><emphasis>Sato</emphasis> – An image with Sato support, a mobile environment | ||
400 | and visual style that works well with mobile devices.</para></listitem> | ||
401 | <listitem><para><emphasis>Sato Development</emphasis> – A Sato image suitable for | ||
402 | development work.</para></listitem> | ||
403 | <listitem><para><emphasis>Sato Direct Disk</emphasis> – A Sato Direct | ||
404 | Disk image.</para></listitem> | ||
405 | <listitem><para><emphasis>Sato Live</emphasis> – A Sato Live image.</para></listitem> | ||
406 | <listitem><para><emphasis>Sato SDK</emphasis> – A Sato image that includes the Yocto Project | ||
407 | toolchain and development libraries.</para></listitem> | ||
408 | <listitem><para><emphasis>Sato SDK Direct Disk</emphasis> – A Sato SDK Direct | ||
409 | Disk image.</para></listitem> | ||
410 | <listitem><para><emphasis>Sato SDK Live</emphasis> – A Sato SDK Live | ||
411 | image.</para></listitem> | ||
412 | </itemizedlist> | ||
413 | </para></listitem> | ||
414 | <listitem><para><emphasis>Make your configuration and recipe changes available | ||
415 | in the kernel layer</emphasis>: Up to this point all the changes to the | ||
416 | kernel have been done and tested iteratively. | ||
417 | Once they are tested and ready to go you can move them into the kernel layer, | ||
418 | which allows you to distribute the layer.</para></listitem> | ||
419 | <listitem><para><emphasis>Make your configuration and recipe changes to the | ||
420 | linux Yocto Git repository (in-tree changes)</emphasis>: If the changes you made | ||
421 | are suited for all Linux Yocto users you might want to push the changes up into | ||
422 | the Linux Yocto Git repository so that they become part of the kernel tree | ||
423 | and available to everyone using the kernel.</para></listitem> | ||
424 | </orderedlist> | ||
425 | </para> | ||
426 | |||
427 | <para> | ||
428 | You can find a web interface to the Yocto Project source repository at | ||
429 | <ulink url='http://git.yoctoproject.org/'></ulink>. | ||
430 | Within the interface you will see groups of related source code, each of which can | ||
431 | be cloned using Git to result in a working Git repository on your local system | ||
432 | (referred to as the "local Yocto Project files" in this manual). | ||
433 | The Yocto Project supports four types of kernels in its source repositories at | ||
434 | <ulink url='http://git.yoctoproject.org/'></ulink>: | ||
435 | <itemizedlist> | ||
436 | <listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The | ||
437 | stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem> | ||
438 | <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The current | ||
439 | Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem> | ||
440 | <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development | ||
441 | kernel based on the Linux 2.6.39-rc1 release.</para></listitem> | ||
442 | <listitem><para><emphasis><filename>linux-2.6</filename></emphasis> - A kernel based on | ||
443 | minimal Linux mainline tracking. | ||
444 | [WRITER'S NOTE: I don't know which Git repository the user needs to clone to get this | ||
445 | repository on their development system.]</para></listitem> | ||
446 | </itemizedlist> | ||
447 | </para> | ||
448 | </section> | ||
230 | </section> | 449 | </section> |
231 | </section> | 450 | </section> |
232 | 451 | ||