diff options
Diffstat (limited to 'documentation/bsp-guide')
| -rw-r--r-- | documentation/bsp-guide/bsp-guide-customization.xsl | 27 | ||||
| -rw-r--r-- | documentation/bsp-guide/bsp-guide.xml | 200 | ||||
| -rw-r--r-- | documentation/bsp-guide/bsp-style.css | 987 | ||||
| -rw-r--r-- | documentation/bsp-guide/bsp.rst | 1495 | ||||
| -rw-r--r-- | documentation/bsp-guide/bsp.xml | 2262 | ||||
| -rw-r--r-- | documentation/bsp-guide/index.rst | 15 |
6 files changed, 1510 insertions, 3476 deletions
diff --git a/documentation/bsp-guide/bsp-guide-customization.xsl b/documentation/bsp-guide/bsp-guide-customization.xsl deleted file mode 100644 index de674a0aec..0000000000 --- a/documentation/bsp-guide/bsp-guide-customization.xsl +++ /dev/null @@ -1,27 +0,0 @@ -<?xml version='1.0'?> -<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/documentation/bsp-guide/bsp-guide.xml b/documentation/bsp-guide/bsp-guide.xml deleted file mode 100644 index f559e0809c..0000000000 --- a/documentation/bsp-guide/bsp-guide.xml +++ /dev/null @@ -1,200 +0,0 @@ -<!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; ] > - -<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> - <firstname>Scott</firstname> <surname>Rifenbark</surname> - <affiliation> - <orgname>Scotty's Documentation Services, INC</orgname> - </affiliation> - <email>srifenbark@gmail.com</email> - </author> - </authorgroup> - - <revhistory> - <revision> - <revnumber>0.9</revnumber> - <date>24 November 2010</date> - <revremark>The initial document draft released with the Yocto Project 0.9 Release.</revremark> - </revision> - <revision> - <revnumber>1.0</revnumber> - <date>6 April 2011</date> - <revremark>Released with the Yocto Project 1.0 Release.</revremark> - </revision> - <revision> - <revnumber>1.0.1</revnumber> - <date>23 May 2011</date> - <revremark>Released with the Yocto Project 1.0.1 Release.</revremark> - </revision> - <revision> - <revnumber>1.1</revnumber> - <date>6 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.5.1</revnumber> - <date>January 2014</date> - <revremark>Released with the Yocto Project 1.5.1 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>&REL_MONTH_YEAR;</date> - <revremark>Released with the Yocto Project 2.7 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_HOME_URL;/documentation'>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_HOME_URL;/documentation'>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 - manual, send an email to the Yocto Project - discussion group at - <filename>yocto@yoctoproject.com</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/documentation/bsp-guide/bsp-style.css b/documentation/bsp-guide/bsp-style.css deleted file mode 100644 index 0c8689b96f..0000000000 --- a/documentation/bsp-guide/bsp-style.css +++ /dev/null @@ -1,987 +0,0 @@ -/* - 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/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst new file mode 100644 index 0000000000..11ca5d8b76 --- /dev/null +++ b/documentation/bsp-guide/bsp.rst @@ -0,0 +1,1495 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +************************************************** +Board Support Packages (BSP) --- Developer's Guide +************************************************** + +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. + +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 BSP +Layer using the :ref:`bitbake-layers <bsp-guide/bsp:Creating a new BSP Layer Using the \`\`bitbake-layers\`\` Script>` +tool. + +BSP Layers +========== + +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 BSP layer. Although not a strict requirement, BSP +layers in the Yocto Project use the following well-established naming +convention:: + + meta-bsp_root_name + +The string "meta-" is prepended to the +machine or platform name, which is "bsp_root_name" in the above form. + +.. note:: + + 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 ``meta-``. + However, various scripts and tools in the Yocto Project development + environment assume this convention. + +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 +:ref:`overview-manual/development-environment:yocto project source repositories` +through +a web interface at :yocto_git:`/`. 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." + +Each repository is a BSP layer supported by the Yocto Project (e.g. +``meta-raspberrypi`` and ``meta-intel``). 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:: + + $ git clone git://git.yoctoproject.org/meta-raspberrypi + +In addition to BSP layers, the ``meta-yocto-bsp`` layer is part of the +shipped ``poky`` repository. The ``meta-yocto-bsp`` layer maintains +several "reference" BSPs including the ARM-based Beaglebone and generic +versions of both 32-bit and 64-bit IA machines. + +For information on typical BSP development workflow, see the +:ref:`bsp-guide/bsp:developing a board support package (bsp)` +section. For more +information on how to set up a local copy of source files from a Git +repository, see the +:ref:`dev-manual/start:locating yocto project source files` +section in the Yocto Project Development Tasks Manual. + +The BSP layer's base directory (``meta-bsp_root_name``) is the root +directory of that Layer. This directory is what you add to the +:term:`BBLAYERS` variable in the +``conf/bblayers.conf`` file found in your +:term:`Build Directory`, which is +established after you run the OpenEmbedded build environment setup +script (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). +Adding the root directory allows the :term:`OpenEmbedded Build System` +to recognize the BSP +layer and from it build an image. Here is an example:: + + 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 \ + " + +.. note:: + + Ordering and :term:`BBFILE_PRIORITY` for the layers listed in :term:`BBLAYERS` + 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 :term:`BBLAYERS`. + +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 ``README`` "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. + +Some layers function as a layer to hold other BSP layers. These layers +are known as ":term:`container layers <Container Layer>`". An example of +this type of layer is OpenEmbedded's :oe_git:`meta-openembedded </meta-openembedded>` +layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers. +In cases like this, you need to include the names of the actual layers +you want to work with, such as:: + + 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 \ + " + +and so on. + +For more information on layers, see the +":ref:`dev-manual/layers:understanding and creating layers`" +section of the Yocto Project Development Tasks Manual. + +Preparing Your Build Host to Work With BSP Layers +================================================= + +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 +":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" +section. + +.. note:: + + For structural information on BSPs, see the + :ref:`bsp-guide/bsp:example filesystem layout` section. + +#. *Set Up the Build Environment:* Be sure you are set up to use BitBake + in a shell. See the ":ref:`dev-manual/start:preparing the build host`" + 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. + +#. *Clone the poky Repository:* You need to have a local copy of the + Yocto Project :term:`Source Directory` (i.e. a local + ``poky`` repository). See the + ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and + possibly the + ":ref:`dev-manual/start:checking out by branch in poky`" or + ":ref:`dev-manual/start:checking out by tag in poky`" + sections + all in the Yocto Project Development Tasks Manual for information on + how to clone the ``poky`` repository and check out the appropriate + branch for your work. + +#. *Determine the BSP Layer You Want:* 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 + :yocto_dl:`index of machines </releases/yocto/yocto-&DISTRO;/machines>` + for the release. + +#. *Optionally Clone the meta-intel BSP Layer:* If your hardware is + based on current Intel CPUs and devices, you can leverage this BSP + layer. For details on the ``meta-intel`` BSP layer, see the layer's + :yocto_git:`README </meta-intel/tree/README>` file. + + #. *Navigate to Your Source Directory:* Typically, you set up the + ``meta-intel`` Git repository inside the :term:`Source Directory` (e.g. + ``poky``). :: + + $ cd /home/you/poky + + #. *Clone the Layer:* :: + + $ 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. + + #. *Check Out the Proper Branch:* The branch you check out for + ``meta-intel`` must match the same branch you are using for the + Yocto Project release (e.g. ``&DISTRO_NAME_NO_CAP;``):: + + $ 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;' + + .. note:: + + To see the available branch names in a cloned repository, use the ``git + branch -al`` command. See the + ":ref:`dev-manual/start:checking out by branch in poky`" + section in the Yocto Project Development Tasks Manual for more + information. + +#. *Optionally Set Up an Alternative BSP Layer:* If your hardware can be + more closely leveraged to an existing BSP not within the + ``meta-intel`` BSP layer, you can clone that BSP layer. + + The process is identical to the process used for the ``meta-intel`` + layer except for the layer's name. For example, if you determine that + your hardware most closely matches the ``meta-raspberrypi``, clone + that layer:: + + $ 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. + +#. *Initialize the Build Environment:* While in the root directory of + the Source Directory (i.e. ``poky``), run the + :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment + setup script to define the OpenEmbedded build environment on your + build host. :: + + $ source oe-init-build-env + + Among other things, the script creates the :term:`Build Directory`, which is + ``build`` in this case and is located in the :term:`Source Directory`. After + the script runs, your current working directory is set to the ``build`` + directory. + +Example Filesystem Layout +========================= + +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. + +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 simple +to extract information and convert it to other formats if required. The +OpenEmbedded build system, through its standard :ref:`layers mechanism +<overview-manual/yp-intro:the yocto project layer model>`, 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. + +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. + +Before looking at the recommended form for the directory structure +inside a BSP layer, you should be aware that there are some requirements +in order for a BSP layer to be considered compliant with the Yocto +Project. For that list of requirements, see the +":ref:`bsp-guide/bsp:released bsp requirements`" section. + +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. :: + + meta-bsp_root_name/ + meta-bsp_root_name/bsp_license_file + meta-bsp_root_name/README + meta-bsp_root_name/README.sources + meta-bsp_root_name/binary/bootable_images + meta-bsp_root_name/conf/layer.conf + meta-bsp_root_name/conf/machine/*.conf + meta-bsp_root_name/recipes-bsp/* + meta-bsp_root_name/recipes-core/* + meta-bsp_root_name/recipes-graphics/* + meta-bsp_root_name/recipes-kernel/linux/linux-yocto_kernel_rev.bbappend + +Below is an example of the Raspberry Pi BSP layer that is available from +the :yocto_git:`Source Repositories <>`: + +.. code-block:: none + + 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_%.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 + +The following sections describe each part of the proposed BSP format. + +License Files +------------- + +You can find these files in the BSP Layer at:: + + meta-bsp_root_name/bsp_license_file + +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 ``COPYING.MIT`` file. + +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 ":ref:`dev-manual/licenses:maintaining open source license compliance during your product's lifecycle`" +section in the Yocto Project Development Tasks Manual. + +README File +----------- + +You can find this file in the BSP Layer at:: + + meta-bsp_root_name/README + +This file provides information on how to boot the live images that are +optionally included in the ``binary/`` directory. The ``README`` file +also provides information needed for building the image. + +At a minimum, the ``README`` 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. + +README.sources File +------------------- + +You can find this file in the BSP Layer at:: + + meta-bsp_root_name/README.sources + +This file provides information on where to locate the BSP source files +used to build the images (if any) that reside in +``meta-bsp_root_name/binary``. Images in the ``binary`` would be images +released with the BSP. The information in the ``README.sources`` file +also helps you find the :term:`Metadata` +used to generate the images that ship with the BSP. + +.. note:: + + If the BSP's ``binary`` directory is missing or the directory has no images, an + existing ``README.sources`` file is meaningless and usually does not exist. + +Pre-built User Binaries +----------------------- + +You can find these files in the BSP Layer at:: + + meta-bsp_root_name/binary/bootable_images + +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 :yocto_home:`Yocto Project <>` website. You can +use these kernels and images to get a system running and quickly get +started on development tasks. + +The exact types of binaries present are highly hardware-dependent. The +:ref:`README <bsp-guide/bsp:readme file>` file should be present in the +BSP Layer and it explains how to use the images with the target +hardware. Additionally, the +:ref:`README.sources <bsp-guide/bsp:readme.sources file>` file should be +present to locate the sources used to build the images and provide +information on the Metadata. + +Layer Configuration File +------------------------ + +You can find this file in the BSP Layer at:: + + meta-bsp_root_name/conf/layer.conf + +The ``conf/layer.conf`` 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 +"bsp" with the actual name of the BSP (i.e. "bsp_root_name" from the example +template). :: + + # We have a conf and classes directory, add 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 += "bsp" + BBFILE_PATTERN_bsp = "^${LAYERDIR}/" + BBFILE_PRIORITY_bsp = "6" + LAYERDEPENDS_bsp = "intel" + +To illustrate the string substitutions, here are the corresponding +statements from the Raspberry Pi ``conf/layer.conf`` file:: + + # 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" + . + . + . + +This file simply makes :term:`BitBake` aware of the recipes and configuration +directories. The file must exist so that the OpenEmbedded build system can +recognize the BSP. + +Hardware Configuration Options +------------------------------ + +You can find these files in the BSP Layer at:: + + meta-bsp_root_name/conf/machine/*.conf + +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 +:term:`MACHINE` variable. + +These files define things such as the kernel package to use +(:term:`PREFERRED_PROVIDER` of +:ref:`virtual/kernel <dev-manual/new-recipe:using virtual providers>`), +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. + +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. + +Tuning files are found in the ``meta/conf/machine/include`` directory +within the :term:`Source Directory`. +For example, many ``tune-*`` files (e.g. ``tune-arm1136jf-s.inc``, +``tune-1586-nlp.inc``, and so forth) reside in the +``poky/meta/conf/machine/include`` directory. + +To use an include file, you simply include them in the machine +configuration file. For example, the Raspberry Pi BSP +``raspberrypi3.conf`` contains the following statement:: + + include conf/machine/include/rpi-base.inc + +Miscellaneous BSP-Specific Recipe Files +--------------------------------------- + +You can find these files in the BSP Layer at:: + + meta-bsp_root_name/recipes-bsp/* + +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 ``formfactor_%.bbappend`` 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 ``machconfig`` file further down in the +directory. Here is the ``machconfig`` file for the Raspberry Pi BSP:: + + HAVE_TOUCHSCREEN=0 + HAVE_KEYBOARD=1 + + DISPLAY_CAN_ROTATE=0 + DISPLAY_ORIENTATION=0 + DISPLAY_DPI=133 + +.. note:: + + 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 + ``meta/recipes-bsp/formfactor/formfactor_0.0.bb``, which is found in + the :term:`Source Directory`. + +Display Support Files +--------------------- + +You can find these files in the BSP Layer at:: + + meta-bsp_root_name/recipes-graphics/* + +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. + +Linux Kernel Configuration +-------------------------- + +You can find these files in the BSP Layer at:: + + meta-bsp_root_name/recipes-kernel/linux/linux*.bbappend + meta-bsp_root_name/recipes-kernel/linux/*.bb + +Append files (``*.bbappend``) modify the main kernel recipe being used +to build the image. The ``*.bb`` 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. + +For your BSP, you typically want to use an existing Yocto Project kernel +recipe found in the :term:`Source Directory` +at +``meta/recipes-kernel/linux``. 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 +``meta-bsp_root_name/recipes-kernel/linux`` directory). + +Suppose you are using the ``linux-yocto_4.4.bb`` recipe to build the +kernel. In other words, you have selected the kernel in your +``"bsp_root_name".conf`` file by adding +:term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION` +statements as follows:: + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "4.4%" + +.. note:: + + When the preferred provider is assumed by default, the :term:`PREFERRED_PROVIDER` + statement does not appear in the ``"bsp_root_name".conf`` file. + +You would use the ``linux-yocto_4.4.bbappend`` file to append specific +BSP settings to the kernel, thus configuring the kernel for your +particular BSP. + +You can find more information on what your append file should contain in +the ":ref:`kernel-dev/common:creating the append file`" section +in the Yocto Project Linux Kernel Development Manual. + +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 +``recipes-kernel/linux`` directory you see the following:: + + linux-raspberrypi-dev.bb + linux-raspberrypi.inc + linux-raspberrypi_4.14.bb + linux-raspberrypi_4.9.bb + +The directory contains three kernel recipes and a common include file. + +Developing a Board Support Package (BSP) +======================================== + +This section describes the high-level procedure you can follow to create +a BSP. Although not required for BSP creation, the ``meta-intel`` +repository, which contains many BSPs supported by the Yocto Project, is +part of the example. + +For an example that shows how to create a new layer using the tools, see +the ":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" +section. + +The following illustration and list summarize the BSP creation general +workflow. + +.. image:: figures/bsp-dev-flow.png + :align: center + :width: 70% + +#. *Set up Your Host Development System to Support Development Using the + Yocto Project*: See the ":ref:`dev-manual/start:preparing the build host`" + section in the Yocto Project Development Tasks Manual for options on how to + get a system ready to use the Yocto Project. + +#. *Establish the meta-intel Repository on Your System:* 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 + ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`" + section. + +#. *Create Your Own BSP Layer Using the bitbake-layers Script:* + 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 + ``bitbake-layers`` script. For information about that script, see the + ":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" + section. + + 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 ":ref:`overview-manual/yp-intro:the yocto project layer model`" + section in the Yocto Project Overview and Concepts Manual. You can also + reference the ":ref:`dev-manual/layers:understanding and creating layers`" + section in the Yocto Project Development Tasks Manual. For more + information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`" + section. + + .. note:: + + - There are three hardware reference BSPs in the Yocto + Project release, located in the ``poky/meta-yocto-bsp`` + BSP layer: + + - Texas Instruments Beaglebone (``beaglebone-yocto``) + + - Two generic IA platforms (``genericx86`` and ``genericx86-64``) + + When you set up a layer for a new BSP, you should follow a standard + layout. This layout is described in the ":ref:`bsp-guide/bsp:example filesystem layout`" + 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 ``meta-intel`` layer inside the Source Directory. + +#. *Make Configuration Changes to Your New BSP Layer:* The standard BSP + layer structure organizes the files you need to edit in ``conf`` and + several ``recipes-*`` 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 + ``bitbake-layers`` script, you are able to interactively configure + many things for the BSP (e.g. keyboard, touchscreen, and so forth). + +#. *Make Recipe Changes to Your New BSP Layer:* Recipe changes include + altering recipes (``*.bb`` files), removing recipes you do not use, + and adding new recipes or append files (``.bbappend``) that support + your hardware. + +#. *Prepare for the Build:* 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. ``oe-init-build-env``) and you need to be sure two + key configuration files are configured appropriately: the + ``conf/local.conf`` and the ``conf/bblayers.conf`` file. You must + make the OpenEmbedded build system aware of your new layer. See the + ":ref:`dev-manual/layers:enabling your layer`" + section in the Yocto Project Development Tasks Manual for information + on how to let the build system know about your new layer. + +#. *Build the Image:* 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 + :doc:`BitBake User Manual <bitbake:index>`. + + The build process supports several types of images to satisfy + different needs. See the + ":ref:`ref-manual/images:Images`" chapter in the Yocto + Project Reference Manual for information on supported images. + +Requirements and Recommendations for Released BSPs +================================================== + +This section describes requirements and recommendations for a released +BSP to be considered compliant with the Yocto Project. + +Released BSP Requirements +------------------------- + +Before looking at BSP requirements, you should consider the following: + +- 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 + ":ref:`bsp-guide/bsp:bsp layers`" section in this manual and the + ":ref:`dev-manual/layers:understanding and creating layers`" + section in the Yocto Project Development Tasks Manual. + +- 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 ":yocto_wiki:`Third Party BSP Release + Process </Third_Party_BSP_Release_Process>`" + wiki page. + +- 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. + +- 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, there is no requirement + dictating that a specific kernel or kernel version be used in a given + BSP. + +The requirements for a released BSP that conform to the Yocto Project are: + +- *Layer Name:* The BSP must have a layer name that follows the Yocto + Project standards. For information on BSP layer names, see the + ":ref:`bsp-guide/bsp:bsp layers`" section. + +- *File System Layout:* When possible, use the same directory names in + your BSP layer as listed in the ``recipes.txt`` file, which is found + in ``poky/meta`` directory of the :term:`Source Directory` + or in the OpenEmbedded-Core Layer (``openembedded-core``) at + :oe_git:`/openembedded-core/tree/meta`. + + You should place recipes (``*.bb`` files) and recipe modifications + (``*.bbappend`` files) into ``recipes-*`` subdirectories by + functional area as outlined in ``recipes.txt``. If you cannot find a + category in ``recipes.txt`` to fit a particular recipe, you can make + up your own ``recipes-*`` subdirectory. + + Within any particular ``recipes-*`` category, the layout should match + what is found in the OpenEmbedded-Core Git repository + (``openembedded-core``) or the Source Directory (``poky``). In other + words, make sure you place related files in appropriately-related + ``recipes-*`` 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 found in the ":doc:`../contributor-guide/recipe-style-guide`" + in the Yocto Project and OpenEmbedded Contributor Guide. + +- *License File:* You must include a license file in the + ``meta-bsp_root_name`` directory. This license covers the BSP + Metadata as a whole. You must specify which license to use since no + default license exists. See the + :yocto_git:`COPYING.MIT </meta-raspberrypi/tree/COPYING.MIT>` + file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer + as an example. + +- *README File:* You must include a ``README`` file in the + ``meta-bsp_root_name`` directory. See the + :yocto_git:`README.md </meta-raspberrypi/tree/README.md>` + file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer + as an example. + + At a minimum, the ``README`` file should contain the following: + + - A brief description of the target hardware. + + - 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. + + - 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. + + - 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 + :doc:`../contributor-guide/submit-changes` section in the Yocto Project and + OpenEmbedded Contributor Guide. + + - Instructions on how to build the BSP using the BSP layer. + + - Instructions on how to boot the BSP build from the BSP layer. + + - Instructions on how to boot the binary images contained in the + ``binary`` directory, if present. + + - Information on any known bugs or issues that users should know + about when either building or booting the BSP binaries. + +- *README.sources File:* If your BSP contains binary images in the + ``binary`` directory, you must include a ``README.sources`` file in + the ``meta-bsp_root_name`` directory. This file specifies exactly + where you can find the sources used to generate the binary images. + +- *Layer Configuration File:* You must include a ``conf/layer.conf`` + file in the ``meta-bsp_root_name`` directory. This file identifies + the ``meta-bsp_root_name`` BSP layer as a layer to the build + system. + +- *Machine Configuration File:* You must include one or more + ``conf/machine/bsp_root_name.conf`` files in the + ``meta-bsp_root_name`` 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 ``README`` 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. ``meta-yocto-bsp`` layer). Such considerations + are outside the scope of this document. + +Released BSP Recommendations +---------------------------- + +Here are recommendations for released BSPs that conform to the +Yocto Project: + +- *Bootable Images:* Released BSPs can contain one or more bootable + images. Including bootable images allows users to easily try out the + BSP using their own hardware. + + 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. + + 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 + ``binary/`` subdirectory located in the ``meta-bsp_root_name`` + 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. + +- *Use a Yocto Linux Kernel:* 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 ``Yocto Linux Kernel`` category in the + :yocto_git:`Source Repositories <>` for these kernels. + +Customizing a Recipe for a BSP +============================== + +If you plan on customizing a recipe for a particular BSP, you need to do +the following: + +- Create a ``*.bbappend`` file for the modified recipe. For information on using + append files, see the + ":ref:`dev-manual/layers:appending other layers metadata with your layer`" + section in the Yocto Project Development Tasks Manual. + +- 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. + +- 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. ``recipes-bsp``, ``recipes-graphics``, ``recipes-core``, + and so forth). + +- 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. + +Here is a specific example to help you better understand the +process. This example customizes a recipe by adding a +BSP-specific configuration file named ``interfaces`` to the +``init-ifupdown_1.0.bb`` recipe for machine "xyz" where the BSP layer +also supports several other machines: + +#. Edit the ``init-ifupdown_1.0.bbappend`` file so that it contains the + following:: + + FILESEXTRAPATHS:prepend := "${THISDIR}/files:" + + The append file needs to be in the ``meta-xyz/recipes-core/init-ifupdown`` + directory. + +#. Create and place the new ``interfaces`` configuration file in the + BSP's layer here:: + + meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces + + .. note:: + + If the ``meta-xyz`` layer did not support multiple machines, you would place + the interfaces configuration file in the layer here:: + + meta-xyz/recipes-core/init-ifupdown/files/interfaces + + The :term:`FILESEXTRAPATHS` 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 ``files`` directory in the same location as + your append file. + +BSP Licensing Considerations +============================ + +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. + +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. + +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 :yocto_home:`Yocto Project Website <>` 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. + +There are two different methods within the OpenEmbedded build system to +satisfy the licensing requirements for an encumbered BSP. The following +list describes them in order of preference: + +#. *Use the LICENSE_FLAGS Variable to Define the Recipes that Have Commercial or + Other Types of Specially-Licensed Packages:* For each of those recipes, you can + specify a matching license string in a ``local.conf`` variable named + :term:`LICENSE_FLAGS_ACCEPTED`. + 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 + ":ref:`dev-manual/licenses:enabling commercially licensed recipes`" + section in the Yocto Project Development Tasks Manual for details on + how to use these variables. + + If you build as you normally would, without specifying any recipes in + the :term:`LICENSE_FLAGS_ACCEPTED` variable, 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 :term:`LICENSE_FLAGS_ACCEPTED` variable. Once you + enter the appropriate license flags into it, restart the build to continue + where it left off. During the build, the prompt will not appear again since + you have satisfied the requirement. + + Once the appropriate license flags are on the white list in the + :term:`LICENSE_FLAGS_ACCEPTED` variable, you can build the encumbered + image with no change at all to the normal build process. + +#. *Get a Pre-Built Version of the BSP:* You can get this type of BSP by + selecting the "DOWNLOADS" item from the "SOFTWARE" tab on the + :yocto_home:`Yocto Project website <>`. 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 + :term:`LICENSE_FLAGS_ACCEPTED` to match the encumbered recipes in the + BSP. + +.. 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. + +Creating a new BSP Layer Using the ``bitbake-layers`` Script +============================================================ + +The ``bitbake-layers create-layer`` 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. + +Use these steps to create a BSP layer: + +- *Create a General Layer:* Use the ``bitbake-layers`` script with the + ``create-layer`` subcommand to create a new general layer. For + instructions on how to create a general layer using the + ``bitbake-layers`` script, see the + ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" + section in the Yocto Project Development Tasks Manual. + +- *Create a Layer Configuration File:* 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 ``layer.conf`` files in the Yocto Project + :yocto_git:`Source Repositories <>`. To get examples of what you need + in your configuration file, locate a layer (e.g. "meta-ti") and + examine the + :yocto_git:`local.conf </meta-ti/tree/meta-ti-bsp/conf/layer.conf>` + file. + +- *Create a Machine Configuration File:* Create a + ``conf/machine/bsp_root_name.conf`` file. See + :yocto_git:`meta-yocto-bsp/conf/machine </poky/tree/meta-yocto-bsp/conf/machine>` + for sample ``bsp_root_name.conf`` files. There are other samples such as + :yocto_git:`meta-ti </meta-ti/tree/meta-ti-bsp/conf/machine>` + and + :yocto_git:`meta-freescale </meta-freescale/tree/conf/machine>` + from other vendors that have more specific machine and tuning + examples. + +- *Create a Kernel Recipe:* Create a kernel recipe in + ``recipes-kernel/linux`` by either using a kernel append file or a + new custom kernel recipe file (e.g. ``linux-yocto_4.12.bb``). The BSP + layers mentioned in the previous step also contain different kernel + examples. See the ":ref:`kernel-dev/common:modifying an existing recipe`" + section in the Yocto Project Linux Kernel Development Manual for + information on how to create a custom kernel. + +The remainder of this section provides a description of the Yocto +Project reference BSP for Beaglebone, which resides in the +:yocto_git:`meta-yocto-bsp </poky/tree/meta-yocto-bsp>` +layer. + +BSP Layer Configuration Example +------------------------------- + +The layer's ``conf`` directory contains the ``layer.conf`` configuration +file. In this example, the ``conf/layer.conf`` file is the following:: + + # We have a conf and classes directory, add 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 += "yoctobsp" + BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" + BBFILE_PRIORITY_yoctobsp = "5" + LAYERVERSION_yoctobsp = "4" + LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;" + +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 +:yocto_git:`Source Repositories <>`. + +For a detailed description of this particular layer configuration file, +see ":ref:`step 3 <dev-manual/layers:creating your own layer>`" +in the discussion that describes how to create layers in the Yocto +Project Development Tasks Manual. + +BSP Machine Configuration Example +--------------------------------- + +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. + +There are one or more machine configuration files in the +``bsp_layer/conf/machine/`` directory of the layer:: + + bsp_layer/conf/machine/machine1\.conf + bsp_layer/conf/machine/machine2\.conf + bsp_layer/conf/machine/machine3\.conf + ... more ... + +For example, the machine configuration file for the `BeagleBone and +BeagleBone Black development boards <https://beagleboard.org/bone>`__ is +located in :yocto_git:`poky/meta-yocto-bsp/conf/machine/beaglebone-yocto.conf +</poky/tree/meta-yocto-bsp/conf/machine/beaglebone-yocto.conf>`:: + + #@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" + + MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree" + + EXTRA_IMAGEDEPENDS += "virtual/bootloader" + + DEFAULTTUNE ?= "cortexa8hf-neon" + include conf/machine/include/arm/armv7a/tune-cortexa8.inc + + IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap" + EXTRA_IMAGECMD:jffs2 = "-lnp " + WKS_FILE ?= "beaglebone-yocto.wks" + MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "kernel-image kernel-devicetree" + do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot virtual/bootloader:do_deploy" + + SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0 115200;ttyAMA0" + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "6.1%" + + KERNEL_IMAGETYPE = "zImage" + KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" + KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}" + + PREFERRED_PROVIDER_virtual/bootloader ?= "u-boot" + + 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} ${SPL_BINARY} ${KERNEL_IMAGETYPE} ${KERNEL_DEVICETREE}" + + # support runqemu + EXTRA_IMAGEDEPENDS += "qemu-native qemu-helper-native" + IMAGE_CLASSES += "qemuboot" + QB_DEFAULT_FSTYPE = "wic" + QB_FSINFO = "wic:no-kernel-in-fs" + QB_KERNEL_ROOT = "/dev/vda2" + QB_SYSTEM_NAME = "qemu-system-arm" + QB_MACHINE = "-machine virt" + QB_CPU = "-cpu cortex-a15" + QB_KERNEL_CMDLINE_APPEND = "console=ttyAMA0 systemd.mask=systemd-networkd" + QB_OPT_APPEND = "-device virtio-rng-device" + QB_TAP_OPT = "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no" + QB_NETWORK_DEVICE = "-device virtio-net-device,netdev=net0,mac=@MAC@" + QB_ROOTFS_OPT = "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0" + QB_SERIAL_OPT = "" + QB_TCPSERIAL_OPT = "-device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon" + +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. + +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 ":ref:`ref-manual/variables:variables glossary`" in the Yocto +Project Reference Manual. + +- :term:`PREFERRED_PROVIDER_virtual/xserver <PREFERRED_PROVIDER>`: + 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", available in + ``poky/meta/recipes-graphics/xorg-xserver``. + +- :term:`MACHINE_EXTRA_RRECOMMENDS`: + 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. + + .. tip:: + + There are many ``MACHINE*`` variables that help you configure a particular piece + of hardware. + +- :term:`EXTRA_IMAGEDEPENDS`: + 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. + + At the end of the file, we also use this setings to implement + ``runqemu`` support on the host machine. + +- :term:`DEFAULTTUNE`: Machines + use tunings to optimize machine, CPU, and application performance. + These features, which are collectively known as "tuning features", + are set in the :term:`OpenEmbedded-Core (OE-Core)` layer. In this + example, the default tuning file is :oe_git:`tune-cortexa8 + </openembedded-core/tree/meta/conf/machine/include/arm/armv7a/tune-cortexa8.inc>`. + + .. note:: + + The include statement that pulls in the + ``conf/machine/include/arm/tune-cortexa8.inc`` file provides many tuning + possibilities. + +- :term:`IMAGE_FSTYPES`: The + formats the OpenEmbedded build system uses during the build when + creating the root filesystem. In this example, four types of images + are supported. + +- :term:`EXTRA_IMAGECMD`: + Specifies additional options for image creation commands. In this + example, the "-lnp " option is used when creating the + :wikipedia:`JFFS2 <JFFS2>` image. + +- :term:`WKS_FILE`: The location of + the :ref:`Wic kickstart <ref-manual/kickstart:openembedded kickstart (\`\`.wks\`\`) reference>` file used + by the OpenEmbedded build system to create a partitioned image. + +- ``do_image_wic[depends]``: A task that is constructed during the + build. In this example, the task depends on specific tools in order + to create the sysroot when building a Wic image. + +- :term:`SERIAL_CONSOLES`: + Defines a serial console (TTY) to enable using getty. In this case, + the baud rate is "115200" and the device name is "ttyO0". + +- :term:`PREFERRED_PROVIDER_virtual/kernel <PREFERRED_PROVIDER>`: + 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 + ``recipes-kernel/linux`` directory. + +- :term:`PREFERRED_VERSION_linux-yocto <PREFERRED_VERSION>`: + Defines the version of the recipe used to build the kernel, which is + "6.1" in this case. + +- :term:`KERNEL_IMAGETYPE`: + The type of kernel to build for the device. In this case, the + OpenEmbedded build system creates a "zImage" image type. + +- :term:`KERNEL_DEVICETREE`: + The names of the generated Linux kernel device trees (i.e. the + ``*.dtb``) files. All the device trees for the various BeagleBone + devices are included. + +- :term:`KERNEL_EXTRA_ARGS`: + Additional ``make`` 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. + +- :term:`SPL_BINARY`: Defines the + Secondary Program Loader (SPL) binary type. In this case, the SPL + binary is set to "MLO", which stands for Multimedia card LOader. + + The BeagleBone development board requires an SPL to boot and that SPL + file type must be MLO. Consequently, the machine configuration needs + to define :term:`SPL_BINARY` as ``MLO``. + + .. note:: + + For more information on how the SPL variables are used, see the + :yocto_git:`u-boot.inc </poky/tree/meta/recipes-bsp/u-boot/u-boot.inc>` + include file. + +- :term:`UBOOT_* <UBOOT_ENTRYPOINT>`: 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: + + - :term:`UBOOT_SUFFIX`: + Points to the generated U-Boot extension. + + - :term:`UBOOT_MACHINE`: + Specifies the value passed on the make command line when building + a U-Boot image. + + - :term:`UBOOT_ENTRYPOINT`: + Specifies the entry point for the U-Boot image. + + - :term:`UBOOT_LOADADDRESS`: + Specifies the load address for the U-Boot image. + +- :term:`MACHINE_FEATURES`: + Specifies the list of hardware features the BeagleBone device is + capable of supporting. In this case, the device supports "usbgadget + usbhost vfat alsa". + +- :term:`IMAGE_BOOT_FILES`: + Files installed into the device's boot partition when preparing the + image using the Wic tool with the ``bootimg-partition`` or + ``bootimg-efi`` source plugin. + +BSP Kernel Recipe Example +------------------------- + +The kernel recipe used to build the kernel image for the BeagleBone +device was established in the machine configuration:: + + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "6.1%" + +The ``meta-yocto-bsp/recipes-kernel/linux`` directory in the layer contains +metadata used to build the kernel. In this case, a kernel append file +(i.e. ``linux-yocto_6.1.bbappend``) is used to override an established +kernel recipe (i.e. ``linux-yocto_6.1.bb``), which is located in +:yocto_git:`/poky/tree/meta/recipes-kernel/linux`. + +The contents of the append file are:: + + KBRANCH:genericx86 = "v6.1/standard/base" + KBRANCH:genericx86-64 = "v6.1/standard/base" + KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone" + + KMACHINE:genericx86 ?= "common-pc" + KMACHINE:genericx86-64 ?= "common-pc-64" + KMACHINE:beaglebone-yocto ?= "beaglebone" + + SRCREV_machine:genericx86 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86" + SRCREV_machine:genericx86-64 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86" + SRCREV_machine:beaglebone-yocto ?= "423e1996694b61fbfc8ec3bf062fc6461d64fde1" + + COMPATIBLE_MACHINE:genericx86 = "genericx86" + COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64" + COMPATIBLE_MACHINE:beaglebone-yocto = "beaglebone-yocto" + + LINUX_VERSION:genericx86 = "6.1.30" + LINUX_VERSION:genericx86-64 = "6.1.30" + LINUX_VERSION:beaglebone-yocto = "6.1.20" + +This particular append file works for all the machines that are +part of the ``meta-yocto-bsp`` 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: + +- :term:`KBRANCH`: Identifies the + kernel branch that is validated, patched, and configured during the + build. + +- :term:`KMACHINE`: Identifies the + machine name as known by the kernel, which is sometimes a different + name than what is known by the OpenEmbedded build system. + +- :term:`SRCREV`: Identifies the + revision of the source code used to build the image. + +- :term:`COMPATIBLE_MACHINE`: + A regular expression that resolves to one or more target machines + with which the recipe is compatible. + +- :term:`LINUX_VERSION`: The + Linux version from kernel.org used by the OpenEmbedded build system + to build the kernel image. diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml deleted file mode 100644 index 0327f6db62..0000000000 --- a/documentation/bsp-guide/bsp.xml +++ /dev/null @@ -1,2262 +0,0 @@ -<!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; ] > - -<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 BSP Layer. - 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 a - layer reveals information that includes two links from which you can choose - to set up a clone of the layer's repository on your local host 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 - BSPs such as the Beaglebone, EdgeRouter, and generic versions of - both 32-bit and 64-bit IA machines. - </para> - - <para> - For information on the 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 layer's base directory - (<filename>meta-<replaceable>bsp_root_name</replaceable></filename>) - is the root directory of the BSP 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 the - <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. - </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 to be combined in - certain end products. - </para> - - <para> - Before looking at the common form for the file structure - inside a BSP Layer, you should be aware that some - requirements do exist in order for a BSP layer to - be considered compliant 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 common form for the file structure - inside a BSP Layer. - While this basic form represents the standard, - realize that the actual file structures for specific - 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>tun-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 contains 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> - Freescale MPC8315E-RDB - (<filename>mpc8315e-rdb</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 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 about the hardware the BSP - targets. - </para></listitem> - <listitem><para> - A list of all the dependencies - on which a BSP layer depends. - 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 a 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> - 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>machine</replaceable><filename>.conf</filename> - </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;ttyO0" - - PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" - PREFERRED_VERSION_linux-yocto ?= "4.12%" - - 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_boneblack_config" - UBOOT_ENTRYPOINT = "0x80008000" - UBOOT_LOADADDRESS = "0x80008000" - - MACHINE_FEATURES = "usbgadget usbhost vfat alsa" - - IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO" - </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 machines 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/xserver-xorg</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 "4.12" 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 name of the generated Linux kernel device - tree (i.e. the <filename>.dtb</filename>) file. - 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> - source plugin. - In this case, the "u-boot.${UBOOT_SUFFIX}" and - "MLO" files are installed. - </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 ?= "4.12%" - </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 is used to - override an established kernel recipe, which is - located in - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux'></ulink> - and named - <filename>linux-yocto_4.12.bb</filename>. - </para> - - <para> - Following is the contents of the append file: - <literallayout class='monospaced'> - KBRANCH_genericx86 = "standard/base" - KBRANCH_genericx86-64 = "standard/base" - - KMACHINE_genericx86 ?= "common-pc" - KMACHINE_genericx86-64 ?= "common-pc-64" - KBRANCH_edgerouter = "standard/edgerouter" - KBRANCH_beaglebone-yocto = "standard/beaglebone" - KMACHINE_beaglebone-yocto = "beaglebone" - KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb" - - SRCREV_machine_genericx86 ?= "1c4ad569af3e23a77994235435040e322908687f" - SRCREV_machine_genericx86-64 ?= "1c4ad569af3e23a77994235435040e322908687f" - SRCREV_machine_edgerouter ?= "257f843ea367744620f1d92910afd2f454e31483" - SRCREV_machine_beaglebone-yocto ?= "257f843ea367744620f1d92910afd2f454e31483" - SRCREV_machine_mpc8315e-rdb ?= "014560874f9eb2a86138c9cc35046ff1720485e1" - - - COMPATIBLE_MACHINE_genericx86 = "genericx86" - COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" - COMPATIBLE_MACHINE_edgerouter = "edgerouter" - COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto" - COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb" - - LINUX_VERSION_genericx86 = "4.12.20" - LINUX_VERSION_genericx86-64 = "4.12.20" - LINUX_VERSION_edgerouter = "4.12.19" - LINUX_VERSION_beaglebone-yocto = "4.12.19" - LINUX_VERSION_mpc8315e-rdb = "4.12.19" - </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. -<!-- - You find out about that point in the kernel source tree by - doing the following command: - - git log ‐‐decorate 257f843ea367744620f1d92910afd2f454e31483 - - Returns information about the commit, which is usually - that it is a merge point for a stable kernel release. ---> - </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/documentation/bsp-guide/index.rst b/documentation/bsp-guide/index.rst new file mode 100644 index 0000000000..9a8e034ae6 --- /dev/null +++ b/documentation/bsp-guide/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +===================================================== +Yocto Project Board Support Package Developer's Guide +===================================================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + bsp + +.. include:: /boilerplate.rst |