summaryrefslogtreecommitdiffstats
path: root/documentation/bsp-guide
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 16:30:32 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-06 13:56:17 +0100
commit43d07a285181e64c30d98d10ff93ef50391efe59 (patch)
tree78918fc94d55d44d35e1e3e61c7a6fccc28bca24 /documentation/bsp-guide
parent1fd9c4b2c0ae927df29f7a0d34c3e595bcf48e89 (diff)
downloadpoky-43d07a285181e64c30d98d10ff93ef50391efe59.tar.gz
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/bsp-guide')
-rw-r--r--documentation/bsp-guide/bsp-guide-customization.xsl29
-rwxr-xr-xdocumentation/bsp-guide/bsp-guide.xml202
-rw-r--r--documentation/bsp-guide/bsp-style.css989
-rw-r--r--documentation/bsp-guide/bsp.xml2259
4 files changed, 0 insertions, 3479 deletions
diff --git a/documentation/bsp-guide/bsp-guide-customization.xsl b/documentation/bsp-guide/bsp-guide-customization.xsl
deleted file mode 100644
index 37fcbcd208..0000000000
--- a/documentation/bsp-guide/bsp-guide-customization.xsl
+++ /dev/null
@@ -1,29 +0,0 @@
1<?xml version='1.0'?>
2<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
3
4<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
5
6 <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
7
8<!--
9
10 <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
11
12 <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
13
14-->
15
16 <xsl:include href="../template/permalinks.xsl"/>
17 <xsl:include href="../template/section.title.xsl"/>
18 <xsl:include href="../template/component.title.xsl"/>
19 <xsl:include href="../template/division.title.xsl"/>
20 <xsl:include href="../template/formal.object.heading.xsl"/>
21
22 <xsl:param name="html.stylesheet" select="'bsp-style.css'" />
23 <xsl:param name="chapter.autolabel" select="1" />
24 <xsl:param name="appendix.autolabel" select="A" />
25 <xsl:param name="section.autolabel" select="1" />
26 <xsl:param name="section.label.includes.component.label" select="1" />
27 <xsl:param name="generate.id.attributes" select="1" />
28
29</xsl:stylesheet>
diff --git a/documentation/bsp-guide/bsp-guide.xml b/documentation/bsp-guide/bsp-guide.xml
deleted file mode 100755
index 93ba1e7fec..0000000000
--- a/documentation/bsp-guide/bsp-guide.xml
+++ /dev/null
@@ -1,202 +0,0 @@
1<!DOCTYPE book 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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<book id='bsp-guide' lang='en'
7 xmlns:xi="http://www.w3.org/2003/XInclude"
8 xmlns="http://docbook.org/ns/docbook"
9 >
10 <bookinfo>
11
12 <mediaobject>
13 <imageobject>
14 <imagedata fileref='figures/bsp-title.png'
15 format='SVG'
16 align='center' scalefit='1' width='100%'/>
17 </imageobject>
18 </mediaobject>
19
20 <title>
21 Yocto Project Board Support Package Developer's Guide
22 </title>
23
24 <authorgroup>
25 <author>
26 <affiliation>
27 <orgname>&ORGNAME;</orgname>
28 </affiliation>
29 <email>&ORGEMAIL;</email>
30 </author>
31 </authorgroup>
32
33 <revhistory>
34 <revision>
35 <revnumber>0.9</revnumber>
36 <date>November 2010</date>
37 <revremark>The initial document released with the Yocto Project 0.9 Release.</revremark>
38 </revision>
39 <revision>
40 <revnumber>1.0</revnumber>
41 <date>April 2011</date>
42 <revremark>Released with the Yocto Project 1.0 Release.</revremark>
43 </revision>
44 <revision>
45 <revnumber>1.1</revnumber>
46 <date>October 2011</date>
47 <revremark>Released with the Yocto Project 1.1 Release.</revremark>
48 </revision>
49 <revision>
50 <revnumber>1.2</revnumber>
51 <date>April 2012</date>
52 <revremark>Released with the Yocto Project 1.2 Release.</revremark>
53 </revision>
54 <revision>
55 <revnumber>1.3</revnumber>
56 <date>October 2012</date>
57 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
58 </revision>
59 <revision>
60 <revnumber>1.4</revnumber>
61 <date>April 2013</date>
62 <revremark>Released with the Yocto Project 1.4 Release.</revremark>
63 </revision>
64 <revision>
65 <revnumber>1.5</revnumber>
66 <date>October 2013</date>
67 <revremark>Released with the Yocto Project 1.5 Release.</revremark>
68 </revision>
69 <revision>
70 <revnumber>1.6</revnumber>
71 <date>April 2014</date>
72 <revremark>Released with the Yocto Project 1.6 Release.</revremark>
73 </revision>
74 <revision>
75 <revnumber>1.7</revnumber>
76 <date>October 2014</date>
77 <revremark>Released with the Yocto Project 1.7 Release.</revremark>
78 </revision>
79 <revision>
80 <revnumber>1.8</revnumber>
81 <date>April 2015</date>
82 <revremark>Released with the Yocto Project 1.8 Release.</revremark>
83 </revision>
84 <revision>
85 <revnumber>2.0</revnumber>
86 <date>October 2015</date>
87 <revremark>Released with the Yocto Project 2.0 Release.</revremark>
88 </revision>
89 <revision>
90 <revnumber>2.1</revnumber>
91 <date>April 2016</date>
92 <revremark>Released with the Yocto Project 2.1 Release.</revremark>
93 </revision>
94 <revision>
95 <revnumber>2.2</revnumber>
96 <date>October 2016</date>
97 <revremark>Released with the Yocto Project 2.2 Release.</revremark>
98 </revision>
99 <revision>
100 <revnumber>2.3</revnumber>
101 <date>May 2017</date>
102 <revremark>Released with the Yocto Project 2.3 Release.</revremark>
103 </revision>
104 <revision>
105 <revnumber>2.4</revnumber>
106 <date>October 2017</date>
107 <revremark>Released with the Yocto Project 2.4 Release.</revremark>
108 </revision>
109 <revision>
110 <revnumber>2.5</revnumber>
111 <date>May 2018</date>
112 <revremark>Released with the Yocto Project 2.5 Release.</revremark>
113 </revision>
114 <revision>
115 <revnumber>2.6</revnumber>
116 <date>November 2018</date>
117 <revremark>Released with the Yocto Project 2.6 Release.</revremark>
118 </revision>
119 <revision>
120 <revnumber>2.7</revnumber>
121 <date>May 2019</date>
122 <revremark>Released with the Yocto Project 2.7 Release.</revremark>
123 </revision>
124 <revision>
125 <revnumber>3.0</revnumber>
126 <date>October 2019</date>
127 <revremark>Released with the Yocto Project 3.0 Release.</revremark>
128 </revision>
129 <revision>
130 <revnumber>3.1</revnumber>
131 <date>&REL_MONTH_YEAR;</date>
132 <revremark>Released with the Yocto Project 3.1 Release.</revremark>
133 </revision>
134 </revhistory>
135
136 <copyright>
137 <year>&COPYRIGHT_YEAR;</year>
138 <holder>Linux Foundation</holder>
139 </copyright>
140
141 <legalnotice>
142 <para>
143 Permission is granted to copy, distribute and/or modify this document under
144 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
145 </para>
146 <note><title>Manual Notes</title>
147 <itemizedlist>
148 <listitem><para>
149 This version of the
150 <emphasis>Yocto Project Board Support Package (BSP) Developer's Guide</emphasis>
151 is for the &YOCTO_DOC_VERSION; release of the
152 Yocto Project.
153 To be sure you have the latest version of the manual
154 for this release, go to the
155 <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
156 and select the manual from that site.
157 Manuals from the site are more up-to-date than manuals
158 derived from the Yocto Project released TAR files.
159 </para></listitem>
160 <listitem><para>
161 If you located this manual through a web search, the
162 version of the manual might not be the one you want
163 (e.g. the search might have returned a manual much
164 older than the Yocto Project version with which you
165 are working).
166 You can see all Yocto Project major releases by
167 visiting the
168 <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
169 page.
170 If you need a version of this manual for a different
171 Yocto Project release, visit the
172 <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
173 and select the manual set by using the
174 "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
175 pull-down menus.
176 </para></listitem>
177 <listitem>
178 <para>
179 To report any inaccuracies or problems with this
180 (or any other Yocto Project) manual, send an email to
181 the Yocto Project documentation mailing list at
182 <filename>docs@lists.yoctoproject.org</filename> or
183 log into the freenode <filename>#yocto</filename> channel.
184 </para>
185 </listitem>
186 </itemizedlist>
187 </note>
188 </legalnotice>
189
190 </bookinfo>
191
192 <xi:include href="bsp.xml"/>
193
194<!-- <index id='index'>
195 <title>Index</title>
196 </index>
197-->
198
199</book>
200<!--
201vim: expandtab tw=80 ts=4
202-->
diff --git a/documentation/bsp-guide/bsp-style.css b/documentation/bsp-guide/bsp-style.css
deleted file mode 100644
index 4ccf5d8aef..0000000000
--- a/documentation/bsp-guide/bsp-style.css
+++ /dev/null
@@ -1,989 +0,0 @@
1/*
2 SPDX-License-Identifier: CC-BY-2.0-UK
3
4 Generic XHTML / DocBook XHTML CSS Stylesheet.
5
6 Browser wrangling and typographic design by
7 Oyvind Kolas / pippin@gimp.org
8
9 Customised for Poky by
10 Matthew Allum / mallum@o-hand.com
11
12 Thanks to:
13 Liam R. E. Quin
14 William Skaggs
15 Jakub Steiner
16
17 Structure
18 ---------
19
20 The stylesheet is divided into the following sections:
21
22 Positioning
23 Margins, paddings, width, font-size, clearing.
24 Decorations
25 Borders, style
26 Colors
27 Colors
28 Graphics
29 Graphical backgrounds
30 Nasty IE tweaks
31 Workarounds needed to make it work in internet explorer,
32 currently makes the stylesheet non validating, but up until
33 this point it is validating.
34 Mozilla extensions
35 Transparency for footer
36 Rounded corners on boxes
37
38*/
39
40
41 /*************** /
42 / Positioning /
43/ ***************/
44
45body {
46 font-family: Verdana, Sans, sans-serif;
47
48 min-width: 640px;
49 width: 80%;
50 margin: 0em auto;
51 padding: 2em 5em 5em 5em;
52 color: #333;
53}
54
55h1,h2,h3,h4,h5,h6,h7 {
56 font-family: Arial, Sans;
57 color: #00557D;
58 clear: both;
59}
60
61h1 {
62 font-size: 2em;
63 text-align: left;
64 padding: 0em 0em 0em 0em;
65 margin: 2em 0em 0em 0em;
66}
67
68h2.subtitle {
69 margin: 0.10em 0em 3.0em 0em;
70 padding: 0em 0em 0em 0em;
71 font-size: 1.8em;
72 padding-left: 20%;
73 font-weight: normal;
74 font-style: italic;
75}
76
77h2 {
78 margin: 2em 0em 0.66em 0em;
79 padding: 0.5em 0em 0em 0em;
80 font-size: 1.5em;
81 font-weight: bold;
82}
83
84h3.subtitle {
85 margin: 0em 0em 1em 0em;
86 padding: 0em 0em 0em 0em;
87 font-size: 142.14%;
88 text-align: right;
89}
90
91h3 {
92 margin: 1em 0em 0.5em 0em;
93 padding: 1em 0em 0em 0em;
94 font-size: 140%;
95 font-weight: bold;
96}
97
98h4 {
99 margin: 1em 0em 0.5em 0em;
100 padding: 1em 0em 0em 0em;
101 font-size: 120%;
102 font-weight: bold;
103}
104
105h5 {
106 margin: 1em 0em 0.5em 0em;
107 padding: 1em 0em 0em 0em;
108 font-size: 110%;
109 font-weight: bold;
110}
111
112h6 {
113 margin: 1em 0em 0em 0em;
114 padding: 1em 0em 0em 0em;
115 font-size: 110%;
116 font-weight: bold;
117}
118
119.authorgroup {
120 background-color: transparent;
121 background-repeat: no-repeat;
122 padding-top: 256px;
123 background-image: url("figures/bsp-title.png");
124 background-position: left top;
125 margin-top: -256px;
126 padding-right: 50px;
127 margin-left: 0px;
128 text-align: right;
129 width: 740px;
130}
131
132h3.author {
133 margin: 0em 0me 0em 0em;
134 padding: 0em 0em 0em 0em;
135 font-weight: normal;
136 font-size: 100%;
137 color: #333;
138 clear: both;
139}
140
141.author tt.email {
142 font-size: 66%;
143}
144
145.titlepage hr {
146 width: 0em;
147 clear: both;
148}
149
150.revhistory {
151 padding-top: 2em;
152 clear: both;
153}
154
155.toc,
156.list-of-tables,
157.list-of-examples,
158.list-of-figures {
159 padding: 1.33em 0em 2.5em 0em;
160 color: #00557D;
161}
162
163.toc p,
164.list-of-tables p,
165.list-of-figures p,
166.list-of-examples p {
167 padding: 0em 0em 0em 0em;
168 padding: 0em 0em 0.3em;
169 margin: 1.5em 0em 0em 0em;
170}
171
172.toc p b,
173.list-of-tables p b,
174.list-of-figures p b,
175.list-of-examples p b{
176 font-size: 100.0%;
177 font-weight: bold;
178}
179
180.toc dl,
181.list-of-tables dl,
182.list-of-figures dl,
183.list-of-examples dl {
184 margin: 0em 0em 0.5em 0em;
185 padding: 0em 0em 0em 0em;
186}
187
188.toc dt {
189 margin: 0em 0em 0em 0em;
190 padding: 0em 0em 0em 0em;
191}
192
193.toc dd {
194 margin: 0em 0em 0em 2.6em;
195 padding: 0em 0em 0em 0em;
196}
197
198div.glossary dl,
199div.variablelist dl {
200}
201
202.glossary dl dt,
203.variablelist dl dt,
204.variablelist dl dt span.term {
205 font-weight: normal;
206 width: 20em;
207 text-align: right;
208}
209
210.variablelist dl dt {
211 margin-top: 0.5em;
212}
213
214.glossary dl dd,
215.variablelist dl dd {
216 margin-top: -1em;
217 margin-left: 25.5em;
218}
219
220.glossary dd p,
221.variablelist dd p {
222 margin-top: 0em;
223 margin-bottom: 1em;
224}
225
226
227div.calloutlist table td {
228 padding: 0em 0em 0em 0em;
229 margin: 0em 0em 0em 0em;
230}
231
232div.calloutlist table td p {
233 margin-top: 0em;
234 margin-bottom: 1em;
235}
236
237div p.copyright {
238 text-align: left;
239}
240
241div.legalnotice p.legalnotice-title {
242 margin-bottom: 0em;
243}
244
245p {
246 line-height: 1.5em;
247 margin-top: 0em;
248
249}
250
251dl {
252 padding-top: 0em;
253}
254
255hr {
256 border: solid 1px;
257}
258
259
260.mediaobject,
261.mediaobjectco {
262 text-align: center;
263}
264
265img {
266 border: none;
267}
268
269ul {
270 padding: 0em 0em 0em 1.5em;
271}
272
273ul li {
274 padding: 0em 0em 0em 0em;
275}
276
277ul li p {
278 text-align: left;
279}
280
281table {
282 width :100%;
283}
284
285th {
286 padding: 0.25em;
287 text-align: left;
288 font-weight: normal;
289 vertical-align: top;
290}
291
292td {
293 padding: 0.25em;
294 vertical-align: top;
295}
296
297p a[id] {
298 margin: 0px;
299 padding: 0px;
300 display: inline;
301 background-image: none;
302}
303
304a {
305 text-decoration: underline;
306 color: #444;
307}
308
309pre {
310 overflow: auto;
311}
312
313a:hover {
314 text-decoration: underline;
315 /*font-weight: bold;*/
316}
317
318/* This style defines how the permalink character
319 appears by itself and when hovered over with
320 the mouse. */
321
322[alt='Permalink'] { color: #eee; }
323[alt='Permalink']:hover { color: black; }
324
325
326div.informalfigure,
327div.informalexample,
328div.informaltable,
329div.figure,
330div.table,
331div.example {
332 margin: 1em 0em;
333 padding: 1em;
334 page-break-inside: avoid;
335}
336
337
338div.informalfigure p.title b,
339div.informalexample p.title b,
340div.informaltable p.title b,
341div.figure p.title b,
342div.example p.title b,
343div.table p.title b{
344 padding-top: 0em;
345 margin-top: 0em;
346 font-size: 100%;
347 font-weight: normal;
348}
349
350.mediaobject .caption,
351.mediaobject .caption p {
352 text-align: center;
353 font-size: 80%;
354 padding-top: 0.5em;
355 padding-bottom: 0.5em;
356}
357
358.epigraph {
359 padding-left: 55%;
360 margin-bottom: 1em;
361}
362
363.epigraph p {
364 text-align: left;
365}
366
367.epigraph .quote {
368 font-style: italic;
369}
370.epigraph .attribution {
371 font-style: normal;
372 text-align: right;
373}
374
375span.application {
376 font-style: italic;
377}
378
379.programlisting {
380 font-family: monospace;
381 font-size: 80%;
382 white-space: pre;
383 margin: 1.33em 0em;
384 padding: 1.33em;
385}
386
387.tip,
388.warning,
389.caution,
390.note {
391 margin-top: 1em;
392 margin-bottom: 1em;
393
394}
395
396/* force full width of table within div */
397.tip table,
398.warning table,
399.caution table,
400.note table {
401 border: none;
402 width: 100%;
403}
404
405
406.tip table th,
407.warning table th,
408.caution table th,
409.note table th {
410 padding: 0.8em 0.0em 0.0em 0.0em;
411 margin : 0em 0em 0em 0em;
412}
413
414.tip p,
415.warning p,
416.caution p,
417.note p {
418 margin-top: 0.5em;
419 margin-bottom: 0.5em;
420 padding-right: 1em;
421 text-align: left;
422}
423
424.acronym {
425 text-transform: uppercase;
426}
427
428b.keycap,
429.keycap {
430 padding: 0.09em 0.3em;
431 margin: 0em;
432}
433
434.itemizedlist li {
435 clear: none;
436}
437
438.filename {
439 font-size: medium;
440 font-family: Courier, monospace;
441}
442
443
444div.navheader, div.heading{
445 position: absolute;
446 left: 0em;
447 top: 0em;
448 width: 100%;
449 background-color: #cdf;
450 width: 100%;
451}
452
453div.navfooter, div.footing{
454 position: fixed;
455 left: 0em;
456 bottom: 0em;
457 background-color: #eee;
458 width: 100%;
459}
460
461
462div.navheader td,
463div.navfooter td {
464 font-size: 66%;
465}
466
467div.navheader table th {
468 /*font-family: Georgia, Times, serif;*/
469 /*font-size: x-large;*/
470 font-size: 80%;
471}
472
473div.navheader table {
474 border-left: 0em;
475 border-right: 0em;
476 border-top: 0em;
477 width: 100%;
478}
479
480div.navfooter table {
481 border-left: 0em;
482 border-right: 0em;
483 border-bottom: 0em;
484 width: 100%;
485}
486
487div.navheader table td a,
488div.navfooter table td a {
489 color: #777;
490 text-decoration: none;
491}
492
493/* normal text in the footer */
494div.navfooter table td {
495 color: black;
496}
497
498div.navheader table td a:visited,
499div.navfooter table td a:visited {
500 color: #444;
501}
502
503
504/* links in header and footer */
505div.navheader table td a:hover,
506div.navfooter table td a:hover {
507 text-decoration: underline;
508 background-color: transparent;
509 color: #33a;
510}
511
512div.navheader hr,
513div.navfooter hr {
514 display: none;
515}
516
517
518.qandaset tr.question td p {
519 margin: 0em 0em 1em 0em;
520 padding: 0em 0em 0em 0em;
521}
522
523.qandaset tr.answer td p {
524 margin: 0em 0em 1em 0em;
525 padding: 0em 0em 0em 0em;
526}
527.answer td {
528 padding-bottom: 1.5em;
529}
530
531.emphasis {
532 font-weight: bold;
533}
534
535
536 /************* /
537 / decorations /
538/ *************/
539
540.titlepage {
541}
542
543.part .title {
544}
545
546.subtitle {
547 border: none;
548}
549
550/*
551h1 {
552 border: none;
553}
554
555h2 {
556 border-top: solid 0.2em;
557 border-bottom: solid 0.06em;
558}
559
560h3 {
561 border-top: 0em;
562 border-bottom: solid 0.06em;
563}
564
565h4 {
566 border: 0em;
567 border-bottom: solid 0.06em;
568}
569
570h5 {
571 border: 0em;
572}
573*/
574
575.programlisting {
576 border: solid 1px;
577}
578
579div.figure,
580div.table,
581div.informalfigure,
582div.informaltable,
583div.informalexample,
584div.example {
585 border: 1px solid;
586}
587
588
589
590.tip,
591.warning,
592.caution,
593.note {
594 border: 1px solid;
595}
596
597.tip table th,
598.warning table th,
599.caution table th,
600.note table th {
601 border-bottom: 1px solid;
602}
603
604.question td {
605 border-top: 1px solid black;
606}
607
608.answer {
609}
610
611
612b.keycap,
613.keycap {
614 border: 1px solid;
615}
616
617
618div.navheader, div.heading{
619 border-bottom: 1px solid;
620}
621
622
623div.navfooter, div.footing{
624 border-top: 1px solid;
625}
626
627 /********* /
628 / colors /
629/ *********/
630
631body {
632 color: #333;
633 background: white;
634}
635
636a {
637 background: transparent;
638}
639
640a:hover {
641 background-color: #dedede;
642}
643
644
645h1,
646h2,
647h3,
648h4,
649h5,
650h6,
651h7,
652h8 {
653 background-color: transparent;
654}
655
656hr {
657 border-color: #aaa;
658}
659
660
661.tip, .warning, .caution, .note {
662 border-color: #fff;
663}
664
665
666.tip table th,
667.warning table th,
668.caution table th,
669.note table th {
670 border-bottom-color: #fff;
671}
672
673
674.warning {
675 background-color: #f0f0f2;
676}
677
678.caution {
679 background-color: #f0f0f2;
680}
681
682.tip {
683 background-color: #f0f0f2;
684}
685
686.note {
687 background-color: #f0f0f2;
688}
689
690.glossary dl dt,
691.variablelist dl dt,
692.variablelist dl dt span.term {
693 color: #044;
694}
695
696div.figure,
697div.table,
698div.example,
699div.informalfigure,
700div.informaltable,
701div.informalexample {
702 border-color: #aaa;
703}
704
705pre.programlisting {
706 color: black;
707 background-color: #fff;
708 border-color: #aaa;
709 border-width: 2px;
710}
711
712.guimenu,
713.guilabel,
714.guimenuitem {
715 background-color: #eee;
716}
717
718
719b.keycap,
720.keycap {
721 background-color: #eee;
722 border-color: #999;
723}
724
725
726div.navheader {
727 border-color: black;
728}
729
730
731div.navfooter {
732 border-color: black;
733}
734
735.writernotes {
736 color: red;
737}
738
739 /*********** /
740 / graphics /
741/ ***********/
742
743/*
744body {
745 background-image: url("images/body_bg.jpg");
746 background-attachment: fixed;
747}
748
749.navheader,
750.note,
751.tip {
752 background-image: url("images/note_bg.jpg");
753 background-attachment: fixed;
754}
755
756.warning,
757.caution {
758 background-image: url("images/warning_bg.jpg");
759 background-attachment: fixed;
760}
761
762.figure,
763.informalfigure,
764.example,
765.informalexample,
766.table,
767.informaltable {
768 background-image: url("images/figure_bg.jpg");
769 background-attachment: fixed;
770}
771
772*/
773h1,
774h2,
775h3,
776h4,
777h5,
778h6,
779h7{
780}
781
782/*
783Example of how to stick an image as part of the title.
784
785div.article .titlepage .title
786{
787 background-image: url("figures/white-on-black.png");
788 background-position: center;
789 background-repeat: repeat-x;
790}
791*/
792
793div.preface .titlepage .title,
794div.colophon .title,
795div.chapter .titlepage .title {
796 background-position: bottom;
797 background-repeat: repeat-x;
798}
799
800div.section div.section .titlepage .title,
801div.sect2 .titlepage .title {
802 background: none;
803}
804
805
806h1.title {
807 background-color: transparent;
808 background-repeat: no-repeat;
809 height: 256px;
810 text-indent: -9000px;
811 overflow:hidden;
812}
813
814h2.subtitle {
815 background-color: transparent;
816 text-indent: -9000px;
817 overflow:hidden;
818 width: 0px;
819 display: none;
820}
821
822 /*************************************** /
823 / pippin.gimp.org specific alterations /
824/ ***************************************/
825
826/*
827div.heading, div.navheader {
828 color: #777;
829 font-size: 80%;
830 padding: 0;
831 margin: 0;
832 text-align: left;
833 position: absolute;
834 top: 0px;
835 left: 0px;
836 width: 100%;
837 height: 50px;
838 background: url('/gfx/heading_bg.png') transparent;
839 background-repeat: repeat-x;
840 background-attachment: fixed;
841 border: none;
842}
843
844div.heading a {
845 color: #444;
846}
847
848div.footing, div.navfooter {
849 border: none;
850 color: #ddd;
851 font-size: 80%;
852 text-align:right;
853
854 width: 100%;
855 padding-top: 10px;
856 position: absolute;
857 bottom: 0px;
858 left: 0px;
859
860 background: url('/gfx/footing_bg.png') transparent;
861}
862*/
863
864
865
866 /****************** /
867 / nasty ie tweaks /
868/ ******************/
869
870/*
871div.heading, div.navheader {
872 width:expression(document.body.clientWidth + "px");
873}
874
875div.footing, div.navfooter {
876 width:expression(document.body.clientWidth + "px");
877 margin-left:expression("-5em");
878}
879body {
880 padding:expression("4em 5em 0em 5em");
881}
882*/
883
884 /**************************************** /
885 / mozilla vendor specific css extensions /
886/ ****************************************/
887/*
888div.navfooter, div.footing{
889 -moz-opacity: 0.8em;
890}
891
892div.figure,
893div.table,
894div.informalfigure,
895div.informaltable,
896div.informalexample,
897div.example,
898.tip,
899.warning,
900.caution,
901.note {
902 -moz-border-radius: 0.5em;
903}
904
905b.keycap,
906.keycap {
907 -moz-border-radius: 0.3em;
908}
909*/
910
911table tr td table tr td {
912 display: none;
913}
914
915
916hr {
917 display: none;
918}
919
920table {
921 border: 0em;
922}
923
924 .photo {
925 float: right;
926 margin-left: 1.5em;
927 margin-bottom: 1.5em;
928 margin-top: 0em;
929 max-width: 17em;
930 border: 1px solid gray;
931 padding: 3px;
932 background: white;
933}
934 .seperator {
935 padding-top: 2em;
936 clear: both;
937 }
938
939 #validators {
940 margin-top: 5em;
941 text-align: right;
942 color: #777;
943 }
944 @media print {
945 body {
946 font-size: 8pt;
947 }
948 .noprint {
949 display: none;
950 }
951 }
952
953
954.tip,
955.note {
956 background: #f0f0f2;
957 color: #333;
958 padding: 20px;
959 margin: 20px;
960}
961
962.tip h3,
963.note h3 {
964 padding: 0em;
965 margin: 0em;
966 font-size: 2em;
967 font-weight: bold;
968 color: #333;
969}
970
971.tip a,
972.note a {
973 color: #333;
974 text-decoration: underline;
975}
976
977.footnote {
978 font-size: small;
979 color: #333;
980}
981
982/* Changes the announcement text */
983.tip h3,
984.warning h3,
985.caution h3,
986.note h3 {
987 font-size:large;
988 color: #00557D;
989}
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
deleted file mode 100644
index f5c3f31faf..0000000000
--- a/documentation/bsp-guide/bsp.xml
+++ /dev/null
@@ -1,2259 +0,0 @@
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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='bsp'>
7
8<title>Board Support Packages (BSP) - Developer's Guide</title>
9
10<para>
11 A Board Support Package (BSP) is a collection of information that
12 defines how to support a particular hardware device, set of devices, or
13 hardware platform.
14 The BSP includes information about the hardware features
15 present on the device and kernel configuration information along with any
16 additional hardware drivers required.
17 The BSP also lists any additional software
18 components required in addition to a generic Linux software stack for both
19 essential and optional platform features.
20</para>
21
22<para>
23 This guide presents information about BSP layers, defines a structure for components
24 so that BSPs follow a commonly understood layout, discusses how to customize
25 a recipe for a BSP, addresses BSP licensing, and provides information that
26 shows you how to create a
27 <link linkend='bsp-layers'>BSP Layer</link> using the
28 <link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'><filename>bitbake-layers</filename></link>
29 tool.
30</para>
31
32<section id='bsp-layers'>
33 <title>BSP Layers</title>
34
35 <para>
36 A BSP consists of a file structure inside a base directory.
37 Collectively, you can think of the base directory, its file structure,
38 and the contents as a <firstterm>BSP layer</firstterm>.
39 Although not a strict requirement, BSP layers in the Yocto Project
40 use the following well-established naming convention:
41 <literallayout class='monospaced'>
42 meta-<replaceable>bsp_root_name</replaceable>
43 </literallayout>
44 The string "meta-" is prepended to the machine or platform name, which is
45 <replaceable>bsp_root_name</replaceable> in the above form.
46 <note><title>Tip</title>
47 Because the BSP layer naming convention is well-established,
48 it is advisable to follow it when creating layers.
49 Technically speaking, a BSP layer name does not need to
50 start with <filename>meta-</filename>.
51 However, various scripts and tools in the Yocto Project
52 development environment assume this convention.
53 </note>
54 </para>
55
56 <para>
57 To help understand the BSP layer concept, consider the BSPs that the
58 Yocto Project supports and provides with each release.
59 You can see the layers in the
60 <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>
61 through a web interface at
62 <ulink url='&YOCTO_GIT_URL;'></ulink>.
63 If you go to that interface, you will find a list of repositories
64 under "Yocto Metadata Layers".
65 <note>
66 Layers that are no longer actively supported as part of the
67 Yocto Project appear under the heading "Yocto Metadata Layer
68 Archive."
69 </note>
70 Each repository is a BSP layer supported by the Yocto Project
71 (e.g. <filename>meta-raspberrypi</filename> and
72 <filename>meta-intel</filename>).
73 Each of these layers is a repository unto itself and clicking on
74 the layer name displays two URLs from which you can
75 clone the layer's repository to your local system.
76 Here is an example that clones the Raspberry Pi BSP layer:
77 <literallayout class='monospaced'>
78 $ git clone git://git.yoctoproject.org/meta-raspberrypi
79 </literallayout>
80 </para>
81
82 <para>
83 In addition to BSP layers, the
84 <filename>meta-yocto-bsp</filename> layer is part of the
85 shipped <filename>poky</filename> repository.
86 The <filename>meta-yocto-bsp</filename> layer maintains several
87 "reference" BSPs including the ARM-based Beaglebone, MIPS-based
88 EdgeRouter, and generic versions of
89 both 32-bit and 64-bit IA machines.
90 </para>
91
92 <para>
93 For information on typical BSP development workflow, see the
94 "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>"
95 section.
96 For more information on how to set up a local copy of source files
97 from a Git repository, see the
98 "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
99 section in the Yocto Project Development Tasks Manual.
100 </para>
101
102 <para>
103 The BSP layer's base directory
104 (<filename>meta-<replaceable>bsp_root_name</replaceable></filename>)
105 is the root directory of that Layer.
106 This directory is what you add to the
107 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
108 variable in the <filename>conf/bblayers.conf</filename> file found in your
109 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
110 which is established after you run the OpenEmbedded build environment
111 setup script (i.e.
112 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
113 Adding the root directory allows the
114 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
115 to recognize the BSP layer and from it build an image.
116 Here is an example:
117 <literallayout class='monospaced'>
118 BBLAYERS ?= " \
119 /usr/local/src/yocto/meta \
120 /usr/local/src/yocto/meta-poky \
121 /usr/local/src/yocto/meta-yocto-bsp \
122 /usr/local/src/yocto/meta-mylayer \
123 "
124 </literallayout>
125 <note><title>Tip</title>
126 Ordering and
127 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
128 for the layers listed in <filename>BBLAYERS</filename>
129 matter.
130 For example, if multiple layers define a machine
131 configuration, the OpenEmbedded build system uses
132 the last layer searched given similar layer
133 priorities.
134 The build system works from the top-down through
135 the layers listed in <filename>BBLAYERS</filename>.
136 </note>
137 </para>
138
139 <para>
140 Some BSPs require or depend on additional layers
141 beyond the BSP's root layer in order to be functional.
142 In this case, you need to specify these layers in the
143 <filename>README</filename> "Dependencies" section of the
144 BSP's root layer.
145 Additionally, if any build instructions exist for the
146 BSP, you must add them to the "Dependencies" section.
147 </para>
148
149 <para>
150 Some layers function as a layer to hold other BSP layers.
151 These layers are knows as
152 "<ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>container layers</ulink>".
153 An example of this type of layer is OpenEmbedded's
154 <ulink url='https://github.com/openembedded/meta-openembedded'><filename>meta-openembedded</filename></ulink>
155 layer.
156 The <filename>meta-openembedded</filename> layer contains
157 many <filename>meta-*</filename> layers.
158 In cases like this, you need to include the names of the actual
159 layers you want to work with, such as:
160 <literallayout class='monospaced'>
161 BBLAYERS ?= " \
162 /usr/local/src/yocto/meta \
163 /usr/local/src/yocto/meta-poky \
164 /usr/local/src/yocto/meta-yocto-bsp \
165 /usr/local/src/yocto/meta-mylayer \
166 .../meta-openembedded/meta-oe \
167 .../meta-openembedded/meta-perl \
168 .../meta-openembedded/meta-networking \
169 "
170 </literallayout>
171 and so on.
172 </para>
173
174 <para>
175 For more information on layers, see the
176 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
177 section of the Yocto Project Development Tasks Manual.
178 </para>
179</section>
180
181<section id='preparing-your-build-host-to-work-with-bsp-layers'>
182 <title>Preparing Your Build Host to Work With BSP Layers</title>
183
184 <para>
185 This section describes how to get your build host ready
186 to work with BSP layers.
187 Once you have the host set up, you can create the layer
188 as described in the
189 "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</link>"
190 section.
191 <note>
192 For structural information on BSPs, see the
193 <link linkend='bsp-filelayout'>Example Filesystem Layout</link>
194 section.
195 </note>
196 <orderedlist>
197 <listitem><para>
198 <emphasis>Set Up the Build Environment:</emphasis>
199 Be sure you are set up to use BitBake in a shell.
200 See the
201 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
202 section in the Yocto Project Development Tasks Manual for information
203 on how to get a build host ready that is either a native
204 Linux machine or a machine that uses CROPS.
205 </para></listitem>
206 <listitem><para>
207 <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
208 You need to have a local copy of the Yocto Project
209 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
210 (i.e. a local <filename>poky</filename> repository).
211 See the
212 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
213 and possibly the
214 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
215 or
216 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
217 sections all in the Yocto Project Development Tasks Manual for
218 information on how to clone the <filename>poky</filename>
219 repository and check out the appropriate branch for your work.
220 </para></listitem>
221 <listitem><para>
222 <emphasis>Determine the BSP Layer You Want:</emphasis>
223 The Yocto Project supports many BSPs, which are maintained in
224 their own layers or in layers designed to contain several
225 BSPs.
226 To get an idea of machine support through BSP layers, you can
227 look at the
228 <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
229 for the release.
230 </para></listitem>
231 <listitem><para>
232 <emphasis>Optionally Clone the
233 <filename>meta-intel</filename> BSP Layer:</emphasis>
234 If your hardware is based on current Intel CPUs and devices,
235 you can leverage this BSP layer.
236 For details on the <filename>meta-intel</filename> BSP layer,
237 see the layer's
238 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
239 file.
240 <orderedlist>
241 <listitem><para>
242 <emphasis>Navigate to Your Source Directory:</emphasis>
243 Typically, you set up the
244 <filename>meta-intel</filename> Git repository
245 inside the
246 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
247 (e.g. <filename>poky</filename>).
248 <literallayout class='monospaced'>
249 $ cd /home/<replaceable>you</replaceable>/poky
250 </literallayout>
251 </para></listitem>
252 <listitem><para>
253 <emphasis>Clone the Layer:</emphasis>
254 <literallayout class='monospaced'>
255 $ git clone git://git.yoctoproject.org/meta-intel.git
256 Cloning into 'meta-intel'...
257 remote: Counting objects: 15585, done.
258 remote: Compressing objects: 100% (5056/5056), done.
259 remote: Total 15585 (delta 9123), reused 15329 (delta 8867)
260 Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done.
261 Resolving deltas: 100% (9123/9123), done.
262 Checking connectivity... done.
263 </literallayout>
264 </para></listitem>
265 <listitem><para>
266 <emphasis>Check Out the Proper Branch:</emphasis>
267 The branch you check out for
268 <filename>meta-intel</filename> must match the same
269 branch you are using for the Yocto Project release
270 (e.g. &DISTRO_NAME_NO_CAP;):
271 <literallayout class='monospaced'>
272 $ cd meta-intel
273 $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP;
274 Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin.
275 Switched to a new branch '&DISTRO_NAME_NO_CAP;'
276 </literallayout>
277 <note>
278 To see the available branch names in a cloned repository,
279 use the <filename>git branch -al</filename> command.
280 See the
281 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>"
282 section in the Yocto Project Development Tasks
283 Manual for more information.
284 </note>
285 </para></listitem>
286 </orderedlist>
287 </para></listitem>
288 <listitem><para>
289 <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis>
290 If your hardware can be more closely leveraged to an
291 existing BSP not within the <filename>meta-intel</filename>
292 BSP layer, you can clone that BSP layer.</para>
293
294 <para>The process is identical to the process used for the
295 <filename>meta-intel</filename> layer except for the layer's
296 name.
297 For example, if you determine that your hardware most
298 closely matches the <filename>meta-raspberrypi</filename>,
299 clone that layer:
300 <literallayout class='monospaced'>
301 $ git clone git://git.yoctoproject.org/meta-raspberrypi
302 Cloning into 'meta-raspberrypi'...
303 remote: Counting objects: 4743, done.
304 remote: Compressing objects: 100% (2185/2185), done.
305 remote: Total 4743 (delta 2447), reused 4496 (delta 2258)
306 Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done.
307 Resolving deltas: 100% (2447/2447), done.
308 Checking connectivity... done.
309 </literallayout>
310 </para></listitem>
311 <listitem><para>
312 <emphasis>Initialize the Build Environment:</emphasis>
313 While in the root directory of the Source Directory (i.e.
314 <filename>poky</filename>), run the
315 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
316 environment setup script to define the OpenEmbedded
317 build environment on your build host.
318 <literallayout class='monospaced'>
319 $ source &OE_INIT_FILE;
320 </literallayout>
321 Among other things, the script creates the
322 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
323 which is <filename>build</filename> in this case
324 and is located in the
325 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
326 After the script runs, your current working directory
327 is set to the <filename>build</filename> directory.
328 </para></listitem>
329 </orderedlist>
330 </para>
331</section>
332
333<section id="bsp-filelayout">
334 <title>Example Filesystem Layout</title>
335
336 <para>
337 Defining a common BSP directory structure allows
338 end-users to understand and become familiar with
339 that standard.
340 A common format also encourages standardization
341 of software support for hardware.
342 </para>
343
344 <para>
345 The proposed form described in this section does
346 have elements that are specific to the OpenEmbedded
347 build system.
348 It is intended that developers can use this structure
349 with other build systems besides the OpenEmbedded build
350 system.
351 It is also intended that it will be be simple to extract
352 information and convert it to other formats if required.
353 The OpenEmbedded build system, through its standard
354 <ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>layers mechanism</ulink>,
355 can directly accept the format described as a layer.
356 The BSP layer captures all the hardware-specific details
357 in one place using a standard format, which is useful
358 for any person wishing to use the hardware platform
359 regardless of the build system they are using.
360 </para>
361
362 <para>
363 The BSP specification does not include a build system
364 or other tools - the specification is concerned with
365 the hardware-specific components only.
366 At the end-distribution point, you can ship the BSP
367 layer combined with a build system and other tools.
368 Realize that it is important to maintain the distinction
369 that the BSP layer, a build system, and tools are
370 separate components that could be combined in
371 certain end products.
372 </para>
373
374 <para>
375 Before looking at the recommended form for the directory structure
376 inside a BSP layer, you should be aware that some
377 requirements do exist in order for a BSP layer to
378 be considered <firstterm>compliant</firstterm> with the Yocto Project.
379 For that list of requirements, see the
380 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
381 section.
382 </para>
383
384 <para>
385 Below is the typical directory structure for a BSP layer.
386 While this basic form represents the standard,
387 realize that the actual layout for individual
388 BSPs could differ.
389 <literallayout class='monospaced'>
390 meta-<replaceable>bsp_root_name</replaceable>/
391 meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable>
392 meta-<replaceable>bsp_root_name</replaceable>/README
393 meta-<replaceable>bsp_root_name</replaceable>/README.sources
394 meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
395 meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf
396 meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf
397 meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/*
398 meta-<replaceable>bsp_root_name</replaceable>/recipes-core/*
399 meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/*
400 meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend
401 </literallayout>
402 </para>
403
404 <para>
405 Below is an example of the Raspberry Pi BSP
406 layer that is available from the
407 <ulink url='&YOCTO_GIT_URL;'>Source Respositories</ulink>:
408 <literallayout class='monospaced'>
409 meta-raspberrypi/COPYING.MIT
410 meta-raspberrypi/README.md
411 meta-raspberrypi/classes
412 meta-raspberrypi/classes/sdcard_image-rpi.bbclass
413 meta-raspberrypi/conf/
414 meta-raspberrypi/conf/layer.conf
415 meta-raspberrypi/conf/machine/
416 meta-raspberrypi/conf/machine/raspberrypi-cm.conf
417 meta-raspberrypi/conf/machine/raspberrypi-cm3.conf
418 meta-raspberrypi/conf/machine/raspberrypi.conf
419 meta-raspberrypi/conf/machine/raspberrypi0-wifi.conf
420 meta-raspberrypi/conf/machine/raspberrypi0.conf
421 meta-raspberrypi/conf/machine/raspberrypi2.conf
422 meta-raspberrypi/conf/machine/raspberrypi3-64.conf
423 meta-raspberrypi/conf/machine/raspberrypi3.conf
424 meta-raspberrypi/conf/machine/include
425 meta-raspberrypi/conf/machine/include/rpi-base.inc
426 meta-raspberrypi/conf/machine/include/rpi-default-providers.inc
427 meta-raspberrypi/conf/machine/include/rpi-default-settings.inc
428 meta-raspberrypi/conf/machine/include/rpi-default-versions.inc
429 meta-raspberrypi/conf/machine/include/tune-arm1176jzf-s.inc
430 meta-raspberrypi/docs
431 meta-raspberrypi/docs/Makefile
432 meta-raspberrypi/docs/conf.py
433 meta-raspberrypi/docs/contributing.md
434 meta-raspberrypi/docs/extra-apps.md
435 meta-raspberrypi/docs/extra-build-config.md
436 meta-raspberrypi/docs/index.rst
437 meta-raspberrypi/docs/layer-contents.md
438 meta-raspberrypi/docs/readme.md
439 meta-raspberrypi/files
440 meta-raspberrypi/files/custom-licenses
441 meta-raspberrypi/files/custom-licenses/Broadcom
442 meta-raspberrypi/recipes-bsp
443 meta-raspberrypi/recipes-bsp/bootfiles
444 meta-raspberrypi/recipes-bsp/bootfiles/bcm2835-bootfiles.bb
445 meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb
446 meta-raspberrypi/recipes-bsp/common
447 meta-raspberrypi/recipes-bsp/common/firmware.inc
448 meta-raspberrypi/recipes-bsp/formfactor
449 meta-raspberrypi/recipes-bsp/formfactor/formfactor
450 meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi
451 meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi/machconfig
452 meta-raspberrypi/recipes-bsp/formfactor/formfactor_0.0.bbappend
453 meta-raspberrypi/recipes-bsp/rpi-u-boot-src
454 meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files
455 meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files/boot.cmd.in
456 meta-raspberrypi/recipes-bsp/rpi-u-boot-src/rpi-u-boot-scr.bb
457 meta-raspberrypi/recipes-bsp/u-boot
458 meta-raspberrypi/recipes-bsp/u-boot/u-boot
459 meta-raspberrypi/recipes-bsp/u-boot/u-boot/*.patch
460 meta-raspberrypi/recipes-bsp/u-boot/u-boot_%.bbappend
461 meta-raspberrypi/recipes-connectivity
462 meta-raspberrypi/recipes-connectivity/bluez5
463 meta-raspberrypi/recipes-connectivity/bluez5/bluez5
464 meta-raspberrypi/recipes-connectivity/bluez5/bluez5/*.patch
465 meta-raspberrypi/recipes-connectivity/bluez5/bluez5/BCM43430A1.hcd
466 meta-raspberrypi/recipes-connectivity/bluez5/bluez5brcm43438.service
467 meta-raspberrypi/recipes-connectivity/bluez5/bluez5_%.bbappend
468 meta-raspberrypi/recipes-core
469 meta-raspberrypi/recipes-core/images
470 meta-raspberrypi/recipes-core/images/rpi-basic-image.bb
471 meta-raspberrypi/recipes-core/images/rpi-hwup-image.bb
472 meta-raspberrypi/recipes-core/images/rpi-test-image.bb
473 meta-raspberrypi/recipes-core/packagegroups
474 meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb
475 meta-raspberrypi/recipes-core/psplash
476 meta-raspberrypi/recipes-core/psplash/files
477 meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h
478 meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend
479 meta-raspberrypi/recipes-core/udev
480 meta-raspberrypi/recipes-core/udev/udev-rules-rpi
481 meta-raspberrypi/recipes-core/udev/udev-rules-rpi/99-com.rules
482 meta-raspberrypi/recipes-core/udev/udev-rules-rpi.bb
483 meta-raspberrypi/recipes-devtools
484 meta-raspberrypi/recipes-devtools/bcm2835
485 meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.52.bb
486 meta-raspberrypi/recipes-devtools/pi-blaster
487 meta-raspberrypi/recipes-devtools/pi-blaster/files
488 meta-raspberrypi/recipes-devtools/pi-blaster/files/*.patch
489 meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb
490 meta-raspberrypi/recipes-devtools/python
491 meta-raspberrypi/recipes-devtools/python/python-rtimu
492 meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch
493 meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb
494 meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.2.0.bb
495 meta-raspberrypi/recipes-devtools/python/rpi-gpio
496 meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch
497 meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.3.bb
498 meta-raspberrypi/recipes-devtools/python/rpio
499 meta-raspberrypi/recipes-devtools/python/rpio/*.patch
500 meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb
501 meta-raspberrypi/recipes-devtools/wiringPi
502 meta-raspberrypi/recipes-devtools/wiringPi/files
503 meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch
504 meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb
505 meta-raspberrypi/recipes-graphics
506 meta-raspberrypi/recipes-graphics/eglinfo
507 meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend
508 meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend
509 meta-raspberrypi/recipes-graphics/mesa
510 meta-raspberrypi/recipes-graphics/mesa/mesa-gl_%.bbappend
511 meta-raspberrypi/recipes-graphics/mesa/mesa_%.bbappend
512 meta-raspberrypi/recipes-graphics/userland
513 meta-raspberrypi/recipes-graphics/userland/userland
514 meta-raspberrypi/recipes-graphics/userland/userland/*.patch
515 meta-raspberrypi/recipes-graphics/userland/userland_git.bb
516 meta-raspberrypi/recipes-graphics/vc-graphics
517 meta-raspberrypi/recipes-graphics/vc-graphics/files
518 meta-raspberrypi/recipes-graphics/vc-graphics/files/egl.pc
519 meta-raspberrypi/recipes-graphics/vc-graphics/files/vchiq.sh
520 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics-hardfp.bb
521 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.bb
522 meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc
523 meta-raspberrypi/recipes-graphics/wayland
524 meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend
525 meta-raspberrypi/recipes-graphics/xorg-xserver
526 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config
527 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi
528 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf
529 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d
530 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf
531 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/98-pitft.conf
532 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-calibration.conf
533 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
534 meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xorg_%.bbappend
535 meta-raspberrypi/recipes-kernel
536 meta-raspberrypi/recipes-kernel/linux-firmware
537 meta-raspberrypi/recipes-kernel/linux-firmware/files
538 meta-raspberrypi/recipes-kernel/linux-firmware/files/brcmfmac43430-sdio.bin
539 meta-raspberrypi/recipes-kernel/linux-firmware/files/brcfmac43430-sdio.txt
540 meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_%.bbappend
541 meta-raspberrypi/recipes-kernel/linux
542 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-dev.bb
543 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc
544 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.14.bb
545 meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.9.bb
546 meta-raspberrypi/recipes-multimedia
547 meta-raspberrypi/recipes-multimedia/gstreamer
548 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx
549 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch
550 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend
551 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend
552 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12
553 meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12/*.patch
554 meta-raspberrypi/recipes-multimedia/omxplayer
555 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer
556 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch
557 meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb
558 meta-raspberrypi/recipes-multimedia/x264
559 meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend
560 meta-raspberrypi/wic
561 meta-raspberrypi/wic/sdimage-raspberrypi.wks
562 </literallayout>
563 </para>
564
565 <para>
566 The following sections describe each part of the proposed
567 BSP format.
568 </para>
569
570 <section id="bsp-filelayout-license">
571 <title>License Files</title>
572
573 <para>
574 You can find these files in the BSP Layer at:
575 <literallayout class='monospaced'>
576 meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable>
577 </literallayout>
578 </para>
579
580 <para>
581 These optional files satisfy licensing requirements
582 for the BSP.
583 The type or types of files here can vary depending
584 on the licensing requirements.
585 For example, in the Raspberry Pi BSP, all licensing
586 requirements are handled with the
587 <filename>COPYING.MIT</filename> file.
588 </para>
589
590 <para>
591 Licensing files can be MIT, BSD, GPLv*, and so forth.
592 These files are recommended for the BSP but are
593 optional and totally up to the BSP developer.
594 For information on how to maintain license
595 compliance, see the
596 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
597 section in the Yocto Project Development Tasks
598 Manual.
599 </para>
600 </section>
601
602 <section id="bsp-filelayout-readme">
603 <title>README File</title>
604
605 <para>
606 You can find this file in the BSP Layer at:
607 <literallayout class='monospaced'>
608 meta-<replaceable>bsp_root_name</replaceable>/README
609 </literallayout>
610 </para>
611
612 <para>
613 This file provides information on how to boot the live
614 images that are optionally included in the
615 <filename>binary/</filename> directory.
616 The <filename>README</filename> file also provides
617 information needed for building the image.
618 </para>
619
620 <para>
621 At a minimum, the <filename>README</filename> file must
622 contain a list of dependencies, such as the names of
623 any other layers on which the BSP depends and the name of
624 the BSP maintainer with his or her contact information.
625 </para>
626 </section>
627
628 <section id="bsp-filelayout-readme-sources">
629 <title>README.sources File</title>
630
631 <para>
632 You can find this file in the BSP Layer at:
633 <literallayout class='monospaced'>
634 meta-<replaceable>bsp_root_name</replaceable>/README.sources
635 </literallayout>
636 </para>
637
638 <para>
639 This file provides information on where to locate the BSP
640 source files used to build the images (if any) that
641 reside in
642 <filename>meta-<replaceable>bsp_root_name</replaceable>/binary</filename>.
643 Images in the <filename>binary</filename> would be images
644 released with the BSP.
645 The information in the <filename>README.sources</filename>
646 file also helps you find the
647 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
648 used to generate the images that ship with the BSP.
649 <note>
650 If the BSP's <filename>binary</filename> directory is
651 missing or the directory has no images, an existing
652 <filename>README.sources</filename> file is
653 meaningless and usually does not exist.
654 </note>
655 </para>
656 </section>
657
658 <section id="bsp-filelayout-binary">
659 <title>Pre-built User Binaries</title>
660
661 <para>
662 You can find these files in the BSP Layer at:
663 <literallayout class='monospaced'>
664 meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
665 </literallayout>
666 </para>
667
668 <para>
669 This optional area contains useful pre-built kernels
670 and user-space filesystem images released with the
671 BSP that are appropriate to the target system.
672 This directory typically contains graphical (e.g. Sato)
673 and minimal live images when the BSP tarball has been
674 created and made available in the
675 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink>
676 website.
677 You can use these kernels and images to get a system
678 running and quickly get started on development tasks.
679 </para>
680
681 <para>
682 The exact types of binaries present are highly
683 hardware-dependent.
684 The
685 <link linkend='bsp-filelayout-readme'><filename>README</filename></link>
686 file should be present in the BSP Layer and it
687 explains how to use the images with the target hardware.
688 Additionally, the
689 <link linkend='bsp-filelayout-readme-sources'><filename>README.sources</filename></link>
690 file should be present to locate the sources used to
691 build the images and provide information on the
692 Metadata.
693 </para>
694 </section>
695
696 <section id='bsp-filelayout-layer'>
697 <title>Layer Configuration File</title>
698
699 <para>
700 You can find this file in the BSP Layer at:
701 <literallayout class='monospaced'>
702 meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf
703 </literallayout>
704 </para>
705
706 <para>
707 The <filename>conf/layer.conf</filename> file
708 identifies the file structure as a layer,
709 identifies the contents of the layer, and
710 contains information about how the build system should
711 use it.
712 Generally, a standard boilerplate file such as the
713 following works.
714 In the following example, you would replace
715 <replaceable>bsp</replaceable> with the actual
716 name of the BSP (i.e.
717 <replaceable>bsp_root_name</replaceable> from the example
718 template).
719 </para>
720
721 <para>
722 <literallayout class='monospaced'>
723 # We have a conf and classes directory, add to BBPATH
724 BBPATH .= ":${LAYERDIR}"
725
726 # We have a recipes directory, add to BBFILES
727 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
728 ${LAYERDIR}/recipes-*/*/*.bbappend"
729
730 BBFILE_COLLECTIONS += "<replaceable>bsp</replaceable>"
731 BBFILE_PATTERN_<replaceable>bsp</replaceable> = "^${LAYERDIR}/"
732 BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6"
733
734 LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel"
735 </literallayout>
736 </para>
737
738 <para>
739 To illustrate the string substitutions, here are
740 the corresponding statements from the Raspberry
741 Pi <filename>conf/layer.conf</filename> file:
742 <literallayout class='monospaced'>
743 # We have a conf and classes directory, append to BBPATH
744 BBPATH .= ":${LAYERDIR}"
745
746 # We have a recipes directory containing .bb and .bbappend files, add to BBFILES
747 BBFILES += "${LAYERDIR}/recipes*/*/*.bb \
748 ${LAYERDIR}/recipes*/*/*.bbappend"
749
750 BBFILE_COLLECTIONS += "raspberrypi"
751 BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/"
752 BBFILE_PRIORITY_raspberrypi = "9"
753
754 # Additional license directories.
755 LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
756 .
757 .
758 .
759 </literallayout>
760 </para>
761
762 <para>
763 This file simply makes
764 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
765 aware of the recipes and configuration directories.
766 The file must exist so that the OpenEmbedded build system
767 can recognize the BSP.
768 </para>
769 </section>
770
771 <section id="bsp-filelayout-machine">
772 <title>Hardware Configuration Options</title>
773
774 <para>
775 You can find these files in the BSP Layer at:
776 <literallayout class='monospaced'>
777 meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf
778 </literallayout>
779 </para>
780
781 <para>
782 The machine files bind together all the information
783 contained elsewhere in the BSP into a format that
784 the build system can understand.
785 Each BSP Layer requires at least one machine file.
786 If the BSP supports multiple machines, multiple
787 machine configuration files can exist.
788 These filenames correspond to the values to which
789 users have set the
790 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
791 </para>
792
793 <para>
794 These files define things such as the kernel package
795 to use
796 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
797 of
798 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>virtual/kernel</ulink>),
799 the hardware drivers to include in different types
800 of images, any special software components that are
801 needed, any bootloader information, and also any
802 special image format requirements.
803 </para>
804
805 <para>
806 This configuration file could also include a hardware
807 "tuning" file that is commonly used to define the
808 package architecture and specify optimization flags,
809 which are carefully chosen to give best performance
810 on a given processor.
811 </para>
812
813 <para>
814 Tuning files are found in the
815 <filename>meta/conf/machine/include</filename>
816 directory within the
817 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
818 For example, many <filename>tune-*</filename> files
819 (e.g. <filename>tune-arm1136jf-s.inc</filename>,
820 <filename>tune-1586-nlp.inc</filename>, and so forth)
821 reside in the
822 <filename>poky/meta/conf/machine/include</filename>
823 directory.
824 </para>
825
826 <para>
827 To use an include file, you simply include them in the
828 machine configuration file.
829 For example, the Raspberry Pi BSP
830 <filename>raspberrypi3.conf</filename> contains the
831 following statement:
832 <literallayout class='monospaced'>
833 include conf/machine/include/rpi-base.inc
834 </literallayout>
835 </para>
836 </section>
837
838 <section id='bsp-filelayout-misc-recipes'>
839 <title>Miscellaneous BSP-Specific Recipe Files</title>
840
841 <para>
842 You can find these files in the BSP Layer at:
843 <literallayout class='monospaced'>
844 meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/*
845 </literallayout>
846 </para>
847
848 <para>
849 This optional directory contains miscellaneous recipe
850 files for the BSP.
851 Most notably would be the formfactor files.
852 For example, in the Raspberry Pi BSP, there is the
853 <filename>formfactor_0.0.bbappend</filename> file,
854 which is an append file used to augment the recipe
855 that starts the build.
856 Furthermore, there are machine-specific settings used
857 during the build that are defined by the
858 <filename>machconfig</filename> file further down in
859 the directory.
860 Here is the <filename>machconfig</filename> file for
861 the Raspberry Pi BSP:
862 <literallayout class='monospaced'>
863 HAVE_TOUCHSCREEN=0
864 HAVE_KEYBOARD=1
865
866 DISPLAY_CAN_ROTATE=0
867 DISPLAY_ORIENTATION=0
868 DISPLAY_DPI=133
869 </literallayout>
870 </para>
871
872 <note><para>
873 If a BSP does not have a formfactor entry, defaults
874 are established according to the formfactor
875 configuration file that is installed by the main
876 formfactor recipe
877 <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
878 which is found in the
879 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
880 </para></note>
881 </section>
882
883 <section id='bsp-filelayout-recipes-graphics'>
884 <title>Display Support Files</title>
885
886 <para>
887 You can find these files in the BSP Layer at:
888 <literallayout class='monospaced'>
889 meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/*
890 </literallayout>
891 </para>
892
893 <para>
894 This optional directory contains recipes for the
895 BSP if it has special requirements for graphics
896 support.
897 All files that are needed for the BSP to support
898 a display are kept here.
899 </para>
900 </section>
901
902 <section id='bsp-filelayout-kernel'>
903 <title>Linux Kernel Configuration</title>
904
905 <para>
906 You can find these files in the BSP Layer at:
907 <literallayout class='monospaced'>
908 meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux*.bbappend
909 meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/*.bb
910 </literallayout>
911 </para>
912
913 <para>
914 Append files (<filename>*.bbappend</filename>) modify
915 the main kernel recipe being used to build the image.
916 The <filename>*.bb</filename> files would be a
917 developer-supplied kernel recipe.
918 This area of the BSP hierarchy can contain both these
919 types of files although, in practice, it is likely that
920 you would have one or the other.
921 </para>
922
923 <para>
924 For your BSP, you typically want to use an existing Yocto
925 Project kernel recipe found in the
926 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
927 at <filename>meta/recipes-kernel/linux</filename>.
928 You can append machine-specific changes to the
929 kernel recipe by using a similarly named append
930 file, which is located in the BSP Layer for your
931 target device (e.g. the
932 <filename>meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux</filename> directory).
933 </para>
934
935 <para>
936 Suppose you are using the
937 <filename>linux-yocto_4.4.bb</filename> recipe to
938 build the kernel.
939 In other words, you have selected the kernel in your
940 <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
941 file by adding
942 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
943 and
944 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
945 statements as follows:
946 <literallayout class='monospaced'>
947 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
948 PREFERRED_VERSION_linux-yocto ?= "4.4%"
949 </literallayout>
950 <note>
951 When the preferred provider is assumed by
952 default, the
953 <filename>PREFERRED_PROVIDER</filename>
954 statement does not appear in the
955 <replaceable>bsp_root_name</replaceable><filename>.conf</filename> file.
956 </note>
957 You would use the
958 <filename>linux-yocto_4.4.bbappend</filename>
959 file to append specific BSP settings to the kernel,
960 thus configuring the kernel for your particular BSP.
961 </para>
962
963 <para>
964 You can find more information on what your append file
965 should contain in the
966 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-the-append-file'>Creating the Append File</ulink>"
967 section in the Yocto Project Linux Kernel Development
968 Manual.
969 </para>
970
971 <para>
972 An alternate scenario is when you create your own
973 kernel recipe for the BSP.
974 A good example of this is the Raspberry Pi BSP.
975 If you examine the
976 <filename>recipes-kernel/linux</filename> directory
977 you see the following:
978 <literallayout class='monospaced'>
979 linux-raspberrypi-dev.bb
980 linux-raspberrypi.inc
981 linux-raspberrypi_4.14.bb
982 linux-raspberrypi_4.9.bb
983 </literallayout>
984 The directory contains three kernel recipes and a
985 common include file.
986 </para>
987 </section>
988</section>
989
990<section id='developing-a-board-support-package-bsp'>
991 <title>Developing a Board Support Package (BSP)</title>
992
993 <para>
994 This section describes the high-level procedure you can
995 follow to create a BSP.
996 Although not required for BSP creation, the
997 <filename>meta-intel</filename> repository, which
998 contains many BSPs supported by the Yocto Project,
999 is part of the example.
1000 </para>
1001
1002 <para>
1003 For an example that shows how to create a new
1004 layer using the tools, see the
1005 "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</link>"
1006 section.
1007 </para>
1008
1009 <para>
1010 The following illustration and list summarize the BSP
1011 creation general workflow.
1012 </para>
1013
1014 <para>
1015 <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" />
1016 </para>
1017
1018 <para>
1019 <orderedlist>
1020 <listitem><para>
1021 <emphasis>Set up Your Host Development System
1022 to Support Development Using the Yocto
1023 Project</emphasis>:
1024 See the
1025 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
1026 section in the Yocto Project Development Tasks
1027 Manual for options on how to get a system ready
1028 to use the Yocto Project.
1029 </para></listitem>
1030 <listitem><para>
1031 <emphasis>Establish the
1032 <filename>meta-intel</filename>
1033 Repository on Your System:</emphasis>
1034 Having local copies of these supported BSP layers
1035 on your system gives you access to layers you
1036 might be able to leverage when creating your BSP.
1037 For information on how to get these files, see the
1038 "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>"
1039 section.
1040 </para></listitem>
1041 <listitem><para>
1042 <emphasis>Create Your Own BSP Layer Using the
1043 <filename>bitbake-layers</filename>
1044 Script:</emphasis>
1045 Layers are ideal for isolating and storing work
1046 for a given piece of hardware.
1047 A layer is really just a location or area in which you
1048 place the recipes and configurations for your BSP.
1049 In fact, a BSP is, in itself, a special type of layer.
1050 The simplest way to create a new BSP layer that is
1051 compliant with the Yocto Project is to use the
1052 <filename>bitbake-layers</filename> script.
1053 For information about that script, see the
1054 "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</link>"
1055 section.</para>
1056
1057 <para>Another example that illustrates a layer
1058 is an application.
1059 Suppose you are creating an application that has
1060 library or other dependencies in order for it to
1061 compile and run.
1062 The layer, in this case, would be where all the
1063 recipes that define those dependencies are kept.
1064 The key point for a layer is that it is an
1065 isolated area that contains all the relevant
1066 information for the project that the
1067 OpenEmbedded build system knows about.
1068 For more information on layers, see the
1069 "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
1070 section in the Yocto Project Overview and Concepts
1071 Manual.
1072 You can also reference the
1073 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
1074 section in the Yocto Project Development Tasks
1075 Manual.
1076 For more information on BSP layers, see the
1077 "<link linkend='bsp-layers'>BSP Layers</link>"
1078 section.
1079 <note><title>Notes</title>
1080 <itemizedlist>
1081 <listitem><para>
1082 Five hardware reference BSPs exist
1083 that are part of the Yocto Project release
1084 and are located in the
1085 <filename>poky/meta-yocto-bsp</filename> BSP
1086 layer:
1087 <itemizedlist>
1088 <listitem><para>
1089 Texas Instruments Beaglebone
1090 (<filename>beaglebone-yocto</filename>)
1091 </para></listitem>
1092 <listitem><para>
1093 Ubiquiti Networks EdgeRouter Lite
1094 (<filename>edgerouter</filename>)
1095 </para></listitem>
1096 <listitem><para>
1097 Two general IA platforms
1098 (<filename>genericx86</filename> and
1099 <filename>genericx86-64</filename>)
1100 </para></listitem>
1101 </itemizedlist>
1102 </para></listitem>
1103 <listitem><para>
1104 Three core Intel BSPs exist as part of
1105 the Yocto Project release in the
1106 <filename>meta-intel</filename> layer:
1107 <itemizedlist>
1108 <listitem><para>
1109 <filename>intel-core2-32</filename>,
1110 which is a BSP optimized for the Core2
1111 family of CPUs as well as all CPUs
1112 prior to the Silvermont core.
1113 </para></listitem>
1114 <listitem><para>
1115 <filename>intel-corei7-64</filename>,
1116 which is a BSP optimized for Nehalem
1117 and later Core and Xeon CPUs as well
1118 as Silvermont and later Atom CPUs,
1119 such as the Baytrail SoCs.
1120 </para></listitem>
1121 <listitem><para>
1122 <filename>intel-quark</filename>,
1123 which is a BSP optimized for the
1124 Intel Galileo gen1 &amp; gen2
1125 development boards.
1126 </para></listitem>
1127 </itemizedlist>
1128 </para></listitem>
1129 </itemizedlist>
1130 </note></para>
1131
1132 <para>When you set up a layer for a new BSP,
1133 you should follow a standard layout.
1134 This layout is described in the
1135 "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>"
1136 section.
1137 In the standard layout, notice the suggested
1138 structure for recipes and configuration
1139 information.
1140 You can see the standard layout for a BSP
1141 by examining any supported BSP found in the
1142 <filename>meta-intel</filename> layer inside
1143 the Source Directory.
1144 </para></listitem>
1145 <listitem><para>
1146 <emphasis>Make Configuration Changes to Your New
1147 BSP Layer:</emphasis>
1148 The standard BSP layer structure organizes the
1149 files you need to edit in
1150 <filename>conf</filename> and several
1151 <filename>recipes-*</filename> directories
1152 within the BSP layer.
1153 Configuration changes identify where your new
1154 layer is on the local system and identifies the
1155 kernel you are going to use.
1156 When you run the
1157 <filename>bitbake-layers</filename> script,
1158 you are able to interactively configure many
1159 things for the BSP (e.g. keyboard, touchscreen,
1160 and so forth).
1161 </para></listitem>
1162 <listitem><para>
1163 <emphasis>Make Recipe Changes to Your New BSP
1164 Layer:</emphasis>
1165 Recipe changes include altering recipes
1166 (<filename>*.bb</filename> files), removing
1167 recipes you do not use, and adding new recipes
1168 or append files (<filename>.bbappend</filename>)
1169 that support your hardware.
1170 </para></listitem>
1171 <listitem><para>
1172 <emphasis>Prepare for the Build:</emphasis>
1173 Once you have made all the changes to your BSP
1174 layer, there remains a few things you need to
1175 do for the OpenEmbedded build system in order
1176 for it to create your image.
1177 You need to get the build environment ready by
1178 sourcing an environment setup script
1179 (i.e. <filename>oe-init-build-env</filename>)
1180 and you need to be sure two key configuration
1181 files are configured appropriately: the
1182 <filename>conf/local.conf</filename> and the
1183 <filename>conf/bblayers.conf</filename> file.
1184 You must make the OpenEmbedded build system aware
1185 of your new layer.
1186 See the
1187 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
1188 section in the Yocto Project Development Tasks Manual
1189 for information on how to let the build system
1190 know about your new layer.
1191 </para></listitem>
1192 <listitem><para>
1193 <emphasis>Build the Image:</emphasis>
1194 The OpenEmbedded build system uses the BitBake tool
1195 to build images based on the type of image you want to
1196 create.
1197 You can find more information about BitBake in the
1198 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
1199 </para>
1200
1201 <para>The build process supports several types of
1202 images to satisfy different needs.
1203 See the
1204 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1205 chapter in the Yocto Project Reference Manual for
1206 information on supported images.
1207 </para></listitem>
1208 </orderedlist>
1209 </para>
1210</section>
1211
1212<section id='requirements-and-recommendations-for-released-bsps'>
1213 <title>Requirements and Recommendations for Released BSPs</title>
1214
1215 <para>
1216 Certain requirements exist for a released BSP to be
1217 considered compliant with the Yocto Project.
1218 Additionally, recommendations also exist.
1219 This section describes the requirements and
1220 recommendations for released BSPs.
1221 </para>
1222
1223 <section id='released-bsp-requirements'>
1224 <title>Released BSP Requirements</title>
1225
1226 <para>
1227 Before looking at BSP requirements, you should consider
1228 the following:
1229 <itemizedlist>
1230 <listitem><para>
1231 The requirements here assume the BSP layer
1232 is a well-formed, "legal" layer that can be
1233 added to the Yocto Project.
1234 For guidelines on creating a layer that meets
1235 these base requirements, see the
1236 "<link linkend='bsp-layers'>BSP Layers</link>"
1237 section in this manual and the
1238 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers"</ulink>"
1239 section in the Yocto Project Development Tasks
1240 Manual.
1241 </para></listitem>
1242 <listitem><para>
1243 The requirements in this section apply
1244 regardless of how you package a BSP.
1245 You should consult the packaging and distribution
1246 guidelines for your specific release process.
1247 For an example of packaging and distribution
1248 requirements, see the
1249 "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
1250 wiki page.
1251 </para></listitem>
1252 <listitem><para>
1253 The requirements for the BSP as it is made
1254 available to a developer are completely
1255 independent of the released form of the BSP.
1256 For example, the BSP Metadata can be contained
1257 within a Git repository and could have a directory
1258 structure completely different from what appears
1259 in the officially released BSP layer.
1260 </para></listitem>
1261 <listitem><para>
1262 It is not required that specific packages or
1263 package modifications exist in the BSP layer,
1264 beyond the requirements for general
1265 compliance with the Yocto Project.
1266 For example, no requirement exists dictating
1267 that a specific kernel or kernel version be
1268 used in a given BSP.
1269 </para></listitem>
1270 </itemizedlist>
1271 </para>
1272
1273 <para>
1274 Following are the requirements for a released BSP
1275 that conform to the Yocto Project:
1276 <itemizedlist>
1277 <listitem><para>
1278 <emphasis>Layer Name:</emphasis>
1279 The BSP must have a layer name that follows
1280 the Yocto Project standards.
1281 For information on BSP layer names, see the
1282 "<link linkend='bsp-layers'>BSP Layers</link>" section.
1283 </para></listitem>
1284 <listitem><para>
1285 <emphasis>File System Layout:</emphasis>
1286 When possible, use the same directory names
1287 in your BSP layer as listed in the
1288 <filename>recipes.txt</filename> file, which
1289 is found in <filename>poky/meta</filename>
1290 directory of the
1291 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
1292 or in the OpenEmbedded-Core Layer
1293 (<filename>openembedded-core</filename>) at
1294 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
1295 </para>
1296
1297 <para>You should place recipes
1298 (<filename>*.bb</filename> files) and recipe
1299 modifications (<filename>*.bbappend</filename>
1300 files) into <filename>recipes-*</filename>
1301 subdirectories by functional area as outlined
1302 in <filename>recipes.txt</filename>.
1303 If you cannot find a category in
1304 <filename>recipes.txt</filename> to fit a
1305 particular recipe, you can make up your own
1306 <filename>recipes-*</filename> subdirectory.
1307 </para>
1308
1309 <para>Within any particular
1310 <filename>recipes-*</filename> category, the
1311 layout should match what is found in the
1312 OpenEmbedded-Core Git repository
1313 (<filename>openembedded-core</filename>)
1314 or the Source Directory (<filename>poky</filename>).
1315 In other words, make sure you place related
1316 files in appropriately-related
1317 <filename>recipes-*</filename> subdirectories
1318 specific to the recipe's function, or within
1319 a subdirectory containing a set of closely-related
1320 recipes.
1321 The recipes themselves should follow the general
1322 guidelines for recipes used in the Yocto Project
1323 found in the
1324 "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>".
1325 </para></listitem>
1326 <listitem><para>
1327 <emphasis>License File:</emphasis>
1328 You must include a license file in the
1329 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1330 directory.
1331 This license covers the BSP Metadata as a whole.
1332 You must specify which license to use since no
1333 default license exists when one is not specified.
1334 See the
1335 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
1336 file for the Raspberry Pi BSP in the
1337 <filename>meta-raspberrypi</filename> BSP layer
1338 as an example.
1339 </para></listitem>
1340 <listitem><para>
1341 <emphasis>README File:</emphasis>
1342 You must include a <filename>README</filename>
1343 file in the
1344 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1345 directory.
1346 See the
1347 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README.md'><filename>README.md</filename></ulink>
1348 file for the Raspberry Pi BSP in the
1349 <filename>meta-raspberrypi</filename> BSP layer
1350 as an example.</para>
1351
1352 <para>At a minimum, the <filename>README</filename>
1353 file should contain the following:
1354 <itemizedlist>
1355 <listitem><para>
1356 A brief description of the target hardware.
1357 </para></listitem>
1358 <listitem><para>
1359 A list of all the dependencies of the BSP.
1360 These dependencies are typically a list
1361 of required layers needed to build the
1362 BSP.
1363 However, the dependencies should also
1364 contain information regarding any other
1365 dependencies the BSP might have.
1366 </para></listitem>
1367 <listitem><para>
1368 Any required special licensing information.
1369 For example, this information includes
1370 information on special variables needed
1371 to satisfy a EULA, or instructions on
1372 information needed to build or distribute
1373 binaries built from the BSP Metadata.
1374 </para></listitem>
1375 <listitem><para>
1376 The name and contact information for the
1377 BSP layer maintainer.
1378 This is the person to whom patches and
1379 questions should be sent.
1380 For information on how to find the right
1381 person, see the
1382 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
1383 section in the Yocto Project Development
1384 Tasks Manual.
1385 </para></listitem>
1386 <listitem><para>
1387 Instructions on how to build the BSP using
1388 the BSP layer.
1389 </para></listitem>
1390 <listitem><para>
1391 Instructions on how to boot the BSP build
1392 from the BSP layer.
1393 </para></listitem>
1394 <listitem><para>
1395 Instructions on how to boot the binary
1396 images contained in the
1397 <filename>binary</filename> directory,
1398 if present.
1399 </para></listitem>
1400 <listitem><para>
1401 Information on any known bugs or issues
1402 that users should know about when either
1403 building or booting the BSP binaries.
1404 </para></listitem>
1405 </itemizedlist>
1406 </para></listitem>
1407 <listitem><para>
1408 <emphasis>README.sources File:</emphasis>
1409 If you BSP contains binary images in the
1410 <filename>binary</filename> directory, you must
1411 include a <filename>README.sources</filename>
1412 file in the
1413 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1414 directory.
1415 This file specifies exactly where you can find
1416 the sources used to generate the binary images.
1417 </para></listitem>
1418 <listitem><para>
1419 <emphasis>Layer Configuration File:</emphasis>
1420 You must include a
1421 <filename>conf/layer.conf</filename> file in
1422 the
1423 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1424 directory.
1425 This file identifies the
1426 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1427 BSP layer as a layer to the build system.
1428 </para></listitem>
1429 <listitem><para>
1430 <emphasis>Machine Configuration File:</emphasis>
1431 You must include one or more
1432 <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
1433 files in the
1434 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1435 directory.
1436 These configuration files define machine targets
1437 that can be built using the BSP layer.
1438 Multiple machine configuration files define
1439 variations of machine configurations that the
1440 BSP supports.
1441 If a BSP supports multiple machine variations,
1442 you need to adequately describe each variation
1443 in the BSP <filename>README</filename> file.
1444 Do not use multiple machine configuration files
1445 to describe disparate hardware.
1446 If you do have very different targets, you should
1447 create separate BSP layers for each target.
1448 <note>
1449 It is completely possible for a developer to
1450 structure the working repository as a
1451 conglomeration of unrelated BSP files, and to
1452 possibly generate BSPs targeted for release
1453 from that directory using scripts or some
1454 other mechanism
1455 (e.g. <filename>meta-yocto-bsp</filename> layer).
1456 Such considerations are outside the scope of
1457 this document.
1458 </note>
1459 </para></listitem>
1460 </itemizedlist>
1461 </para>
1462 </section>
1463
1464 <section id='released-bsp-recommendations'>
1465 <title>Released BSP Recommendations</title>
1466
1467 <para>
1468 Following are recommendations for released BSPs that
1469 conform to the Yocto Project:
1470 <itemizedlist>
1471 <listitem><para>
1472 <emphasis>Bootable Images:</emphasis>
1473 Released BSPs can contain one or more bootable
1474 images.
1475 Including bootable images allows users to easily
1476 try out the BSP using their own hardware.</para>
1477
1478 <para>In some cases, it might not be convenient
1479 to include a bootable image.
1480 If so, you might want to make two versions of the
1481 BSP available: one that contains binary images, and
1482 one that does not.
1483 The version that does not contain bootable images
1484 avoids unnecessary download times for users not
1485 interested in the images.</para>
1486
1487 <para>If you need to distribute a BSP and include
1488 bootable images or build kernel and filesystems
1489 meant to allow users to boot the BSP for evaluation
1490 purposes, you should put the images and artifacts
1491 within a
1492 <filename>binary/</filename> subdirectory located
1493 in the
1494 <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
1495 directory.
1496 <note>
1497 If you do include a bootable image as part
1498 of the BSP and the image was built by software
1499 covered by the GPL or other open source licenses,
1500 it is your responsibility to understand
1501 and meet all licensing requirements, which could
1502 include distribution of source files.
1503 </note>
1504 </para></listitem>
1505 <listitem><para>
1506 <emphasis>Use a Yocto Linux Kernel:</emphasis>
1507 Kernel recipes in the BSP should be based on a
1508 Yocto Linux kernel.
1509 Basing your recipes on these kernels reduces
1510 the costs for maintaining the BSP and increases
1511 its scalability.
1512 See the <filename>Yocto Linux Kernel</filename>
1513 category in the
1514 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
1515 for these kernels.
1516 </para></listitem>
1517 </itemizedlist>
1518 </para>
1519 </section>
1520</section>
1521
1522<section id='customizing-a-recipe-for-a-bsp'>
1523 <title>Customizing a Recipe for a BSP</title>
1524
1525 <para>
1526 If you plan on customizing a recipe for a particular BSP,
1527 you need to do the following:
1528 <itemizedlist>
1529 <listitem><para>
1530 Create a <filename>*.bbappend</filename> file for
1531 the modified recipe.
1532 For information on using append files, see the
1533 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
1534 section in the Yocto Project Development Tasks
1535 Manual.
1536 </para></listitem>
1537 <listitem><para>
1538 Ensure your directory structure in the BSP layer
1539 that supports your machine is such that the
1540 OpenEmbedded build system can find it.
1541 See the example later in this section for more
1542 information.
1543 </para></listitem>
1544 <listitem><para>
1545 Put the append file in a directory whose name matches
1546 the machine's name and is located in an appropriate
1547 sub-directory inside the BSP layer (i.e.
1548 <filename>recipes-bsp</filename>,
1549 <filename>recipes-graphics</filename>,
1550 <filename>recipes-core</filename>, and so forth).
1551 </para></listitem>
1552 <listitem><para>
1553 Place the BSP-specific files in the proper
1554 directory inside the BSP layer.
1555 How expansive the layer is affects where you must
1556 place these files.
1557 For example, if your layer supports several
1558 different machine types, you need to be sure your
1559 layer's directory structure includes hierarchy
1560 that separates the files according to machine.
1561 If your layer does not support multiple machines,
1562 the layer would not have that additional hierarchy
1563 and the files would obviously not be able to reside
1564 in a machine-specific directory.
1565 </para></listitem>
1566 </itemizedlist>
1567 </para>
1568
1569 <para>
1570 Following is a specific example to help you better understand
1571 the process.
1572 This example customizes customizes a recipe by adding a
1573 BSP-specific configuration file named
1574 <filename>interfaces</filename> to the
1575 <filename>init-ifupdown_1.0.bb</filename> recipe for machine
1576 "xyz" where the BSP layer also supports several other
1577 machines:
1578 <orderedlist>
1579 <listitem><para>
1580 Edit the
1581 <filename>init-ifupdown_1.0.bbappend</filename> file
1582 so that it contains the following:
1583 <literallayout class='monospaced'>
1584 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
1585 </literallayout>
1586 The append file needs to be in the
1587 <filename>meta-xyz/recipes-core/init-ifupdown</filename>
1588 directory.
1589 </para></listitem>
1590 <listitem><para>
1591 Create and place the new
1592 <filename>interfaces</filename> configuration file in
1593 the BSP's layer here:
1594 <literallayout class='monospaced'>
1595 meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
1596 </literallayout>
1597 <note>
1598 If the <filename>meta-xyz</filename> layer did
1599 not support multiple machines, you would place
1600 the <filename>interfaces</filename> configuration
1601 file in the layer here:
1602 <literallayout class='monospaced'>
1603 meta-xyz/recipes-core/init-ifupdown/files/interfaces
1604 </literallayout>
1605 </note>
1606 The
1607 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
1608 variable in the append files extends the search path
1609 the build system uses to find files during the build.
1610 Consequently, for this example you need to have the
1611 <filename>files</filename> directory in the same
1612 location as your append file.
1613 </para></listitem>
1614 </orderedlist>
1615 </para>
1616</section>
1617
1618<section id='bsp-licensing-considerations'>
1619 <title>BSP Licensing Considerations</title>
1620
1621 <para>
1622 In some cases, a BSP contains separately-licensed
1623 Intellectual Property (IP) for a component or components.
1624 For these cases, you are required to accept the terms
1625 of a commercial or other type of license that requires
1626 some kind of explicit End User License Agreement (EULA).
1627 Once you accept the license, the OpenEmbedded build system
1628 can then build and include the corresponding component
1629 in the final BSP image.
1630 If the BSP is available as a pre-built image, you can
1631 download the image after agreeing to the license or EULA.
1632 </para>
1633
1634 <para>
1635 You could find that some separately-licensed components
1636 that are essential for normal operation of the system might
1637 not have an unencumbered (or free) substitute.
1638 Without these essential components, the system would be
1639 non-functional.
1640 Then again, you might find that other licensed components
1641 that are simply 'good-to-have' or purely elective do have
1642 an unencumbered, free replacement component that you can
1643 use rather than agreeing to the separately-licensed
1644 component.
1645 Even for components essential to the system, you might
1646 find an unencumbered component that is not identical but
1647 will work as a less-capable version of the licensed version
1648 in the BSP recipe.
1649 </para>
1650
1651 <para>
1652 For cases where you can substitute a free component and
1653 still maintain the system's functionality, the "DOWNLOADS"
1654 selection from the "SOFTWARE" tab on the
1655 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>
1656 makes available de-featured BSPs that are completely free
1657 of any IP encumbrances.
1658 For these cases, you can use the substitution directly and
1659 without any further licensing requirements.
1660 If present, these fully de-featured BSPs are named
1661 appropriately different as compared to the names of their
1662 respective encumbered BSPs.
1663 If available, these substitutions are your simplest and
1664 most preferred options.
1665 Obviously, use of these substitutions assumes the resulting
1666 functionality meets system requirements.
1667 <note>
1668 If however, a non-encumbered version is unavailable or
1669 it provides unsuitable functionality or quality, you can
1670 use an encumbered version.
1671 </note>
1672 </para>
1673
1674 <para>
1675 A couple different methods exist within the OpenEmbedded
1676 build system to satisfy the licensing requirements for an
1677 encumbered BSP.
1678 The following list describes them in order of preference:
1679 <orderedlist>
1680 <listitem><para>
1681 <emphasis>Use the
1682 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1683 Variable to Define the Recipes that Have Commercial
1684 or Other Types of Specially-Licensed Packages:</emphasis>
1685 For each of those recipes, you can specify a
1686 matching license string in a
1687 <filename>local.conf</filename> variable named
1688 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>.
1689 Specifying the matching license string signifies
1690 that you agree to the license.
1691 Thus, the build system can build the corresponding
1692 recipe and include the component in the image.
1693 See the
1694 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
1695 section in the Yocto Project Development Tasks
1696 Manual for details on how to use these variables.
1697 </para>
1698
1699 <para>If you build as you normally would, without
1700 specifying any recipes in the
1701 <filename>LICENSE_FLAGS_WHITELIST</filename>, the
1702 build stops and provides you with the list of recipes
1703 that you have tried to include in the image that
1704 need entries in the
1705 <filename>LICENSE_FLAGS_WHITELIST</filename>.
1706 Once you enter the appropriate license flags into
1707 the whitelist, restart the build to continue where
1708 it left off.
1709 During the build, the prompt will not appear again
1710 since you have satisfied the requirement.</para>
1711
1712 <para>Once the appropriate license flags are on the
1713 white list in the
1714 <filename>LICENSE_FLAGS_WHITELIST</filename> variable,
1715 you can build the encumbered image with no change
1716 at all to the normal build process.
1717 </para></listitem>
1718 <listitem><para>
1719 <emphasis>Get a Pre-Built Version of the BSP:</emphasis>
1720 You can get this type of BSP by selecting the
1721 "DOWNLOADS" item from the "SOFTWARE" tab on the
1722 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
1723 You can download BSP tarballs that contain
1724 proprietary components after agreeing to the
1725 licensing requirements of each of the individually
1726 encumbered packages as part of the download process.
1727 Obtaining the BSP this way allows you to access an
1728 encumbered image immediately after agreeing to the
1729 click-through license agreements presented by the
1730 website.
1731 If you want to build the image yourself using
1732 the recipes contained within the BSP tarball,
1733 you will still need to create an appropriate
1734 <filename>LICENSE_FLAGS_WHITELIST</filename>
1735 to match the encumbered recipes in the BSP.
1736 </para></listitem>
1737 </orderedlist>
1738 <note>
1739 Pre-compiled images are bundled with a time-limited
1740 kernel that runs for a predetermined amount of time
1741 (10 days) before it forces the system to reboot.
1742 This limitation is meant to discourage direct
1743 redistribution of the image.
1744 You must eventually rebuild the image if you want
1745 to remove this restriction.
1746 </note>
1747 </para>
1748</section>
1749
1750<section id='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>
1751 <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title>
1752
1753 <para>
1754 The <filename>bitbake-layers create-layer</filename> script
1755 automates creating a BSP layer.
1756 What makes a layer a "BSP layer" is the presence of at least one machine
1757 configuration file.
1758 Additionally, a BSP layer usually has a kernel recipe
1759 or an append file that leverages off an existing kernel recipe.
1760 The primary requirement, however, is the machine configuration.
1761 </para>
1762
1763 <para>
1764 Use these steps to create a BSP layer:
1765 <itemizedlist>
1766 <listitem><para>
1767 <emphasis>Create a General Layer:</emphasis>
1768 Use the <filename>bitbake-layers</filename> script with the
1769 <filename>create-layer</filename> subcommand to create a
1770 new general layer.
1771 For instructions on how to create a general layer using the
1772 <filename>bitbake-layers</filename> script, see the
1773 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
1774 section in the Yocto Project Development Tasks Manual.
1775 </para></listitem>
1776 <listitem><para>
1777 <emphasis>Create a Layer Configuration File:</emphasis>
1778 Every layer needs a layer configuration file.
1779 This configuration file establishes locations for the
1780 layer's recipes, priorities for the layer, and so forth.
1781 You can find examples of <filename>layer.conf</filename>
1782 files in the Yocto Project
1783 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
1784 To get examples of what you need in your configuration
1785 file, locate a layer (e.g. "meta-ti") and examine the
1786 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/layer.conf'></ulink>
1787 file.
1788 </para></listitem>
1789 <listitem><para>
1790 <emphasis>Create a Machine Configuration File:</emphasis>
1791 Create a <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
1792 file.
1793 See
1794 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf/machine'><filename>meta-yocto-bsp/conf/machine</filename></ulink>
1795 for sample
1796 <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
1797 files.
1798 Other samples such as
1799 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/machine'><filename>meta-ti</filename></ulink>
1800 and
1801 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/conf/machine'><filename>meta-freescale</filename></ulink>
1802 exist from other vendors that have more specific machine
1803 and tuning examples.
1804 </para></listitem>
1805 <listitem><para>
1806 <emphasis>Create a Kernel Recipe:</emphasis>
1807 Create a kernel recipe in <filename>recipes-kernel/linux</filename>
1808 by either using a kernel append file or a new custom kernel
1809 recipe file (e.g. <filename>yocto-linux_4.12.bb</filename>).
1810 The BSP layers mentioned in the previous step also contain different
1811 kernel examples.
1812 See the
1813 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>"
1814 section in the Yocto Project Linux Kernel Development Manual
1815 for information on how to create a custom kernel.
1816 </para></listitem>
1817 </itemizedlist>
1818 </para>
1819
1820 <para>
1821 The remainder of this section provides a description of
1822 the Yocto Project reference BSP for Beaglebone, which
1823 resides in the
1824 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp'><filename>meta-yocto-bsp</filename></ulink>
1825 layer.
1826 </para>
1827
1828 <section id='bsp-layer-configuration-example'>
1829 <title>BSP Layer Configuration Example</title>
1830
1831 <para>
1832 The layer's <filename>conf</filename> directory
1833 contains the <filename>layer.conf</filename>
1834 configuration file.
1835 In this example, the
1836 <filename>conf/layer.conf</filename> is the
1837 following:
1838 <literallayout class='monospaced'>
1839 # We have a conf and classes directory, add to BBPATH
1840 BBPATH .= ":${LAYERDIR}"
1841
1842 # We have recipes-* directories, add to BBFILES
1843 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
1844 ${LAYERDIR}/recipes-*/*/*.bbappend"
1845
1846 BBFILE_COLLECTIONS += "yoctobsp"
1847 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
1848 BBFILE_PRIORITY_yoctobsp = "5"
1849 LAYERVERSION_yoctobsp = "4"
1850 LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;"
1851 </literallayout>
1852 The variables used in this file configure the
1853 layer.
1854 A good way to learn about layer configuration
1855 files is to examine various files for BSP from
1856 the
1857 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
1858 </para>
1859
1860 <para>
1861 For a detailed description of this particular
1862 layer configuration file, see
1863 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-layer-config-file-description'>step 3</ulink>
1864 in the discussion that describes how to create
1865 layers in the Yocto Project Development Tasks Manual.
1866 </para>
1867 </section>
1868
1869 <section id='bsp-machine-configuration-example'>
1870 <title>BSP Machine Configuration Example</title>
1871
1872 <para>
1873 As mentioned earlier in this section, the existence
1874 of a machine configuration file is what makes a
1875 layer a BSP layer as compared to a general or
1876 kernel layer.
1877 </para>
1878
1879 <para>
1880 One or more machine configuration files exist in the
1881 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename>
1882 directory of the layer:
1883 <literallayout class='monospaced'>
1884 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine1</replaceable><filename>.conf</filename>
1885 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine2</replaceable><filename>.conf</filename>
1886 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine3</replaceable><filename>.conf</filename>
1887 ... more ...
1888 </literallayout>
1889 For example, the machine configuration file for the
1890 <ulink url='http://beagleboard.org/bone'>BeagleBone and BeagleBone Black development boards</ulink>
1891 is located in the layer
1892 <filename>poky/meta-yocto-bsp/conf/machine</filename>
1893 and is named <filename>beaglebone-yocto.conf</filename>:
1894 <literallayout class='monospaced'>
1895 #@TYPE: Machine
1896 #@NAME: Beaglebone-yocto machine
1897 #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards
1898
1899 PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg"
1900 XSERVER ?= "xserver-xorg \
1901 xf86-video-modesetting \
1902 "
1903
1904 MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree"
1905
1906 EXTRA_IMAGEDEPENDS += "u-boot"
1907
1908 DEFAULTTUNE ?= "cortexa8hf-neon"
1909 include conf/machine/include/tune-cortexa8.inc
1910
1911 IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap"
1912 EXTRA_IMAGECMD_jffs2 = "-lnp "
1913 WKS_FILE ?= "beaglebone-yocto.wks"
1914 IMAGE_INSTALL_append = " kernel-devicetree kernel-image-zimage"
1915 do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot"
1916
1917 SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0"
1918 SERIAL_CONSOLES_CHECK = "${SERIAL_CONSOLES}"
1919
1920 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
1921 PREFERRED_VERSION_linux-yocto ?= "5.0%"
1922
1923 KERNEL_IMAGETYPE = "zImage"
1924 KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb"
1925 KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}"
1926
1927 SPL_BINARY = "MLO"
1928 UBOOT_SUFFIX = "img"
1929 UBOOT_MACHINE = "am335x_evm_defconfig"
1930 UBOOT_ENTRYPOINT = "0x80008000"
1931 UBOOT_LOADADDRESS = "0x80008000"
1932
1933 MACHINE_FEATURES = "usbgadget usbhost vfat alsa"
1934
1935 IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb"
1936 </literallayout>
1937 The variables used to configure the machine define
1938 machine-specific properties;
1939 for example, machine-dependent packages, machine
1940 tunings, the type of kernel to build, and
1941 U-Boot configurations.
1942 </para>
1943
1944 <para>
1945 The following list provides some explanation
1946 for the statements found in the example reference
1947 machine configuration file for the BeagleBone
1948 development boards.
1949 Realize that much more can be defined as part of
1950 a machine's configuration file.
1951 In general, you can learn about related variables
1952 that this example does not have by locating the
1953 variables in the
1954 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>Yocto Project Variables Glossary</ulink>"
1955 in the Yocto Project Reference Manual.
1956 <itemizedlist>
1957 <listitem><para>
1958 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/xserver</filename></ulink>:
1959 The recipe that provides "virtual/xserver" when
1960 more than one provider is found.
1961 In this case, the recipe that provides
1962 "virtual/xserver" is "xserver-xorg", which
1963 exists in
1964 <filename>poky/meta/recipes-graphics/xorg-xserver</filename>.
1965 </para></listitem>
1966 <listitem><para>
1967 <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>:
1968 The packages that should be installed to provide
1969 an X server and drivers for the machine.
1970 In this example, the "xserver-xorg" and
1971 "xf86-video-modesetting" are installed.
1972 </para></listitem>
1973 <listitem><para>
1974 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>:
1975 A list of machine-dependent packages
1976 not essential for booting the image.
1977 Thus, the build does not fail if the packages
1978 do not exist.
1979 However, the packages are required for a
1980 fully-featured image.
1981 <note><title>Tip</title>
1982 Many <filename>MACHINE*</filename> variables
1983 exist that help you configure a particular
1984 piece of hardware.
1985 </note>
1986 </para></listitem>
1987 <listitem><para>
1988 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGEDEPENDS'><filename>EXTRA_IMAGEDEPENDS</filename></ulink>:
1989 Recipes to build that do not provide packages
1990 for installing into the root filesystem
1991 but building the image depends on the
1992 recipes.
1993 Sometimes a recipe is required to build
1994 the final image but is not needed in the
1995 root filesystem.
1996 In this case, the U-Boot recipe must be
1997 built for the image.
1998 </para></listitem>
1999 <listitem><para>
2000 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>:
2001 Machines use tunings to optimize machine,
2002 CPU, and application performance.
2003 These features, which are collectively known
2004 as "tuning features", exist in the
2005 <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core (OE-Core)</ulink>
2006 layer (e.g.
2007 <filename>poky/meta/conf/machine/include</filename>).
2008 In this example, the default tunning file is
2009 "cortexa8hf-neon".
2010 <note>
2011 The <filename>include</filename> statement
2012 that pulls in the
2013 <filename>conf/machine/include/tune-cortexa8.inc</filename>
2014 file provides many tuning possibilities.
2015 </note>
2016 </para></listitem>
2017 <listitem><para>
2018 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>:
2019 The formats the OpenEmbedded build system
2020 uses during the build when creating the
2021 root filesystem.
2022 In this example, four types of images are
2023 supported.
2024 </para></listitem>
2025 <listitem><para>
2026 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGECMD'><filename>EXTRA_IMAGECMD</filename></ulink>:
2027 Specifies additional options for image
2028 creation commands.
2029 In this example, the "-lnp " option is used
2030 when creating the
2031 <ulink url='https://en.wikipedia.org/wiki/JFFS2'>JFFS2</ulink>
2032 image.
2033 </para></listitem>
2034 <listitem><para>
2035 <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE'><filename>WKS_FILE</filename></ulink>:
2036 The location of the
2037 <ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>Wic kickstart</ulink>
2038 file used by the OpenEmbedded build system to
2039 create a partitioned image (image.wic).
2040 </para></listitem>
2041 <listitem><para>
2042 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
2043 Specifies packages to install into an image
2044 through the
2045 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
2046 class.
2047 Recipes use the <filename>IMAGE_INSTALL</filename>
2048 variable.
2049 </para></listitem>
2050 <listitem><para>
2051 <filename>do_image_wic[depends]</filename>:
2052 A task that is constructed during the build.
2053 In this example, the task depends on specific tools
2054 in order to create the sysroot when buiding a Wic
2055 image.
2056 </para></listitem>
2057 <listitem><para>
2058 <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>:
2059 Defines a serial console (TTY) to enable using
2060 getty.
2061 In this case, the baud rate is "115200" and the
2062 device name is "ttyO0".
2063 </para></listitem>
2064 <listitem><para>
2065 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/kernel</filename></ulink>:
2066 Specifies the recipe that provides
2067 "virtual/kernel" when more than one provider
2068 is found.
2069 In this case, the recipe that provides
2070 "virtual/kernel" is "linux-yocto", which
2071 exists in the layer's
2072 <filename>recipes-kernel/linux</filename> directory.
2073 </para></listitem>
2074 <listitem><para>
2075 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION_linux-yocto</filename></ulink>:
2076 Defines the version of the recipe used
2077 to build the kernel, which is "5.0" in this
2078 case.
2079 </para></listitem>
2080 <listitem><para>
2081 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>:
2082 The type of kernel to build for the device.
2083 In this case, the OpenEmbedded build system
2084 creates a "zImage" image type.
2085 </para></listitem>
2086 <listitem><para>
2087 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></ulink>:
2088 The names of the generated Linux kernel device
2089 trees (i.e. the <filename>*.dtb</filename>) files.
2090 All the device trees for the various BeagleBone
2091 devices are included.
2092<!--
2093 You have to include some *.inc files according to the definition of KERNEL_DEVICETREE.
2094 I don't see where these are being provided.
2095-->
2096 </para></listitem>
2097 <listitem><para>
2098 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_EXTRA_ARGS'><filename>KERNEL_EXTRA_ARGS</filename></ulink>:
2099 Additional <filename>make</filename>
2100 command-line arguments the OpenEmbedded build
2101 system passes on when compiling the kernel.
2102 In this example, "LOADADDR=${UBOOT_ENTRYPOINT}"
2103 is passed as a command-line argument.
2104 </para></listitem>
2105 <listitem><para>
2106 <ulink url='&YOCTO_DOCS_REF_URL;#var-SPL_BINARY'><filename>SPL_BINARY</filename></ulink>:
2107 Defines the Secondary Program Loader (SPL) binary
2108 type.
2109 In this case, the SPL binary is set to
2110 "MLO", which stands for Multimedia card LOader.
2111 </para>
2112
2113 <para>The BeagleBone development board requires an
2114 SPL to boot and that SPL file type must be MLO.
2115 Consequently, the machine configuration needs to
2116 define <filename>SPL_BINARY</filename> as "MLO".
2117 <note>
2118 For more information on how the SPL variables
2119 are used, see the
2120 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-bsp/u-boot/u-boot.inc'><filename>u-boot.inc</filename></ulink>
2121 include file.
2122 </note>
2123 </para></listitem>
2124 <listitem><para>
2125 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_*</filename></ulink>:
2126 Defines various U-Boot configurations needed
2127 to build a U-Boot image.
2128 In this example, a U-Boot image is required
2129 to boot the BeagleBone device.
2130 See the following variables for more information:
2131 <itemizedlist>
2132 <listitem><para>
2133 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_SUFFIX'><filename>UBOOT_SUFFIX</filename></ulink>:
2134 Points to the generated U-Boot extension.
2135 </para></listitem>
2136 <listitem><para>
2137 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></ulink>:
2138 Specifies the value passed on the make command line when building a U-Boot image.
2139 </para></listitem>
2140 <listitem><para>
2141 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_ENTRYPOINT</filename></ulink>:
2142 Specifies the entry point for the U-Boot image.
2143 </para></listitem>
2144 <listitem><para>
2145 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_LOADADDRESS'><filename>UBOOT_LOADADDRESS</filename></ulink>:
2146 Specifies the load address for the U-Boot image.
2147 </para></listitem>
2148 </itemizedlist>
2149 </para></listitem>
2150 <listitem><para>
2151 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>:
2152 Specifies the list of hardware features the
2153 BeagleBone device is capable of supporting.
2154 In this case, the device supports
2155 "usbgadget usbhost vfat alsa".
2156 </para></listitem>
2157 <listitem><para>
2158 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_BOOT_FILES'><filename>IMAGE_BOOT_FILES</filename></ulink>:
2159 Files installed into the device's boot partition
2160 when preparing the image using the Wic tool
2161 with the <filename>bootimg-partition</filename> or <filename>bootimg-efi</filename>
2162 source plugin.
2163 </para></listitem>
2164 </itemizedlist>
2165 </para>
2166 </section>
2167
2168 <section id='bsp-kernel-recipe-example'>
2169 <title>BSP Kernel Recipe Example</title>
2170
2171 <para>
2172 The kernel recipe used to build the kernel image
2173 for the BeagleBone device was established in the
2174 machine configuration:
2175 <literallayout class='monospaced'>
2176 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
2177 PREFERRED_VERSION_linux-yocto ?= "5.0%"
2178 </literallayout>
2179 The <filename>meta-yocto-bsp/recipes-kernel/linux</filename>
2180 directory in the layer contains metadata used
2181 to build the kernel.
2182 In this case, a kernel append file (i.e.
2183 <filename>linux-yocto_5.0.bbappend</filename>) is used to
2184 override an established kernel recipe (i.e.
2185 <filename>linux-yocto_5.0.bb</filename>), which is
2186 located in
2187 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux'></ulink>.
2188 </para>
2189
2190 <para>
2191 Following is the contents of the append file:
2192 <literallayout class='monospaced'>
2193 KBRANCH_genericx86 = "v5.0/standard/base"
2194 KBRANCH_genericx86-64 = "v5.0/standard/base"
2195 KBRANCH_edgerouter = "v5.0/standard/edgerouter"
2196 KBRANCH_beaglebone-yocto = "v5.0/standard/beaglebone"
2197
2198 KMACHINE_genericx86 ?= "common-pc"
2199 KMACHINE_genericx86-64 ?= "common-pc-64"
2200 KMACHINE_beaglebone-yocto ?= "beaglebone"
2201
2202 SRCREV_machine_genericx86 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d"
2203 SRCREV_machine_genericx86-64 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d"
2204 SRCREV_machine_edgerouter ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d"
2205 SRCREV_machine_beaglebone-yocto ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d"
2206
2207 COMPATIBLE_MACHINE_genericx86 = "genericx86"
2208 COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
2209 COMPATIBLE_MACHINE_edgerouter = "edgerouter"
2210 COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto"
2211
2212 LINUX_VERSION_genericx86 = "5.0.3"
2213 LINUX_VERSION_genericx86-64 = "5.0.3"
2214 LINUX_VERSION_edgerouter = "5.0.3"
2215 LINUX_VERSION_beaglebone-yocto = "5.0.3"
2216 </literallayout>
2217 This particular append file works for all the
2218 machines that are part of the
2219 <filename>meta-yocto-bsp</filename> layer.
2220 The relevant statements are appended with
2221 the "beaglebone-yocto" string.
2222 The OpenEmbedded build system uses these
2223 statements to override similar statements
2224 in the kernel recipe:
2225 <itemizedlist>
2226 <listitem><para>
2227 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>:
2228 Identifies the kernel branch that is validated,
2229 patched, and configured during the build.
2230 </para></listitem>
2231 <listitem><para>
2232 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>:
2233 Identifies the machine name as known by the
2234 kernel, which is sometimes a different name
2235 than what is known by the OpenEmbedded build
2236 system.
2237 </para></listitem>
2238 <listitem><para>
2239 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
2240 Identifies the revision of the source code used
2241 to build the image.
2242 </para></listitem>
2243 <listitem><para>
2244 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
2245 A regular expression that resolves to one or
2246 more target machines with which the recipe
2247 is compatible.
2248 </para></listitem>
2249 <listitem><para>
2250 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
2251 The Linux version from kernel.org used by
2252 the OpenEmbedded build system to build the
2253 kernel image.
2254 </para></listitem>
2255 </itemizedlist>
2256 </para>
2257 </section>
2258</section>
2259</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-09 04:33:47 +0000