diff options
author | Tudor Florea <tudor.florea@enea.com> | 2015-10-09 22:59:03 +0200 |
---|---|---|
committer | Tudor Florea <tudor.florea@enea.com> | 2015-10-09 22:59:03 +0200 |
commit | 972dcfcdbfe75dcfeb777150c136576cf1a71e99 (patch) | |
tree | 97a61cd7e293d7ae9d56ef7ed0f81253365bb026 /documentation/bsp-guide/bsp.xml | |
download | poky-972dcfcdbfe75dcfeb777150c136576cf1a71e99.tar.gz |
initial commit for Enea Linux 5.0 arm
Signed-off-by: Tudor Florea <tudor.florea@enea.com>
Diffstat (limited to 'documentation/bsp-guide/bsp.xml')
-rw-r--r-- | documentation/bsp-guide/bsp.xml | 1527 |
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 <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] | ||
1146 | [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] | ||
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 <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] | ||
1169 | [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] | ||
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> | ||