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