diff options
Diffstat (limited to 'poky/documentation/bsp-guide')
-rw-r--r-- | poky/documentation/bsp-guide/bsp-guide-customization.xsl | 29 | ||||
-rw-r--r-- | poky/documentation/bsp-guide/bsp-guide.rst | 2 | ||||
-rwxr-xr-x | poky/documentation/bsp-guide/bsp-guide.xml | 202 | ||||
-rw-r--r-- | poky/documentation/bsp-guide/bsp-style.css | 989 | ||||
-rw-r--r-- | poky/documentation/bsp-guide/bsp.rst | 2 | ||||
-rw-r--r-- | poky/documentation/bsp-guide/bsp.xml | 2259 | ||||
-rw-r--r-- | poky/documentation/bsp-guide/history.rst | 2 |
7 files changed, 3482 insertions, 3 deletions
diff --git a/poky/documentation/bsp-guide/bsp-guide-customization.xsl b/poky/documentation/bsp-guide/bsp-guide-customization.xsl new file mode 100644 index 000000000..37fcbcd20 --- /dev/null +++ b/poky/documentation/bsp-guide/bsp-guide-customization.xsl @@ -0,0 +1,29 @@ +<?xml version='1.0'?> +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> + +<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"> + + <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> + +<!-- + + <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> + + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> + +--> + + <xsl:include href="../template/permalinks.xsl"/> + <xsl:include href="../template/section.title.xsl"/> + <xsl:include href="../template/component.title.xsl"/> + <xsl:include href="../template/division.title.xsl"/> + <xsl:include href="../template/formal.object.heading.xsl"/> + + <xsl:param name="html.stylesheet" select="'bsp-style.css'" /> + <xsl:param name="chapter.autolabel" select="1" /> + <xsl:param name="appendix.autolabel" select="A" /> + <xsl:param name="section.autolabel" select="1" /> + <xsl:param name="section.label.includes.component.label" select="1" /> + <xsl:param name="generate.id.attributes" select="1" /> + +</xsl:stylesheet> diff --git a/poky/documentation/bsp-guide/bsp-guide.rst b/poky/documentation/bsp-guide/bsp-guide.rst index a4394a85e..435a399d5 100644 --- a/poky/documentation/bsp-guide/bsp-guide.rst +++ b/poky/documentation/bsp-guide/bsp-guide.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK +.. SPDX-License-Identifier: CC-BY-2.0-UK ===================================================== Yocto Project Board Support Package Developer's Guide diff --git a/poky/documentation/bsp-guide/bsp-guide.xml b/poky/documentation/bsp-guide/bsp-guide.xml new file mode 100755 index 000000000..93ba1e7fe --- /dev/null +++ b/poky/documentation/bsp-guide/bsp-guide.xml @@ -0,0 +1,202 @@ +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> + +<book id='bsp-guide' lang='en' + xmlns:xi="http://www.w3.org/2003/XInclude" + xmlns="http://docbook.org/ns/docbook" + > + <bookinfo> + + <mediaobject> + <imageobject> + <imagedata fileref='figures/bsp-title.png' + format='SVG' + align='center' scalefit='1' width='100%'/> + </imageobject> + </mediaobject> + + <title> + Yocto Project Board Support Package Developer's Guide + </title> + + <authorgroup> + <author> + <affiliation> + <orgname>&ORGNAME;</orgname> + </affiliation> + <email>&ORGEMAIL;</email> + </author> + </authorgroup> + + <revhistory> + <revision> + <revnumber>0.9</revnumber> + <date>November 2010</date> + <revremark>The initial document released with the Yocto Project 0.9 Release.</revremark> + </revision> + <revision> + <revnumber>1.0</revnumber> + <date>April 2011</date> + <revremark>Released with the Yocto Project 1.0 Release.</revremark> + </revision> + <revision> + <revnumber>1.1</revnumber> + <date>October 2011</date> + <revremark>Released with the Yocto Project 1.1 Release.</revremark> + </revision> + <revision> + <revnumber>1.2</revnumber> + <date>April 2012</date> + <revremark>Released with the Yocto Project 1.2 Release.</revremark> + </revision> + <revision> + <revnumber>1.3</revnumber> + <date>October 2012</date> + <revremark>Released with the Yocto Project 1.3 Release.</revremark> + </revision> + <revision> + <revnumber>1.4</revnumber> + <date>April 2013</date> + <revremark>Released with the Yocto Project 1.4 Release.</revremark> + </revision> + <revision> + <revnumber>1.5</revnumber> + <date>October 2013</date> + <revremark>Released with the Yocto Project 1.5 Release.</revremark> + </revision> + <revision> + <revnumber>1.6</revnumber> + <date>April 2014</date> + <revremark>Released with the Yocto Project 1.6 Release.</revremark> + </revision> + <revision> + <revnumber>1.7</revnumber> + <date>October 2014</date> + <revremark>Released with the Yocto Project 1.7 Release.</revremark> + </revision> + <revision> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> + <revision> + <revnumber>2.0</revnumber> + <date>October 2015</date> + <revremark>Released with the Yocto Project 2.0 Release.</revremark> + </revision> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.1 Release.</revremark> + </revision> + <revision> + <revnumber>2.2</revnumber> + <date>October 2016</date> + <revremark>Released with the Yocto Project 2.2 Release.</revremark> + </revision> + <revision> + <revnumber>2.3</revnumber> + <date>May 2017</date> + <revremark>Released with the Yocto Project 2.3 Release.</revremark> + </revision> + <revision> + <revnumber>2.4</revnumber> + <date>October 2017</date> + <revremark>Released with the Yocto Project 2.4 Release.</revremark> + </revision> + <revision> + <revnumber>2.5</revnumber> + <date>May 2018</date> + <revremark>Released with the Yocto Project 2.5 Release.</revremark> + </revision> + <revision> + <revnumber>2.6</revnumber> + <date>November 2018</date> + <revremark>Released with the Yocto Project 2.6 Release.</revremark> + </revision> + <revision> + <revnumber>2.7</revnumber> + <date>May 2019</date> + <revremark>Released with the Yocto Project 2.7 Release.</revremark> + </revision> + <revision> + <revnumber>3.0</revnumber> + <date>October 2019</date> + <revremark>Released with the Yocto Project 3.0 Release.</revremark> + </revision> + <revision> + <revnumber>3.1</revnumber> + <date>&REL_MONTH_YEAR;</date> + <revremark>Released with the Yocto Project 3.1 Release.</revremark> + </revision> + </revhistory> + + <copyright> + <year>©RIGHT_YEAR;</year> + <holder>Linux Foundation</holder> + </copyright> + + <legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. + </para> + <note><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + This version of the + <emphasis>Yocto Project Board Support Package (BSP) Developer's Guide</emphasis> + is for the &YOCTO_DOC_VERSION; release of the + Yocto Project. + To be sure you have the latest version of the manual + for this release, go to the + <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink> + and select the manual from that site. + Manuals from the site are more up-to-date than manuals + derived from the Yocto Project released TAR files. + </para></listitem> + <listitem><para> + If you located this manual through a web search, the + version of the manual might not be the one you want + (e.g. the search might have returned a manual much + older than the Yocto Project version with which you + are working). + You can see all Yocto Project major releases by + visiting the + <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink> + page. + If you need a version of this manual for a different + Yocto Project release, visit the + <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink> + and select the manual set by using the + "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE" + pull-down menus. + </para></listitem> + <listitem> + <para> + To report any inaccuracies or problems with this + (or any other Yocto Project) manual, send an email to + the Yocto Project documentation mailing list at + <filename>docs@lists.yoctoproject.org</filename> or + log into the freenode <filename>#yocto</filename> channel. + </para> + </listitem> + </itemizedlist> + </note> + </legalnotice> + + </bookinfo> + + <xi:include href="bsp.xml"/> + +<!-- <index id='index'> + <title>Index</title> + </index> +--> + +</book> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/poky/documentation/bsp-guide/bsp-style.css b/poky/documentation/bsp-guide/bsp-style.css new file mode 100644 index 000000000..4ccf5d8ae --- /dev/null +++ b/poky/documentation/bsp-guide/bsp-style.css @@ -0,0 +1,989 @@ +/* + SPDX-License-Identifier: CC-BY-2.0-UK + + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/bsp-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + +.writernotes { + color: red; +} + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title { + background-position: bottom; + background-repeat: repeat-x; +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/poky/documentation/bsp-guide/bsp.rst b/poky/documentation/bsp-guide/bsp.rst index 61b295827..024a240c2 100644 --- a/poky/documentation/bsp-guide/bsp.rst +++ b/poky/documentation/bsp-guide/bsp.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK +.. SPDX-License-Identifier: CC-BY-2.0-UK ************************************************ Board Support Packages (BSP) - Developer's Guide diff --git a/poky/documentation/bsp-guide/bsp.xml b/poky/documentation/bsp-guide/bsp.xml new file mode 100644 index 000000000..f5c3f31fa --- /dev/null +++ b/poky/documentation/bsp-guide/bsp.xml @@ -0,0 +1,2259 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> + +<chapter id='bsp'> + +<title>Board Support Packages (BSP) - Developer's Guide</title> + +<para> + A Board Support Package (BSP) is a collection of information that + defines how to support a particular hardware device, set of devices, or + hardware platform. + The BSP includes information about the hardware features + present on the device and kernel configuration information along with any + additional hardware drivers required. + The BSP also lists any additional software + components required in addition to a generic Linux software stack for both + essential and optional platform features. +</para> + +<para> + This guide presents information about BSP layers, defines a structure for components + so that BSPs follow a commonly understood layout, discusses how to customize + a recipe for a BSP, addresses BSP licensing, and provides information that + shows you how to create a + <link linkend='bsp-layers'>BSP Layer</link> using the + <link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'><filename>bitbake-layers</filename></link> + tool. +</para> + +<section id='bsp-layers'> + <title>BSP Layers</title> + + <para> + A BSP consists of a file structure inside a base directory. + Collectively, you can think of the base directory, its file structure, + and the contents as a <firstterm>BSP layer</firstterm>. + Although not a strict requirement, BSP layers in the Yocto Project + use the following well-established naming convention: + <literallayout class='monospaced'> + meta-<replaceable>bsp_root_name</replaceable> + </literallayout> + The string "meta-" is prepended to the machine or platform name, which is + <replaceable>bsp_root_name</replaceable> in the above form. + <note><title>Tip</title> + Because the BSP layer naming convention is well-established, + it is advisable to follow it when creating layers. + Technically speaking, a BSP layer name does not need to + start with <filename>meta-</filename>. + However, various scripts and tools in the Yocto Project + development environment assume this convention. + </note> + </para> + + <para> + To help understand the BSP layer concept, consider the BSPs that the + Yocto Project supports and provides with each release. + You can see the layers in the + <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink> + through a web interface at + <ulink url='&YOCTO_GIT_URL;'></ulink>. + If you go to that interface, you will find a list of repositories + under "Yocto Metadata Layers". + <note> + Layers that are no longer actively supported as part of the + Yocto Project appear under the heading "Yocto Metadata Layer + Archive." + </note> + Each repository is a BSP layer supported by the Yocto Project + (e.g. <filename>meta-raspberrypi</filename> and + <filename>meta-intel</filename>). + Each of these layers is a repository unto itself and clicking on + the layer name displays two URLs from which you can + clone the layer's repository to your local system. + Here is an example that clones the Raspberry Pi BSP layer: + <literallayout class='monospaced'> + $ git clone git://git.yoctoproject.org/meta-raspberrypi + </literallayout> + </para> + + <para> + In addition to BSP layers, the + <filename>meta-yocto-bsp</filename> layer is part of the + shipped <filename>poky</filename> repository. + The <filename>meta-yocto-bsp</filename> layer maintains several + "reference" BSPs including the ARM-based Beaglebone, MIPS-based + EdgeRouter, and generic versions of + both 32-bit and 64-bit IA machines. + </para> + + <para> + For information on typical BSP development workflow, see the + "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>" + section. + For more information on how to set up a local copy of source files + from a Git repository, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>" + section in the Yocto Project Development Tasks Manual. + </para> + + <para> + The BSP layer's base directory + (<filename>meta-<replaceable>bsp_root_name</replaceable></filename>) + is the root directory of that Layer. + This directory is what you add to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> + variable in the <filename>conf/bblayers.conf</filename> file found in your + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, + which is established after you run the OpenEmbedded build environment + setup script (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>). + Adding the root directory allows the + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink> + to recognize the BSP layer and from it build an image. + Here is an example: + <literallayout class='monospaced'> + BBLAYERS ?= " \ + /usr/local/src/yocto/meta \ + /usr/local/src/yocto/meta-poky \ + /usr/local/src/yocto/meta-yocto-bsp \ + /usr/local/src/yocto/meta-mylayer \ + " + </literallayout> + <note><title>Tip</title> + Ordering and + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink> + for the layers listed in <filename>BBLAYERS</filename> + matter. + For example, if multiple layers define a machine + configuration, the OpenEmbedded build system uses + the last layer searched given similar layer + priorities. + The build system works from the top-down through + the layers listed in <filename>BBLAYERS</filename>. + </note> + </para> + + <para> + Some BSPs require or depend on additional layers + beyond the BSP's root layer in order to be functional. + In this case, you need to specify these layers in the + <filename>README</filename> "Dependencies" section of the + BSP's root layer. + Additionally, if any build instructions exist for the + BSP, you must add them to the "Dependencies" section. + </para> + + <para> + Some layers function as a layer to hold other BSP layers. + These layers are knows as + "<ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>container layers</ulink>". + An example of this type of layer is OpenEmbedded's + <ulink url='https://github.com/openembedded/meta-openembedded'><filename>meta-openembedded</filename></ulink> + layer. + The <filename>meta-openembedded</filename> layer contains + many <filename>meta-*</filename> layers. + In cases like this, you need to include the names of the actual + layers you want to work with, such as: + <literallayout class='monospaced'> + BBLAYERS ?= " \ + /usr/local/src/yocto/meta \ + /usr/local/src/yocto/meta-poky \ + /usr/local/src/yocto/meta-yocto-bsp \ + /usr/local/src/yocto/meta-mylayer \ + .../meta-openembedded/meta-oe \ + .../meta-openembedded/meta-perl \ + .../meta-openembedded/meta-networking \ + " + </literallayout> + and so on. + </para> + + <para> + For more information on layers, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section of the Yocto Project Development Tasks Manual. + </para> +</section> + +<section id='preparing-your-build-host-to-work-with-bsp-layers'> + <title>Preparing Your Build Host to Work With BSP Layers</title> + + <para> + This section describes how to get your build host ready + to work with BSP layers. + Once you have the host set up, you can create the layer + as described in the + "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</link>" + section. + <note> + For structural information on BSPs, see the + <link linkend='bsp-filelayout'>Example Filesystem Layout</link> + section. + </note> + <orderedlist> + <listitem><para> + <emphasis>Set Up the Build Environment:</emphasis> + Be sure you are set up to use BitBake in a shell. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>" + section in the Yocto Project Development Tasks Manual for information + on how to get a build host ready that is either a native + Linux machine or a machine that uses CROPS. + </para></listitem> + <listitem><para> + <emphasis>Clone the <filename>poky</filename> Repository:</emphasis> + You need to have a local copy of the Yocto Project + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + (i.e. a local <filename>poky</filename> repository). + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>" + and possibly the + "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>" + or + "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>" + sections all in the Yocto Project Development Tasks Manual for + information on how to clone the <filename>poky</filename> + repository and check out the appropriate branch for your work. + </para></listitem> + <listitem><para> + <emphasis>Determine the BSP Layer You Want:</emphasis> + The Yocto Project supports many BSPs, which are maintained in + their own layers or in layers designed to contain several + BSPs. + To get an idea of machine support through BSP layers, you can + look at the + <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink> + for the release. + </para></listitem> + <listitem><para> + <emphasis>Optionally Clone the + <filename>meta-intel</filename> BSP Layer:</emphasis> + If your hardware is based on current Intel CPUs and devices, + you can leverage this BSP layer. + For details on the <filename>meta-intel</filename> BSP layer, + see the layer's + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink> + file. + <orderedlist> + <listitem><para> + <emphasis>Navigate to Your Source Directory:</emphasis> + Typically, you set up the + <filename>meta-intel</filename> Git repository + inside the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>poky</filename>). + <literallayout class='monospaced'> + $ cd /home/<replaceable>you</replaceable>/poky + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Clone the Layer:</emphasis> + <literallayout class='monospaced'> + $ git clone git://git.yoctoproject.org/meta-intel.git + Cloning into 'meta-intel'... + remote: Counting objects: 15585, done. + remote: Compressing objects: 100% (5056/5056), done. + remote: Total 15585 (delta 9123), reused 15329 (delta 8867) + Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done. + Resolving deltas: 100% (9123/9123), done. + Checking connectivity... done. + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Check Out the Proper Branch:</emphasis> + The branch you check out for + <filename>meta-intel</filename> must match the same + branch you are using for the Yocto Project release + (e.g. &DISTRO_NAME_NO_CAP;): + <literallayout class='monospaced'> + $ cd meta-intel + $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP; + Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin. + Switched to a new branch '&DISTRO_NAME_NO_CAP;' + </literallayout> + <note> + To see the available branch names in a cloned repository, + use the <filename>git branch -al</filename> command. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>" + section in the Yocto Project Development Tasks + Manual for more information. + </note> + </para></listitem> + </orderedlist> + </para></listitem> + <listitem><para> + <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis> + If your hardware can be more closely leveraged to an + existing BSP not within the <filename>meta-intel</filename> + BSP layer, you can clone that BSP layer.</para> + + <para>The process is identical to the process used for the + <filename>meta-intel</filename> layer except for the layer's + name. + For example, if you determine that your hardware most + closely matches the <filename>meta-raspberrypi</filename>, + clone that layer: + <literallayout class='monospaced'> + $ git clone git://git.yoctoproject.org/meta-raspberrypi + Cloning into 'meta-raspberrypi'... + remote: Counting objects: 4743, done. + remote: Compressing objects: 100% (2185/2185), done. + remote: Total 4743 (delta 2447), reused 4496 (delta 2258) + Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done. + Resolving deltas: 100% (2447/2447), done. + Checking connectivity... done. + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Initialize the Build Environment:</emphasis> + While in the root directory of the Source Directory (i.e. + <filename>poky</filename>), run the + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> + environment setup script to define the OpenEmbedded + build environment on your build host. + <literallayout class='monospaced'> + $ source &OE_INIT_FILE; + </literallayout> + Among other things, the script creates the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, + which is <filename>build</filename> in this case + and is located in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. + After the script runs, your current working directory + is set to the <filename>build</filename> directory. + </para></listitem> + </orderedlist> + </para> +</section> + +<section id="bsp-filelayout"> + <title>Example Filesystem Layout</title> + + <para> + Defining a common BSP directory structure allows + end-users to understand and become familiar with + that standard. + A common format also encourages standardization + of software support for hardware. + </para> + + <para> + The proposed form described in this section does + have elements that are specific to the OpenEmbedded + build system. + It is intended that developers can use this structure + with other build systems besides the OpenEmbedded build + system. + It is also intended that it will be be simple to extract + information and convert it to other formats if required. + The OpenEmbedded build system, through its standard + <ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>layers mechanism</ulink>, + can directly accept the format described as a layer. + The BSP layer captures all the hardware-specific details + in one place using a standard format, which is useful + for any person wishing to use the hardware platform + regardless of the build system they are using. + </para> + + <para> + The BSP specification does not include a build system + or other tools - the specification is concerned with + the hardware-specific components only. + At the end-distribution point, you can ship the BSP + layer combined with a build system and other tools. + Realize that it is important to maintain the distinction + that the BSP layer, a build system, and tools are + separate components that could be combined in + certain end products. + </para> + + <para> + Before looking at the recommended form for the directory structure + inside a BSP layer, you should be aware that some + requirements do exist in order for a BSP layer to + be considered <firstterm>compliant</firstterm> with the Yocto Project. + For that list of requirements, see the + "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>" + section. + </para> + + <para> + Below is the typical directory structure for a BSP layer. + While this basic form represents the standard, + realize that the actual layout for individual + BSPs could differ. + <literallayout class='monospaced'> + meta-<replaceable>bsp_root_name</replaceable>/ + meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable> + meta-<replaceable>bsp_root_name</replaceable>/README + meta-<replaceable>bsp_root_name</replaceable>/README.sources + meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable> + meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf + meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf + meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/* + meta-<replaceable>bsp_root_name</replaceable>/recipes-core/* + meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/* + meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend + </literallayout> + </para> + + <para> + Below is an example of the Raspberry Pi BSP + layer that is available from the + <ulink url='&YOCTO_GIT_URL;'>Source Respositories</ulink>: + <literallayout class='monospaced'> + meta-raspberrypi/COPYING.MIT + meta-raspberrypi/README.md + meta-raspberrypi/classes + meta-raspberrypi/classes/sdcard_image-rpi.bbclass + meta-raspberrypi/conf/ + meta-raspberrypi/conf/layer.conf + meta-raspberrypi/conf/machine/ + meta-raspberrypi/conf/machine/raspberrypi-cm.conf + meta-raspberrypi/conf/machine/raspberrypi-cm3.conf + meta-raspberrypi/conf/machine/raspberrypi.conf + meta-raspberrypi/conf/machine/raspberrypi0-wifi.conf + meta-raspberrypi/conf/machine/raspberrypi0.conf + meta-raspberrypi/conf/machine/raspberrypi2.conf + meta-raspberrypi/conf/machine/raspberrypi3-64.conf + meta-raspberrypi/conf/machine/raspberrypi3.conf + meta-raspberrypi/conf/machine/include + meta-raspberrypi/conf/machine/include/rpi-base.inc + meta-raspberrypi/conf/machine/include/rpi-default-providers.inc + meta-raspberrypi/conf/machine/include/rpi-default-settings.inc + meta-raspberrypi/conf/machine/include/rpi-default-versions.inc + meta-raspberrypi/conf/machine/include/tune-arm1176jzf-s.inc + meta-raspberrypi/docs + meta-raspberrypi/docs/Makefile + meta-raspberrypi/docs/conf.py + meta-raspberrypi/docs/contributing.md + meta-raspberrypi/docs/extra-apps.md + meta-raspberrypi/docs/extra-build-config.md + meta-raspberrypi/docs/index.rst + meta-raspberrypi/docs/layer-contents.md + meta-raspberrypi/docs/readme.md + meta-raspberrypi/files + meta-raspberrypi/files/custom-licenses + meta-raspberrypi/files/custom-licenses/Broadcom + meta-raspberrypi/recipes-bsp + meta-raspberrypi/recipes-bsp/bootfiles + meta-raspberrypi/recipes-bsp/bootfiles/bcm2835-bootfiles.bb + meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb + meta-raspberrypi/recipes-bsp/common + meta-raspberrypi/recipes-bsp/common/firmware.inc + meta-raspberrypi/recipes-bsp/formfactor + meta-raspberrypi/recipes-bsp/formfactor/formfactor + meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi + meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi/machconfig + meta-raspberrypi/recipes-bsp/formfactor/formfactor_0.0.bbappend + meta-raspberrypi/recipes-bsp/rpi-u-boot-src + meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files + meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files/boot.cmd.in + meta-raspberrypi/recipes-bsp/rpi-u-boot-src/rpi-u-boot-scr.bb + meta-raspberrypi/recipes-bsp/u-boot + meta-raspberrypi/recipes-bsp/u-boot/u-boot + meta-raspberrypi/recipes-bsp/u-boot/u-boot/*.patch + meta-raspberrypi/recipes-bsp/u-boot/u-boot_%.bbappend + meta-raspberrypi/recipes-connectivity + meta-raspberrypi/recipes-connectivity/bluez5 + meta-raspberrypi/recipes-connectivity/bluez5/bluez5 + meta-raspberrypi/recipes-connectivity/bluez5/bluez5/*.patch + meta-raspberrypi/recipes-connectivity/bluez5/bluez5/BCM43430A1.hcd + meta-raspberrypi/recipes-connectivity/bluez5/bluez5brcm43438.service + meta-raspberrypi/recipes-connectivity/bluez5/bluez5_%.bbappend + meta-raspberrypi/recipes-core + meta-raspberrypi/recipes-core/images + meta-raspberrypi/recipes-core/images/rpi-basic-image.bb + meta-raspberrypi/recipes-core/images/rpi-hwup-image.bb + meta-raspberrypi/recipes-core/images/rpi-test-image.bb + meta-raspberrypi/recipes-core/packagegroups + meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb + meta-raspberrypi/recipes-core/psplash + meta-raspberrypi/recipes-core/psplash/files + meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h + meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend + meta-raspberrypi/recipes-core/udev + meta-raspberrypi/recipes-core/udev/udev-rules-rpi + meta-raspberrypi/recipes-core/udev/udev-rules-rpi/99-com.rules + meta-raspberrypi/recipes-core/udev/udev-rules-rpi.bb + meta-raspberrypi/recipes-devtools + meta-raspberrypi/recipes-devtools/bcm2835 + meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.52.bb + meta-raspberrypi/recipes-devtools/pi-blaster + meta-raspberrypi/recipes-devtools/pi-blaster/files + meta-raspberrypi/recipes-devtools/pi-blaster/files/*.patch + meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb + meta-raspberrypi/recipes-devtools/python + meta-raspberrypi/recipes-devtools/python/python-rtimu + meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch + meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb + meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.2.0.bb + meta-raspberrypi/recipes-devtools/python/rpi-gpio + meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch + meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.3.bb + meta-raspberrypi/recipes-devtools/python/rpio + meta-raspberrypi/recipes-devtools/python/rpio/*.patch + meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb + meta-raspberrypi/recipes-devtools/wiringPi + meta-raspberrypi/recipes-devtools/wiringPi/files + meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch + meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb + meta-raspberrypi/recipes-graphics + meta-raspberrypi/recipes-graphics/eglinfo + meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend + meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend + meta-raspberrypi/recipes-graphics/mesa + meta-raspberrypi/recipes-graphics/mesa/mesa-gl_%.bbappend + meta-raspberrypi/recipes-graphics/mesa/mesa_%.bbappend + meta-raspberrypi/recipes-graphics/userland + meta-raspberrypi/recipes-graphics/userland/userland + meta-raspberrypi/recipes-graphics/userland/userland/*.patch + meta-raspberrypi/recipes-graphics/userland/userland_git.bb + meta-raspberrypi/recipes-graphics/vc-graphics + meta-raspberrypi/recipes-graphics/vc-graphics/files + meta-raspberrypi/recipes-graphics/vc-graphics/files/egl.pc + meta-raspberrypi/recipes-graphics/vc-graphics/files/vchiq.sh + meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics-hardfp.bb + meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.bb + meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc + meta-raspberrypi/recipes-graphics/wayland + meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend + meta-raspberrypi/recipes-graphics/xorg-xserver + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/98-pitft.conf + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-calibration.conf + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xorg_%.bbappend + meta-raspberrypi/recipes-kernel + meta-raspberrypi/recipes-kernel/linux-firmware + meta-raspberrypi/recipes-kernel/linux-firmware/files + meta-raspberrypi/recipes-kernel/linux-firmware/files/brcmfmac43430-sdio.bin + meta-raspberrypi/recipes-kernel/linux-firmware/files/brcfmac43430-sdio.txt + meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_%.bbappend + meta-raspberrypi/recipes-kernel/linux + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-dev.bb + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.14.bb + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.9.bb + meta-raspberrypi/recipes-multimedia + meta-raspberrypi/recipes-multimedia/gstreamer + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12 + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12/*.patch + meta-raspberrypi/recipes-multimedia/omxplayer + meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer + meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch + meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb + meta-raspberrypi/recipes-multimedia/x264 + meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend + meta-raspberrypi/wic + meta-raspberrypi/wic/sdimage-raspberrypi.wks + </literallayout> + </para> + + <para> + The following sections describe each part of the proposed + BSP format. + </para> + + <section id="bsp-filelayout-license"> + <title>License Files</title> + + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> + meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable> + </literallayout> + </para> + + <para> + These optional files satisfy licensing requirements + for the BSP. + The type or types of files here can vary depending + on the licensing requirements. + For example, in the Raspberry Pi BSP, all licensing + requirements are handled with the + <filename>COPYING.MIT</filename> file. + </para> + + <para> + Licensing files can be MIT, BSD, GPLv*, and so forth. + These files are recommended for the BSP but are + optional and totally up to the BSP developer. + For information on how to maintain license + compliance, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>" + section in the Yocto Project Development Tasks + Manual. + </para> + </section> + + <section id="bsp-filelayout-readme"> + <title>README File</title> + + <para> + You can find this file in the BSP Layer at: + <literallayout class='monospaced'> + meta-<replaceable>bsp_root_name</replaceable>/README + </literallayout> + </para> + + <para> + This file provides information on how to boot the live + images that are optionally included in the + <filename>binary/</filename> directory. + The <filename>README</filename> file also provides + information needed for building the image. + </para> + + <para> + At a minimum, the <filename>README</filename> file must + contain a list of dependencies, such as the names of + any other layers on which the BSP depends and the name of + the BSP maintainer with his or her contact information. + </para> + </section> + + <section id="bsp-filelayout-readme-sources"> + <title>README.sources File</title> + + <para> + You can find this file in the BSP Layer at: + <literallayout class='monospaced'> + meta-<replaceable>bsp_root_name</replaceable>/README.sources + </literallayout> + </para> + + <para> + This file provides information on where to locate the BSP + source files used to build the images (if any) that + reside in + <filename>meta-<replaceable>bsp_root_name</replaceable>/binary</filename>. + Images in the <filename>binary</filename> would be images + released with the BSP. + The information in the <filename>README.sources</filename> + file also helps you find the + <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> + used to generate the images that ship with the BSP. + <note> + If the BSP's <filename>binary</filename> directory is + missing or the directory has no images, an existing + <filename>README.sources</filename> file is + meaningless and usually does not exist. + </note> + </para> + </section> + + <section id="bsp-filelayout-binary"> + <title>Pre-built User Binaries</title> + + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> + meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable> + </literallayout> + </para> + + <para> + This optional area contains useful pre-built kernels + and user-space filesystem images released with the + BSP that are appropriate to the target system. + This directory typically contains graphical (e.g. Sato) + and minimal live images when the BSP tarball has been + created and made available in the + <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> + website. + You can use these kernels and images to get a system + running and quickly get started on development tasks. + </para> + + <para> + The exact types of binaries present are highly + hardware-dependent. + The + <link linkend='bsp-filelayout-readme'><filename>README</filename></link> + file should be present in the BSP Layer and it + explains how to use the images with the target hardware. + Additionally, the + <link linkend='bsp-filelayout-readme-sources'><filename>README.sources</filename></link> + file should be present to locate the sources used to + build the images and provide information on the + Metadata. + </para> + </section> + + <section id='bsp-filelayout-layer'> + <title>Layer Configuration File</title> + + <para> + You can find this file in the BSP Layer at: + <literallayout class='monospaced'> + meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf + </literallayout> + </para> + + <para> + The <filename>conf/layer.conf</filename> file + identifies the file structure as a layer, + identifies the contents of the layer, and + contains information about how the build system should + use it. + Generally, a standard boilerplate file such as the + following works. + In the following example, you would replace + <replaceable>bsp</replaceable> with the actual + name of the BSP (i.e. + <replaceable>bsp_root_name</replaceable> from the example + template). + </para> + + <para> + <literallayout class='monospaced'> + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have a recipes directory, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "<replaceable>bsp</replaceable>" + BBFILE_PATTERN_<replaceable>bsp</replaceable> = "^${LAYERDIR}/" + BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6" + + LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel" + </literallayout> + </para> + + <para> + To illustrate the string substitutions, here are + the corresponding statements from the Raspberry + Pi <filename>conf/layer.conf</filename> file: + <literallayout class='monospaced'> + # We have a conf and classes directory, append to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have a recipes directory containing .bb and .bbappend files, add to BBFILES + BBFILES += "${LAYERDIR}/recipes*/*/*.bb \ + ${LAYERDIR}/recipes*/*/*.bbappend" + + BBFILE_COLLECTIONS += "raspberrypi" + BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/" + BBFILE_PRIORITY_raspberrypi = "9" + + # Additional license directories. + LICENSE_PATH += "${LAYERDIR}/files/custom-licenses" + . + . + . + </literallayout> + </para> + + <para> + This file simply makes + <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> + aware of the recipes and configuration directories. + The file must exist so that the OpenEmbedded build system + can recognize the BSP. + </para> + </section> + + <section id="bsp-filelayout-machine"> + <title>Hardware Configuration Options</title> + + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> + meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf + </literallayout> + </para> + + <para> + The machine files bind together all the information + contained elsewhere in the BSP into a format that + the build system can understand. + Each BSP Layer requires at least one machine file. + If the BSP supports multiple machines, multiple + machine configuration files can exist. + These filenames correspond to the values to which + users have set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable. + </para> + + <para> + These files define things such as the kernel package + to use + (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> + of + <ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>virtual/kernel</ulink>), + the hardware drivers to include in different types + of images, any special software components that are + needed, any bootloader information, and also any + special image format requirements. + </para> + + <para> + This configuration file could also include a hardware + "tuning" file that is commonly used to define the + package architecture and specify optimization flags, + which are carefully chosen to give best performance + on a given processor. + </para> + + <para> + Tuning files are found in the + <filename>meta/conf/machine/include</filename> + directory within the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. + For example, many <filename>tune-*</filename> files + (e.g. <filename>tune-arm1136jf-s.inc</filename>, + <filename>tune-1586-nlp.inc</filename>, and so forth) + reside in the + <filename>poky/meta/conf/machine/include</filename> + directory. + </para> + + <para> + To use an include file, you simply include them in the + machine configuration file. + For example, the Raspberry Pi BSP + <filename>raspberrypi3.conf</filename> contains the + following statement: + <literallayout class='monospaced'> + include conf/machine/include/rpi-base.inc + </literallayout> + </para> + </section> + + <section id='bsp-filelayout-misc-recipes'> + <title>Miscellaneous BSP-Specific Recipe Files</title> + + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> + meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/* + </literallayout> + </para> + + <para> + This optional directory contains miscellaneous recipe + files for the BSP. + Most notably would be the formfactor files. + For example, in the Raspberry Pi BSP, there is the + <filename>formfactor_0.0.bbappend</filename> file, + which is an append file used to augment the recipe + that starts the build. + Furthermore, there are machine-specific settings used + during the build that are defined by the + <filename>machconfig</filename> file further down in + the directory. + Here is the <filename>machconfig</filename> file for + the Raspberry Pi BSP: + <literallayout class='monospaced'> + HAVE_TOUCHSCREEN=0 + HAVE_KEYBOARD=1 + + DISPLAY_CAN_ROTATE=0 + DISPLAY_ORIENTATION=0 + DISPLAY_DPI=133 + </literallayout> + </para> + + <note><para> + If a BSP does not have a formfactor entry, defaults + are established according to the formfactor + configuration file that is installed by the main + formfactor recipe + <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>, + which is found in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. + </para></note> + </section> + + <section id='bsp-filelayout-recipes-graphics'> + <title>Display Support Files</title> + + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> + meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/* + </literallayout> + </para> + + <para> + This optional directory contains recipes for the + BSP if it has special requirements for graphics + support. + All files that are needed for the BSP to support + a display are kept here. + </para> + </section> + + <section id='bsp-filelayout-kernel'> + <title>Linux Kernel Configuration</title> + + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> + meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux*.bbappend + meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/*.bb + </literallayout> + </para> + + <para> + Append files (<filename>*.bbappend</filename>) modify + the main kernel recipe being used to build the image. + The <filename>*.bb</filename> files would be a + developer-supplied kernel recipe. + This area of the BSP hierarchy can contain both these + types of files although, in practice, it is likely that + you would have one or the other. + </para> + + <para> + For your BSP, you typically want to use an existing Yocto + Project kernel recipe found in the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + at <filename>meta/recipes-kernel/linux</filename>. + You can append machine-specific changes to the + kernel recipe by using a similarly named append + file, which is located in the BSP Layer for your + target device (e.g. the + <filename>meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux</filename> directory). + </para> + + <para> + Suppose you are using the + <filename>linux-yocto_4.4.bb</filename> recipe to + build the kernel. + In other words, you have selected the kernel in your + <replaceable>bsp_root_name</replaceable><filename>.conf</filename> + file by adding + <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink> + statements as follows: + <literallayout class='monospaced'> + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "4.4%" + </literallayout> + <note> + When the preferred provider is assumed by + default, the + <filename>PREFERRED_PROVIDER</filename> + statement does not appear in the + <replaceable>bsp_root_name</replaceable><filename>.conf</filename> file. + </note> + You would use the + <filename>linux-yocto_4.4.bbappend</filename> + file to append specific BSP settings to the kernel, + thus configuring the kernel for your particular BSP. + </para> + + <para> + You can find more information on what your append file + should contain in the + "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-the-append-file'>Creating the Append File</ulink>" + section in the Yocto Project Linux Kernel Development + Manual. + </para> + + <para> + An alternate scenario is when you create your own + kernel recipe for the BSP. + A good example of this is the Raspberry Pi BSP. + If you examine the + <filename>recipes-kernel/linux</filename> directory + you see the following: + <literallayout class='monospaced'> + linux-raspberrypi-dev.bb + linux-raspberrypi.inc + linux-raspberrypi_4.14.bb + linux-raspberrypi_4.9.bb + </literallayout> + The directory contains three kernel recipes and a + common include file. + </para> + </section> +</section> + +<section id='developing-a-board-support-package-bsp'> + <title>Developing a Board Support Package (BSP)</title> + + <para> + This section describes the high-level procedure you can + follow to create a BSP. + Although not required for BSP creation, the + <filename>meta-intel</filename> repository, which + contains many BSPs supported by the Yocto Project, + is part of the example. + </para> + + <para> + For an example that shows how to create a new + layer using the tools, see the + "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</link>" + section. + </para> + + <para> + The following illustration and list summarize the BSP + creation general workflow. + </para> + + <para> + <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" /> + </para> + + <para> + <orderedlist> + <listitem><para> + <emphasis>Set up Your Host Development System + to Support Development Using the Yocto + Project</emphasis>: + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>" + section in the Yocto Project Development Tasks + Manual for options on how to get a system ready + to use the Yocto Project. + </para></listitem> + <listitem><para> + <emphasis>Establish the + <filename>meta-intel</filename> + Repository on Your System:</emphasis> + Having local copies of these supported BSP layers + on your system gives you access to layers you + might be able to leverage when creating your BSP. + For information on how to get these files, see the + "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>" + section. + </para></listitem> + <listitem><para> + <emphasis>Create Your Own BSP Layer Using the + <filename>bitbake-layers</filename> + Script:</emphasis> + Layers are ideal for isolating and storing work + for a given piece of hardware. + A layer is really just a location or area in which you + place the recipes and configurations for your BSP. + In fact, a BSP is, in itself, a special type of layer. + The simplest way to create a new BSP layer that is + compliant with the Yocto Project is to use the + <filename>bitbake-layers</filename> script. + For information about that script, see the + "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</link>" + section.</para> + + <para>Another example that illustrates a layer + is an application. + Suppose you are creating an application that has + library or other dependencies in order for it to + compile and run. + The layer, in this case, would be where all the + recipes that define those dependencies are kept. + The key point for a layer is that it is an + isolated area that contains all the relevant + information for the project that the + OpenEmbedded build system knows about. + For more information on layers, see the + "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>" + section in the Yocto Project Overview and Concepts + Manual. + You can also reference the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section in the Yocto Project Development Tasks + Manual. + For more information on BSP layers, see the + "<link linkend='bsp-layers'>BSP Layers</link>" + section. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + Five hardware reference BSPs exist + that are part of the Yocto Project release + and are located in the + <filename>poky/meta-yocto-bsp</filename> BSP + layer: + <itemizedlist> + <listitem><para> + Texas Instruments Beaglebone + (<filename>beaglebone-yocto</filename>) + </para></listitem> + <listitem><para> + Ubiquiti Networks EdgeRouter Lite + (<filename>edgerouter</filename>) + </para></listitem> + <listitem><para> + Two general IA platforms + (<filename>genericx86</filename> and + <filename>genericx86-64</filename>) + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + Three core Intel BSPs exist as part of + the Yocto Project release in the + <filename>meta-intel</filename> layer: + <itemizedlist> + <listitem><para> + <filename>intel-core2-32</filename>, + which is a BSP optimized for the Core2 + family of CPUs as well as all CPUs + prior to the Silvermont core. + </para></listitem> + <listitem><para> + <filename>intel-corei7-64</filename>, + which is a BSP optimized for Nehalem + and later Core and Xeon CPUs as well + as Silvermont and later Atom CPUs, + such as the Baytrail SoCs. + </para></listitem> + <listitem><para> + <filename>intel-quark</filename>, + which is a BSP optimized for the + Intel Galileo gen1 & gen2 + development boards. + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> + </note></para> + + <para>When you set up a layer for a new BSP, + you should follow a standard layout. + This layout is described in the + "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>" + section. + In the standard layout, notice the suggested + structure for recipes and configuration + information. + You can see the standard layout for a BSP + by examining any supported BSP found in the + <filename>meta-intel</filename> layer inside + the Source Directory. + </para></listitem> + <listitem><para> + <emphasis>Make Configuration Changes to Your New + BSP Layer:</emphasis> + The standard BSP layer structure organizes the + files you need to edit in + <filename>conf</filename> and several + <filename>recipes-*</filename> directories + within the BSP layer. + Configuration changes identify where your new + layer is on the local system and identifies the + kernel you are going to use. + When you run the + <filename>bitbake-layers</filename> script, + you are able to interactively configure many + things for the BSP (e.g. keyboard, touchscreen, + and so forth). + </para></listitem> + <listitem><para> + <emphasis>Make Recipe Changes to Your New BSP + Layer:</emphasis> + Recipe changes include altering recipes + (<filename>*.bb</filename> files), removing + recipes you do not use, and adding new recipes + or append files (<filename>.bbappend</filename>) + that support your hardware. + </para></listitem> + <listitem><para> + <emphasis>Prepare for the Build:</emphasis> + Once you have made all the changes to your BSP + layer, there remains a few things you need to + do for the OpenEmbedded build system in order + for it to create your image. + You need to get the build environment ready by + sourcing an environment setup script + (i.e. <filename>oe-init-build-env</filename>) + and you need to be sure two key configuration + files are configured appropriately: the + <filename>conf/local.conf</filename> and the + <filename>conf/bblayers.conf</filename> file. + You must make the OpenEmbedded build system aware + of your new layer. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>" + section in the Yocto Project Development Tasks Manual + for information on how to let the build system + know about your new layer. + </para></listitem> + <listitem><para> + <emphasis>Build the Image:</emphasis> + The OpenEmbedded build system uses the BitBake tool + to build images based on the type of image you want to + create. + You can find more information about BitBake in the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. + </para> + + <para>The build process supports several types of + images to satisfy different needs. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" + chapter in the Yocto Project Reference Manual for + information on supported images. + </para></listitem> + </orderedlist> + </para> +</section> + +<section id='requirements-and-recommendations-for-released-bsps'> + <title>Requirements and Recommendations for Released BSPs</title> + + <para> + Certain requirements exist for a released BSP to be + considered compliant with the Yocto Project. + Additionally, recommendations also exist. + This section describes the requirements and + recommendations for released BSPs. + </para> + + <section id='released-bsp-requirements'> + <title>Released BSP Requirements</title> + + <para> + Before looking at BSP requirements, you should consider + the following: + <itemizedlist> + <listitem><para> + The requirements here assume the BSP layer + is a well-formed, "legal" layer that can be + added to the Yocto Project. + For guidelines on creating a layer that meets + these base requirements, see the + "<link linkend='bsp-layers'>BSP Layers</link>" + section in this manual and the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers"</ulink>" + section in the Yocto Project Development Tasks + Manual. + </para></listitem> + <listitem><para> + The requirements in this section apply + regardless of how you package a BSP. + You should consult the packaging and distribution + guidelines for your specific release process. + For an example of packaging and distribution + requirements, see the + "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>" + wiki page. + </para></listitem> + <listitem><para> + The requirements for the BSP as it is made + available to a developer are completely + independent of the released form of the BSP. + For example, the BSP Metadata can be contained + within a Git repository and could have a directory + structure completely different from what appears + in the officially released BSP layer. + </para></listitem> + <listitem><para> + It is not required that specific packages or + package modifications exist in the BSP layer, + beyond the requirements for general + compliance with the Yocto Project. + For example, no requirement exists dictating + that a specific kernel or kernel version be + used in a given BSP. + </para></listitem> + </itemizedlist> + </para> + + <para> + Following are the requirements for a released BSP + that conform to the Yocto Project: + <itemizedlist> + <listitem><para> + <emphasis>Layer Name:</emphasis> + The BSP must have a layer name that follows + the Yocto Project standards. + For information on BSP layer names, see the + "<link linkend='bsp-layers'>BSP Layers</link>" section. + </para></listitem> + <listitem><para> + <emphasis>File System Layout:</emphasis> + When possible, use the same directory names + in your BSP layer as listed in the + <filename>recipes.txt</filename> file, which + is found in <filename>poky/meta</filename> + directory of the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + or in the OpenEmbedded-Core Layer + (<filename>openembedded-core</filename>) at + <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>. + </para> + + <para>You should place recipes + (<filename>*.bb</filename> files) and recipe + modifications (<filename>*.bbappend</filename> + files) into <filename>recipes-*</filename> + subdirectories by functional area as outlined + in <filename>recipes.txt</filename>. + If you cannot find a category in + <filename>recipes.txt</filename> to fit a + particular recipe, you can make up your own + <filename>recipes-*</filename> subdirectory. + </para> + + <para>Within any particular + <filename>recipes-*</filename> category, the + layout should match what is found in the + OpenEmbedded-Core Git repository + (<filename>openembedded-core</filename>) + or the Source Directory (<filename>poky</filename>). + In other words, make sure you place related + files in appropriately-related + <filename>recipes-*</filename> subdirectories + specific to the recipe's function, or within + a subdirectory containing a set of closely-related + recipes. + The recipes themselves should follow the general + guidelines for recipes used in the Yocto Project + found in the + "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>". + </para></listitem> + <listitem><para> + <emphasis>License File:</emphasis> + You must include a license file in the + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> + directory. + This license covers the BSP Metadata as a whole. + You must specify which license to use since no + default license exists when one is not specified. + See the + <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink> + file for the Raspberry Pi BSP in the + <filename>meta-raspberrypi</filename> BSP layer + as an example. + </para></listitem> + <listitem><para> + <emphasis>README File:</emphasis> + You must include a <filename>README</filename> + file in the + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> + directory. + See the + <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README.md'><filename>README.md</filename></ulink> + file for the Raspberry Pi BSP in the + <filename>meta-raspberrypi</filename> BSP layer + as an example.</para> + + <para>At a minimum, the <filename>README</filename> + file should contain the following: + <itemizedlist> + <listitem><para> + A brief description of the target hardware. + </para></listitem> + <listitem><para> + A list of all the dependencies of the BSP. + These dependencies are typically a list + of required layers needed to build the + BSP. + However, the dependencies should also + contain information regarding any other + dependencies the BSP might have. + </para></listitem> + <listitem><para> + Any required special licensing information. + For example, this information includes + information on special variables needed + to satisfy a EULA, or instructions on + information needed to build or distribute + binaries built from the BSP Metadata. + </para></listitem> + <listitem><para> + The name and contact information for the + BSP layer maintainer. + This is the person to whom patches and + questions should be sent. + For information on how to find the right + person, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>" + section in the Yocto Project Development + Tasks Manual. + </para></listitem> + <listitem><para> + Instructions on how to build the BSP using + the BSP layer. + </para></listitem> + <listitem><para> + Instructions on how to boot the BSP build + from the BSP layer. + </para></listitem> + <listitem><para> + Instructions on how to boot the binary + images contained in the + <filename>binary</filename> directory, + if present. + </para></listitem> + <listitem><para> + Information on any known bugs or issues + that users should know about when either + building or booting the BSP binaries. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>README.sources File:</emphasis> + If you BSP contains binary images in the + <filename>binary</filename> directory, you must + include a <filename>README.sources</filename> + file in the + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> + directory. + This file specifies exactly where you can find + the sources used to generate the binary images. + </para></listitem> + <listitem><para> + <emphasis>Layer Configuration File:</emphasis> + You must include a + <filename>conf/layer.conf</filename> file in + the + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> + directory. + This file identifies the + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> + BSP layer as a layer to the build system. + </para></listitem> + <listitem><para> + <emphasis>Machine Configuration File:</emphasis> + You must include one or more + <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename> + files in the + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> + directory. + These configuration files define machine targets + that can be built using the BSP layer. + Multiple machine configuration files define + variations of machine configurations that the + BSP supports. + If a BSP supports multiple machine variations, + you need to adequately describe each variation + in the BSP <filename>README</filename> file. + Do not use multiple machine configuration files + to describe disparate hardware. + If you do have very different targets, you should + create separate BSP layers for each target. + <note> + It is completely possible for a developer to + structure the working repository as a + conglomeration of unrelated BSP files, and to + possibly generate BSPs targeted for release + from that directory using scripts or some + other mechanism + (e.g. <filename>meta-yocto-bsp</filename> layer). + Such considerations are outside the scope of + this document. + </note> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='released-bsp-recommendations'> + <title>Released BSP Recommendations</title> + + <para> + Following are recommendations for released BSPs that + conform to the Yocto Project: + <itemizedlist> + <listitem><para> + <emphasis>Bootable Images:</emphasis> + Released BSPs can contain one or more bootable + images. + Including bootable images allows users to easily + try out the BSP using their own hardware.</para> + + <para>In some cases, it might not be convenient + to include a bootable image. + If so, you might want to make two versions of the + BSP available: one that contains binary images, and + one that does not. + The version that does not contain bootable images + avoids unnecessary download times for users not + interested in the images.</para> + + <para>If you need to distribute a BSP and include + bootable images or build kernel and filesystems + meant to allow users to boot the BSP for evaluation + purposes, you should put the images and artifacts + within a + <filename>binary/</filename> subdirectory located + in the + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> + directory. + <note> + If you do include a bootable image as part + of the BSP and the image was built by software + covered by the GPL or other open source licenses, + it is your responsibility to understand + and meet all licensing requirements, which could + include distribution of source files. + </note> + </para></listitem> + <listitem><para> + <emphasis>Use a Yocto Linux Kernel:</emphasis> + Kernel recipes in the BSP should be based on a + Yocto Linux kernel. + Basing your recipes on these kernels reduces + the costs for maintaining the BSP and increases + its scalability. + See the <filename>Yocto Linux Kernel</filename> + category in the + <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> + for these kernels. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='customizing-a-recipe-for-a-bsp'> + <title>Customizing a Recipe for a BSP</title> + + <para> + If you plan on customizing a recipe for a particular BSP, + you need to do the following: + <itemizedlist> + <listitem><para> + Create a <filename>*.bbappend</filename> file for + the modified recipe. + For information on using append files, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" + section in the Yocto Project Development Tasks + Manual. + </para></listitem> + <listitem><para> + Ensure your directory structure in the BSP layer + that supports your machine is such that the + OpenEmbedded build system can find it. + See the example later in this section for more + information. + </para></listitem> + <listitem><para> + Put the append file in a directory whose name matches + the machine's name and is located in an appropriate + sub-directory inside the BSP layer (i.e. + <filename>recipes-bsp</filename>, + <filename>recipes-graphics</filename>, + <filename>recipes-core</filename>, and so forth). + </para></listitem> + <listitem><para> + Place the BSP-specific files in the proper + directory inside the BSP layer. + How expansive the layer is affects where you must + place these files. + For example, if your layer supports several + different machine types, you need to be sure your + layer's directory structure includes hierarchy + that separates the files according to machine. + If your layer does not support multiple machines, + the layer would not have that additional hierarchy + and the files would obviously not be able to reside + in a machine-specific directory. + </para></listitem> + </itemizedlist> + </para> + + <para> + Following is a specific example to help you better understand + the process. + This example customizes customizes a recipe by adding a + BSP-specific configuration file named + <filename>interfaces</filename> to the + <filename>init-ifupdown_1.0.bb</filename> recipe for machine + "xyz" where the BSP layer also supports several other + machines: + <orderedlist> + <listitem><para> + Edit the + <filename>init-ifupdown_1.0.bbappend</filename> file + so that it contains the following: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + </literallayout> + The append file needs to be in the + <filename>meta-xyz/recipes-core/init-ifupdown</filename> + directory. + </para></listitem> + <listitem><para> + Create and place the new + <filename>interfaces</filename> configuration file in + the BSP's layer here: + <literallayout class='monospaced'> + meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces + </literallayout> + <note> + If the <filename>meta-xyz</filename> layer did + not support multiple machines, you would place + the <filename>interfaces</filename> configuration + file in the layer here: + <literallayout class='monospaced'> + meta-xyz/recipes-core/init-ifupdown/files/interfaces + </literallayout> + </note> + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + variable in the append files extends the search path + the build system uses to find files during the build. + Consequently, for this example you need to have the + <filename>files</filename> directory in the same + location as your append file. + </para></listitem> + </orderedlist> + </para> +</section> + +<section id='bsp-licensing-considerations'> + <title>BSP Licensing Considerations</title> + + <para> + In some cases, a BSP contains separately-licensed + Intellectual Property (IP) for a component or components. + For these cases, you are required to accept the terms + of a commercial or other type of license that requires + some kind of explicit End User License Agreement (EULA). + Once you accept the license, the OpenEmbedded build system + can then build and include the corresponding component + in the final BSP image. + If the BSP is available as a pre-built image, you can + download the image after agreeing to the license or EULA. + </para> + + <para> + You could find that some separately-licensed components + that are essential for normal operation of the system might + not have an unencumbered (or free) substitute. + Without these essential components, the system would be + non-functional. + Then again, you might find that other licensed components + that are simply 'good-to-have' or purely elective do have + an unencumbered, free replacement component that you can + use rather than agreeing to the separately-licensed + component. + Even for components essential to the system, you might + find an unencumbered component that is not identical but + will work as a less-capable version of the licensed version + in the BSP recipe. + </para> + + <para> + For cases where you can substitute a free component and + still maintain the system's functionality, the "DOWNLOADS" + selection from the "SOFTWARE" tab on the + <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink> + makes available de-featured BSPs that are completely free + of any IP encumbrances. + For these cases, you can use the substitution directly and + without any further licensing requirements. + If present, these fully de-featured BSPs are named + appropriately different as compared to the names of their + respective encumbered BSPs. + If available, these substitutions are your simplest and + most preferred options. + Obviously, use of these substitutions assumes the resulting + functionality meets system requirements. + <note> + If however, a non-encumbered version is unavailable or + it provides unsuitable functionality or quality, you can + use an encumbered version. + </note> + </para> + + <para> + A couple different methods exist within the OpenEmbedded + build system to satisfy the licensing requirements for an + encumbered BSP. + The following list describes them in order of preference: + <orderedlist> + <listitem><para> + <emphasis>Use the + <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink> + Variable to Define the Recipes that Have Commercial + or Other Types of Specially-Licensed Packages:</emphasis> + For each of those recipes, you can specify a + matching license string in a + <filename>local.conf</filename> variable named + <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>. + Specifying the matching license string signifies + that you agree to the license. + Thus, the build system can build the corresponding + recipe and include the component in the image. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>" + section in the Yocto Project Development Tasks + Manual for details on how to use these variables. + </para> + + <para>If you build as you normally would, without + specifying any recipes in the + <filename>LICENSE_FLAGS_WHITELIST</filename>, the + build stops and provides you with the list of recipes + that you have tried to include in the image that + need entries in the + <filename>LICENSE_FLAGS_WHITELIST</filename>. + Once you enter the appropriate license flags into + the whitelist, restart the build to continue where + it left off. + During the build, the prompt will not appear again + since you have satisfied the requirement.</para> + + <para>Once the appropriate license flags are on the + white list in the + <filename>LICENSE_FLAGS_WHITELIST</filename> variable, + you can build the encumbered image with no change + at all to the normal build process. + </para></listitem> + <listitem><para> + <emphasis>Get a Pre-Built Version of the BSP:</emphasis> + You can get this type of BSP by selecting the + "DOWNLOADS" item from the "SOFTWARE" tab on the + <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>. + You can download BSP tarballs that contain + proprietary components after agreeing to the + licensing requirements of each of the individually + encumbered packages as part of the download process. + Obtaining the BSP this way allows you to access an + encumbered image immediately after agreeing to the + click-through license agreements presented by the + website. + If you want to build the image yourself using + the recipes contained within the BSP tarball, + you will still need to create an appropriate + <filename>LICENSE_FLAGS_WHITELIST</filename> + to match the encumbered recipes in the BSP. + </para></listitem> + </orderedlist> + <note> + Pre-compiled images are bundled with a time-limited + kernel that runs for a predetermined amount of time + (10 days) before it forces the system to reboot. + This limitation is meant to discourage direct + redistribution of the image. + You must eventually rebuild the image if you want + to remove this restriction. + </note> + </para> +</section> + +<section id='creating-a-new-bsp-layer-using-the-bitbake-layers-script'> + <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title> + + <para> + The <filename>bitbake-layers create-layer</filename> script + automates creating a BSP layer. + What makes a layer a "BSP layer" is the presence of at least one machine + configuration file. + Additionally, a BSP layer usually has a kernel recipe + or an append file that leverages off an existing kernel recipe. + The primary requirement, however, is the machine configuration. + </para> + + <para> + Use these steps to create a BSP layer: + <itemizedlist> + <listitem><para> + <emphasis>Create a General Layer:</emphasis> + Use the <filename>bitbake-layers</filename> script with the + <filename>create-layer</filename> subcommand to create a + new general layer. + For instructions on how to create a general layer using the + <filename>bitbake-layers</filename> script, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>" + section in the Yocto Project Development Tasks Manual. + </para></listitem> + <listitem><para> + <emphasis>Create a Layer Configuration File:</emphasis> + Every layer needs a layer configuration file. + This configuration file establishes locations for the + layer's recipes, priorities for the layer, and so forth. + You can find examples of <filename>layer.conf</filename> + files in the Yocto Project + <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>. + To get examples of what you need in your configuration + file, locate a layer (e.g. "meta-ti") and examine the + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/layer.conf'></ulink> + file. + </para></listitem> + <listitem><para> + <emphasis>Create a Machine Configuration File:</emphasis> + Create a <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename> + file. + See + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf/machine'><filename>meta-yocto-bsp/conf/machine</filename></ulink> + for sample + <replaceable>bsp_root_name</replaceable><filename>.conf</filename> + files. + Other samples such as + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/machine'><filename>meta-ti</filename></ulink> + and + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/conf/machine'><filename>meta-freescale</filename></ulink> + exist from other vendors that have more specific machine + and tuning examples. + </para></listitem> + <listitem><para> + <emphasis>Create a Kernel Recipe:</emphasis> + Create a kernel recipe in <filename>recipes-kernel/linux</filename> + by either using a kernel append file or a new custom kernel + recipe file (e.g. <filename>yocto-linux_4.12.bb</filename>). + The BSP layers mentioned in the previous step also contain different + kernel examples. + See the + "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>" + section in the Yocto Project Linux Kernel Development Manual + for information on how to create a custom kernel. + </para></listitem> + </itemizedlist> + </para> + + <para> + The remainder of this section provides a description of + the Yocto Project reference BSP for Beaglebone, which + resides in the + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp'><filename>meta-yocto-bsp</filename></ulink> + layer. + </para> + + <section id='bsp-layer-configuration-example'> + <title>BSP Layer Configuration Example</title> + + <para> + The layer's <filename>conf</filename> directory + contains the <filename>layer.conf</filename> + configuration file. + In this example, the + <filename>conf/layer.conf</filename> is the + following: + <literallayout class='monospaced'> + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have recipes-* directories, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "yoctobsp" + BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" + BBFILE_PRIORITY_yoctobsp = "5" + LAYERVERSION_yoctobsp = "4" + LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;" + </literallayout> + The variables used in this file configure the + layer. + A good way to learn about layer configuration + files is to examine various files for BSP from + the + <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>. + </para> + + <para> + For a detailed description of this particular + layer configuration file, see + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-layer-config-file-description'>step 3</ulink> + in the discussion that describes how to create + layers in the Yocto Project Development Tasks Manual. + </para> + </section> + + <section id='bsp-machine-configuration-example'> + <title>BSP Machine Configuration Example</title> + + <para> + As mentioned earlier in this section, the existence + of a machine configuration file is what makes a + layer a BSP layer as compared to a general or + kernel layer. + </para> + + <para> + One or more machine configuration files exist in the + <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename> + directory of the layer: + <literallayout class='monospaced'> + <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine1</replaceable><filename>.conf</filename> + <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine2</replaceable><filename>.conf</filename> + <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine3</replaceable><filename>.conf</filename> + ... more ... + </literallayout> + For example, the machine configuration file for the + <ulink url='http://beagleboard.org/bone'>BeagleBone and BeagleBone Black development boards</ulink> + is located in the layer + <filename>poky/meta-yocto-bsp/conf/machine</filename> + and is named <filename>beaglebone-yocto.conf</filename>: + <literallayout class='monospaced'> + #@TYPE: Machine + #@NAME: Beaglebone-yocto machine + #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards + + PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg" + XSERVER ?= "xserver-xorg \ + xf86-video-modesetting \ + " + + MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree" + + EXTRA_IMAGEDEPENDS += "u-boot" + + DEFAULTTUNE ?= "cortexa8hf-neon" + include conf/machine/include/tune-cortexa8.inc + + IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap" + EXTRA_IMAGECMD_jffs2 = "-lnp " + WKS_FILE ?= "beaglebone-yocto.wks" + IMAGE_INSTALL_append = " kernel-devicetree kernel-image-zimage" + do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot" + + SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0" + SERIAL_CONSOLES_CHECK = "${SERIAL_CONSOLES}" + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "5.0%" + + KERNEL_IMAGETYPE = "zImage" + KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" + KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}" + + SPL_BINARY = "MLO" + UBOOT_SUFFIX = "img" + UBOOT_MACHINE = "am335x_evm_defconfig" + UBOOT_ENTRYPOINT = "0x80008000" + UBOOT_LOADADDRESS = "0x80008000" + + MACHINE_FEATURES = "usbgadget usbhost vfat alsa" + + IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" + </literallayout> + The variables used to configure the machine define + machine-specific properties; + for example, machine-dependent packages, machine + tunings, the type of kernel to build, and + U-Boot configurations. + </para> + + <para> + The following list provides some explanation + for the statements found in the example reference + machine configuration file for the BeagleBone + development boards. + Realize that much more can be defined as part of + a machine's configuration file. + In general, you can learn about related variables + that this example does not have by locating the + variables in the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>Yocto Project Variables Glossary</ulink>" + in the Yocto Project Reference Manual. + <itemizedlist> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/xserver</filename></ulink>: + The recipe that provides "virtual/xserver" when + more than one provider is found. + In this case, the recipe that provides + "virtual/xserver" is "xserver-xorg", which + exists in + <filename>poky/meta/recipes-graphics/xorg-xserver</filename>. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>: + The packages that should be installed to provide + an X server and drivers for the machine. + In this example, the "xserver-xorg" and + "xf86-video-modesetting" are installed. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>: + A list of machine-dependent packages + not essential for booting the image. + Thus, the build does not fail if the packages + do not exist. + However, the packages are required for a + fully-featured image. + <note><title>Tip</title> + Many <filename>MACHINE*</filename> variables + exist that help you configure a particular + piece of hardware. + </note> + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGEDEPENDS'><filename>EXTRA_IMAGEDEPENDS</filename></ulink>: + Recipes to build that do not provide packages + for installing into the root filesystem + but building the image depends on the + recipes. + Sometimes a recipe is required to build + the final image but is not needed in the + root filesystem. + In this case, the U-Boot recipe must be + built for the image. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>: + Machines use tunings to optimize machine, + CPU, and application performance. + These features, which are collectively known + as "tuning features", exist in the + <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core (OE-Core)</ulink> + layer (e.g. + <filename>poky/meta/conf/machine/include</filename>). + In this example, the default tunning file is + "cortexa8hf-neon". + <note> + The <filename>include</filename> statement + that pulls in the + <filename>conf/machine/include/tune-cortexa8.inc</filename> + file provides many tuning possibilities. + </note> + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>: + The formats the OpenEmbedded build system + uses during the build when creating the + root filesystem. + In this example, four types of images are + supported. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGECMD'><filename>EXTRA_IMAGECMD</filename></ulink>: + Specifies additional options for image + creation commands. + In this example, the "-lnp " option is used + when creating the + <ulink url='https://en.wikipedia.org/wiki/JFFS2'>JFFS2</ulink> + image. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE'><filename>WKS_FILE</filename></ulink>: + The location of the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>Wic kickstart</ulink> + file used by the OpenEmbedded build system to + create a partitioned image (image.wic). + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>: + Specifies packages to install into an image + through the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink> + class. + Recipes use the <filename>IMAGE_INSTALL</filename> + variable. + </para></listitem> + <listitem><para> + <filename>do_image_wic[depends]</filename>: + A task that is constructed during the build. + In this example, the task depends on specific tools + in order to create the sysroot when buiding a Wic + image. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>: + Defines a serial console (TTY) to enable using + getty. + In this case, the baud rate is "115200" and the + device name is "ttyO0". + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/kernel</filename></ulink>: + Specifies the recipe that provides + "virtual/kernel" when more than one provider + is found. + In this case, the recipe that provides + "virtual/kernel" is "linux-yocto", which + exists in the layer's + <filename>recipes-kernel/linux</filename> directory. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION_linux-yocto</filename></ulink>: + Defines the version of the recipe used + to build the kernel, which is "5.0" in this + case. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>: + The type of kernel to build for the device. + In this case, the OpenEmbedded build system + creates a "zImage" image type. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></ulink>: + The names of the generated Linux kernel device + trees (i.e. the <filename>*.dtb</filename>) files. + All the device trees for the various BeagleBone + devices are included. +<!-- + You have to include some *.inc files according to the definition of KERNEL_DEVICETREE. + I don't see where these are being provided. +--> + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_EXTRA_ARGS'><filename>KERNEL_EXTRA_ARGS</filename></ulink>: + Additional <filename>make</filename> + command-line arguments the OpenEmbedded build + system passes on when compiling the kernel. + In this example, "LOADADDR=${UBOOT_ENTRYPOINT}" + is passed as a command-line argument. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-SPL_BINARY'><filename>SPL_BINARY</filename></ulink>: + Defines the Secondary Program Loader (SPL) binary + type. + In this case, the SPL binary is set to + "MLO", which stands for Multimedia card LOader. + </para> + + <para>The BeagleBone development board requires an + SPL to boot and that SPL file type must be MLO. + Consequently, the machine configuration needs to + define <filename>SPL_BINARY</filename> as "MLO". + <note> + For more information on how the SPL variables + are used, see the + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-bsp/u-boot/u-boot.inc'><filename>u-boot.inc</filename></ulink> + include file. + </note> + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_*</filename></ulink>: + Defines various U-Boot configurations needed + to build a U-Boot image. + In this example, a U-Boot image is required + to boot the BeagleBone device. + See the following variables for more information: + <itemizedlist> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_SUFFIX'><filename>UBOOT_SUFFIX</filename></ulink>: + Points to the generated U-Boot extension. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></ulink>: + Specifies the value passed on the make command line when building a U-Boot image. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_ENTRYPOINT</filename></ulink>: + Specifies the entry point for the U-Boot image. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_LOADADDRESS'><filename>UBOOT_LOADADDRESS</filename></ulink>: + Specifies the load address for the U-Boot image. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>: + Specifies the list of hardware features the + BeagleBone device is capable of supporting. + In this case, the device supports + "usbgadget usbhost vfat alsa". + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_BOOT_FILES'><filename>IMAGE_BOOT_FILES</filename></ulink>: + Files installed into the device's boot partition + when preparing the image using the Wic tool + with the <filename>bootimg-partition</filename> or <filename>bootimg-efi</filename> + source plugin. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='bsp-kernel-recipe-example'> + <title>BSP Kernel Recipe Example</title> + + <para> + The kernel recipe used to build the kernel image + for the BeagleBone device was established in the + machine configuration: + <literallayout class='monospaced'> + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "5.0%" + </literallayout> + The <filename>meta-yocto-bsp/recipes-kernel/linux</filename> + directory in the layer contains metadata used + to build the kernel. + In this case, a kernel append file (i.e. + <filename>linux-yocto_5.0.bbappend</filename>) is used to + override an established kernel recipe (i.e. + <filename>linux-yocto_5.0.bb</filename>), which is + located in + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux'></ulink>. + </para> + + <para> + Following is the contents of the append file: + <literallayout class='monospaced'> + KBRANCH_genericx86 = "v5.0/standard/base" + KBRANCH_genericx86-64 = "v5.0/standard/base" + KBRANCH_edgerouter = "v5.0/standard/edgerouter" + KBRANCH_beaglebone-yocto = "v5.0/standard/beaglebone" + + KMACHINE_genericx86 ?= "common-pc" + KMACHINE_genericx86-64 ?= "common-pc-64" + KMACHINE_beaglebone-yocto ?= "beaglebone" + + SRCREV_machine_genericx86 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" + SRCREV_machine_genericx86-64 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" + SRCREV_machine_edgerouter ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" + SRCREV_machine_beaglebone-yocto ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" + + COMPATIBLE_MACHINE_genericx86 = "genericx86" + COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" + COMPATIBLE_MACHINE_edgerouter = "edgerouter" + COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto" + + LINUX_VERSION_genericx86 = "5.0.3" + LINUX_VERSION_genericx86-64 = "5.0.3" + LINUX_VERSION_edgerouter = "5.0.3" + LINUX_VERSION_beaglebone-yocto = "5.0.3" + </literallayout> + This particular append file works for all the + machines that are part of the + <filename>meta-yocto-bsp</filename> layer. + The relevant statements are appended with + the "beaglebone-yocto" string. + The OpenEmbedded build system uses these + statements to override similar statements + in the kernel recipe: + <itemizedlist> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>: + Identifies the kernel branch that is validated, + patched, and configured during the build. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>: + Identifies the machine name as known by the + kernel, which is sometimes a different name + than what is known by the OpenEmbedded build + system. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>: + Identifies the revision of the source code used + to build the image. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>: + A regular expression that resolves to one or + more target machines with which the recipe + is compatible. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>: + The Linux version from kernel.org used by + the OpenEmbedded build system to build the + kernel image. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> +</chapter> diff --git a/poky/documentation/bsp-guide/history.rst b/poky/documentation/bsp-guide/history.rst index d7cd8ef7f..b52006adf 100644 --- a/poky/documentation/bsp-guide/history.rst +++ b/poky/documentation/bsp-guide/history.rst @@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK +.. SPDX-License-Identifier: CC-BY-2.0-UK *********************** Manual Revision History |