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