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