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