path: root/documentation/bsp-guide/bsp.xml
diff options
Diffstat (limited to 'documentation/bsp-guide/bsp.xml')
1 files changed, 1493 insertions, 0 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
new file mode 100644
index 0000000..eef36cb
--- /dev/null
+++ b/documentation/bsp-guide/bsp.xml
@@ -0,0 +1,1493 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
5<chapter id='bsp'>
7 <title>Board Support Packages (BSP) - Developer's Guide</title>
9 <para>
10 A Board Support Package (BSP) is a collection of information that
11 defines how to support a particular hardware device, set of devices, or
12 hardware platform.
13 The BSP includes information about the hardware features
14 present on the device and kernel configuration information along with any
15 additional hardware drivers required.
16 The BSP also lists any additional software
17 components required in addition to a generic Linux software stack for both
18 essential and optional platform features.
19 </para>
21 <para>
22 This guide presents information about BSP Layers, defines a structure for components
23 so that BSPs follow a commonly understood layout, discusses how to customize
24 a recipe for a BSP, addresses BSP licensing, and provides information that
25 shows you how to create and manage a
26 <link linkend='bsp-layers'>BSP Layer</link> using two Yocto Project
27 <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
28 </para>
30 <section id='bsp-layers'>
31 <title>BSP Layers</title>
33 <para>
34 The BSP consists of a file structure inside a base directory.
35 Collectively, you can think of the base directory and the file structure
36 as a BSP Layer.
37 Although not a strict requirement, layers in the Yocto Project use the
38 following well established naming convention:
39 <literallayout class='monospaced'>
40 meta-&lt;bsp_name&gt;
41 </literallayout>
42 The string "meta-" is prepended to the machine or platform name, which is
43 "bsp_name" in the above form.
44 </para>
46 <para>
47 The layer's base directory (<filename>meta-&lt;bsp_name&gt;</filename>) is the root
48 of the BSP Layer.
49 This root is what you add to the
50 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
51 variable in the <filename>conf/bblayers.conf</filename> file found in the
52 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
53 Adding the root allows the OpenEmbedded build system to recognize the BSP
54 definition and from it build an image.
55 Here is an example:
56 <literallayout class='monospaced'>
57 BBLAYERS ?= " \
58 /usr/local/src/yocto/meta \
59 /usr/local/src/yocto/meta-yocto \
60 /usr/local/src/yocto/meta-yocto-bsp \
61 /usr/local/src/yocto/meta-mylayer \
62 "
65 /usr/local/src/yocto/meta \
66 /usr/local/src/yocto/meta-yocto \
67 "
68 </literallayout>
69 </para>
71 <para>
72 Some BSPs require additional layers on
73 top of the BSP's root layer in order to be functional.
74 For these cases, you also need to add those layers to the
75 <filename>BBLAYERS</filename> variable in order to build the BSP.
76 You must also specify in the "Dependencies" section of the BSP's
77 <filename>README</filename> file any requirements for additional
78 layers and, preferably, any
79 build instructions that might be contained elsewhere
80 in the <filename>README</filename> file.
81 </para>
83 <para>
84 Some layers function as a layer to hold other BSP layers.
85 An example of this type of layer is the <filename>meta-intel</filename> layer.
86 The <filename>meta-intel</filename> layer contains many individual BSP layers.
87 </para>
89 <para>
90 For more detailed information on layers, see the
91 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
92 section of the Yocto Project Development Manual.
93 </para>
94 </section>
97 <section id="bsp-filelayout">
98 <title>Example Filesystem Layout</title>
100 <para>
101 Providing a common form allows end-users to understand and become familiar
102 with the layout.
103 A common format also encourages standardization of software support of hardware.
104 </para>
106 <para>
107 The proposed form does have elements that are specific to the
108 OpenEmbedded build system.
109 It is intended that this information can be
110 used by other build systems besides the OpenEmbedded build system
111 and that it will be simple
112 to extract information and convert it to other formats if required.
113 The OpenEmbedded build system, through its standard layers mechanism, can directly
114 accept the format described as a layer.
115 The BSP captures all
116 the hardware-specific details in one place in a standard format, which is
117 useful for any person wishing to use the hardware platform regardless of
118 the build system they are using.
119 </para>
121 <para>
122 The BSP specification does not include a build system or other tools -
123 it is concerned with the hardware-specific components only.
124 At the end-distribution point, you can ship the BSP combined with a build system
125 and other tools.
126 However, it is important to maintain the distinction that these
127 are separate components that happen to be combined in certain end products.
128 </para>
130 <para>
131 Before looking at the common form for the file structure inside a BSP Layer,
132 you should be aware that some requirements do exist in order for a BSP to
133 be considered compliant with the Yocto Project.
134 For that list of requirements, see the
135 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
136 section.
137 </para>
139 <para>
140 Below is the common form for the file structure inside a BSP Layer.
141 While you can use this basic form for the standard, realize that the actual structures
142 for specific BSPs could differ.
144 <literallayout class='monospaced'>
145 meta-&lt;bsp_name&gt;/
146 meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
147 meta-&lt;bsp_name&gt;/README
148 meta-&lt;bsp_name&gt;/README.sources
149 meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
150 meta-&lt;bsp_name&gt;/conf/layer.conf
151 meta-&lt;bsp_name&gt;/conf/machine/*.conf
152 meta-&lt;bsp_name&gt;/recipes-bsp/*
153 meta-&lt;bsp_name&gt;/recipes-core/*
154 meta-&lt;bsp_name&gt;/recipes-graphics/*
155 meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_&lt;kernel_rev&gt;.bbappend
156 </literallayout>
157 </para>
159 <para>
160 Below is an example of the Crown Bay BSP:
162 <literallayout class='monospaced'>
163 meta-crownbay/COPYING.MIT
164 meta-crownbay/README
165 meta-crownbay/README.sources
166 meta-crownbay/binary/
167 meta-crownbay/conf/
168 meta-crownbay/conf/layer.conf
169 meta-crownbay/conf/machine/
170 meta-crownbay/conf/machine/crownbay.conf
171 meta-crownbay/conf/machine/crownbay-noemgd.conf
172 meta-crownbay/recipes-bsp/
173 meta-crownbay/recipes-bsp/formfactor/
174 meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
175 meta-crownbay/recipes-bsp/formfactor/formfactor/
176 meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/
177 meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig
178 meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/
179 meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig
180 meta-crownbay/recipes-graphics/
181 meta-crownbay/recipes-graphics/xorg-xserver/
182 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
183 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/
184 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/
185 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf
186 meta-crownbay/recipes-kernel/
187 meta-crownbay/recipes-kernel/linux/
188 meta-crownbay/recipes-kernel/linux/linux-yocto-dev.bbappend
189 meta-crownbay/recipes-kernel/linux/linux-yocto-rt_3.10.bbappend
190 meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend
191 meta-crownbay/recipes-kernel/linux/linux-yocto_3.14.bbappend
192 </literallayout>
193 </para>
195 <para>
196 The following sections describe each part of the proposed BSP format.
197 </para>
199 <section id="bsp-filelayout-license">
200 <title>License Files</title>
202 <para>
203 You can find these files in the BSP Layer at:
204 <literallayout class='monospaced'>
205 meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
206 </literallayout>
207 </para>
209 <para>
210 These optional files satisfy licensing requirements for the BSP.
211 The type or types of files here can vary depending on the licensing requirements.
212 For example, in the Crown Bay BSP all licensing requirements are handled with the
213 <filename>COPYING.MIT</filename> file.
214 </para>
216 <para>
217 Licensing files can be MIT, BSD, GPLv*, and so forth.
218 These files are recommended for the BSP but are optional and totally up to the BSP developer.
219 </para>
220 </section>
222 <section id="bsp-filelayout-readme">
223 <title>README File</title>
224 <para>
225 You can find this file in the BSP Layer at:
226 <literallayout class='monospaced'>
227 meta-&lt;bsp_name&gt;/README
228 </literallayout>
229 </para>
231 <para>
232 This file provides information on how to boot the live images that are optionally
233 included in the <filename>binary/</filename> directory.
234 The <filename>README</filename> file also provides special information needed for
235 building the image.
236 </para>
238 <para>
239 At a minimum, the <filename>README</filename> file must
240 contain a list of dependencies, such as the names of
241 any other layers on which the BSP depends and the name of
242 the BSP maintainer with his or her contact information.
243 </para>
244 </section>
246 <section id="bsp-filelayout-readme-sources">
247 <title>README.sources File</title>
248 <para>
249 You can find this file in the BSP Layer at:
250 <literallayout class='monospaced'>
251 meta-&lt;bsp_name&gt;/README.sources
252 </literallayout>
253 </para>
255 <para>
256 This file provides information on where to locate the BSP source files.
257 For example, information provides where to find the sources that comprise
258 the images shipped with the BSP.
259 Information is also included to help you find the
260 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
261 used to generate the images that ship with the BSP.
262 </para>
263 </section>
265 <section id="bsp-filelayout-binary">
266 <title>Pre-built User Binaries</title>
267 <para>
268 You can find these files in the BSP Layer at:
269 <literallayout class='monospaced'>
270 meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
271 </literallayout>
272 </para>
274 <para>
275 This optional area contains useful pre-built kernels and user-space filesystem
276 images appropriate to the target system.
277 This directory typically contains graphical (e.g. Sato) and minimal live images
278 when the BSP tarball has been created and made available in the
279 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
280 You can use these kernels and images to get a system running and quickly get started
281 on development tasks.
282 </para>
284 <para>
285 The exact types of binaries present are highly hardware-dependent.
286 However, a README file should be present in the BSP Layer that explains how to use
287 the kernels and images with the target hardware.
288 If pre-built binaries are present, source code to meet licensing requirements must also
289 exist in some form.
290 </para>
291 </section>
293 <section id='bsp-filelayout-layer'>
294 <title>Layer Configuration File</title>
295 <para>
296 You can find this file in the BSP Layer at:
297 <literallayout class='monospaced'>
298 meta-&lt;bsp_name&gt;/conf/layer.conf
299 </literallayout>
300 </para>
302 <para>
303 The <filename>conf/layer.conf</filename> file identifies the file structure as a
304 layer, identifies the
305 contents of the layer, and contains information about how the build
306 system should use it.
307 Generally, a standard boilerplate file such as the following works.
308 In the following example, you would replace "<filename>bsp</filename>" and
309 "<filename>_bsp</filename>" with the actual name
310 of the BSP (i.e. <filename>&lt;bsp_name&gt;</filename> from the example template).
311 </para>
313 <para>
314 <literallayout class='monospaced'>
315 # We have a conf and classes directory, add to BBPATH
316 BBPATH .= ":${LAYERDIR}"
318 # We have a recipes directory, add to BBFILES
319 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
320 ${LAYERDIR}/recipes-*/*/*.bbappend"
324 BBFILE_PRIORITY_bsp = "6"
325 </literallayout>
326 </para>
328 <para>
329 To illustrate the string substitutions, here are the corresponding statements
330 from the Crown Bay <filename>conf/layer.conf</filename> file:
331 <literallayout class='monospaced'>
332 BBFILE_COLLECTIONS += "crownbay"
333 BBFILE_PATTERN_crownbay = "^${LAYERDIR}/"
334 BBFILE_PRIORITY_crownbay = "6"
335 </literallayout>
336 </para>
338 <para>
339 This file simply makes
340 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
341 aware of the recipes and configuration directories.
342 The file must exist so that the OpenEmbedded build system can recognize the BSP.
343 </para>
344 </section>
346 <section id="bsp-filelayout-machine">
347 <title>Hardware Configuration Options</title>
348 <para>
349 You can find these files in the BSP Layer at:
350 <literallayout class='monospaced'>
351 meta-&lt;bsp_name&gt;/conf/machine/*.conf
352 </literallayout>
353 </para>
355 <para>
356 The machine files bind together all the information contained elsewhere
357 in the BSP into a format that the build system can understand.
358 If the BSP supports multiple machines, multiple machine configuration files
359 can be present.
360 These filenames correspond to the values to which users have set the
361 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
362 </para>
364 <para>
365 These files define things such as the kernel package to use
366 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
367 of virtual/kernel), the hardware drivers to
368 include in different types of images, any special software components
369 that are needed, any bootloader information, and also any special image
370 format requirements.
371 </para>
373 <para>
374 Each BSP Layer requires at least one machine file.
375 However, you can supply more than one file.
376 </para>
378 <para>
379 This <filename>crownbay.conf</filename> file could also include
380 a hardware "tuning" file that is commonly used to
381 define the package architecture and specify
382 optimization flags, which are carefully chosen to give best
383 performance on a given processor.
384 </para>
386 <para>
387 Tuning files are found in the <filename>meta/conf/machine/include</filename>
388 directory within the
389 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
390 For example, the <filename></filename> file resides in the
391 <filename>meta/conf/machine/include</filename> directory.
392 </para>
394 <para>
395 To use an include file, you simply include them in the machine configuration file.
396 For example, the Crown Bay BSP <filename>crownbay.conf</filename> contains the
397 following statements:
398 <literallayout class='monospaced'>
399 require conf/machine/include/
400 require conf/machine/include/
401 require conf/machine/include/
402 </literallayout>
403 </para>
404 </section>
406 <section id='bsp-filelayout-misc-recipes'>
407 <title>Miscellaneous BSP-Specific Recipe Files</title>
408 <para>
409 You can find these files in the BSP Layer at:
410 <literallayout class='monospaced'>
411 meta-&lt;bsp_name&gt;/recipes-bsp/*
412 </literallayout>
413 </para>
415 <para>
416 This optional directory contains miscellaneous recipe files for the BSP.
417 Most notably would be the formfactor files.
418 For example, in the Crown Bay BSP there is the
419 <filename>formfactor_0.0.bbappend</filename> file, which is an
420 append file used to augment the recipe that starts the build.
421 Furthermore, there are machine-specific settings used during the
422 build that are defined by the <filename>machconfig</filename> file.
423 In the Crown Bay example, two <filename>machconfig</filename> files
424 exist: one that supports the Intel® Embedded Media and Graphics
425 Driver (Intel® EMGD) and one that does not:
426 <literallayout class='monospaced'>
427 meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig
428 meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig
429 meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
430 </literallayout>
431 </para>
433 <note><para>
434 If a BSP does not have a formfactor entry, defaults are established according to
435 the formfactor configuration file that is installed by the main
436 formfactor recipe
437 <filename>meta/recipes-bsp/formfactor/</filename>,
438 which is found in the
439 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
440 </para></note>
441 </section>
443 <section id='bsp-filelayout-recipes-graphics'>
444 <title>Display Support Files</title>
445 <para>
446 You can find these files in the BSP Layer at:
447 <literallayout class='monospaced'>
448 meta-&lt;bsp_name&gt;/recipes-graphics/*
449 </literallayout>
450 </para>
452 <para>
453 This optional directory contains recipes for the BSP if it has
454 special requirements for graphics support.
455 All files that are needed for the BSP to support a display are kept here.
456 For example, the Crown Bay BSP's <filename>xorg.conf</filename> file
457 detects the graphics support needed (i.e. the Intel® Embedded Media
458 Graphics Driver (EMGD) or the Video Electronics Standards Association
459 (VESA) graphics):
460 <literallayout class='monospaced'>
461 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
462 meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf
463 </literallayout>
464 </para>
465 </section>
467 <section id='bsp-filelayout-kernel'>
468 <title>Linux Kernel Configuration</title>
469 <para>
470 You can find these files in the BSP Layer at:
471 <literallayout class='monospaced'>
472 meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_*.bbappend
473 </literallayout>
474 </para>
476 <para>
477 These files append your specific changes to the main kernel recipe you are using.
478 </para>
479 <para>
480 For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the
481 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
482 at <filename>meta/recipes-kernel/linux</filename>.
483 You can append your specific changes to the kernel recipe by using a
484 similarly named append file, which is located in the BSP Layer (e.g.
485 the <filename>meta-&lt;bsp_name&gt;/recipes-kernel/linux</filename> directory).
486 </para>
487 <para>
488 Suppose you are using the <filename></filename> recipe to build
489 the kernel.
490 In other words, you have selected the kernel in your
491 <filename>&lt;bsp_name&gt;.conf</filename> file by adding these types
492 of statements:
493 <literallayout class='monospaced'>
494 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
495 PREFERRED_VERSION_linux-yocto ?= "3.10%"
496 </literallayout>
497 <note>
498 When the preferred provider is assumed by default, the
499 <filename>PREFERRED_PROVIDER</filename> statement does not appear in the
500 <filename>&lt;bsp_name&gt;.conf</filename> file.
501 </note>
502 You would use the <filename>linux-yocto_3.10.bbappend</filename> file to append
503 specific BSP settings to the kernel, thus configuring the kernel for your particular BSP.
504 </para>
505 <para>
506 As an example, look at the existing Crown Bay BSP.
507 The append file used is:
508 <literallayout class='monospaced'>
509 meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend
510 </literallayout>
511 The following listing shows the file.
512 Be aware that the actual commit ID strings in this example listing might be different
513 than the actual strings in the file from the <filename>meta-intel</filename>
514 Git source repository.
515 <literallayout class='monospaced'>
516 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
519 COMPATIBLE_MACHINE_crownbay = "crownbay"
520 KMACHINE_crownbay = "crownbay"
521 KBRANCH_crownbay = "standard/crownbay"
522 KERNEL_FEATURES_append_crownbay = " features/drm-emgd/drm-emgd-1.18 cfg/vesafb"
524 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
525 KMACHINE_crownbay-noemgd = "crownbay"
526 KBRANCH_crownbay-noemgd = "standard/crownbay"
527 KERNEL_FEATURES_append_crownbay-noemgd = " cfg/vesafb"
529 LINUX_VERSION_crownbay = "3.10.35"
530 SRCREV_meta_crownbay = "b6e58b33dd427fe471f8827c83e311acdf4558a4"
531 SRCREV_machine_crownbay = "cee957655fe67826b2e827e2db41f156fa8f0cc4"
532 SRCREV_emgd_crownbay = "42d5e4548e8e79e094fa8697949eed4cf6af00a3"
534 LINUX_VERSION_crownbay-noemgd = "3.10.35"
535 SRCREV_meta_crownbay-noemgd = "b6e58b33dd427fe471f8827c83e311acdf4558a4"
536 SRCREV_machine_crownbay-noemgd = "cee957655fe67826b2e827e2db41f156fa8f0cc4"
538 SRC_URI_crownbay = "git://;protocol=git;nocheckout=1;branch=${KBRANCH},${KMETA},emgd-1.18;name=machine,meta,emgd"
539 </literallayout>
540 This append file contains statements used to support the Crown Bay BSP.
541 The file defines machines using the
542 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
543 variable and uses the
544 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> variable to
545 ensure the machine name used by the OpenEmbedded build system maps to the
546 machine name used by the Linux Yocto kernel.
547 The file also uses the optional
548 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> variable
549 to ensure the build process uses the <filename>standard/crownbay</filename>
550 kernel branch.
551 The
552 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
553 variable enables features specific to the kernel
554 (e.g. graphics support in this case).
555 The append file points to specific commits in the
556 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> Git
557 repository and the <filename>meta</filename> Git repository branches to identify the
558 exact kernel needed to build the Crown Bay BSP.
559 Finally, the file includes the
560 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
561 statement to locate the source files.
562 </para>
564 <para>
565 One thing missing in this particular BSP, which you will typically need when
566 developing a BSP, is the kernel configuration file (<filename>.config</filename>) for your BSP.
567 When developing a BSP, you probably have a kernel configuration file or a set of kernel
568 configuration files that, when taken together, define the kernel configuration for your BSP.
569 You can accomplish this definition by putting the configurations in a file or a set of files
570 inside a directory located at the same level as your kernel's append file and having the same
571 name as the kernel's main recipe file.
572 With all these conditions met, simply reference those files in the
573 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
574 statement in the append file.
575 </para>
577 <para>
578 For example, suppose you had some configuration options in a file called
579 <filename>network_configs.cfg</filename>.
580 You can place that file inside a directory named <filename>linux-yocto</filename> and then add
581 a <filename>SRC_URI</filename> statement such as the following to the append file.
582 When the OpenEmbedded build system builds the kernel, the configuration options are
583 picked up and applied.
584 <literallayout class='monospaced'>
585 SRC_URI += "file://network_configs.cfg"
586 </literallayout>
587 </para>
589 <para>
590 To group related configurations into multiple files, you perform a similar procedure.
591 Here is an example that groups separate configurations specifically for Ethernet and graphics
592 into their own files and adds the configurations
593 by using a <filename>SRC_URI</filename> statement like the following in your append file:
594 <literallayout class='monospaced'>
595 SRC_URI += "file://myconfig.cfg \
596 file://eth.cfg \
597 file://gfx.cfg"
598 </literallayout>
599 </para>
601 <para>
602 The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
603 variable is in boilerplate form in the
604 previous example in order to make it easy to do that.
605 This variable must be in your layer or BitBake will not find the patches or
606 configurations even if you have them in your <filename>SRC_URI</filename>.
607 The <filename>FILESEXTRAPATHS</filename> variable enables the build process to
608 find those configuration files.
609 </para>
611 <note>
612 <para>
613 Other methods exist to accomplish grouping and defining configuration options.
614 For example, if you are working with a local clone of the kernel repository,
615 you could checkout the kernel's <filename>meta</filename> branch, make your changes,
616 and then push the changes to the local bare clone of the kernel.
617 The result is that you directly add configuration options to the
618 <filename>meta</filename> branch for your BSP.
619 The configuration options will likely end up in that location anyway if the BSP gets
620 added to the Yocto Project.
621 </para>
623 <para>
624 In general, however, the Yocto Project maintainers take care of moving the
625 <filename>SRC_URI</filename>-specified
626 configuration options to the kernel's <filename>meta</filename> branch.
627 Not only is it easier for BSP developers to not have to worry about putting those
628 configurations in the branch, but having the maintainers do it allows them to apply
629 'global' knowledge about the kinds of common configuration options multiple BSPs in
630 the tree are typically using.
631 This allows for promotion of common configurations into common features.
632 </para>
633 </note>
634 </section>
635 </section>
637 <section id='requirements-and-recommendations-for-released-bsps'>
638 <title>Requirements and Recommendations for Released BSPs</title>
640 <para>
641 Certain requirements exist for a released BSP to be considered
642 compliant with the Yocto Project.
643 Additionally, recommendations also exist.
644 This section describes the requirements and recommendations for
645 released BSPs.
646 </para>
648 <section id='released-bsp-requirements'>
649 <title>Released BSP Requirements</title>
651 <para>
652 Before looking at BSP requirements, you should consider the following:
653 <itemizedlist>
654 <listitem><para>The requirements here assume the BSP layer is a well-formed, "legal"
655 layer that can be added to the Yocto Project.
656 For guidelines on creating a layer that meets these base requirements, see the
657 "<link linkend='bsp-layers'>BSP Layers</link>" and the
658 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding
659 and Creating Layers"</ulink> in the Yocto Project Development Manual.</para></listitem>
660 <listitem><para>The requirements in this section apply regardless of how you
661 ultimately package a BSP.
662 You should consult the packaging and distribution guidelines for your
663 specific release process.
664 For an example of packaging and distribution requirements, see the
665 "<ulink url=''>Third Party BSP Release Process</ulink>"
666 wiki page.</para></listitem>
667 <listitem><para>The requirements for the BSP as it is made available to a developer
668 are completely independent of the released form of the BSP.
669 For example, the BSP Metadata can be contained within a Git repository
670 and could have a directory structure completely different from what appears
671 in the officially released BSP layer.</para></listitem>
672 <listitem><para>It is not required that specific packages or package
673 modifications exist in the BSP layer, beyond the requirements for general
674 compliance with the Yocto Project.
675 For example, no requirement exists dictating that a specific kernel or
676 kernel version be used in a given BSP.</para></listitem>
677 </itemizedlist>
678 </para>
680 <para>
681 Following are the requirements for a released BSP that conforms to the
682 Yocto Project:
683 <itemizedlist>
684 <listitem><para><emphasis>Layer Name:</emphasis>
685 The BSP must have a layer name that follows the Yocto
686 Project standards.
687 For information on BSP layer names, see the
688 "<link linkend='bsp-layers'>BSP Layers</link>" section.
689 </para></listitem>
690 <listitem><para><emphasis>File System Layout:</emphasis>
691 When possible, use the same directory names in your
692 BSP layer as listed in the <filename>recipes.txt</filename> file.
693 In particular, you should place recipes
694 (<filename>.bb</filename> files) and recipe
695 modifications (<filename>.bbappend</filename> files) into
696 <filename>recipes-*</filename> subdirectories by functional area
697 as outlined in <filename>recipes.txt</filename>.
698 If you cannot find a category in <filename>recipes.txt</filename>
699 to fit a particular recipe, you can make up your own
700 <filename>recipes-*</filename> subdirectory.
701 You can find <filename>recipes.txt</filename> in the
702 <filename>meta</filename> directory of the
703 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
704 or in the OpenEmbedded Core Layer
705 (<filename>openembedded-core</filename>) found at
706 <ulink url=''></ulink>.
707 </para>
708 <para>Within any particular <filename>recipes-*</filename> category, the layout
709 should match what is found in the OpenEmbedded Core
710 Git repository (<filename>openembedded-core</filename>)
711 or the Source Directory (<filename>poky</filename>).
712 In other words, make sure you place related files in appropriately
713 related <filename>recipes-*</filename> subdirectories specific to the
714 recipe's function, or within a subdirectory containing a set of closely-related
715 recipes.
716 The recipes themselves should follow the general guidelines
717 for recipes used in the Yocto Project found in the
718 "<ulink url=''>Yocto Recipe and Patch Style Guide</ulink>".
719 </para></listitem>
720 <listitem><para><emphasis>License File:</emphasis>
721 You must include a license file in the
722 <filename>meta-&lt;bsp_name&gt;</filename> directory.
723 This license covers the BSP Metadata as a whole.
724 You must specify which license to use since there is no
725 default license if one is not specified.
726 See the
727 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
728 file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer
729 as an example.</para></listitem>
730 <listitem><para><emphasis>README File:</emphasis>
731 You must include a <filename>README</filename> file in the
732 <filename>meta-&lt;bsp_name&gt;</filename> directory.
733 See the
734 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/README'><filename>README</filename></ulink>
735 file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer
736 as an example.</para>
737 <para>At a minimum, the <filename>README</filename> file should
738 contain the following:
739 <itemizedlist>
740 <listitem><para>A brief description about the hardware the BSP
741 targets.</para></listitem>
742 <listitem><para>A list of all the dependencies
743 on which a BSP layer depends.
744 These dependencies are typically a list of required layers needed
745 to build the BSP.
746 However, the dependencies should also contain information regarding
747 any other dependencies the BSP might have.</para></listitem>
748 <listitem><para>Any required special licensing information.
749 For example, this information includes information on
750 special variables needed to satisfy a EULA,
751 or instructions on information needed to build or distribute
752 binaries built from the BSP Metadata.</para></listitem>
753 <listitem><para>The name and contact information for the
754 BSP layer maintainer.
755 This is the person to whom patches and questions should
756 be sent.
757 For information on how to find the right person, see the
758 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
759 section in the Yocto Project Development Manual.
760 </para></listitem>
761 <listitem><para>Instructions on how to build the BSP using the BSP
762 layer.</para></listitem>
763 <listitem><para>Instructions on how to boot the BSP build from
764 the BSP layer.</para></listitem>
765 <listitem><para>Instructions on how to boot the binary images
766 contained in the <filename>binary</filename> directory,
767 if present.</para></listitem>
768 <listitem><para>Information on any known bugs or issues that users
769 should know about when either building or booting the BSP
770 binaries.</para></listitem>
771 </itemizedlist></para></listitem>
772 <listitem><para><emphasis>README.sources File:</emphasis>
773 You must include a <filename>README.sources</filename> in the
774 <filename>meta-&lt;bsp_name&gt;</filename> directory.
775 This file specifies exactly where you can find the sources used to
776 generate the binary images contained in the
777 <filename>binary</filename> directory, if present.
778 See the
779 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/README.sources'><filename>README.sources</filename></ulink>
780 file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer
781 as an example.</para></listitem>
782 <listitem><para><emphasis>Layer Configuration File:</emphasis>
783 You must include a <filename>conf/layer.conf</filename> in the
784 <filename>meta-&lt;bsp_name&gt;</filename> directory.
785 This file identifies the <filename>meta-&lt;bsp_name&gt;</filename>
786 BSP layer as a layer to the build system.</para></listitem>
787 <listitem><para><emphasis>Machine Configuration File:</emphasis>
788 You must include one or more <filename>conf/machine/&lt;bsp_name&gt;.conf</filename>
789 files in the <filename>meta-&lt;bsp_name&gt;</filename> directory.
790 These configuration files define machine targets that can be built
791 using the BSP layer.
792 Multiple machine configuration files define variations of machine
793 configurations that are supported by the BSP.
794 If a BSP supports multiple machine variations, you need to
795 adequately describe each variation in the BSP
796 <filename>README</filename> file.
797 Do not use multiple machine configuration files to describe disparate
798 hardware.
799 If you do have very different targets, you should create separate
800 BSP layers for each target.
801 <note>It is completely possible for a developer to structure the
802 working repository as a conglomeration of unrelated BSP
803 files, and to possibly generate BSPs targeted for release
804 from that directory using scripts or some other mechanism
805 (e.g. <filename>meta-yocto-bsp</filename> layer).
806 Such considerations are outside the scope of this document.</note>
807 </para></listitem>
808 </itemizedlist>
809 </para>
810 </section>
812 <section id='released-bsp-recommendations'>
813 <title>Released BSP Recommendations</title>
815 <para>
816 Following are recommendations for a released BSP that conforms to the
817 Yocto Project:
818 <itemizedlist>
819 <listitem><para><emphasis>Bootable Images:</emphasis>
820 BSP releases
821 can contain one or more bootable images.
822 Including bootable images allows users to easily try out the BSP
823 on their own hardware.</para>
824 <para>In some cases, it might not be convenient to include a
825 bootable image.
826 In this case, you might want to make two versions of the
827 BSP available: one that contains binary images, and one
828 that does not.
829 The version that does not contain bootable images avoids
830 unnecessary download times for users not interested in the images.
831 </para>
832 <para>If you need to distribute a BSP and include bootable images or build kernel and
833 filesystems meant to allow users to boot the BSP for evaluation
834 purposes, you should put the images and artifacts within a
835 <filename>binary/</filename> subdirectory located in the
836 <filename>meta-&lt;bsp_name&gt;</filename> directory.
837 <note>If you do include a bootable image as part of the BSP and the image
838 was built by software covered by the GPL or other open source licenses,
839 it is your responsibility to understand
840 and meet all licensing requirements, which could include distribution
841 of source files.</note></para></listitem>
842 <listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis>
843 Kernel recipes in the BSP should be based on a Yocto Linux kernel.
844 Basing your recipes on these kernels reduces the costs for maintaining
845 the BSP and increases its scalability.
846 See the <filename>Yocto Linux Kernel</filename> category in the
847 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
848 for these kernels.</para></listitem>
849 </itemizedlist>
850 </para>
851 </section>
852 </section>
854 <section id='customizing-a-recipe-for-a-bsp'>
855 <title>Customizing a Recipe for a BSP</title>
857 <para>
858 If you plan on customizing a recipe for a particular BSP, you need to do the
859 following:
860 <itemizedlist>
861 <listitem><para>Create a <filename>.bbappend</filename>
862 file for the modified recipe.
863 For information on using append files, see the
864 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
865 section in the Yocto Project Development Manual.
866 </para></listitem>
867 <listitem><para>
868 Ensure your directory structure in the BSP layer
869 that supports your machine is such that it can be found
870 by the build system.
871 See the example later in this section for more information.
872 </para></listitem>
873 <listitem><para>
874 Put the append file in a directory whose name matches
875 the machine's name and is located in an appropriate
876 sub-directory inside the BSP layer (i.e.
877 <filename>recipes-bsp</filename>, <filename>recipes-graphics</filename>,
878 <filename>recipes-core</filename>, and so forth).
879 </para></listitem>
880 <listitem><para>Place the BSP-specific files in the directory named for
881 your machine inside the BSP layer.
882 </para></listitem>
883 </itemizedlist>
884 </para>
886 <para>
887 Following is a specific example to help you better understand the process.
888 Consider an example that customizes a recipe by adding
889 a BSP-specific configuration file named <filename>interfaces</filename> to the
890 <filename></filename> recipe for machine "xyz".
891 Do the following:
892 <orderedlist>
893 <listitem><para>Edit the <filename>init-ifupdown_1.0.bbappend</filename> file so that it
894 contains the following:
895 <literallayout class='monospaced'>
896 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
897 </literallayout>
898 The append file needs to be in the
899 <filename>meta-xyz/recipes-core/init-ifupdown</filename> directory.
900 </para></listitem>
901 <listitem><para>Create and place the new <filename>interfaces</filename>
902 configuration file in the BSP's layer here:
903 <literallayout class='monospaced'>
904 meta-xyz/recipes-core/init-ifupdown/files/xyz/interfaces
905 </literallayout>
906 The
907 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
908 variable in the append files extends the search path
909 the build system uses to find files during the build.
910 Consequently, for this example you need to have the
911 <filename>files</filename> directory in the same location
912 as your append file.</para></listitem>
913 </orderedlist>
914 </para>
915 </section>
917 <section id='bsp-licensing-considerations'>
918 <title>BSP Licensing Considerations</title>
920 <para>
921 In some cases, a BSP contains separately licensed Intellectual Property (IP)
922 for a component or components.
923 For these cases, you are required to accept the terms of a commercial or other
924 type of license that requires some kind of explicit End User License Agreement (EULA).
925 Once the license is accepted, the OpenEmbedded build system can then build and
926 include the corresponding component in the final BSP image.
927 If the BSP is available as a pre-built image, you can download the image after
928 agreeing to the license or EULA.
929 </para>
931 <para>
932 You could find that some separately licensed components that are essential
933 for normal operation of the system might not have an unencumbered (or free)
934 substitute.
935 Without these essential components, the system would be non-functional.
936 Then again, you might find that other licensed components that are simply
937 'good-to-have' or purely elective do have an unencumbered, free replacement
938 component that you can use rather than agreeing to the separately licensed component.
939 Even for components essential to the system, you might find an unencumbered component
940 that is not identical but will work as a less-capable version of the
941 licensed version in the BSP recipe.
942 </para>
944 <para>
945 For cases where you can substitute a free component and still
946 maintain the system's functionality, the "Downloads" page from the
947 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website's</ulink>
948 makes available de-featured BSPs
949 that are completely free of any IP encumbrances.
950 For these cases, you can use the substitution directly and
951 without any further licensing requirements.
952 If present, these fully de-featured BSPs are named appropriately
953 different as compared to the names of the respective
954 encumbered BSPs.
955 If available, these substitutions are your
956 simplest and most preferred options.
957 Use of these substitutions of course assumes the resulting functionality meets
958 system requirements.
959 </para>
961 <para>
962 If however, a non-encumbered version is unavailable or
963 it provides unsuitable functionality or quality, you can use an encumbered
964 version.
965 </para>
967 <para>
968 A couple different methods exist within the OpenEmbedded build system to
969 satisfy the licensing requirements for an encumbered BSP.
970 The following list describes them in order of preference:
971 <orderedlist>
972 <listitem><para><emphasis>Use the <filename>LICENSE_FLAGS</filename> variable
973 to define the recipes that have commercial or other types of
974 specially-licensed packages:</emphasis>
975 For each of those recipes, you can
976 specify a matching license string in a
977 <filename>local.conf</filename> variable named
978 <filename>LICENSE_FLAGS_WHITELIST</filename>.
979 Specifying the matching license string signifies that you agree to the license.
980 Thus, the build system can build the corresponding recipe and include
981 the component in the image.
982 See the
983 "<ulink url='&YOCTO_DOCS_REF_URL;#enabling-commercially-licensed-recipes'>Enabling
984 Commercially Licensed Recipes</ulink>" section in the Yocto Project Reference
985 Manual for details on how to use these variables.</para>
986 <para>If you build as you normally would, without
987 specifying any recipes in the
988 <filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and
989 provides you with the list of recipes that you have
990 tried to include in the image that need entries in
991 the <filename>LICENSE_FLAGS_WHITELIST</filename>.
992 Once you enter the appropriate license flags into the whitelist,
993 restart the build to continue where it left off.
994 During the build, the prompt will not appear again
995 since you have satisfied the requirement.</para>
996 <para>Once the appropriate license flags are on the white list
997 in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you
998 can build the encumbered image with no change at all
999 to the normal build process.</para></listitem>
1000 <listitem><para><emphasis>Get a pre-built version of the BSP:</emphasis>
1001 You can get this type of BSP by visiting the
1002 "Downloads" page of the
1003 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
1004 You can download BSP tarballs that contain proprietary components
1005 after agreeing to the licensing
1006 requirements of each of the individually encumbered
1007 packages as part of the download process.
1008 Obtaining the BSP this way allows you to access an encumbered
1009 image immediately after agreeing to the
1010 click-through license agreements presented by the
1011 website.
1012 Note that if you want to build the image
1013 yourself using the recipes contained within the BSP
1014 tarball, you will still need to create an
1015 appropriate <filename>LICENSE_FLAGS_WHITELIST</filename> to match the
1016 encumbered recipes in the BSP.</para></listitem>
1017 </orderedlist>
1018 </para>
1020 <note>
1021 Pre-compiled images are bundled with
1022 a time-limited kernel that runs for a
1023 predetermined amount of time (10 days) before it forces
1024 the system to reboot.
1025 This limitation is meant to discourage direct redistribution
1026 of the image.
1027 You must eventually rebuild the image if you want to remove this restriction.
1028 </note>
1029 </section>
1031 <section id='using-the-yocto-projects-bsp-tools'>
1032 <title>Using the Yocto Project's BSP Tools</title>
1034 <para>
1035 The Yocto Project includes a couple of tools that enable
1036 you to create a <link linkend='bsp-layers'>BSP layer</link>
1037 from scratch and do basic configuration and maintenance
1038 of the kernel without ever looking at a Metadata file.
1039 These tools are <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename>,
1040 respectively.
1041 </para>
1043 <para>
1044 The following sections describe the common location and help features as well
1045 as provide details for the
1046 <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename> tools.
1047 </para>
1049 <section id='common-features'>
1050 <title>Common Features</title>
1052 <para>
1053 Designed to have a command interface somewhat like
1054 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>, each
1055 tool is structured as a set of sub-commands under a
1056 top-level command.
1057 The top-level command (<filename>yocto-bsp</filename>
1058 or <filename>yocto-kernel</filename>) itself does
1059 nothing but invoke or provide help on the sub-commands
1060 it supports.
1061 </para>
1063 <para>
1064 Both tools reside in the <filename>scripts/</filename> subdirectory
1065 of the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1066 Consequently, to use the scripts, you must <filename>source</filename> the
1067 environment just as you would when invoking a build:
1068 <literallayout class='monospaced'>
1069 $ source oe-init-build-env [build_dir]
1070 </literallayout>
1071 </para>
1073 <para>
1074 The most immediately useful function is to get help on both tools.
1075 The built-in help system makes it easy to drill down at
1076 any time and view the syntax required for any specific command.
1077 Simply enter the name of the command with the <filename>help</filename>
1078 switch:
1079 <literallayout class='monospaced'>
1080 $ yocto-bsp help
1081 Usage:
1083 Create a customized Yocto BSP layer.
1085 usage: yocto-bsp [--version] [--help] COMMAND [ARGS]
1087 Current 'yocto-bsp' commands are:
1088 create Create a new Yocto BSP
1089 list List available values for options and BSP properties
1091 See 'yocto-bsp help COMMAND' for more information on a specific command.
1094 Options:
1095 --version show program's version number and exit
1096 -h, --help show this help message and exit
1097 -D, --debug output debug information
1098 </literallayout>
1099 </para>
1101 <para>
1102 Similarly, entering just the name of a sub-command shows the detailed usage
1103 for that sub-command:
1104 <literallayout class='monospaced'>
1105 $ yocto-bsp create
1107 Usage:
1109 Create a new Yocto BSP
1111 usage: yocto-bsp create &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
1112 [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
1114 This command creates a Yocto BSP based on the specified parameters.
1115 The new BSP will be a new Yocto BSP layer contained by default within
1116 the top-level directory specified as 'meta-bsp-name'. The -o option
1117 can be used to place the BSP layer in a directory with a different
1118 name and location.
1120 ...
1121 </literallayout>
1122 </para>
1124 <para>
1125 For any sub-command, you can use the word "help" option just before the
1126 sub-command to get more extensive documentation:
1127 <literallayout class='monospaced'>
1128 $ yocto-bsp help create
1130 NAME
1131 yocto-bsp create - Create a new Yocto BSP
1134 yocto-bsp create &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
1135 [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
1138 This command creates a Yocto BSP based on the specified
1139 parameters. The new BSP will be a new Yocto BSP layer contained
1140 by default within the top-level directory specified as
1141 'meta-bsp-name'. The -o option can be used to place the BSP layer
1142 in a directory with a different name and location.
1144 The value of the 'karch' parameter determines the set of files
1145 that will be generated for the BSP, along with the specific set of
1146 'properties' that will be used to fill out the BSP-specific
1147 portions of the BSP. The possible values for the 'karch' parameter
1148 can be listed via 'yocto-bsp list karch'.
1150 ...
1151 </literallayout>
1152 </para>
1154 <para>
1155 Now that you know where these two commands reside and how to access information
1156 on them, you should find it relatively straightforward to discover the commands
1157 necessary to create a BSP and perform basic kernel maintenance on that BSP using
1158 the tools.
1159 <note>
1160 You can also use the <filename>yocto-layer</filename> tool to create
1161 a "generic" layer.
1162 For information on this tool, see the
1163 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>"
1164 section in the Yocto Project Development Guide.
1165 </note>
1166 </para>
1168 <para>
1169 The next sections provide a concrete starting point to expand on a few points that
1170 might not be immediately obvious or that could use further explanation.
1171 </para>
1172 </section>
1175 <section id='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
1176 <title>Creating a new BSP Layer Using the yocto-bsp Script</title>
1178 <para>
1179 The <filename>yocto-bsp</filename> script creates a new
1180 <link linkend='bsp-layers'>BSP layer</link> for any architecture supported
1181 by the Yocto Project, as well as QEMU versions of the same.
1182 The default mode of the script's operation is to prompt you for information needed
1183 to generate the BSP layer.
1184 </para>
1186 <para>
1187 For the current set of BSPs, the script prompts you for various important
1188 parameters such as:
1189 <itemizedlist>
1190 <listitem><para>The kernel to use</para></listitem>
1191 <listitem><para>The branch of that kernel to use (or re-use)</para></listitem>
1192 <listitem><para>Whether or not to use X, and if so, which drivers to use</para></listitem>
1193 <listitem><para>Whether to turn on SMP</para></listitem>
1194 <listitem><para>Whether the BSP has a keyboard</para></listitem>
1195 <listitem><para>Whether the BSP has a touchscreen</para></listitem>
1196 <listitem><para>Remaining configurable items associated with the BSP</para></listitem>
1197 </itemizedlist>
1198 </para>
1200 <para>
1201 You use the <filename>yocto-bsp create</filename> sub-command to create
1202 a new BSP layer.
1203 This command requires you to specify a particular kernel architecture
1204 (<filename>karch</filename>) on which to base the BSP.
1205 Assuming you have sourced the environment, you can use the
1206 <filename>yocto-bsp list karch</filename> sub-command to list the
1207 architectures available for BSP creation as follows:
1208 <literallayout class='monospaced'>
1209 $ yocto-bsp list karch
1210 Architectures available:
1211 powerpc
1212 i386
1213 x86_64
1214 arm
1215 qemu
1216 mips
1217 </literallayout>
1218 </para>
1220 <para>
1221 The remainder of this section presents an example that uses
1222 <filename>myarm</filename> as the machine name and <filename>qemu</filename>
1223 as the machine architecture.
1224 Of the available architectures, <filename>qemu</filename> is the only architecture
1225 that causes the script to prompt you further for an actual architecture.
1226 In every other way, this architecture is representative of how creating a BSP for
1227 an actual machine would work.
1228 The reason the example uses this architecture is because it is an emulated architecture
1229 and can easily be followed without requiring actual hardware.
1230 </para>
1232 <para>
1233 As the <filename>yocto-bsp create</filename> command runs, default values for
1234 the prompts appear in brackets.
1235 Pressing enter without supplying anything on the command line or pressing enter
1236 with an invalid response causes the script to accept the default value.
1237 Once the script completes, the new <filename>meta-myarm</filename> BSP layer
1238 is created in the current working directory.
1239 This example assumes you have sourced the
1240 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1241 setup script.
1242 </para>
1244 <para>
1245 Following is the complete example:
1246 <literallayout class='monospaced'>
1247 $ yocto-bsp create myarm qemu
1248 Checking basic git connectivity...
1249 Done.
1251 Which qemu architecture would you like to use? [default: i386]
1252 1) i386 (32-bit)
1253 2) x86_64 (64-bit)
1254 3) ARM (32-bit)
1255 4) PowerPC (32-bit)
1256 5) MIPS (32-bit)
1257 3
1258 Would you like to use the default (3.10) kernel? (y/n) [default: y] y
1259 Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [y/n] [default: y]
1260 Getting branches from remote repo git://
1261 Please choose a machine branch to base your new BSP branch on: [default: standard/base]
1262 1) standard/arm-versatile-926ejs
1263 2) standard/base
1264 3) standard/beagleboard
1265 4) standard/beaglebone
1266 5) standard/ck
1267 6) standard/crownbay
1268 7) standard/edgerouter
1269 8) standard/emenlow
1270 9) standard/fri2
1271 10) standard/fsl-mpc8315e-rdb
1272 11) standard/mti-malta32
1273 12) standard/mti-malta64
1274 13) standard/qemuppc
1275 14) standard/routerstationpro
1276 15) standard/sys940x
1277 1
1278 Would you like SMP support? (y/n) [default: y]
1279 Does your BSP have a touchscreen? (y/n) [default: n]
1280 Does your BSP have a keyboard? (y/n) [default: y]
1282 New qemu BSP created in meta-myarm
1283 </literallayout>
1284 Take a closer look at the example now:
1285 <orderedlist>
1286 <listitem><para>For the QEMU architecture,
1287 the script first prompts you for which emulated architecture to use.
1288 In the example, we use the ARM architecture.
1289 </para></listitem>
1290 <listitem><para>The script then prompts you for the kernel.
1291 The default 3.14 kernel is acceptable.
1292 So, the example accepts the default.
1293 If you enter 'n', the script prompts you to further enter the kernel
1294 you do want to use.</para></listitem>
1295 <listitem><para>Next, the script asks whether you would like to have a new
1296 branch created especially for your BSP in the local
1297 <ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Linux Yocto Kernel</ulink>
1298 Git repository .
1299 If not, then the script re-uses an existing branch.</para>
1300 <para>In this example, the default (or "yes") is accepted.
1301 Thus, a new branch is created for the BSP rather than using a common, shared
1302 branch.
1303 The new branch is the branch committed to for any patches you might later add.
1304 The reason a new branch is the default is that typically
1305 new BSPs do require BSP-specific patches.
1306 The tool thus assumes that most of time a new branch is required.
1307 </para></listitem>
1308 <listitem><para>Regardless of which choice you make in the previous step,
1309 you are now given the opportunity to select a particular machine branch on
1310 which to base your new BSP-specific machine branch
1311 (or to re-use if you had elected to not create a new branch).
1312 Because this example is generating an ARM-based BSP, the example
1313 uses <filename>#1</filename> at the prompt, which selects the ARM-versatile branch.
1314 </para></listitem>
1315 <listitem><para>The remainder of the prompts are routine.
1316 Defaults are accepted for each.</para></listitem>
1317 <listitem><para>By default, the script creates the new BSP Layer in the
1318 current working directory of the
1319 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
1320 which is <filename>poky</filename> in this case.
1321 </para></listitem>
1322 </orderedlist>
1323 </para>
1325 <para>
1326 Once the BSP Layer is created, you must add it to your
1327 <filename>bblayers.conf</filename> file.
1328 Here is an example:
1329 <literallayout class='monospaced'>
1330 BBLAYERS = ? " \
1331 /usr/local/src/yocto/meta \
1332 /usr/local/src/yocto/meta-yocto \
1333 /usr/local/src/yocto/meta-yocto-bsp \
1334 /usr/local/src/yocto/meta-myarm \
1335 "
1338 /usr/local/src/yocto/meta \
1339 /usr/local/src/yocto/meta-yocto \
1340 "
1341 </literallayout>
1342 Adding the layer to this file allows the build system to build the BSP and
1343 the <filename>yocto-kernel</filename> tool to be able to find the layer and
1344 other Metadata it needs on which to operate.
1345 </para>
1346 </section>
1348 <section id='managing-kernel-patches-and-config-items-with-yocto-kernel'>
1349 <title>Managing Kernel Patches and Config Items with yocto-kernel</title>
1351 <para>
1352 Assuming you have created a <link linkend='bsp-layers'>BSP Layer</link> using
1353 <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
1354 <filename>yocto-bsp</filename></link> and you added it to your
1355 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
1356 variable in the <filename>bblayers.conf</filename> file, you can now use
1357 the <filename>yocto-kernel</filename> script to add patches and configuration
1358 items to the BSP's kernel.
1359 </para>
1361 <para>
1362 The <filename>yocto-kernel</filename> script allows you to add, remove, and list patches
1363 and kernel config settings to a BSP's kernel
1364 <filename>.bbappend</filename> file.
1365 All you need to do is use the appropriate sub-command.
1366 Recall that the easiest way to see exactly what sub-commands are available
1367 is to use the <filename>yocto-kernel</filename> built-in help as follows:
1368 <literallayout class='monospaced'>
1369 $ yocto-kernel
1370 Usage:
1372 Modify and list Yocto BSP kernel config items and patches.
1374 usage: yocto-kernel [--version] [--help] COMMAND [ARGS]
1376 Current 'yocto-kernel' commands are:
1377 config list List the modifiable set of bare kernel config options for a BSP
1378 config add Add or modify bare kernel config options for a BSP
1379 config rm Remove bare kernel config options from a BSP
1380 patch list List the patches associated with a BSP
1381 patch add Patch the Yocto kernel for a BSP
1382 patch rm Remove patches from a BSP
1383 feature list List the features used by a BSP
1384 feature add Have a BSP use a feature
1385 feature rm Have a BSP stop using a feature
1386 features list List the features available to BSPs
1387 feature describe Describe a particular feature
1388 feature create Create a new BSP-local feature
1389 feature destroy Remove a BSP-local feature
1391 See 'yocto-kernel help COMMAND' for more information on a specific command.
1395 Options:
1396 --version show program's version number and exit
1397 -h, --help show this help message and exit
1398 -D, --debug output debug information
1399 </literallayout>
1400 </para>
1402 <para>
1403 The <filename>yocto-kernel patch add</filename> sub-command allows you to add a
1404 patch to a BSP.
1405 The following example adds two patches to the <filename>myarm</filename> BSP:
1406 <literallayout class='monospaced'>
1407 $ yocto-kernel patch add myarm ~/test.patch
1408 Added patches:
1409 test.patch
1411 $ yocto-kernel patch add myarm ~/yocto-testmod.patch
1412 Added patches:
1413 yocto-testmod.patch
1414 </literallayout>
1415 <note>Although the previous example adds patches one at a time, it is possible
1416 to add multiple patches at the same time.</note>
1417 </para>
1419 <para>
1420 You can verify patches have been added by using the
1421 <filename>yocto-kernel patch list</filename> sub-command.
1422 Here is an example:
1423 <literallayout class='monospaced'>
1424 $ yocto-kernel patch list myarm
1425 The current set of machine-specific patches for myarm is:
1426 1) test.patch
1427 2) yocto-testmod.patch
1428 </literallayout>
1429 </para>
1431 <para>
1432 You can also use the <filename>yocto-kernel</filename> script to
1433 remove a patch using the <filename>yocto-kernel patch rm</filename> sub-command.
1434 Here is an example:
1435 <literallayout class='monospaced'>
1436 $ yocto-kernel patch rm myarm
1437 Specify the patches to remove:
1438 1) test.patch
1439 2) yocto-testmod.patch
1440 1
1441 Removed patches:
1442 test.patch
1443 </literallayout>
1444 </para>
1446 <para>
1447 Again, using the <filename>yocto-kernel patch list</filename> sub-command,
1448 you can verify that the patch was in fact removed:
1449 <literallayout class='monospaced'>
1450 $ yocto-kernel patch list myarm
1451 The current set of machine-specific patches for myarm is:
1452 1) yocto-testmod.patch
1453 </literallayout>
1454 </para>
1456 <para>
1457 In a completely similar way, you can use the <filename>yocto-kernel config add</filename>
1458 sub-command to add one or more kernel config item settings to a BSP.
1459 The following commands add a couple of config items to the
1460 <filename>myarm</filename> BSP:
1461 <literallayout class='monospaced'>
1462 $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y
1463 Added items:
1466 $ yocto-kernel config add myarm CONFIG_YOCTO_TESTMOD=y
1467 Added items:
1469 </literallayout>
1470 <note>Although the previous example adds config items one at a time, it is possible
1471 to add multiple config items at the same time.</note>
1472 </para>
1474 <para>
1475 You can list the config items now associated with the BSP.
1476 Doing so shows you the config items you added as well as others associated
1477 with the BSP:
1478 <literallayout class='monospaced'>
1479 $ yocto-kernel config list myarm
1480 The current set of machine-specific kernel config items for myarm is:
1483 </literallayout>
1484 </para>
1486 <para>
1487 Finally, you can remove one or more config items using the
1488 <filename>yocto-kernel config rm</filename> sub-command in a manner
1489 completely analogous to <filename>yocto-kernel patch rm</filename>.
1490 </para>
1491 </section>
1492 </section>