summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/bsp-guide/bsp.xml89
1 files changed, 63 insertions, 26 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 75640cc58c..ff8a4818f8 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -324,21 +324,22 @@ meta-<bsp_name>/recipes-kernel/linux/linux-wrs_git.bbappend
324 <para> 324 <para>
325 For your BSP you typically want to use an existing Poky kernel found in the 325 For your BSP you typically want to use an existing Poky kernel found in the
326 Poky repository at <filename class='directory'>meta/recipes-kernel/kernel</filename>. 326 Poky repository at <filename class='directory'>meta/recipes-kernel/kernel</filename>.
327 You can append your specific changes to the kernel by using a 327 You can append your specific changes to the kernel recipe by using an append file,
328 <filename>.bbappend</filename> file, which is located in the 328 which is located in the
329 <filename class='directory'>meta-&lt;bsp_name&gt;/recipes-kernel/linux</filename> 329 <filename class='directory'>meta-&lt;bsp_name&gt;/recipes-kernel/linux</filename>
330 directory. 330 directory.
331 </para> 331 </para>
332 <para> 332 <para>
333 Consider a BSP that uses the <filename>linux-yocto-stable_git.bb</filename> kernel. 333 Consider a BSP that uses the <filename>linux-yocto-stable_git.bb</filename> kernel,
334 You would use the <filename>linux-yocto-stable_git.bbappend</filename> file to add 334 which is the preferred kernel to use for developing a new BSP using the Yocto Project.
335 You would use the <filename>linux-yocto-stable_git.bbappend</filename> file to append
335 specific BSP settings to the kernel, thus configuring the kernel for your particular BSP. 336 specific BSP settings to the kernel, thus configuring the kernel for your particular BSP.
336 </para> 337 </para>
337 <para> 338 <para>
338 Consider an example for the existing "crownbay" BSP. 339 Consider an example for the existing "crownbay" BSP.
339 The <filename>.bbaappend</filename> file used for the "crownbay" BSP is: 340 The append file used for the "crownbay" BSP is:
340 <programlisting> 341 <programlisting>
341meta-crownbay/recipes-kernel/linux/linux-wrs_git.bbappend 342meta-crownbay/recipes-kernel/linux/linux-yocto-stable_git.bbappend
342 </programlisting> 343 </programlisting>
343 The file contains the following: 344 The file contains the following:
344 <programlisting> 345 <programlisting>
@@ -346,31 +347,67 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}"
346COMPATIBLE_MACHINE_crownbay = "cronwbay" 347COMPATIBLE_MACHINE_crownbay = "cronwbay"
347KMACHINE_crownbay = "crownbay" 348KMACHINE_crownbay = "crownbay"
348 </programlisting> 349 </programlisting>
349 This <filename>.bbappend</filename> file adds "crownbay" as a compatible machine, 350 This append file adds "crownbay" as a compatible machine,
350 and additionally sets a Yocto Kernel-specific variable that identifies the name of the 351 and additionally sets a Yocto Kernel-specific variable that identifies the name of the
351 BSP branch to use in the GIT repository to find configuration information. 352 BSP branch to use in the GIT repository to find configuration information.
352 </para> 353 </para>
353 <note><para> 354 <para>
354 For an established BSP the configuration information is incorporated directly into the 355 One thing missing in this particular BSP, which you will typically need when
355 git tree. 356 developing a BSP, is the kernel configuration (.config) for your BSP.
356 For a new BSP, however, the <filename>.bbappend</filename> file needs to 357 When developing a BSP, you probably have a kernel configuration file or a set of kernel
357 include its own set of configuration options in a file called 358 configuration files that, when taken together, define the kernel configuration for your BSP.
358 <filename>defconfig</filename> located in a directory that matches the recipe name. 359 You can accomplish this definition by putting the configurations in a file or a set of files
360 inside a directory located at the same level as your append file and having the same name
361 as the kernel.
362 With all these conditions met simply reference those files in a SRC_URI statement in the append
363 file.
364 </para>
365 <para>
366 For example, suppose you had a set of configuration options in a file called
367 <filename>defonfig</filename>.
368 If you put that file inside a directory named
369 <filename class='directory'>/linux-yocto-stable_git</filename> and then added
370 a SRC_URI statement such as the following to the append file, those configuration
371 options will be picked up and applied when the kernel is built.
359 <programlisting> 372 <programlisting>
360SRC_URI += "file://defconfig" 373SRC_URI += "file://defconfig"
361 </programlisting> 374 </programlisting>
362 Once a BSP is committed, the Yocto kernel maintainer moves this configuration information 375 </para>
363 into the git tree so that the <filename>.bbappend</filename> file does not need to locate 376 <para>
364 its own configuration options. 377 As mentioned earlier, you can group related configurations into multiple files and
365 Again, the initial configuration options using the SRC_URI are put into a 378 name them all in the SRC_URI statement as well.
366 directory named 379 For example, you could group separate configurations specifically for ethernet and graphics
367 <filename class='directory'>meta-&lt;bsp_name&gt;/recipes/linux/linux-yocto-stable</filename>. 380 into their own files and add those by using a SRC_URI statement like the
368 </para> 381 following in your append file:
369 <para> 382 <programlisting>
370 You can find more information about creating a BSP that is based on an existing similar 383SRC_URI += "file://defconfig \
371 BSP by reading the "Creating a BSP Based on an Existing Similar BSP" section in the 384 file://eth.cfg \
372 "<ulink url="http://www.yoctoproject.org/community/documentation">Yocto Project 385 file://gfx.cfg"
373 Kernel Architecture and Use Manual</ulink>". 386 </programlisting>
387 </para>
388 <para>
389 The FILESEXTRAPATHS variable is boilerplated here in order to make it easy to do that.
390 It basically allows those configuration files to be found by the build process.
391 </para>
392 <note><para>
393 Other methods exist to accomplish grouping and defining configuration options.
394 For example, you could directly add configuration options to the Yocto kernel
395 <filename class='directory'>wrs_meta</filename> branch for your BSP.
396 The configuration options will likely end up in that location anyway if the BSP gets
397 added to the Yocto Project.
398 For information on how to add these configurations directly, see the
399 "Yocto Project Kernel Architecture and Use Manual" on the
400 <ulink url="http://yoctoproject.org/community/documentation">Yocto Project website
401 Documentation Page</ulink>
402 </para>
403 <para>
404 In general, however, the Yocto Project maintainers take care of moving the SRC_URI-specified
405 configuration options to the <filename class='directory'>wrs_meta</filename> branch.
406 Not only is it easier for BSP developers to not have to worry about putting those
407 configurations in the branch, but having the manintainers do it allows them to apply
408 'global' knowledge about the kinds of common configuration options multiple BSPs in
409 the tree are typically using.
410 This allows for promotion of common configurations into common features.
374 </para></note> 411 </para></note>
375 </section> 412 </section>
376 413