summaryrefslogtreecommitdiffstats
path: root/documentation/bsp-guide
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/bsp-guide')
-rw-r--r--documentation/bsp-guide/bsp.xml3312
1 files changed, 1491 insertions, 1821 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 1edbc049de..a93ac50f6f 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -4,230 +4,231 @@
4 4
5<chapter id='bsp'> 5<chapter id='bsp'>
6 6
7 <title>Board Support Packages (BSP) - Developer's Guide</title> 7<title>Board Support Packages (BSP) - Developer's Guide</title>
8 8
9 <para> 9<para>
10 A Board Support Package (BSP) is a collection of information that 10 A Board Support Package (BSP) is a collection of information that
11 defines how to support a particular hardware device, set of devices, or 11 defines how to support a particular hardware device, set of devices, or
12 hardware platform. 12 hardware platform.
13 The BSP includes information about the hardware features 13 The BSP includes information about the hardware features
14 present on the device and kernel configuration information along with any 14 present on the device and kernel configuration information along with any
15 additional hardware drivers required. 15 additional hardware drivers required.
16 The BSP also lists any additional software 16 The BSP also lists any additional software
17 components required in addition to a generic Linux software stack for both 17 components required in addition to a generic Linux software stack for both
18 essential and optional platform features. 18 essential and optional platform features.
19 </para> 19</para>
20 20
21 <para> 21<para>
22 This guide presents information about BSP Layers, defines a structure for components 22 This guide presents information about BSP Layers, defines a structure for components
23 so that BSPs follow a commonly understood layout, discusses how to customize 23 so that BSPs follow a commonly understood layout, discusses how to customize
24 a recipe for a BSP, addresses BSP licensing, and provides information that 24 a recipe for a BSP, addresses BSP licensing, and provides information that
25 shows you how to create and manage a 25 shows you how to create a
26 <link linkend='bsp-layers'>BSP Layer</link> using two Yocto Project 26 <link linkend='bsp-layers'>BSP Layer</link> using the
27 <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>. 27 <link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'><filename>bitbake-layers</filename></link>
28 </para> 28 tool.
29 29</para>
30 <section id='bsp-layers'> 30
31 <title>BSP Layers</title> 31<section id='bsp-layers'>
32 32 <title>BSP Layers</title>
33 <para> 33
34 A BSP consists of a file structure inside a base directory. 34 <para>
35 Collectively, you can think of the base directory, its file structure, 35 A BSP consists of a file structure inside a base directory.
36 and the contents as a BSP Layer. 36 Collectively, you can think of the base directory, its file structure,
37 Although not a strict requirement, BSP layers in the Yocto Project 37 and the contents as a BSP Layer.
38 use the following well-established naming convention: 38 Although not a strict requirement, BSP layers in the Yocto Project
39 <literallayout class='monospaced'> 39 use the following well-established naming convention:
40 <literallayout class='monospaced'>
40 meta-<replaceable>bsp_name</replaceable> 41 meta-<replaceable>bsp_name</replaceable>
41 </literallayout> 42 </literallayout>
42 The string "meta-" is prepended to the machine or platform name, which is 43 The string "meta-" is prepended to the machine or platform name, which is
43 <replaceable>bsp_name</replaceable> in the above form. 44 <replaceable>bsp_name</replaceable> in the above form.
44 <note><title>Tip</title> 45 <note><title>Tip</title>
45 Because the BSP layer naming convention is well-established, 46 Because the BSP layer naming convention is well-established,
46 it is advisable to follow it when creating layers. 47 it is advisable to follow it when creating layers.
47 Technically speaking, a BSP layer name does not need to 48 Technically speaking, a BSP layer name does not need to
48 start with <filename>meta-</filename>. 49 start with <filename>meta-</filename>.
49 However, various scripts and tools in the Yocto Project 50 However, various scripts and tools in the Yocto Project
50 development environment assume this convention. 51 development environment assume this convention.
51 </note> 52 </note>
52 </para> 53 </para>
53 54
54 <para> 55 <para>
55 To help understand the BSP layer concept, consider the BSPs that the 56 To help understand the BSP layer concept, consider the BSPs that the
56 Yocto Project supports and provides with each release. 57 Yocto Project supports and provides with each release.
57 You can see the layers in the 58 You can see the layers in the
58 <ulink url='&YOCTO_DOCS_GS_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink> 59 <ulink url='&YOCTO_DOCS_GS_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>
59 through a web interface at 60 through a web interface at
60 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>. 61 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
61 If you go to that interface, you will find a list of repositories 62 If you go to that interface, you will find a list of repositories
62 under "Yocto Metadata Layers". 63 under "Yocto Metadata Layers".
63 <note> 64 <note>
64 Layers that are no longer actively supported as part of the 65 Layers that are no longer actively supported as part of the
65 Yocto Project appear under the heading "Yocto Metadata Layer 66 Yocto Project appear under the heading "Yocto Metadata Layer
66 Archive." 67 Archive."
67 </note> 68 </note>
68 Each repository is a BSP layer supported by the Yocto Project 69 Each repository is a BSP layer supported by the Yocto Project
69 (e.g. <filename>meta-raspberrypi</filename> and 70 (e.g. <filename>meta-raspberrypi</filename> and
70 <filename>meta-intel</filename>). 71 <filename>meta-intel</filename>).
71 Each of these layers is a repository unto itself and clicking on a 72 Each of these layers is a repository unto itself and clicking on a
72 layer reveals information that includes two links from which you can choose 73 layer reveals information that includes two links from which you can choose
73 to set up a clone of the layer's repository on your local host system. 74 to set up a clone of the layer's repository on your local host system.
74 Here is an example that clones the Raspberry Pi BSP layer: 75 Here is an example that clones the Raspberry Pi BSP layer:
75 <literallayout class='monospaced'> 76 <literallayout class='monospaced'>
76 $ git clone git://git.yoctoproject.org/meta-raspberrypi 77 $ git clone git://git.yoctoproject.org/meta-raspberrypi
77 </literallayout> 78 </literallayout>
78 </para> 79 </para>
79 80
80 <para> 81 <para>
81 In addition to BSP layers, the 82 In addition to BSP layers, the
82 <filename>meta-yocto-bsp</filename> layer is part of the 83 <filename>meta-yocto-bsp</filename> layer is part of the
83 shipped <filename>poky</filename> repository. 84 shipped <filename>poky</filename> repository.
84 The <filename>meta-yocto-bsp</filename> layer maintains several 85 The <filename>meta-yocto-bsp</filename> layer maintains several
85 BSPs such as the Beaglebone, EdgeRouter, and generic versions of 86 BSPs such as the Beaglebone, EdgeRouter, and generic versions of
86 both 32-bit and 64-bit IA machines. 87 both 32-bit and 64-bit IA machines.
87 </para> 88 </para>
88 89
89 <para> 90 <para>
90 For information on the BSP development workflow, see the 91 For information on the BSP development workflow, see the
91 "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>" 92 "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>"
92 section. 93 section.
93 For more information on how to set up a local copy of source files 94 For more information on how to set up a local copy of source files
94 from a Git repository, see the 95 from a Git repository, see the
95 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>" 96 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
96 section also in the Yocto Project Development Tasks Manual. 97 section also in the Yocto Project Development Tasks Manual.
97 </para> 98 </para>
98 99
99 <para> 100 <para>
100 The layer's base directory 101 The layer's base directory
101 (<filename>meta-<replaceable>bsp_name</replaceable></filename>) 102 (<filename>meta-<replaceable>bsp_name</replaceable></filename>)
102 is the root of the BSP Layer. 103 is the root of the BSP Layer.
103 This root is what you add to the 104 This root is what you add to the
104 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> 105 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
105 variable in the <filename>conf/bblayers.conf</filename> file found in the 106 variable in the <filename>conf/bblayers.conf</filename> file found in the
106 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, 107 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
107 which is established after you run the OpenEmbedded build environment 108 which is established after you run the OpenEmbedded build environment
108 setup script (i.e. 109 setup script (i.e.
109 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>). 110 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
110 Adding the root allows the 111 Adding the root allows the
111 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink> 112 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
112 to recognize the BSP layer and from it build an image. 113 to recognize the BSP layer and from it build an image.
113 Here is an example: 114 Here is an example:
114 <literallayout class='monospaced'> 115 <literallayout class='monospaced'>
115 BBLAYERS ?= " \ 116 BBLAYERS ?= " \
116 /usr/local/src/yocto/meta \ 117 /usr/local/src/yocto/meta \
117 /usr/local/src/yocto/meta-poky \ 118 /usr/local/src/yocto/meta-poky \
118 /usr/local/src/yocto/meta-yocto-bsp \ 119 /usr/local/src/yocto/meta-yocto-bsp \
119 /usr/local/src/yocto/meta-mylayer \ 120 /usr/local/src/yocto/meta-mylayer \
120 " 121 "
121 </literallayout> 122 </literallayout>
122 </para> 123 </para>
123 124
124 <para> 125 <para>
125 Some BSPs require additional layers on 126 Some BSPs require additional layers on
126 top of the BSP's root layer in order to be functional. 127 top of the BSP's root layer in order to be functional.
127 For these cases, you also need to add those layers to the 128 For these cases, you also need to add those layers to the
128 <filename>BBLAYERS</filename> variable in order to build the BSP. 129 <filename>BBLAYERS</filename> variable in order to build the BSP.
129 You must also specify in the "Dependencies" section of the BSP's 130 You must also specify in the "Dependencies" section of the BSP's
130 <filename>README</filename> file any requirements for additional 131 <filename>README</filename> file any requirements for additional
131 layers and, preferably, any 132 layers and, preferably, any
132 build instructions that might be contained elsewhere 133 build instructions that might be contained elsewhere
133 in the <filename>README</filename> file. 134 in the <filename>README</filename> file.
134 </para> 135 </para>
135 136
136 <para> 137 <para>
137 Some layers function as a layer to hold other BSP layers. 138 Some layers function as a layer to hold other BSP layers.
138 An example of this type of layer is the 139 An example of this type of layer is the
139 <filename>meta-intel</filename> layer. 140 <filename>meta-intel</filename> layer.
140 This layer contains BSP layers for the Intel-core2-32 141 This layer contains BSP layers for the Intel-core2-32
141 <trademark class='registered'>Intel</trademark> Common Core 142 <trademark class='registered'>Intel</trademark> Common Core
142 (Intel-core2-32) and the Intel-corei7-64 143 (Intel-core2-32) and the Intel-corei7-64
143 <trademark class='registered'>Intel</trademark> Common Core 144 <trademark class='registered'>Intel</trademark> Common Core
144 (Intel-corei7-64). 145 (Intel-corei7-64).
145 the <filename>meta-intel</filename> layer also contains 146 the <filename>meta-intel</filename> layer also contains
146 the <filename>common/</filename> directory, which contains 147 the <filename>common/</filename> directory, which contains
147 common content across those layers. 148 common content across those layers.
148 </para> 149 </para>
149 150
150 <para> 151 <para>
151 For more information on layers, see the 152 For more information on layers, see the
152 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" 153 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
153 section of the Yocto Project Development Tasks Manual. 154 section of the Yocto Project Development Tasks Manual.
154 </para> 155 </para>
155 </section> 156</section>
156 157
157 <section id='preparing-your-build-host-to-work-with-bsp-layers'> 158<section id='preparing-your-build-host-to-work-with-bsp-layers'>
158 <title>Preparing Your Build Host to Work With BSP Layers</title> 159 <title>Preparing Your Build Host to Work With BSP Layers</title>
159 160
160 <para> 161 <para>
161 This section describes how to get your build host ready 162 This section describes how to get your build host ready
162 to work with BSP layers. 163 to work with BSP layers.
163 Once you have the host set up, you can create the layer 164 Once you have the host set up, you can create the layer
164 as described in the 165 as described in the
165 "<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>" 166 "<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>"
166 section. 167 section.
167 <note> 168 <note>
168 For structural information on BSPs, see the 169 For structural information on BSPs, see the
169 <link linkend='bsp-filelayout'>Example Filesystem Layout</link> 170 <link linkend='bsp-filelayout'>Example Filesystem Layout</link>
170 section. 171 section.
171 </note> 172 </note>
173 <orderedlist>
174 <listitem><para>
175 <emphasis>Set Up the Build Environment:</emphasis>
176 Be sure you are set up to use BitBake in a shell.
177 See the
178 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
179 section in the Yocto Project Development Tasks Manual for information
180 on how to get a build host ready that is either a native
181 Linux machine or a machine that uses CROPS.
182 </para></listitem>
183 <listitem><para>
184 <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
185 You need to have a local copy of the Yocto Project
186 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
187 (i.e. a local <filename>poky</filename> repository).
188 See the
189 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
190 and possibly the
191 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
192 or
193 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
194 sections all in the Yocto Project Development Tasks Manual for
195 information on how to clone the <filename>poky</filename>
196 repository and check out the appropriate branch for your work.
197 </para></listitem>
198 <listitem><para>
199 <emphasis>Determine the BSP Layer You Want:</emphasis>
200 The Yocto Project supports many BSPs, which are maintained in
201 their own layers or in layers designed to contain several
202 BSPs.
203 To get an idea of machine support through BSP layers, you can
204 look at the
205 <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
206 for the release.
207 </para></listitem>
208 <listitem><para>
209 <emphasis>Optionally Clone the
210 <filename>meta-intel</filename> BSP Layer:</emphasis>
211 If your hardware is based on current Intel CPUs and devices,
212 you can leverage this BSP layer.
213 For details on the <filename>meta-intel</filename> BSP layer,
214 see the layer's
215 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
216 file.
172 <orderedlist> 217 <orderedlist>
173 <listitem><para> 218 <listitem><para>
174 <emphasis>Set Up the Build Environment:</emphasis> 219 <emphasis>Navigate to Your Source Directory:</emphasis>
175 Be sure you are set up to use BitBake in a shell. 220 Typically, you set up the
176 See the 221 <filename>meta-intel</filename> Git repository
177 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>" 222 inside the
178 section in the Yocto Project Development Tasks Manual for information
179 on how to get a build host ready that is either a native
180 Linux machine or a machine that uses CROPS.
181 </para></listitem>
182 <listitem><para>
183 <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
184 You need to have a local copy of the Yocto Project
185 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> 223 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
186 (i.e. a local <filename>poky</filename> repository). 224 (e.g. <filename>poky</filename>).
187 See the 225 <literallayout class='monospaced'>
188 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>" 226 $ cd /home/<replaceable>you</replaceable>/poky
189 and possibly the 227 </literallayout>
190 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
191 or
192 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
193 sections all in the Yocto Project Development Tasks Manual for
194 information on how to clone the <filename>poky</filename>
195 repository and check out the appropriate branch for your work.
196 </para></listitem>
197 <listitem><para>
198 <emphasis>Determine the BSP Layer You Want:</emphasis>
199 The Yocto Project supports many BSPs, which are maintained in
200 their own layers or in layers designed to contain several
201 BSPs.
202 To get an idea of machine support through BSP layers, you can
203 look at the
204 <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
205 for the release.
206 </para></listitem> 228 </para></listitem>
207 <listitem><para> 229 <listitem><para>
208 <emphasis>Optionally Clone the 230 <emphasis>Clone the Layer:</emphasis>
209 <filename>meta-intel</filename> BSP Layer:</emphasis> 231 <literallayout class='monospaced'>
210 If your hardware is based on current Intel CPUs and devices,
211 you can leverage this BSP layer.
212 For details on the <filename>meta-intel</filename> BSP layer,
213 see the layer's
214 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
215 file.
216 <orderedlist>
217 <listitem><para>
218 <emphasis>Navigate to Your Source Directory:</emphasis>
219 Typically, you set up the
220 <filename>meta-intel</filename> Git repository
221 inside the
222 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
223 (e.g. <filename>poky</filename>).
224 <literallayout class='monospaced'>
225 $ cd /home/<replaceable>you</replaceable>/poky
226 </literallayout>
227 </para></listitem>
228 <listitem><para>
229 <emphasis>Clone the Layer:</emphasis>
230 <literallayout class='monospaced'>
231 $ git clone git://git.yoctoproject.org/meta-intel.git 232 $ git clone git://git.yoctoproject.org/meta-intel.git
232 Cloning into 'meta-intel'... 233 Cloning into 'meta-intel'...
233 remote: Counting objects: 15585, done. 234 remote: Counting objects: 15585, done.
@@ -236,44 +237,44 @@
236 Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done. 237 Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done.
237 Resolving deltas: 100% (9123/9123), done. 238 Resolving deltas: 100% (9123/9123), done.
238 Checking connectivity... done. 239 Checking connectivity... done.
239 </literallayout> 240 </literallayout>
240 </para></listitem> 241 </para></listitem>
241 <listitem><para> 242 <listitem><para>
242 <emphasis>Check Out the Proper Branch:</emphasis> 243 <emphasis>Check Out the Proper Branch:</emphasis>
243 The branch you check out for 244 The branch you check out for
244 <filename>meta-intel</filename> must match the same 245 <filename>meta-intel</filename> must match the same
245 branch you are using for the Yocto Project release 246 branch you are using for the Yocto Project release
246 (e.g. &DISTRO_NAME_NO_CAP;): 247 (e.g. &DISTRO_NAME_NO_CAP;):
247 <literallayout class='monospaced'> 248 <literallayout class='monospaced'>
248 $ cd meta-intel 249 $ cd meta-intel
249 $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP; 250 $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP;
250 Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin. 251 Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin.
251 Switched to a new branch '&DISTRO_NAME_NO_CAP;' 252 Switched to a new branch '&DISTRO_NAME_NO_CAP;'
252 </literallayout> 253 </literallayout>
253 <note> 254 <note>
254 To see the available branch names in a cloned repository, 255 To see the available branch names in a cloned repository,
255 use the <filename>git branch -al</filename> command. 256 use the <filename>git branch -al</filename> command.
256 See the 257 See the
257 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>" 258 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>"
258 section in the Yocto Project Development Tasks 259 section in the Yocto Project Development Tasks
259 Manual for more information. 260 Manual for more information.
260 </note> 261 </note>
261 </para></listitem>
262 </orderedlist>
263 </para></listitem> 262 </para></listitem>
264 <listitem><para> 263 </orderedlist>
265 <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis> 264 </para></listitem>
266 If your hardware can be more closely leveraged to an 265 <listitem><para>
267 existing BSP not within the <filename>meta-intel</filename> 266 <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis>
268 BSP layer, you can clone that BSP layer.</para> 267 If your hardware can be more closely leveraged to an
269 268 existing BSP not within the <filename>meta-intel</filename>
270 <para>The process is identical to the process used for the 269 BSP layer, you can clone that BSP layer.</para>
271 <filename>meta-intel</filename> layer except for the layer's 270
272 name. 271 <para>The process is identical to the process used for the
273 For example, if you determine that your hardware most 272 <filename>meta-intel</filename> layer except for the layer's
274 closely matches the <filename>meta-raspberrypi</filename>, 273 name.
275 clone that layer: 274 For example, if you determine that your hardware most
276 <literallayout class='monospaced'> 275 closely matches the <filename>meta-raspberrypi</filename>,
276 clone that layer:
277 <literallayout class='monospaced'>
277 $ git clone git://git.yoctoproject.org/meta-raspberrypi 278 $ git clone git://git.yoctoproject.org/meta-raspberrypi
278 Cloning into 'meta-raspberrypi'... 279 Cloning into 'meta-raspberrypi'...
279 remote: Counting objects: 4743, done. 280 remote: Counting objects: 4743, done.
@@ -282,88 +283,88 @@
282 Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done. 283 Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done.
283 Resolving deltas: 100% (2447/2447), done. 284 Resolving deltas: 100% (2447/2447), done.
284 Checking connectivity... done. 285 Checking connectivity... done.
285 </literallayout> 286 </literallayout>
286 </para></listitem> 287 </para></listitem>
287 <listitem><para> 288 <listitem><para>
288 <emphasis>Initialize the Build Environment:</emphasis> 289 <emphasis>Initialize the Build Environment:</emphasis>
289 While in the root directory of the Source Directory (i.e. 290 While in the root directory of the Source Directory (i.e.
290 <filename>poky</filename>), run the 291 <filename>poky</filename>), run the
291 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> 292 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
292 environment setup script to define the OpenEmbedded 293 environment setup script to define the OpenEmbedded
293 build environment on your build host. 294 build environment on your build host.
294 <literallayout class='monospaced'>
295 $ source &OE_INIT_FILE;
296 </literallayout>
297 Among other things, the script creates the
298 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
299 which is <filename>build</filename> in this case
300 and is located in the
301 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
302 After the script runs, your current working directory
303 is set to the <filename>build</filename> directory.
304 </para></listitem>
305 </orderedlist>
306 </para>
307 </section>
308
309 <section id="bsp-filelayout">
310 <title>Example Filesystem Layout</title>
311
312 <para>
313 Defining a common BSP directory structure allows
314 end-users to understand and become familiar with
315 that standard.
316 A common format also encourages standardization
317 of software support for hardware.
318 </para>
319
320 <para>
321 The proposed form described in this section does
322 have elements that are specific to the OpenEmbedded
323 build system.
324 It is intended that developers can use this structure
325 with other build systems besides the OpenEmbedded build
326 system.
327 It is also intended that it will be be simple to extract
328 information and convert it to other formats if required.
329 The OpenEmbedded build system, through its standard
330 <ulink url='&YOCTO_DOCS_GS_URL;#the-yocto-project-layer-model'>layers mechanism</ulink>,
331 can directly accept the format described as a layer.
332 The BSP layer captures all the hardware-specific details
333 in one place using a standard format, which is useful
334 for any person wishing to use the hardware platform
335 regardless of the build system they are using.
336 </para>
337
338 <para>
339 The BSP specification does not include a build system
340 or other tools - the specification is concerned with
341 the hardware-specific components only.
342 At the end-distribution point, you can ship the BSP
343 layer combined with a build system and other tools.
344 Realize that it is important to maintain the distinction
345 that the BSP layer, a build system, and tools are
346 separate components that could to be combined in
347 certain end products.
348 </para>
349
350 <para>
351 Before looking at the common form for the file structure
352 inside a BSP Layer, you should be aware that some
353 requirements do exist in order for a BSP layer to
354 be considered compliant with the Yocto Project.
355 For that list of requirements, see the
356 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
357 section.
358 </para>
359
360 <para>
361 Below is the common form for the file structure
362 inside a BSP Layer.
363 While this basic form represents the standard,
364 realize that the actual file structures for specific
365 BSPs could differ.
366 <literallayout class='monospaced'> 295 <literallayout class='monospaced'>
296 $ source &OE_INIT_FILE;
297 </literallayout>
298 Among other things, the script creates the
299 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
300 which is <filename>build</filename> in this case
301 and is located in the
302 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
303 After the script runs, your current working directory
304 is set to the <filename>build</filename> directory.
305 </para></listitem>
306 </orderedlist>
307 </para>
308</section>
309
310<section id="bsp-filelayout">
311 <title>Example Filesystem Layout</title>
312
313 <para>
314 Defining a common BSP directory structure allows
315 end-users to understand and become familiar with
316 that standard.
317 A common format also encourages standardization
318 of software support for hardware.
319 </para>
320
321 <para>
322 The proposed form described in this section does
323 have elements that are specific to the OpenEmbedded
324 build system.
325 It is intended that developers can use this structure
326 with other build systems besides the OpenEmbedded build
327 system.
328 It is also intended that it will be be simple to extract
329 information and convert it to other formats if required.
330 The OpenEmbedded build system, through its standard
331 <ulink url='&YOCTO_DOCS_GS_URL;#the-yocto-project-layer-model'>layers mechanism</ulink>,
332 can directly accept the format described as a layer.
333 The BSP layer captures all the hardware-specific details
334 in one place using a standard format, which is useful
335 for any person wishing to use the hardware platform
336 regardless of the build system they are using.
337 </para>
338
339 <para>
340 The BSP specification does not include a build system
341 or other tools - the specification is concerned with
342 the hardware-specific components only.
343 At the end-distribution point, you can ship the BSP
344 layer combined with a build system and other tools.
345 Realize that it is important to maintain the distinction
346 that the BSP layer, a build system, and tools are
347 separate components that could to be combined in
348 certain end products.
349 </para>
350
351 <para>
352 Before looking at the common form for the file structure
353 inside a BSP Layer, you should be aware that some
354 requirements do exist in order for a BSP layer to
355 be considered compliant with the Yocto Project.
356 For that list of requirements, see the
357 "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
358 section.
359 </para>
360
361 <para>
362 Below is the common form for the file structure
363 inside a BSP Layer.
364 While this basic form represents the standard,
365 realize that the actual file structures for specific
366 BSPs could differ.
367 <literallayout class='monospaced'>
367 meta-<replaceable>bsp_name</replaceable>/ 368 meta-<replaceable>bsp_name</replaceable>/
368 meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> 369 meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
369 meta-<replaceable>bsp_name</replaceable>/README 370 meta-<replaceable>bsp_name</replaceable>/README
@@ -375,13 +376,13 @@
375 meta-<replaceable>bsp_name</replaceable>/recipes-core/* 376 meta-<replaceable>bsp_name</replaceable>/recipes-core/*
376 meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* 377 meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
377 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend 378 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend
378 </literallayout> 379 </literallayout>
379 </para> 380 </para>
380 381
381 <para> 382 <para>
382 Below is an example of the Raspberry Pi BSP 383 Below is an example of the Raspberry Pi BSP
383 layer that ships with the Yocto Project: 384 layer that ships with the Yocto Project:
384 <literallayout class='monospaced'> 385 <literallayout class='monospaced'>
385 meta-raspberrypi/COPYING.MIT 386 meta-raspberrypi/COPYING.MIT
386 meta-raspberrypi/README.md 387 meta-raspberrypi/README.md
387 meta-raspberrypi/classes 388 meta-raspberrypi/classes
@@ -535,167 +536,167 @@
535 meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend 536 meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend
536 meta-raspberrypi/wic 537 meta-raspberrypi/wic
537 meta-raspberrypi/wic/sdimage-raspberrypi.wks 538 meta-raspberrypi/wic/sdimage-raspberrypi.wks
538 </literallayout> 539 </literallayout>
539 </para> 540 </para>
540 541
541 <para> 542 <para>
542 The following sections describe each part of the proposed 543 The following sections describe each part of the proposed
543 BSP format. 544 BSP format.
544 </para> 545 </para>
545 546
546 <section id="bsp-filelayout-license"> 547 <section id="bsp-filelayout-license">
547 <title>License Files</title> 548 <title>License Files</title>
548 549
549 <para> 550 <para>
550 You can find these files in the BSP Layer at: 551 You can find these files in the BSP Layer at:
551 <literallayout class='monospaced'> 552 <literallayout class='monospaced'>
552 meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> 553 meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
553 </literallayout> 554 </literallayout>
554 </para> 555 </para>
555 556
556 <para> 557 <para>
557 These optional files satisfy licensing requirements 558 These optional files satisfy licensing requirements
558 for the BSP. 559 for the BSP.
559 The type or types of files here can vary depending 560 The type or types of files here can vary depending
560 on the licensing requirements. 561 on the licensing requirements.
561 For example, in the Raspberry Pi BSP all licensing 562 For example, in the Raspberry Pi BSP all licensing
562 requirements are handled with the 563 requirements are handled with the
563 <filename>COPYING.MIT</filename> file. 564 <filename>COPYING.MIT</filename> file.
564 </para> 565 </para>
565 566
566 <para> 567 <para>
567 Licensing files can be MIT, BSD, GPLv*, and so forth. 568 Licensing files can be MIT, BSD, GPLv*, and so forth.
568 These files are recommended for the BSP but are 569 These files are recommended for the BSP but are
569 optional and totally up to the BSP developer. 570 optional and totally up to the BSP developer.
570 For information on how to maintain license 571 For information on how to maintain license
571 compliance, see the 572 compliance, see the
572 "<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>" 573 "<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>"
573 section in the Yocto Project Development Tasks 574 section in the Yocto Project Development Tasks
574 Manual. 575 Manual.
575 </para> 576 </para>
576 </section> 577 </section>
577 578
578 <section id="bsp-filelayout-readme"> 579 <section id="bsp-filelayout-readme">
579 <title>README File</title> 580 <title>README File</title>
580 581
581 <para> 582 <para>
582 You can find this file in the BSP Layer at: 583 You can find this file in the BSP Layer at:
583 <literallayout class='monospaced'> 584 <literallayout class='monospaced'>
584 meta-<replaceable>bsp_name</replaceable>/README 585 meta-<replaceable>bsp_name</replaceable>/README
585 </literallayout> 586 </literallayout>
586 </para> 587 </para>
587 588
588 <para> 589 <para>
589 This file provides information on how to boot the live 590 This file provides information on how to boot the live
590 images that are optionally included in the 591 images that are optionally included in the
591 <filename>binary/</filename> directory. 592 <filename>binary/</filename> directory.
592 The <filename>README</filename> file also provides 593 The <filename>README</filename> file also provides
593 information needed for building the image. 594 information needed for building the image.
594 </para> 595 </para>
595 596
596 <para> 597 <para>
597 At a minimum, the <filename>README</filename> file must 598 At a minimum, the <filename>README</filename> file must
598 contain a list of dependencies, such as the names of 599 contain a list of dependencies, such as the names of
599 any other layers on which the BSP depends and the name of 600 any other layers on which the BSP depends and the name of
600 the BSP maintainer with his or her contact information. 601 the BSP maintainer with his or her contact information.
601 </para> 602 </para>
602 </section> 603 </section>
603 604
604 <section id="bsp-filelayout-readme-sources"> 605 <section id="bsp-filelayout-readme-sources">
605 <title>README.sources File</title> 606 <title>README.sources File</title>
606 607
607 <para> 608 <para>
608 You can find this file in the BSP Layer at: 609 You can find this file in the BSP Layer at:
609 <literallayout class='monospaced'> 610 <literallayout class='monospaced'>
610 meta-<replaceable>bsp_name</replaceable>/README.sources 611 meta-<replaceable>bsp_name</replaceable>/README.sources
611 </literallayout> 612 </literallayout>
612 </para> 613 </para>
613 614
614 <para> 615 <para>
615 This file provides information on where to locate the BSP 616 This file provides information on where to locate the BSP
616 source files used to build the images (if any) that 617 source files used to build the images (if any) that
617 reside in 618 reside in
618 <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>. 619 <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>.
619 Images in the <filename>binary</filename> would be images 620 Images in the <filename>binary</filename> would be images
620 released with the BSP. 621 released with the BSP.
621 The information in the <filename>README.sources</filename> 622 The information in the <filename>README.sources</filename>
622 file also helps you find the 623 file also helps you find the
623 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> 624 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
624 used to generate the images that ship with the BSP. 625 used to generate the images that ship with the BSP.
625 <note> 626 <note>
626 If the BSP's <filename>binary</filename> directory is 627 If the BSP's <filename>binary</filename> directory is
627 missing or the directory has no images, an existing 628 missing or the directory has no images, an existing
628 <filename>README.sources</filename> file is 629 <filename>README.sources</filename> file is
629 meaningless and usually does not exist. 630 meaningless and usually does not exist.
630 </note> 631 </note>
631 </para> 632 </para>
632 </section> 633 </section>
633 634
634 <section id="bsp-filelayout-binary"> 635 <section id="bsp-filelayout-binary">
635 <title>Pre-built User Binaries</title> 636 <title>Pre-built User Binaries</title>
636 637
637 <para> 638 <para>
638 You can find these files in the BSP Layer at: 639 You can find these files in the BSP Layer at:
639 <literallayout class='monospaced'> 640 <literallayout class='monospaced'>
640 meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable> 641 meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
641 </literallayout> 642 </literallayout>
642 </para> 643 </para>
643 644
644 <para> 645 <para>
645 This optional area contains useful pre-built kernels 646 This optional area contains useful pre-built kernels
646 and user-space filesystem images released with the 647 and user-space filesystem images released with the
647 BSP that are appropriate to the target system. 648 BSP that are appropriate to the target system.
648 This directory typically contains graphical (e.g. Sato) 649 This directory typically contains graphical (e.g. Sato)
649 and minimal live images when the BSP tarball has been 650 and minimal live images when the BSP tarball has been
650 created and made available in the 651 created and made available in the
651 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> 652 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink>
652 website. 653 website.
653 You can use these kernels and images to get a system 654 You can use these kernels and images to get a system
654 running and quickly get started on development tasks. 655 running and quickly get started on development tasks.
655 </para> 656 </para>
656 657
657 <para> 658 <para>
658 The exact types of binaries present are highly 659 The exact types of binaries present are highly
659 hardware-dependent. 660 hardware-dependent.
660 The 661 The
661 <link linkend='bsp-filelayout-readme'><filename>README</filename></link> 662 <link linkend='bsp-filelayout-readme'><filename>README</filename></link>
662 file should be present in the BSP Layer and it 663 file should be present in the BSP Layer and it
663 explains how to use the images with the target hardware. 664 explains how to use the images with the target hardware.
664 Additionally, the 665 Additionally, the
665 <link linkend='bsp-filelayout-readme-sources'><filename>README.sources</filename></link> 666 <link linkend='bsp-filelayout-readme-sources'><filename>README.sources</filename></link>
666 file should be present to locate the sources used to 667 file should be present to locate the sources used to
667 build the images and provide information on the 668 build the images and provide information on the
668 Metadata. 669 Metadata.
669 </para> 670 </para>
670 </section> 671 </section>
671 672
672 <section id='bsp-filelayout-layer'> 673 <section id='bsp-filelayout-layer'>
673 <title>Layer Configuration File</title> 674 <title>Layer Configuration File</title>
674 675
675 <para> 676 <para>
676 You can find this file in the BSP Layer at: 677 You can find this file in the BSP Layer at:
677 <literallayout class='monospaced'> 678 <literallayout class='monospaced'>
678 meta-<replaceable>bsp_name</replaceable>/conf/layer.conf 679 meta-<replaceable>bsp_name</replaceable>/conf/layer.conf
679 </literallayout> 680 </literallayout>
680 </para> 681 </para>
681 682
682 <para> 683 <para>
683 The <filename>conf/layer.conf</filename> file 684 The <filename>conf/layer.conf</filename> file
684 identifies the file structure as a layer, 685 identifies the file structure as a layer,
685 identifies the contents of the layer, and 686 identifies the contents of the layer, and
686 contains information about how the build system should 687 contains information about how the build system should
687 use it. 688 use it.
688 Generally, a standard boilerplate file such as the 689 Generally, a standard boilerplate file such as the
689 following works. 690 following works.
690 In the following example, you would replace 691 In the following example, you would replace
691 <replaceable>bsp</replaceable> with the actual 692 <replaceable>bsp</replaceable> with the actual
692 name of the BSP (i.e. 693 name of the BSP (i.e.
693 <replaceable>bsp_name</replaceable> from the example 694 <replaceable>bsp_name</replaceable> from the example
694 template). 695 template).
695 </para> 696 </para>
696 697
697 <para> 698 <para>
698 <literallayout class='monospaced'> 699 <literallayout class='monospaced'>
699 # We have a conf and classes directory, add to BBPATH 700 # We have a conf and classes directory, add to BBPATH
700 BBPATH .= ":${LAYERDIR}" 701 BBPATH .= ":${LAYERDIR}"
701 702
@@ -708,14 +709,14 @@
708 BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6" 709 BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6"
709 710
710 LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel" 711 LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel"
711 </literallayout> 712 </literallayout>
712 </para> 713 </para>
713 714
714 <para> 715 <para>
715 To illustrate the string substitutions, here are 716 To illustrate the string substitutions, here are
716 the corresponding statements from the Raspberry 717 the corresponding statements from the Raspberry
717 Pi <filename>conf/layer.conf</filename> file: 718 Pi <filename>conf/layer.conf</filename> file:
718 <literallayout class='monospaced'> 719 <literallayout class='monospaced'>
719 # We have a conf and classes directory, append to BBPATH 720 # We have a conf and classes directory, append to BBPATH
720 BBPATH .= ":${LAYERDIR}" 721 BBPATH .= ":${LAYERDIR}"
721 722
@@ -732,1429 +733,1098 @@
732 . 733 .
733 . 734 .
734 . 735 .
735 </literallayout> 736 </literallayout>
736 </para> 737 </para>
737 738
738 <para> 739 <para>
739 This file simply makes 740 This file simply makes
740 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> 741 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
741 aware of the recipes and configuration directories. 742 aware of the recipes and configuration directories.
742 The file must exist so that the OpenEmbedded build system 743 The file must exist so that the OpenEmbedded build system
743 can recognize the BSP. 744 can recognize the BSP.
744 </para> 745 </para>
745 </section> 746 </section>
746 747
747 <section id="bsp-filelayout-machine"> 748 <section id="bsp-filelayout-machine">
748 <title>Hardware Configuration Options</title> 749 <title>Hardware Configuration Options</title>
749 750
750 <para> 751 <para>
751 You can find these files in the BSP Layer at: 752 You can find these files in the BSP Layer at:
752 <literallayout class='monospaced'> 753 <literallayout class='monospaced'>
753 meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf 754 meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf
754 </literallayout> 755 </literallayout>
755 </para> 756 </para>
756 757
757 <para> 758 <para>
758 The machine files bind together all the information 759 The machine files bind together all the information
759 contained elsewhere in the BSP into a format that 760 contained elsewhere in the BSP into a format that
760 the build system can understand. 761 the build system can understand.
761 Each BSP Layer requires at least one machine file. 762 Each BSP Layer requires at least one machine file.
762 If the BSP supports multiple machines, multiple 763 If the BSP supports multiple machines, multiple
763 machine configuration files can exist. 764 machine configuration files can exist.
764 These filenames correspond to the values to which 765 These filenames correspond to the values to which
765 users have set the 766 users have set the
766 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable. 767 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
767 </para> 768 </para>
768 769
769 <para> 770 <para>
770 These files define things such as the kernel package 771 These files define things such as the kernel package
771 to use 772 to use
772 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> 773 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
773 of 774 of
774 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>virtual/kernel</ulink>), 775 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>virtual/kernel</ulink>),
775 the hardware drivers to include in different types 776 the hardware drivers to include in different types
776 of images, any special software components that are 777 of images, any special software components that are
777 needed, any bootloader information, and also any 778 needed, any bootloader information, and also any
778 special image format requirements. 779 special image format requirements.
779 </para> 780 </para>
780 781
781 <para> 782 <para>
782 This configuration file could also include a hardware 783 This configuration file could also include a hardware
783 "tuning" file that is commonly used to define the 784 "tuning" file that is commonly used to define the
784 package architecture and specify optimization flags, 785 package architecture and specify optimization flags,
785 which are carefully chosen to give best performance 786 which are carefully chosen to give best performance
786 on a given processor. 787 on a given processor.
787 </para> 788 </para>
788 789
789 <para> 790 <para>
790 Tuning files are found in the 791 Tuning files are found in the
791 <filename>meta/conf/machine/include</filename> 792 <filename>meta/conf/machine/include</filename>
792 directory within the 793 directory within the
793 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. 794 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
794 For example, many <filename>tune-*</filename> files 795 For example, many <filename>tune-*</filename> files
795 (e.g. <filename>tune-arm1136jf-s.inc</filename>, 796 (e.g. <filename>tune-arm1136jf-s.inc</filename>,
796 <filename>tun-1586-nlp.inc</filename>, and so forth) 797 <filename>tun-1586-nlp.inc</filename>, and so forth)
797 reside in the 798 reside in the
798 <filename>poky/meta/conf/machine/include</filename> 799 <filename>poky/meta/conf/machine/include</filename>
799 directory. 800 directory.
800 </para> 801 </para>
801 802
802 <para> 803 <para>
803 To use an include file, you simply include them in the 804 To use an include file, you simply include them in the
804 machine configuration file. 805 machine configuration file.
805 For example, the Raspberry Pi BSP 806 For example, the Raspberry Pi BSP
806 <filename>raspberrypi3.conf</filename> contains the 807 <filename>raspberrypi3.conf</filename> contains the
807 following statement: 808 following statement:
808 <literallayout class='monospaced'> 809 <literallayout class='monospaced'>
809 include conf/machine/include/rpi-base.inc 810 include conf/machine/include/rpi-base.inc
810 </literallayout> 811 </literallayout>
811 </para> 812 </para>
812 </section> 813 </section>
813 814
814 <section id='bsp-filelayout-misc-recipes'> 815 <section id='bsp-filelayout-misc-recipes'>
815 <title>Miscellaneous BSP-Specific Recipe Files</title> 816 <title>Miscellaneous BSP-Specific Recipe Files</title>
816 817
817 <para> 818 <para>
818 You can find these files in the BSP Layer at: 819 You can find these files in the BSP Layer at:
819 <literallayout class='monospaced'> 820 <literallayout class='monospaced'>
820 meta-<replaceable>bsp_name</replaceable>/recipes-bsp/* 821 meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
821 </literallayout> 822 </literallayout>
822 </para> 823 </para>
823 824
824 <para> 825 <para>
825 This optional directory contains miscellaneous recipe 826 This optional directory contains miscellaneous recipe
826 files for the BSP. 827 files for the BSP.
827 Most notably would be the formfactor files. 828 Most notably would be the formfactor files.
828 For example, in the Raspberry Pi BSP there is the 829 For example, in the Raspberry Pi BSP there is the
829 <filename>formfactor_0.0.bbappend</filename> file, 830 <filename>formfactor_0.0.bbappend</filename> file,
830 which is an append file used to augment the recipe 831 which is an append file used to augment the recipe
831 that starts the build. 832 that starts the build.
832 Furthermore, there are machine-specific settings used 833 Furthermore, there are machine-specific settings used
833 during the build that are defined by the 834 during the build that are defined by the
834 <filename>machconfig</filename> file further down in 835 <filename>machconfig</filename> file further down in
835 the directory. 836 the directory.
836 Here is the <filename>machconfig</filename> file for 837 Here is the <filename>machconfig</filename> file for
837 the Raspberry Pi BSP: 838 the Raspberry Pi BSP:
838 <literallayout class='monospaced'> 839 <literallayout class='monospaced'>
839 HAVE_TOUCHSCREEN=0 840 HAVE_TOUCHSCREEN=0
840 HAVE_KEYBOARD=1 841 HAVE_KEYBOARD=1
841 842
842 DISPLAY_CAN_ROTATE=0 843 DISPLAY_CAN_ROTATE=0
843 DISPLAY_ORIENTATION=0 844 DISPLAY_ORIENTATION=0
844 DISPLAY_DPI=133 845 DISPLAY_DPI=133
845 </literallayout> 846 </literallayout>
846 </para> 847 </para>
847 848
848 <note><para> 849 <note><para>
849 If a BSP does not have a formfactor entry, defaults 850 If a BSP does not have a formfactor entry, defaults
850 are established according to the formfactor 851 are established according to the formfactor
851 configuration file that is installed by the main 852 configuration file that is installed by the main
852 formfactor recipe 853 formfactor recipe
853 <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>, 854 <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
854 which is found in the 855 which is found in the
855 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. 856 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
856 </para></note> 857 </para></note>
857 </section> 858 </section>
858 859
859 <section id='bsp-filelayout-recipes-graphics'> 860 <section id='bsp-filelayout-recipes-graphics'>
860 <title>Display Support Files</title> 861 <title>Display Support Files</title>
861 862
862 <para> 863 <para>
863 You can find these files in the BSP Layer at: 864 You can find these files in the BSP Layer at:
864 <literallayout class='monospaced'> 865 <literallayout class='monospaced'>
865 meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* 866 meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
866 </literallayout> 867 </literallayout>
867 </para> 868 </para>
868 869
869 <para> 870 <para>
870 This optional directory contains recipes for the 871 This optional directory contains recipes for the
871 BSP if it has special requirements for graphics 872 BSP if it has special requirements for graphics
872 support. 873 support.
873 All files that are needed for the BSP to support 874 All files that are needed for the BSP to support
874 a display are kept here. 875 a display are kept here.
875 </para> 876 </para>
876 </section> 877 </section>
877 878
878 <section id='bsp-filelayout-kernel'> 879 <section id='bsp-filelayout-kernel'>
879 <title>Linux Kernel Configuration</title> 880 <title>Linux Kernel Configuration</title>
880 881
881 <para> 882 <para>
882 You can find these files in the BSP Layer at: 883 You can find these files in the BSP Layer at:
883 <literallayout class='monospaced'> 884 <literallayout class='monospaced'>
884 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend 885 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend
885 </literallayout> 886 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/*.bb
886 </para> 887 </literallayout>
888 </para>
887 889
888 <para> 890 <para>
889 These files append machine-specific changes to the main 891 Append files (<filename>*.bbappend</filename> modify
890 kernel recipe you are using. 892 the main kernel recipe being used to build the image.
891 </para> 893 The <filename>*.bb</filename> files would be a
894 developer-supplied recipe.
895 This area of the BSP hierarchy can contain both these
896 types of files.
897 </para>
892 898
893 <para> 899 <para>
894 For your BSP, you typically want to use an existing Yocto 900 For your BSP, you typically want to use an existing Yocto
895 Project kernel recipe found in the 901 Project kernel recipe found in the
896 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> 902 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
897 at <filename>meta/recipes-kernel/linux</filename>. 903 at <filename>meta/recipes-kernel/linux</filename>.
898 You can append machine-specific changes to the 904 You can append machine-specific changes to the
899 kernel recipe by using a similarly named append 905 kernel recipe by using a similarly named append
900 file, which is located in the BSP Layer for your 906 file, which is located in the BSP Layer for your
901 target device (e.g. the 907 target device (e.g. the
902 <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory). 908 <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory).
903 </para> 909 </para>
904 910
905 <para> 911 <para>
906 Suppose you are using the 912 Suppose you are using the
907 <filename>linux-yocto_4.4.bb</filename> recipe to 913 <filename>linux-yocto_4.4.bb</filename> recipe to
908 build the kernel. 914 build the kernel.
909 In other words, you have selected the kernel in your 915 In other words, you have selected the kernel in your
910 <replaceable>bsp_name</replaceable><filename>.conf</filename> 916 <replaceable>bsp_name</replaceable><filename>.conf</filename>
911 file by adding 917 file by adding
912 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> 918 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
913 and 919 and
914 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink> 920 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
915 statements as follows: 921 statements as follows:
916 <literallayout class='monospaced'> 922 <literallayout class='monospaced'>
917 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" 923 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
918 PREFERRED_VERSION_linux-yocto ?= "4.4%" 924 PREFERRED_VERSION_linux-yocto ?= "4.4%"
919 </literallayout> 925 </literallayout>
920 <note> 926 <note>
921 When the preferred provider is assumed by 927 When the preferred provider is assumed by
922 default, the 928 default, the
923 <filename>PREFERRED_PROVIDER</filename> 929 <filename>PREFERRED_PROVIDER</filename>
924 statement does not appear in the 930 statement does not appear in the
925 <replaceable>bsp_name</replaceable><filename>.conf</filename> file. 931 <replaceable>bsp_name</replaceable><filename>.conf</filename> file.
926 </note> 932 </note>
927 You would use the 933 You would use the
928 <filename>linux-yocto_4.4.bbappend</filename> 934 <filename>linux-yocto_4.4.bbappend</filename>
929 file to append specific BSP settings to the kernel, 935 file to append specific BSP settings to the kernel,
930 thus configuring the kernel for your particular BSP. 936 thus configuring the kernel for your particular BSP.
931 </para> 937 </para>
932
933 <para>
934 You can find more information on what your append file
935 should contain in the
936 "<ulink url='&YOCTO_DOCS_KERNEL_URL;#creating-the-append-file'>Creating the Append File</ulink>"
937 section in the Yocto Project Linux Kernel Development
938 Manual.
939 </para>
940 </section>
941 </section>
942
943 <section id='developing-a-board-support-package-bsp'>
944 <title>Developing a Board Support Package (BSP)</title>
945
946 <para>
947 This section contains the high-level procedure you can
948 follow to create a BSP using the Yocto Project's
949 <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
950 Although not required for BSP creation, the
951 <filename>meta-intel</filename> repository, which
952 contains many BSPs supported by the Yocto Project,
953 is part of the example.
954 </para>
955
956 <para>
957 For an example that shows how to create a new
958 layer using the tools, see the
959 "<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>"
960 section.
961 </para>
962
963 <para>
964 The following illustration and list summarize the BSP
965 creation general workflow.
966 </para>
967
968 <para>
969 <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" />
970 </para>
971 938
972 <para> 939 <para>
973 <orderedlist> 940 You can find more information on what your append file
974 <listitem><para> 941 should contain in the
975 <emphasis>Set up Your Host Development System 942 "<ulink url='&YOCTO_DOCS_KERNEL_URL;#creating-the-append-file'>Creating the Append File</ulink>"
976 to Support Development Using the Yocto 943 section in the Yocto Project Linux Kernel Development
977 Project</emphasis>: 944 Manual.
978 See the 945 </para>
979 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
980 section in the Yocto Project Development Tasks
981 Manual for options on how to get a system ready
982 to use the Yocto Project.
983 </para></listitem>
984 <listitem><para>
985 <emphasis>Establish the
986 <filename>meta-intel</filename>
987 Repository on Your System:</emphasis>
988 Having local copies of these supported BSP layers
989 on your system gives you access to layers you
990 might be able to leverage when creating your BSP.
991 For information on how to get these files, see the
992 "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>"
993 section.
994 </para></listitem>
995 <listitem><para>
996 <emphasis>Create Your Own BSP Layer Using the
997 <filename>bitbake-layers</filename>
998 Script:</emphasis>
999 Layers are ideal for isolating and storing work
1000 for a given piece of hardware.
1001 A layer is really just a location or area in which you
1002 place the recipes and configurations for your BSP.
1003 In fact, a BSP is, in itself, a special type of layer.
1004 The simplest way to create a new BSP layer that is
1005 compliant with the Yocto Project is to use the
1006 <filename>bitbake-layers</filename> script.
1007 For information about that script, see the
1008 "<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>"
1009 section.</para>
1010
1011 <para>Another example that illustrates a layer
1012 is an application.
1013 Suppose you are creating an application that has
1014 library or other dependencies in order for it to
1015 compile and run.
1016 The layer, in this case, would be where all the
1017 recipes that define those dependencies are kept.
1018 The key point for a layer is that it is an
1019 isolated area that contains all the relevant
1020 information for the project that the
1021 OpenEmbedded build system knows about.
1022 For more information on layers, see the
1023 "<ulink url='&YOCTO_DOCS_GS_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
1024 section in the Getting Started With Yocto Project
1025 Manual.
1026 You can also reference the
1027 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
1028 section in the Yocto Project Development Tasks
1029 Manual.
1030 For more information on BSP layers, see the
1031 "<link linkend='bsp-layers'>BSP Layers</link>"
1032 section.
1033 <note><title>Notes</title>
1034 <itemizedlist>
1035 <listitem><para>
1036 Five hardware reference BSPs exist
1037 that are part of the Yocto Project release
1038 and are located in the
1039 <filename>poky/meta-yocto-bsp</filename> BSP
1040 layer:
1041 <itemizedlist>
1042 <listitem><para>
1043 Texas Instruments Beaglebone
1044 (<filename>beaglebone-yocto</filename>
1045 </para></listitem>
1046 <listitem><para>
1047 Freescale MPC8315E-RDB
1048 (<filename>mpc8315e-rdb</filename>)
1049 </para></listitem>
1050 <listitem><para>
1051 Ubiquiti Networks EdgeRouter Lite
1052 (<filename>edgerouter</filename>)
1053 </para></listitem>
1054 <listitem><para>
1055 Two general IA platforms
1056 (<filename>genericx86</filename> and
1057 <filename>genericx86-64</filename>)
1058 </para></listitem>
1059 </itemizedlist>
1060 </para></listitem>
1061 <listitem><para>
1062 Three core Intel BSPs exist as part of
1063 the Yocto Project release in the
1064 <filename>meta-intel</filename> layer:
1065 <itemizedlist>
1066 <listitem><para>
1067 <filename>intel-core2-32</filename>,
1068 which is a BSP optimized for the Core2
1069 family of CPUs as well as all CPUs
1070 prior to the Silvermont core.
1071 </para></listitem>
1072 <listitem><para>
1073 <filename>intel-corei7-64</filename>,
1074 which is a BSP optimized for Nehalem
1075 and later Core and Xeon CPUs as well
1076 as Silvermont and later Atom CPUs,
1077 such as the Baytrail SoCs.
1078 </para></listitem>
1079 <listitem><para>
1080 <filename>intel-quark</filename>,
1081 which is a BSP optimized for the
1082 Intel Galileo gen1 &amp; gen2
1083 development boards.
1084 </para></listitem>
1085 </itemizedlist>
1086 </para></listitem>
1087 </itemizedlist>
1088 </note></para>
1089
1090 <para>When you set up a layer for a new BSP,
1091 you should follow a standard layout.
1092 This layout is described in the
1093 "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>"
1094 section.
1095 In the standard layout, notice the suggested
1096 structure for recipes and configuration
1097 information.
1098 You can see the standard layout for a BSP
1099 by examining any supported BSP found in the
1100 <filename>meta-intel</filename> layer inside
1101 the Source Directory.
1102 </para></listitem>
1103 <listitem><para>
1104 <emphasis>Make Configuration Changes to Your New
1105 BSP Layer:</emphasis>
1106 The standard BSP layer structure organizes the
1107 files you need to edit in
1108 <filename>conf</filename> and several
1109 <filename>recipes-*</filename> directories
1110 within the BSP layer.
1111 Configuration changes identify where your new
1112 layer is on the local system and identifies the
1113 kernel you are going to use.
1114 When you run the
1115 <filename>bitbake-layers</filename> script,
1116 you are able to interactively configure many
1117 things for the BSP (e.g. keyboard, touchscreen,
1118 and so forth).
1119 </para></listitem>
1120 <listitem><para>
1121 <emphasis>Make Recipe Changes to Your New BSP
1122 Layer:</emphasis>
1123 Recipe changes include altering recipes
1124 (<filename>*.bb</filename> files), removing
1125 recipes you do not use, and adding new recipes
1126 or append files (<filename>.bbappend</filename>)
1127 that support your hardware.
1128 </para></listitem>
1129 <listitem><para>
1130 <emphasis>Prepare for the Build:</emphasis>
1131 Once you have made all the changes to your BSP
1132 layer, there remains a few things you need to
1133 do for the OpenEmbedded build system in order
1134 for it to create your image.
1135 You need to get the build environment ready by
1136 sourcing an environment setup script
1137 (i.e. <filename>oe-init-build-env</filename>)
1138 and you need to be sure two key configuration
1139 files are configured appropriately: the
1140 <filename>conf/local.conf</filename> and the
1141 <filename>conf/bblayers.conf</filename> file.
1142 You must make the OpenEmbedded build system aware
1143 of your new layer.
1144 See the
1145 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
1146 section in the Yocto Project Development Tasks Manual
1147 for information on how to let the build system
1148 know about your new layer.
1149 </para></listitem>
1150 <listitem><para>
1151 <emphasis>Build the Image:</emphasis>
1152 The OpenEmbedded build system uses the BitBake tool
1153 to build images based on the type of image you want to
1154 create.
1155 You can find more information about BitBake in the
1156 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
1157 </para>
1158
1159 <para>The build process supports several types of
1160 images to satisfy different needs.
1161 See the
1162 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1163 chapter in the Yocto Project Reference Manual for
1164 information on supported images.
1165 </para></listitem>
1166 </orderedlist>
1167 </para>
1168 </section>
1169
1170 <section id='requirements-and-recommendations-for-released-bsps'>
1171 <title>Requirements and Recommendations for Released BSPs</title>
1172
1173 <para>
1174 Certain requirements exist for a released BSP to be
1175 considered compliant with the Yocto Project.
1176 Additionally, recommendations also exist.
1177 This section describes the requirements and
1178 recommendations for released BSPs.
1179 </para>
1180
1181 <section id='released-bsp-requirements'>
1182 <title>Released BSP Requirements</title>
1183
1184 <para>
1185 Before looking at BSP requirements, you should consider
1186 the following:
1187 <itemizedlist>
1188 <listitem><para>
1189 The requirements here assume the BSP layer
1190 is a well-formed, "legal" layer that can be
1191 added to the Yocto Project.
1192 For guidelines on creating a layer that meets
1193 these base requirements, see the
1194 "<link linkend='bsp-layers'>BSP Layers</link>"
1195 section in this manual and the
1196 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers"</ulink>"
1197 section in the Yocto Project Development Tasks
1198 Manual.
1199 </para></listitem>
1200 <listitem><para>
1201 The requirements in this section apply
1202 regardless of how you package a BSP.
1203 You should consult the packaging and distribution
1204 guidelines for your specific release process.
1205 For an example of packaging and distribution
1206 requirements, see the
1207 "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
1208 wiki page.
1209 </para></listitem>
1210 <listitem><para>
1211 The requirements for the BSP as it is made
1212 available to a developer are completely
1213 independent of the released form of the BSP.
1214 For example, the BSP Metadata can be contained
1215 within a Git repository and could have a directory
1216 structure completely different from what appears
1217 in the officially released BSP layer.
1218 </para></listitem>
1219 <listitem><para>
1220 It is not required that specific packages or
1221 package modifications exist in the BSP layer,
1222 beyond the requirements for general
1223 compliance with the Yocto Project.
1224 For example, no requirement exists dictating
1225 that a specific kernel or kernel version be
1226 used in a given BSP.
1227 </para></listitem>
1228 </itemizedlist>
1229 </para>
1230 946
1231 <para> 947 <para>
1232 Following are the requirements for a released BSP 948 An alternate scenario is when you create your own
1233 that conform to the Yocto Project: 949 kernel recipe for the BSP.
950 A good example of this is the Raspberry Pi BSP.
951 If you examine the
952 <filename>recipes-kernel/linux</filename> directory
953 you see the following:
954 <literallayout class='monospaced'>
955 linux-raspberrypi-dev.bb
956 linux-raspberrypi.inc
957 linux-raspberrypi_4.14.bb
958 linux-raspberrypi_4.9.bb
959 </literallayout>
960 The directory contains three kernel recipes and an
961 include file.
962 </para>
963 </section>
964</section>
965
966<section id='developing-a-board-support-package-bsp'>
967 <title>Developing a Board Support Package (BSP)</title>
968
969 <para>
970 This section contains the high-level procedure you can
971 follow to create a BSP.
972 Although not required for BSP creation, the
973 <filename>meta-intel</filename> repository, which
974 contains many BSPs supported by the Yocto Project,
975 is part of the example.
976 </para>
977
978 <para>
979 For an example that shows how to create a new
980 layer using the tools, see the
981 "<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>"
982 section.
983 </para>
984
985 <para>
986 The following illustration and list summarize the BSP
987 creation general workflow.
988 </para>
989
990 <para>
991 <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" />
992 </para>
993
994 <para>
995 <orderedlist>
996 <listitem><para>
997 <emphasis>Set up Your Host Development System
998 to Support Development Using the Yocto
999 Project</emphasis>:
1000 See the
1001 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
1002 section in the Yocto Project Development Tasks
1003 Manual for options on how to get a system ready
1004 to use the Yocto Project.
1005 </para></listitem>
1006 <listitem><para>
1007 <emphasis>Establish the
1008 <filename>meta-intel</filename>
1009 Repository on Your System:</emphasis>
1010 Having local copies of these supported BSP layers
1011 on your system gives you access to layers you
1012 might be able to leverage when creating your BSP.
1013 For information on how to get these files, see the
1014 "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>"
1015 section.
1016 </para></listitem>
1017 <listitem><para>
1018 <emphasis>Create Your Own BSP Layer Using the
1019 <filename>bitbake-layers</filename>
1020 Script:</emphasis>
1021 Layers are ideal for isolating and storing work
1022 for a given piece of hardware.
1023 A layer is really just a location or area in which you
1024 place the recipes and configurations for your BSP.
1025 In fact, a BSP is, in itself, a special type of layer.
1026 The simplest way to create a new BSP layer that is
1027 compliant with the Yocto Project is to use the
1028 <filename>bitbake-layers</filename> script.
1029 For information about that script, see the
1030 "<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>"
1031 section.</para>
1032
1033 <para>Another example that illustrates a layer
1034 is an application.
1035 Suppose you are creating an application that has
1036 library or other dependencies in order for it to
1037 compile and run.
1038 The layer, in this case, would be where all the
1039 recipes that define those dependencies are kept.
1040 The key point for a layer is that it is an
1041 isolated area that contains all the relevant
1042 information for the project that the
1043 OpenEmbedded build system knows about.
1044 For more information on layers, see the
1045 "<ulink url='&YOCTO_DOCS_GS_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
1046 section in the Getting Started With Yocto Project
1047 Manual.
1048 You can also reference the
1049 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
1050 section in the Yocto Project Development Tasks
1051 Manual.
1052 For more information on BSP layers, see the
1053 "<link linkend='bsp-layers'>BSP Layers</link>"
1054 section.
1055 <note><title>Notes</title>
1234 <itemizedlist> 1056 <itemizedlist>
1235 <listitem><para> 1057 <listitem><para>
1236 <emphasis>Layer Name:</emphasis> 1058 Five hardware reference BSPs exist
1237 The BSP must have a layer name that follows 1059 that are part of the Yocto Project release
1238 the Yocto Project standards. 1060 and are located in the
1239 For information on BSP layer names, see the 1061 <filename>poky/meta-yocto-bsp</filename> BSP
1240 "<link linkend='bsp-layers'>BSP Layers</link>" section. 1062 layer:
1241 </para></listitem>
1242 <listitem><para>
1243 <emphasis>File System Layout:</emphasis>
1244 When possible, use the same directory names
1245 in your BSP layer as listed in the
1246 <filename>recipes.txt</filename> file, which
1247 is found in <filename>poky/meta</filename>
1248 directory of the
1249 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
1250 or in the OpenEmbedded Core Layer
1251 (<filename>openembedded-core</filename>) at
1252 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
1253 </para>
1254
1255 <para>You should place recipes
1256 (<filename>*.bb</filename> files) and recipe
1257 modifications (<filename>*.bbappend</filename>
1258 files) into <filename>recipes-*</filename>
1259 subdirectories by functional area as outlined
1260 in <filename>recipes.txt</filename>.
1261 If you cannot find a category in
1262 <filename>recipes.txt</filename> to fit a
1263 particular recipe, you can make up your own
1264 <filename>recipes-*</filename> subdirectory.
1265 </para>
1266
1267 <para>Within any particular
1268 <filename>recipes-*</filename> category, the
1269 layout should match what is found in the
1270 OpenEmbedded Core Git repository
1271 (<filename>openembedded-core</filename>)
1272 or the Source Directory (<filename>poky</filename>).
1273 In other words, make sure you place related
1274 files in appropriately related
1275 <filename>recipes-*</filename> subdirectories
1276 specific to the recipe's function, or within
1277 a subdirectory containing a set of closely-related
1278 recipes.
1279 The recipes themselves should follow the general
1280 guidelines for recipes used in the Yocto Project
1281 found in the
1282 "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>".
1283 </para></listitem>
1284 <listitem><para>
1285 <emphasis>License File:</emphasis>
1286 You must include a license file in the
1287 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1288 directory.
1289 This license covers the BSP Metadata as a whole.
1290 You must specify which license to use since no
1291 default license exists when one not specified.
1292 See the
1293 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
1294 file for the Raspberry Pi BSP in the
1295 <filename>meta-raspberrypi</filename> BSP layer
1296 as an example.
1297 </para></listitem>
1298 <listitem><para>
1299 <emphasis>README File:</emphasis>
1300 You must include a <filename>README</filename>
1301 file in the
1302 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1303 directory.
1304 See the
1305 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink>
1306 file for the Raspberry Pi BSP in the
1307 <filename>meta-raspberrypi</filename> BSP layer
1308 as an example.</para>
1309
1310 <para>At a minimum, the <filename>README</filename>
1311 file should contain the following:
1312 <itemizedlist> 1063 <itemizedlist>
1313 <listitem><para> 1064 <listitem><para>
1314 A brief description about the hardware the BSP 1065 Texas Instruments Beaglebone
1315 targets. 1066 (<filename>beaglebone-yocto</filename>
1316 </para></listitem> 1067 </para></listitem>
1317 <listitem><para> 1068 <listitem><para>
1318 A list of all the dependencies 1069 Freescale MPC8315E-RDB
1319 on which a BSP layer depends. 1070 (<filename>mpc8315e-rdb</filename>)
1320 These dependencies are typically a list
1321 of required layers needed to build the
1322 BSP.
1323 However, the dependencies should also
1324 contain information regarding any other
1325 dependencies the BSP might have.
1326 </para></listitem> 1071 </para></listitem>
1327 <listitem><para> 1072 <listitem><para>
1328 Any required special licensing information. 1073 Ubiquiti Networks EdgeRouter Lite
1329 For example, this information includes 1074 (<filename>edgerouter</filename>)
1330 information on special variables needed 1075 </para></listitem>
1331 to satisfy a EULA, or instructions on
1332 information needed to build or distribute
1333 binaries built from the BSP Metadata.
1334 </para></listitem>
1335 <listitem><para> 1076 <listitem><para>
1336 The name and contact information for the 1077 Two general IA platforms
1337 BSP layer maintainer. 1078 (<filename>genericx86</filename> and
1338 This is the person to whom patches and 1079 <filename>genericx86-64</filename>)
1339 questions should be sent.
1340 For information on how to find the right
1341 person, see the
1342 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
1343 section in the Yocto Project Development
1344 Tasks Manual.
1345 </para></listitem>
1346 <listitem><para>
1347 Instructions on how to build the BSP using
1348 the BSP layer.
1349 </para></listitem> 1080 </para></listitem>
1081 </itemizedlist>
1082 </para></listitem>
1083 <listitem><para>
1084 Three core Intel BSPs exist as part of
1085 the Yocto Project release in the
1086 <filename>meta-intel</filename> layer:
1087 <itemizedlist>
1350 <listitem><para> 1088 <listitem><para>
1351 Instructions on how to boot the BSP build 1089 <filename>intel-core2-32</filename>,
1352 from the BSP layer. 1090 which is a BSP optimized for the Core2
1091 family of CPUs as well as all CPUs
1092 prior to the Silvermont core.
1353 </para></listitem> 1093 </para></listitem>
1354 <listitem><para> 1094 <listitem><para>
1355 Instructions on how to boot the binary 1095 <filename>intel-corei7-64</filename>,
1356 images contained in the 1096 which is a BSP optimized for Nehalem
1357 <filename>binary</filename> directory, 1097 and later Core and Xeon CPUs as well
1358 if present. 1098 as Silvermont and later Atom CPUs,
1099 such as the Baytrail SoCs.
1359 </para></listitem> 1100 </para></listitem>
1360 <listitem><para> 1101 <listitem><para>
1361 Information on any known bugs or issues 1102 <filename>intel-quark</filename>,
1362 that users should know about when either 1103 which is a BSP optimized for the
1363 building or booting the BSP binaries. 1104 Intel Galileo gen1 &amp; gen2
1105 development boards.
1364 </para></listitem> 1106 </para></listitem>
1365 </itemizedlist> 1107 </itemizedlist>
1366 </para></listitem> 1108 </para></listitem>
1109 </itemizedlist>
1110 </note></para>
1111
1112 <para>When you set up a layer for a new BSP,
1113 you should follow a standard layout.
1114 This layout is described in the
1115 "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>"
1116 section.
1117 In the standard layout, notice the suggested
1118 structure for recipes and configuration
1119 information.
1120 You can see the standard layout for a BSP
1121 by examining any supported BSP found in the
1122 <filename>meta-intel</filename> layer inside
1123 the Source Directory.
1124 </para></listitem>
1125 <listitem><para>
1126 <emphasis>Make Configuration Changes to Your New
1127 BSP Layer:</emphasis>
1128 The standard BSP layer structure organizes the
1129 files you need to edit in
1130 <filename>conf</filename> and several
1131 <filename>recipes-*</filename> directories
1132 within the BSP layer.
1133 Configuration changes identify where your new
1134 layer is on the local system and identifies the
1135 kernel you are going to use.
1136 When you run the
1137 <filename>bitbake-layers</filename> script,
1138 you are able to interactively configure many
1139 things for the BSP (e.g. keyboard, touchscreen,
1140 and so forth).
1141 </para></listitem>
1142 <listitem><para>
1143 <emphasis>Make Recipe Changes to Your New BSP
1144 Layer:</emphasis>
1145 Recipe changes include altering recipes
1146 (<filename>*.bb</filename> files), removing
1147 recipes you do not use, and adding new recipes
1148 or append files (<filename>.bbappend</filename>)
1149 that support your hardware.
1150 </para></listitem>
1151 <listitem><para>
1152 <emphasis>Prepare for the Build:</emphasis>
1153 Once you have made all the changes to your BSP
1154 layer, there remains a few things you need to
1155 do for the OpenEmbedded build system in order
1156 for it to create your image.
1157 You need to get the build environment ready by
1158 sourcing an environment setup script
1159 (i.e. <filename>oe-init-build-env</filename>)
1160 and you need to be sure two key configuration
1161 files are configured appropriately: the
1162 <filename>conf/local.conf</filename> and the
1163 <filename>conf/bblayers.conf</filename> file.
1164 You must make the OpenEmbedded build system aware
1165 of your new layer.
1166 See the
1167 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
1168 section in the Yocto Project Development Tasks Manual
1169 for information on how to let the build system
1170 know about your new layer.
1171 </para></listitem>
1172 <listitem><para>
1173 <emphasis>Build the Image:</emphasis>
1174 The OpenEmbedded build system uses the BitBake tool
1175 to build images based on the type of image you want to
1176 create.
1177 You can find more information about BitBake in the
1178 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
1179 </para>
1180
1181 <para>The build process supports several types of
1182 images to satisfy different needs.
1183 See the
1184 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1185 chapter in the Yocto Project Reference Manual for
1186 information on supported images.
1187 </para></listitem>
1188 </orderedlist>
1189 </para>
1190</section>
1191
1192<section id='requirements-and-recommendations-for-released-bsps'>
1193 <title>Requirements and Recommendations for Released BSPs</title>
1194
1195 <para>
1196 Certain requirements exist for a released BSP to be
1197 considered compliant with the Yocto Project.
1198 Additionally, recommendations also exist.
1199 This section describes the requirements and
1200 recommendations for released BSPs.
1201 </para>
1202
1203 <section id='released-bsp-requirements'>
1204 <title>Released BSP Requirements</title>
1205
1206 <para>
1207 Before looking at BSP requirements, you should consider
1208 the following:
1209 <itemizedlist>
1210 <listitem><para>
1211 The requirements here assume the BSP layer
1212 is a well-formed, "legal" layer that can be
1213 added to the Yocto Project.
1214 For guidelines on creating a layer that meets
1215 these base requirements, see the
1216 "<link linkend='bsp-layers'>BSP Layers</link>"
1217 section in this manual and the
1218 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers"</ulink>"
1219 section in the Yocto Project Development Tasks
1220 Manual.
1221 </para></listitem>
1222 <listitem><para>
1223 The requirements in this section apply
1224 regardless of how you package a BSP.
1225 You should consult the packaging and distribution
1226 guidelines for your specific release process.
1227 For an example of packaging and distribution
1228 requirements, see the
1229 "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
1230 wiki page.
1231 </para></listitem>
1232 <listitem><para>
1233 The requirements for the BSP as it is made
1234 available to a developer are completely
1235 independent of the released form of the BSP.
1236 For example, the BSP Metadata can be contained
1237 within a Git repository and could have a directory
1238 structure completely different from what appears
1239 in the officially released BSP layer.
1240 </para></listitem>
1241 <listitem><para>
1242 It is not required that specific packages or
1243 package modifications exist in the BSP layer,
1244 beyond the requirements for general
1245 compliance with the Yocto Project.
1246 For example, no requirement exists dictating
1247 that a specific kernel or kernel version be
1248 used in a given BSP.
1249 </para></listitem>
1250 </itemizedlist>
1251 </para>
1252
1253 <para>
1254 Following are the requirements for a released BSP
1255 that conform to the Yocto Project:
1256 <itemizedlist>
1257 <listitem><para>
1258 <emphasis>Layer Name:</emphasis>
1259 The BSP must have a layer name that follows
1260 the Yocto Project standards.
1261 For information on BSP layer names, see the
1262 "<link linkend='bsp-layers'>BSP Layers</link>" section.
1263 </para></listitem>
1264 <listitem><para>
1265 <emphasis>File System Layout:</emphasis>
1266 When possible, use the same directory names
1267 in your BSP layer as listed in the
1268 <filename>recipes.txt</filename> file, which
1269 is found in <filename>poky/meta</filename>
1270 directory of the
1271 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
1272 or in the OpenEmbedded Core Layer
1273 (<filename>openembedded-core</filename>) at
1274 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
1275 </para>
1276
1277 <para>You should place recipes
1278 (<filename>*.bb</filename> files) and recipe
1279 modifications (<filename>*.bbappend</filename>
1280 files) into <filename>recipes-*</filename>
1281 subdirectories by functional area as outlined
1282 in <filename>recipes.txt</filename>.
1283 If you cannot find a category in
1284 <filename>recipes.txt</filename> to fit a
1285 particular recipe, you can make up your own
1286 <filename>recipes-*</filename> subdirectory.
1287 </para>
1288
1289 <para>Within any particular
1290 <filename>recipes-*</filename> category, the
1291 layout should match what is found in the
1292 OpenEmbedded Core Git repository
1293 (<filename>openembedded-core</filename>)
1294 or the Source Directory (<filename>poky</filename>).
1295 In other words, make sure you place related
1296 files in appropriately related
1297 <filename>recipes-*</filename> subdirectories
1298 specific to the recipe's function, or within
1299 a subdirectory containing a set of closely-related
1300 recipes.
1301 The recipes themselves should follow the general
1302 guidelines for recipes used in the Yocto Project
1303 found in the
1304 "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>".
1305 </para></listitem>
1306 <listitem><para>
1307 <emphasis>License File:</emphasis>
1308 You must include a license file in the
1309 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1310 directory.
1311 This license covers the BSP Metadata as a whole.
1312 You must specify which license to use since no
1313 default license exists when one not specified.
1314 See the
1315 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
1316 file for the Raspberry Pi BSP in the
1317 <filename>meta-raspberrypi</filename> BSP layer
1318 as an example.
1319 </para></listitem>
1320 <listitem><para>
1321 <emphasis>README File:</emphasis>
1322 You must include a <filename>README</filename>
1323 file in the
1324 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1325 directory.
1326 See the
1327 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink>
1328 file for the Raspberry Pi BSP in the
1329 <filename>meta-raspberrypi</filename> BSP layer
1330 as an example.</para>
1331
1332 <para>At a minimum, the <filename>README</filename>
1333 file should contain the following:
1334 <itemizedlist>
1367 <listitem><para> 1335 <listitem><para>
1368 <emphasis>README.sources File:</emphasis> 1336 A brief description about the hardware the BSP
1369 If you BSP contains binary images in the 1337 targets.
1370 <filename>binary</filename> directory, you must
1371 include a <filename>README.sources</filename>
1372 file in the
1373 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1374 directory.
1375 This file specifies exactly where you can find
1376 the sources used to generate the binary images.
1377 </para></listitem> 1338 </para></listitem>
1378 <listitem><para> 1339 <listitem><para>
1379 <emphasis>Layer Configuration File:</emphasis> 1340 A list of all the dependencies
1380 You must include a 1341 on which a BSP layer depends.
1381 <filename>conf/layer.conf</filename> file in 1342 These dependencies are typically a list
1382 the 1343 of required layers needed to build the
1383 <filename>meta-</filename><replaceable>bsp_name</replaceable> 1344 BSP.
1384 directory. 1345 However, the dependencies should also
1385 This file identifies the 1346 contain information regarding any other
1386 <filename>meta-</filename><replaceable>bsp_name</replaceable> 1347 dependencies the BSP might have.
1387 BSP layer as a layer to the build system.
1388 </para></listitem> 1348 </para></listitem>
1389 <listitem><para> 1349 <listitem><para>
1390 <emphasis>Machine Configuration File:</emphasis> 1350 Any required special licensing information.
1391 You must include one or more 1351 For example, this information includes
1392 <filename>conf/machine/</filename><replaceable>bsp_name</replaceable><filename>.conf</filename> 1352 information on special variables needed
1393 files in the 1353 to satisfy a EULA, or instructions on
1394 <filename>meta-</filename><replaceable>bsp_name</replaceable> 1354 information needed to build or distribute
1395 directory. 1355 binaries built from the BSP Metadata.
1396 These configuration files define machine targets
1397 that can be built using the BSP layer.
1398 Multiple machine configuration files define
1399 variations of machine configurations that the
1400 BSP supports.
1401 If a BSP supports multiple machine variations,
1402 you need to adequately describe each variation
1403 in the BSP <filename>README</filename> file.
1404 Do not use multiple machine configuration files
1405 to describe disparate hardware.
1406 If you do have very different targets, you should
1407 create separate BSP layers for each target.
1408 <note>
1409 It is completely possible for a developer to
1410 structure the working repository as a
1411 conglomeration of unrelated BSP files, and to
1412 possibly generate BSPs targeted for release
1413 from that directory using scripts or some
1414 other mechanism
1415 (e.g. <filename>meta-yocto-bsp</filename> layer).
1416 Such considerations are outside the scope of
1417 this document.
1418 </note>
1419 </para></listitem> 1356 </para></listitem>
1420 </itemizedlist>
1421 </para>
1422 </section>
1423
1424 <section id='released-bsp-recommendations'>
1425 <title>Released BSP Recommendations</title>
1426
1427 <para>
1428 Following are recommendations for released BSPs that
1429 conform to the Yocto Project:
1430 <itemizedlist>
1431 <listitem><para> 1357 <listitem><para>
1432 <emphasis>Bootable Images:</emphasis> 1358 The name and contact information for the
1433 Released BSPs can contain one or more bootable 1359 BSP layer maintainer.
1434 images. 1360 This is the person to whom patches and
1435 Including bootable images allows users to easily 1361 questions should be sent.
1436 try out the BSP using their own hardware.</para> 1362 For information on how to find the right
1437 1363 person, see the
1438 <para>In some cases, it might not be convenient 1364 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
1439 to include a bootable image. 1365 section in the Yocto Project Development
1440 If so, you might want to make two versions of the 1366 Tasks Manual.
1441 BSP available: one that contains binary images, and
1442 one that does not.
1443 The version that does not contain bootable images
1444 avoids unnecessary download times for users not
1445 interested in the images.</para>
1446
1447 <para>If you need to distribute a BSP and include
1448 bootable images or build kernel and filesystems
1449 meant to allow users to boot the BSP for evaluation
1450 purposes, you should put the images and artifacts
1451 within a
1452 <filename>binary/</filename> subdirectory located
1453 in the
1454 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1455 directory.
1456 <note>
1457 If you do include a bootable image as part
1458 of the BSP and the image was built by software
1459 covered by the GPL or other open source licenses,
1460 it is your responsibility to understand
1461 and meet all licensing requirements, which could
1462 include distribution of source files.
1463 </note>
1464 </para></listitem> 1367 </para></listitem>
1465 <listitem><para> 1368 <listitem><para>
1466 <emphasis>Use a Yocto Linux Kernel:</emphasis> 1369 Instructions on how to build the BSP using
1467 Kernel recipes in the BSP should be based on a 1370 the BSP layer.
1468 Yocto Linux kernel.
1469 Basing your recipes on these kernels reduces
1470 the costs for maintaining the BSP and increases
1471 its scalability.
1472 See the <filename>Yocto Linux Kernel</filename>
1473 category in the
1474 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
1475 for these kernels.
1476 </para></listitem> 1371 </para></listitem>
1477 </itemizedlist>
1478 </para>
1479 </section>
1480 </section>
1481
1482 <section id='customizing-a-recipe-for-a-bsp'>
1483 <title>Customizing a Recipe for a BSP</title>
1484
1485 <para>
1486 If you plan on customizing a recipe for a particular BSP,
1487 you need to do the following:
1488 <itemizedlist>
1489 <listitem><para>
1490 Create a <filename>*.bbappend</filename> file for
1491 the modified recipe.
1492 For information on using append files, see the
1493 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
1494 section in the Yocto Project Development Tasks
1495 Manual.
1496 </para></listitem>
1497 <listitem><para>
1498 Ensure your directory structure in the BSP layer
1499 that supports your machine is such that the
1500 OpenEmbedded build system can find it.
1501 See the example later in this section for more
1502 information.
1503 </para></listitem>
1504 <listitem><para>
1505 Put the append file in a directory whose name matches
1506 the machine's name and is located in an appropriate
1507 sub-directory inside the BSP layer (i.e.
1508 <filename>recipes-bsp</filename>,
1509 <filename>recipes-graphics</filename>,
1510 <filename>recipes-core</filename>, and so forth).
1511 </para></listitem>
1512 <listitem><para>
1513 Place the BSP-specific files in the proper
1514 directory inside the BSP layer.
1515 How expansive the layer is affects where you must
1516 place these files.
1517 For example, if your layer supports several
1518 different machine types, you need to be sure your
1519 layer's directory structure includes hierarchy
1520 that separates the files according to machine.
1521 If your layer does not support multiple machines,
1522 the layer would not have that additional hierarchy
1523 and the files would obviously not be able to reside
1524 in a machine-specific directory.
1525 </para></listitem>
1526 </itemizedlist>
1527 </para>
1528
1529 <para>
1530 Following is a specific example to help you better understand
1531 the process.
1532 This example customizes customizes a recipe by adding a
1533 BSP-specific configuration file named
1534 <filename>interfaces</filename> to the
1535 <filename>init-ifupdown_1.0.bb</filename> recipe for machine
1536 "xyz" where the BSP layer also supports several other
1537 machines:
1538 <orderedlist>
1539 <listitem><para>
1540 Edit the
1541 <filename>init-ifupdown_1.0.bbappend</filename> file
1542 so that it contains the following:
1543 <literallayout class='monospaced'>
1544 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
1545 </literallayout>
1546 The append file needs to be in the
1547 <filename>meta-xyz/recipes-core/init-ifupdown</filename>
1548 directory.
1549 </para></listitem>
1550 <listitem><para>
1551 Create and place the new
1552 <filename>interfaces</filename> configuration file in
1553 the BSP's layer here:
1554 <literallayout class='monospaced'>
1555 meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
1556 </literallayout>
1557 <note>
1558 If the <filename>meta-xyz</filename> layer did
1559 not support multiple machines, you would place
1560 the <filename>interfaces</filename> configuration
1561 file in the layer here:
1562 <literallayout class='monospaced'>
1563 meta-xyz/recipes-core/init-ifupdown/files/interfaces
1564 </literallayout>
1565 </note>
1566 The
1567 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
1568 variable in the append files extends the search path
1569 the build system uses to find files during the build.
1570 Consequently, for this example you need to have the
1571 <filename>files</filename> directory in the same
1572 location as your append file.
1573 </para></listitem>
1574 </orderedlist>
1575 </para>
1576 </section>
1577
1578 <section id='bsp-licensing-considerations'>
1579 <title>BSP Licensing Considerations</title>
1580
1581 <para>
1582 In some cases, a BSP contains separately licensed
1583 Intellectual Property (IP) for a component or components.
1584 For these cases, you are required to accept the terms
1585 of a commercial or other type of license that requires
1586 some kind of explicit End User License Agreement (EULA).
1587 Once you accept the license, the OpenEmbedded build system
1588 can then build and include the corresponding component
1589 in the final BSP image.
1590 If the BSP is available as a pre-built image, you can
1591 download the image after agreeing to the license or EULA.
1592 </para>
1593
1594 <para>
1595 You could find that some separately licensed components
1596 that are essential for normal operation of the system might
1597 not have an unencumbered (or free) substitute.
1598 Without these essential components, the system would be
1599 non-functional.
1600 Then again, you might find that other licensed components
1601 that are simply 'good-to-have' or purely elective do have
1602 an unencumbered, free replacement component that you can
1603 use rather than agreeing to the separately licensed
1604 component.
1605 Even for components essential to the system, you might
1606 find an unencumbered component that is not identical but
1607 will work as a less-capable version of the licensed version
1608 in the BSP recipe.
1609 </para>
1610
1611 <para>
1612 For cases where you can substitute a free component and
1613 still maintain the system's functionality, the "DOWNLOADS"
1614 selection from the "SOFTWARE" tab on the
1615 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>
1616 makes available de-featured BSPs that are completely free
1617 of any IP encumbrances.
1618 For these cases, you can use the substitution directly and
1619 without any further licensing requirements.
1620 If present, these fully de-featured BSPs are named
1621 appropriately different as compared to the names of their
1622 respective encumbered BSPs.
1623 If available, these substitutions are your simplest and
1624 most preferred options.
1625 Obviously, use of these substitutions assumes the resulting
1626 functionality meets system requirements.
1627 <note>
1628 If however, a non-encumbered version is unavailable or
1629 it provides unsuitable functionality or quality, you can
1630 use an encumbered version.
1631 </note>
1632 </para>
1633
1634 <para>
1635 A couple different methods exist within the OpenEmbedded
1636 build system to satisfy the licensing requirements for an
1637 encumbered BSP.
1638 The following list describes them in order of preference:
1639 <orderedlist>
1640 <listitem><para>
1641 <emphasis>Use the
1642 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1643 Variable to Define the Recipes that Have Commercial
1644 or Other Types of Specially-Licensed Packages:</emphasis>
1645 For each of those recipes, you can specify a
1646 matching license string in a
1647 <filename>local.conf</filename> variable named
1648 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>.
1649 Specifying the matching license string signifies
1650 that you agree to the license.
1651 Thus, the build system can build the corresponding
1652 recipe and include the component in the image.
1653 See the
1654 "<ulink url='&YOCTO_DOCS_CM_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
1655 section in the Yocto Project Concepts Manual for
1656 details on how to use these variables.</para>
1657
1658 <para>If you build as you normally would, without
1659 specifying any recipes in the
1660 <filename>LICENSE_FLAGS_WHITELIST</filename>, the
1661 build stops and provides you with the list of recipes
1662 that you have tried to include in the image that
1663 need entries in the
1664 <filename>LICENSE_FLAGS_WHITELIST</filename>.
1665 Once you enter the appropriate license flags into
1666 the whitelist, restart the build to continue where
1667 it left off.
1668 During the build, the prompt will not appear again
1669 since you have satisfied the requirement.</para>
1670
1671 <para>Once the appropriate license flags are on the
1672 white list in the
1673 <filename>LICENSE_FLAGS_WHITELIST</filename> variable,
1674 you can build the encumbered image with no change
1675 at all to the normal build process.
1676 </para></listitem>
1677 <listitem><para>
1678 <emphasis>Get a Pre-Built Version of the BSP:</emphasis>
1679 You can get this type of BSP by selecting the
1680 "DOWNLOADS" item from the "SOFTWARE" tab on the
1681 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
1682 You can download BSP tarballs that contain
1683 proprietary components after agreeing to the
1684 licensing requirements of each of the individually
1685 encumbered packages as part of the download process.
1686 Obtaining the BSP this way allows you to access an
1687 encumbered image immediately after agreeing to the
1688 click-through license agreements presented by the
1689 website.
1690 If you want to build the image yourself using
1691 the recipes contained within the BSP tarball,
1692 you will still need to create an appropriate
1693 <filename>LICENSE_FLAGS_WHITELIST</filename>
1694 to match the encumbered recipes in the BSP.
1695 </para></listitem>
1696 </orderedlist>
1697 <note>
1698 Pre-compiled images are bundled with a time-limited
1699 kernel that runs for a predetermined amount of time
1700 (10 days) before it forces the system to reboot.
1701 This limitation is meant to discourage direct
1702 redistribution of the image.
1703 You must eventually rebuild the image if you want
1704 to remove this restriction.
1705 </note>
1706 </para>
1707 </section>
1708
1709 <section id='using-the-yocto-projects-bsp-tools'>
1710 <title>Using the Yocto Project's BSP Tools</title>
1711
1712 <para>
1713 The Yocto Project includes a couple of tools that enable
1714 you to create a <link linkend='bsp-layers'>BSP layer</link>
1715 from scratch and do basic configuration and maintenance
1716 of the kernel without ever looking at a Metadata file.
1717 These tools are <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename>,
1718 respectively.
1719 </para>
1720
1721 <para>
1722 The following sections describe the common location and help features as well
1723 as provide details for the
1724 <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename> tools.
1725 </para>
1726
1727 <section id='common-features'>
1728 <title>Common Features</title>
1729
1730 <para>
1731 Designed to have a command interface somewhat like
1732 <ulink url='&YOCTO_DOCS_GS_URL;#git'>Git</ulink>, each
1733 tool is structured as a set of sub-commands under a
1734 top-level command.
1735 The top-level command (<filename>yocto-bsp</filename>
1736 or <filename>yocto-kernel</filename>) itself does
1737 nothing but invoke or provide help on the sub-commands
1738 it supports.
1739 </para>
1740
1741 <para>
1742 Both tools reside in the <filename>scripts/</filename> subdirectory
1743 of the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
1744 Consequently, to use the scripts, you must <filename>source</filename> the
1745 environment just as you would when invoking a build:
1746 <literallayout class='monospaced'>
1747 $ source oe-init-build-env <replaceable>build_dir</replaceable>
1748 </literallayout>
1749 </para>
1750
1751 <para>
1752 The most immediately useful function is to get help on both tools.
1753 The built-in help system makes it easy to drill down at
1754 any time and view the syntax required for any specific command.
1755 Simply enter the name of the command with the <filename>help</filename>
1756 switch:
1757 <literallayout class='monospaced'>
1758 $ yocto-bsp help
1759 Usage:
1760
1761 Create a customized Yocto BSP layer.
1762
1763 usage: yocto-bsp [--version] [--help] COMMAND [ARGS]
1764
1765 Current 'yocto-bsp' commands are:
1766 create Create a new Yocto BSP
1767 list List available values for options and BSP properties
1768
1769 See 'yocto-bsp help COMMAND' for more information on a specific command.
1770
1771
1772 Options:
1773 --version show program's version number and exit
1774 -h, --help show this help message and exit
1775 -D, --debug output debug information
1776 </literallayout>
1777 </para>
1778
1779 <para>
1780 Similarly, entering just the name of a sub-command shows the detailed usage
1781 for that sub-command:
1782 <literallayout class='monospaced'>
1783 $ yocto-bsp create
1784 ERROR:root:Wrong number of arguments, exiting
1785
1786 Usage:
1787
1788 Create a new Yocto BSP
1789
1790 usage: yocto-bsp create &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
1791 [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
1792
1793 This command creates a Yocto BSP based on the specified parameters.
1794 The new BSP will be a new Yocto BSP layer contained by default within
1795 the top-level directory specified as 'meta-bsp-name'. The -o option
1796 can be used to place the BSP layer in a directory with a different
1797 name and location.
1798
1799 The value of the 'karch' parameter determines the set of files that
1800 will be generated for the BSP, along with the specific set of
1801 'properties' that will be used to fill out the BSP-specific portions
1802 of the BSP. The possible values for the 'karch' parameter can be
1803 listed via 'yocto-bsp list karch'.
1804
1805 ...
1806 </literallayout>
1807 </para>
1808
1809 <para>
1810 For any sub-command, you can use the word "help" option just before the
1811 sub-command to get more extensive documentation:
1812 <literallayout class='monospaced'>
1813 $ yocto-bsp help create
1814
1815 NAME
1816 yocto-bsp create - Create a new Yocto BSP
1817
1818 SYNOPSIS
1819 yocto-bsp create &lt;bsp-name> &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
1820 [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
1821
1822 DESCRIPTION
1823 This command creates a Yocto BSP based on the specified
1824 parameters. The new BSP will be a new Yocto BSP layer contained
1825 by default within the top-level directory specified as
1826 'meta-bsp-name'. The -o option can be used to place the BSP layer
1827 in a directory with a different name and location.
1828
1829 ...
1830 </literallayout>
1831 </para>
1832
1833 <para>
1834 Now that you know where these two commands reside and how to access information
1835 on them, you should find it relatively straightforward to discover the commands
1836 necessary to create a BSP and perform basic kernel maintenance on that BSP using
1837 the tools.
1838 <note>
1839 You can also use the <filename>bitbake-layers</filename> script to create
1840 a "generic" layer.
1841 For information on using this script to create a layer, see the
1842 "<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>"
1843 section in the Yocto Project Development Tasks Manual.
1844 </note>
1845 </para>
1846
1847 <para>
1848 The next sections provide a concrete starting point to expand on a few points that
1849 might not be immediately obvious or that could use further explanation.
1850 </para>
1851 </section>
1852
1853
1854 <section id='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>
1855 <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title>
1856
1857 <para role='writernotes'>
1858 I have put in information that will be the basis of this section,
1859 but it is missing a lot at this point.
1860 This whole section needs reviewed and filled in with proper
1861 information.
1862 </para>
1863
1864 <para>
1865 [INTRODUCE THE PROCEDURE AND LINK BACK TO <link linkend='bsp-layers'>BSP layer</link>.
1866 IF THERE IS A LAUNDRY LIST OF ITEMS THAT NEED DEFINITION OR GET SET
1867 UP AS A RESULT OF THIS PROCEDURE, LIST THEM HERE.]
1868 <itemizedlist>
1869 <listitem><para>[PARAMETER 1]</para></listitem>
1870 <listitem><para>[PARAMETER 2]</para></listitem>
1871 <listitem><para>[PARAMETER 3]</para></listitem>
1872 <listitem><para>[PARAMETER 4]</para></listitem>
1873 <listitem><para>[PARAMETER 5]</para></listitem>
1874 <listitem><para>[PARAMETER 6]</para></listitem>
1875 <listitem><para>[PARAMETER 7]</para></listitem>
1876 </itemizedlist>
1877 </para>
1878
1879 <para>
1880 The following procedure creates a BSP layer:
1881 <itemizedlist>
1882 <listitem><para> 1372 <listitem><para>
1883 <emphasis>Create General Layer:</emphasis> 1373 Instructions on how to boot the BSP build
1884 Use the <filename>bitbake-layers</filename> script with the 1374 from the BSP layer.
1885 <filename>create-layer</filename> subcommand to create a
1886 new general layer.
1887 For instructions on how to create a general layer using the
1888 <filename>bitbake-layers</filename> script, see the
1889 "<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>"
1890 section in the Yocto Project Development Tasks Manual.
1891 </para></listitem> 1375 </para></listitem>
1892 <listitem><para> 1376 <listitem><para>
1893 <emphasis>Create a Machine Configuration File:</emphasis> 1377 Instructions on how to boot the binary
1894 Create a <filename>conf/machine/&gt;machine&lt;.conf</filename> 1378 images contained in the
1895 file. 1379 <filename>binary</filename> directory,
1896 See <filename>meta-yocto-bsp/conf/machine</filename> for sample 1380 if present.
1897 <filename>&gt;machine.conf&lt;</filename> files.
1898 Other samples exist from other vendors such as
1899 <filename>meta-intel</filename>, <filename>meta-ti</filename>,
1900 and <filename>meta-freescale</filename> that have more specific machine
1901 and tuning examples.
1902 </para></listitem> 1381 </para></listitem>
1903 <listitem><para> 1382 <listitem><para>
1904 <emphasis>Create a Kernel Recipe:</emphasis> 1383 Information on any known bugs or issues
1905 Create a kernel recipe in <filename>recipes-kernel/linux</filename> 1384 that users should know about when either
1906 either using a linux-yocto kernel with a <filename>.bbappend</filename> 1385 building or booting the BSP binaries.
1907 file or a new custom kernel recipe file (i.e. <filename>.bb</filename>
1908 file).
1909 The BSP layers mentioned in the previous step also contain different
1910 kernel examples.
1911 You can start with the linux-yocto or use a custom kernel.
1912 See the
1913 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>"
1914 section in the Yocto Project Linux Kernel Development Manual
1915 for information on how to create a custom kernel.
1916 </para></listitem> 1386 </para></listitem>
1917 </itemizedlist> 1387 </itemizedlist>
1918 </para> 1388 </para></listitem>
1919 1389 <listitem><para>
1920 <para role='writernotes'> 1390 <emphasis>README.sources File:</emphasis>
1921 [THERE IS MORE INFORMATION THAT NEEDS TO BE FILLED IN HERE. THIS NEEDS TO 1391 If you BSP contains binary images in the
1922 BE PROVIDED BY ENGINEERS.] 1392 <filename>binary</filename> directory, you must
1923 </para> 1393 include a <filename>README.sources</filename>
1924 1394 file in the
1925 <para> 1395 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1926 The remainder of this section presents an example that uses 1396 directory.
1927 <filename>myarm</filename> as the machine name and <filename>qemu</filename> 1397 This file specifies exactly where you can find
1928 as the machine architecture. 1398 the sources used to generate the binary images.
1929 Of the available architectures, <filename>qemu</filename> is the only architecture 1399 </para></listitem>
1930 that causes the script to prompt you further for an actual architecture. 1400 <listitem><para>
1931 In every other way, this architecture is representative of how creating a BSP for 1401 <emphasis>Layer Configuration File:</emphasis>
1932 an actual machine would work. 1402 You must include a
1933 The reason the example uses this architecture is because it is an emulated architecture 1403 <filename>conf/layer.conf</filename> file in
1934 and can easily be followed without requiring actual hardware. 1404 the
1935 </para> 1405 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1406 directory.
1407 This file identifies the
1408 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1409 BSP layer as a layer to the build system.
1410 </para></listitem>
1411 <listitem><para>
1412 <emphasis>Machine Configuration File:</emphasis>
1413 You must include one or more
1414 <filename>conf/machine/</filename><replaceable>bsp_name</replaceable><filename>.conf</filename>
1415 files in the
1416 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1417 directory.
1418 These configuration files define machine targets
1419 that can be built using the BSP layer.
1420 Multiple machine configuration files define
1421 variations of machine configurations that the
1422 BSP supports.
1423 If a BSP supports multiple machine variations,
1424 you need to adequately describe each variation
1425 in the BSP <filename>README</filename> file.
1426 Do not use multiple machine configuration files
1427 to describe disparate hardware.
1428 If you do have very different targets, you should
1429 create separate BSP layers for each target.
1430 <note>
1431 It is completely possible for a developer to
1432 structure the working repository as a
1433 conglomeration of unrelated BSP files, and to
1434 possibly generate BSPs targeted for release
1435 from that directory using scripts or some
1436 other mechanism
1437 (e.g. <filename>meta-yocto-bsp</filename> layer).
1438 Such considerations are outside the scope of
1439 this document.
1440 </note>
1441 </para></listitem>
1442 </itemizedlist>
1443 </para>
1444 </section>
1936 1445
1937<!-- <para> 1446 <section id='released-bsp-recommendations'>
1938 [ASSUMING SIMILAR ACTION OCCURS]As the [SUBCOMMAND] command runs, default values for 1447 <title>Released BSP Recommendations</title>
1939 the prompts appear in brackets.
1940 Pressing enter without supplying anything on the command line or pressing enter
1941 with an invalid response causes the script to accept the default value.
1942 Once the script completes, the new <filename>meta-myarm</filename> BSP layer
1943 is created in the current working directory.
1944 This example assumes you have sourced the
1945 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
1946 setup script.
1947 </para>
1948-->
1949 1448
1950 <para> 1449 <para>
1951 Following is a complete example: 1450 Following are recommendations for released BSPs that
1451 conform to the Yocto Project:
1452 <itemizedlist>
1453 <listitem><para>
1454 <emphasis>Bootable Images:</emphasis>
1455 Released BSPs can contain one or more bootable
1456 images.
1457 Including bootable images allows users to easily
1458 try out the BSP using their own hardware.</para>
1459
1460 <para>In some cases, it might not be convenient
1461 to include a bootable image.
1462 If so, you might want to make two versions of the
1463 BSP available: one that contains binary images, and
1464 one that does not.
1465 The version that does not contain bootable images
1466 avoids unnecessary download times for users not
1467 interested in the images.</para>
1468
1469 <para>If you need to distribute a BSP and include
1470 bootable images or build kernel and filesystems
1471 meant to allow users to boot the BSP for evaluation
1472 purposes, you should put the images and artifacts
1473 within a
1474 <filename>binary/</filename> subdirectory located
1475 in the
1476 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1477 directory.
1478 <note>
1479 If you do include a bootable image as part
1480 of the BSP and the image was built by software
1481 covered by the GPL or other open source licenses,
1482 it is your responsibility to understand
1483 and meet all licensing requirements, which could
1484 include distribution of source files.
1485 </note>
1486 </para></listitem>
1487 <listitem><para>
1488 <emphasis>Use a Yocto Linux Kernel:</emphasis>
1489 Kernel recipes in the BSP should be based on a
1490 Yocto Linux kernel.
1491 Basing your recipes on these kernels reduces
1492 the costs for maintaining the BSP and increases
1493 its scalability.
1494 See the <filename>Yocto Linux Kernel</filename>
1495 category in the
1496 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
1497 for these kernels.
1498 </para></listitem>
1499 </itemizedlist>
1500 </para>
1501 </section>
1502</section>
1503
1504<section id='customizing-a-recipe-for-a-bsp'>
1505 <title>Customizing a Recipe for a BSP</title>
1506
1507 <para>
1508 If you plan on customizing a recipe for a particular BSP,
1509 you need to do the following:
1510 <itemizedlist>
1511 <listitem><para>
1512 Create a <filename>*.bbappend</filename> file for
1513 the modified recipe.
1514 For information on using append files, see the
1515 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
1516 section in the Yocto Project Development Tasks
1517 Manual.
1518 </para></listitem>
1519 <listitem><para>
1520 Ensure your directory structure in the BSP layer
1521 that supports your machine is such that the
1522 OpenEmbedded build system can find it.
1523 See the example later in this section for more
1524 information.
1525 </para></listitem>
1526 <listitem><para>
1527 Put the append file in a directory whose name matches
1528 the machine's name and is located in an appropriate
1529 sub-directory inside the BSP layer (i.e.
1530 <filename>recipes-bsp</filename>,
1531 <filename>recipes-graphics</filename>,
1532 <filename>recipes-core</filename>, and so forth).
1533 </para></listitem>
1534 <listitem><para>
1535 Place the BSP-specific files in the proper
1536 directory inside the BSP layer.
1537 How expansive the layer is affects where you must
1538 place these files.
1539 For example, if your layer supports several
1540 different machine types, you need to be sure your
1541 layer's directory structure includes hierarchy
1542 that separates the files according to machine.
1543 If your layer does not support multiple machines,
1544 the layer would not have that additional hierarchy
1545 and the files would obviously not be able to reside
1546 in a machine-specific directory.
1547 </para></listitem>
1548 </itemizedlist>
1549 </para>
1550
1551 <para>
1552 Following is a specific example to help you better understand
1553 the process.
1554 This example customizes customizes a recipe by adding a
1555 BSP-specific configuration file named
1556 <filename>interfaces</filename> to the
1557 <filename>init-ifupdown_1.0.bb</filename> recipe for machine
1558 "xyz" where the BSP layer also supports several other
1559 machines:
1560 <orderedlist>
1561 <listitem><para>
1562 Edit the
1563 <filename>init-ifupdown_1.0.bbappend</filename> file
1564 so that it contains the following:
1565 <literallayout class='monospaced'>
1566 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
1567 </literallayout>
1568 The append file needs to be in the
1569 <filename>meta-xyz/recipes-core/init-ifupdown</filename>
1570 directory.
1571 </para></listitem>
1572 <listitem><para>
1573 Create and place the new
1574 <filename>interfaces</filename> configuration file in
1575 the BSP's layer here:
1576 <literallayout class='monospaced'>
1577 meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
1578 </literallayout>
1579 <note>
1580 If the <filename>meta-xyz</filename> layer did
1581 not support multiple machines, you would place
1582 the <filename>interfaces</filename> configuration
1583 file in the layer here:
1952 <literallayout class='monospaced'> 1584 <literallayout class='monospaced'>
1953 [INSERT EXAMPLE - NEED EXAMPLE] 1585 meta-xyz/recipes-core/init-ifupdown/files/interfaces
1954 </literallayout> 1586 </literallayout>
1955<!-- 1587 </note>
1956 <orderedlist> 1588 The
1957 <listitem><para>For the QEMU architecture, 1589 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
1958 the script first prompts you for which emulated architecture to use. 1590 variable in the append files extends the search path
1959 In the example, we use the ARM architecture. 1591 the build system uses to find files during the build.
1960 </para></listitem> 1592 Consequently, for this example you need to have the
1961 <listitem><para>The script then prompts you for the kernel. 1593 <filename>files</filename> directory in the same
1962 The default 4.8 kernel is acceptable. 1594 location as your append file.
1963 So, the example accepts the default. 1595 </para></listitem>
1964 If you enter 'n', the script prompts you to further enter the kernel 1596 </orderedlist>
1965 you do want to use.</para></listitem> 1597 </para>
1966 <listitem><para>Next, the script asks whether you would like to have a new 1598</section>
1967 branch created especially for your BSP in the local 1599
1968 Linux Yocto Kernel Git repository . 1600<section id='bsp-licensing-considerations'>
1969 If not, then the script re-uses an existing branch.</para> 1601 <title>BSP Licensing Considerations</title>
1970 <para>In this example, the default (or "yes") is accepted. 1602
1971 Thus, a new branch is created for the BSP rather than using a common, shared 1603 <para>
1972 branch. 1604 In some cases, a BSP contains separately licensed
1973 The new branch is the branch committed to for any patches you might later add. 1605 Intellectual Property (IP) for a component or components.
1974 The reason a new branch is the default is that typically 1606 For these cases, you are required to accept the terms
1975 new BSPs do require BSP-specific patches. 1607 of a commercial or other type of license that requires
1976 The tool thus assumes that most of time a new branch is required. 1608 some kind of explicit End User License Agreement (EULA).
1977 </para></listitem> 1609 Once you accept the license, the OpenEmbedded build system
1978 <listitem><para>Regardless of which choice you make in the previous step, 1610 can then build and include the corresponding component
1979 you are now given the opportunity to select a particular machine branch on 1611 in the final BSP image.
1980 which to base your new BSP-specific machine branch 1612 If the BSP is available as a pre-built image, you can
1981 (or to re-use if you had elected to not create a new branch). 1613 download the image after agreeing to the license or EULA.
1982 Because this example is generating an ARM-based BSP, the example 1614 </para>
1983 uses <filename>#1</filename> at the prompt, which selects the ARM-versatile branch. 1615
1984 </para></listitem> 1616 <para>
1985 <listitem><para>The remainder of the prompts are routine. 1617 You could find that some separately licensed components
1986 Defaults are accepted for each.</para></listitem> 1618 that are essential for normal operation of the system might
1987 <listitem><para>By default, the script creates the new BSP Layer in the 1619 not have an unencumbered (or free) substitute.
1988 current working directory of the 1620 Without these essential components, the system would be
1989 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>, 1621 non-functional.
1990 (i.e. <filename>poky/build</filename>). 1622 Then again, you might find that other licensed components
1991 </para></listitem> 1623 that are simply 'good-to-have' or purely elective do have
1992 </orderedlist> 1624 an unencumbered, free replacement component that you can
1993--> 1625 use rather than agreeing to the separately licensed
1994 </para> 1626 component.
1995 1627 Even for components essential to the system, you might
1996 <para> 1628 find an unencumbered component that is not identical but
1997 Once the BSP Layer is created, you must add it to your 1629 will work as a less-capable version of the licensed version
1998 <filename>bblayers.conf</filename> file. 1630 in the BSP recipe.
1999 Here is an example: 1631 </para>
2000 <literallayout class='monospaced'> 1632
1633 <para>
1634 For cases where you can substitute a free component and
1635 still maintain the system's functionality, the "DOWNLOADS"
1636 selection from the "SOFTWARE" tab on the
1637 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>
1638 makes available de-featured BSPs that are completely free
1639 of any IP encumbrances.
1640 For these cases, you can use the substitution directly and
1641 without any further licensing requirements.
1642 If present, these fully de-featured BSPs are named
1643 appropriately different as compared to the names of their
1644 respective encumbered BSPs.
1645 If available, these substitutions are your simplest and
1646 most preferred options.
1647 Obviously, use of these substitutions assumes the resulting
1648 functionality meets system requirements.
1649 <note>
1650 If however, a non-encumbered version is unavailable or
1651 it provides unsuitable functionality or quality, you can
1652 use an encumbered version.
1653 </note>
1654 </para>
1655
1656 <para>
1657 A couple different methods exist within the OpenEmbedded
1658 build system to satisfy the licensing requirements for an
1659 encumbered BSP.
1660 The following list describes them in order of preference:
1661 <orderedlist>
1662 <listitem><para>
1663 <emphasis>Use the
1664 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
1665 Variable to Define the Recipes that Have Commercial
1666 or Other Types of Specially-Licensed Packages:</emphasis>
1667 For each of those recipes, you can specify a
1668 matching license string in a
1669 <filename>local.conf</filename> variable named
1670 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>.
1671 Specifying the matching license string signifies
1672 that you agree to the license.
1673 Thus, the build system can build the corresponding
1674 recipe and include the component in the image.
1675 See the
1676 "<ulink url='&YOCTO_DOCS_CM_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
1677 section in the Yocto Project Concepts Manual for
1678 details on how to use these variables.</para>
1679
1680 <para>If you build as you normally would, without
1681 specifying any recipes in the
1682 <filename>LICENSE_FLAGS_WHITELIST</filename>, the
1683 build stops and provides you with the list of recipes
1684 that you have tried to include in the image that
1685 need entries in the
1686 <filename>LICENSE_FLAGS_WHITELIST</filename>.
1687 Once you enter the appropriate license flags into
1688 the whitelist, restart the build to continue where
1689 it left off.
1690 During the build, the prompt will not appear again
1691 since you have satisfied the requirement.</para>
1692
1693 <para>Once the appropriate license flags are on the
1694 white list in the
1695 <filename>LICENSE_FLAGS_WHITELIST</filename> variable,
1696 you can build the encumbered image with no change
1697 at all to the normal build process.
1698 </para></listitem>
1699 <listitem><para>
1700 <emphasis>Get a Pre-Built Version of the BSP:</emphasis>
1701 You can get this type of BSP by selecting the
1702 "DOWNLOADS" item from the "SOFTWARE" tab on the
1703 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
1704 You can download BSP tarballs that contain
1705 proprietary components after agreeing to the
1706 licensing requirements of each of the individually
1707 encumbered packages as part of the download process.
1708 Obtaining the BSP this way allows you to access an
1709 encumbered image immediately after agreeing to the
1710 click-through license agreements presented by the
1711 website.
1712 If you want to build the image yourself using
1713 the recipes contained within the BSP tarball,
1714 you will still need to create an appropriate
1715 <filename>LICENSE_FLAGS_WHITELIST</filename>
1716 to match the encumbered recipes in the BSP.
1717 </para></listitem>
1718 </orderedlist>
1719 <note>
1720 Pre-compiled images are bundled with a time-limited
1721 kernel that runs for a predetermined amount of time
1722 (10 days) before it forces the system to reboot.
1723 This limitation is meant to discourage direct
1724 redistribution of the image.
1725 You must eventually rebuild the image if you want
1726 to remove this restriction.
1727 </note>
1728 </para>
1729</section>
1730
1731<section id='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>
1732 <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title>
1733
1734 <para>
1735 [INTRODUCE THE PROCEDURE AND LINK BACK TO <link linkend='bsp-layers'>BSP layer</link>.
1736 IF THERE IS A LAUNDRY LIST OF ITEMS THAT NEED DEFINITION OR GET SET
1737 UP AS A RESULT OF THIS PROCEDURE, LIST THEM HERE.]
1738 <itemizedlist>
1739 <listitem><para>[PARAMETER 1]</para></listitem>
1740 <listitem><para>[PARAMETER 2]</para></listitem>
1741 <listitem><para>[PARAMETER 3]</para></listitem>
1742 <listitem><para>[PARAMETER 4]</para></listitem>
1743 <listitem><para>[PARAMETER 5]</para></listitem>
1744 <listitem><para>[PARAMETER 6]</para></listitem>
1745 <listitem><para>[PARAMETER 7]</para></listitem>
1746 </itemizedlist>
1747 </para>
1748
1749 <para>
1750 The following procedure creates a BSP layer:
1751 <itemizedlist>
1752 <listitem><para>
1753 <emphasis>Create General Layer:</emphasis>
1754 Use the <filename>bitbake-layers</filename> script with the
1755 <filename>create-layer</filename> subcommand to create a
1756 new general layer.
1757 For instructions on how to create a general layer using the
1758 <filename>bitbake-layers</filename> script, see the
1759 "<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>"
1760 section in the Yocto Project Development Tasks Manual.
1761 </para></listitem>
1762 <listitem><para>
1763 <emphasis>Create a Machine Configuration File:</emphasis>
1764 Create a <filename>conf/machine/&gt;machine&lt;.conf</filename>
1765 file.
1766 See <filename>meta-yocto-bsp/conf/machine</filename> for sample
1767 <filename>&gt;machine.conf&lt;</filename> files.
1768 Other samples exist from other vendors such as
1769 <filename>meta-intel</filename>, <filename>meta-ti</filename>,
1770 and <filename>meta-freescale</filename> that have more specific machine
1771 and tuning examples.
1772 </para></listitem>
1773 <listitem><para>
1774 <emphasis>Create a Kernel Recipe:</emphasis>
1775 Create a kernel recipe in <filename>recipes-kernel/linux</filename>
1776 either using a linux-yocto kernel with a <filename>.bbappend</filename>
1777 file or a new custom kernel recipe file (i.e. <filename>.bb</filename>
1778 file).
1779 The BSP layers mentioned in the previous step also contain different
1780 kernel examples.
1781 You can start with the linux-yocto or use a custom kernel.
1782 See the
1783 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>"
1784 section in the Yocto Project Linux Kernel Development Manual
1785 for information on how to create a custom kernel.
1786 </para></listitem>
1787 </itemizedlist>
1788 </para>
1789
1790 <para>
1791 [THERE IS MORE INFORMATION THAT NEEDS TO BE FILLED IN HERE. THIS NEEDS TO
1792 BE PROVIDED BY ENGINEERS.]
1793 </para>
1794
1795 <para>
1796 The remainder of this section presents an example that uses
1797 <filename>myarm</filename> as the machine name and <filename>qemu</filename>
1798 as the machine architecture.
1799 Of the available architectures, <filename>qemu</filename> is the only architecture
1800 that causes the script to prompt you further for an actual architecture.
1801 In every other way, this architecture is representative of how creating a BSP for
1802 an actual machine would work.
1803 The reason the example uses this architecture is because it is an emulated architecture
1804 and can easily be followed without requiring actual hardware.
1805 </para>
1806
1807 <para>
1808 Following is a complete example:
1809 <literallayout class='monospaced'>
1810 [INSERT EXAMPLE - NEED EXAMPLE]
1811 </literallayout>
1812 </para>
1813
1814 <para>
1815 Once the BSP Layer is created, you must add it to your
1816 <filename>bblayers.conf</filename> file.
1817 Here is an example:
1818 <literallayout class='monospaced'>
2001 BBLAYERS = ? " \ 1819 BBLAYERS = ? " \
2002 /usr/local/src/yocto/meta \ 1820 /usr/local/src/yocto/meta \
2003 /usr/local/src/yocto/meta-poky \ 1821 /usr/local/src/yocto/meta-poky \
2004 /usr/local/src/yocto/meta-yocto-bsp \ 1822 /usr/local/src/yocto/meta-yocto-bsp \
2005 /usr/local/src/yocto/meta-myarm \ 1823 /usr/local/src/yocto/meta-myarm \
2006 " 1824 "
2007 </literallayout> 1825 </literallayout>
2008 Adding the layer to this file allows the build system to build the BSP and 1826 Adding the layer to this file allows the build system to build the BSP and
2009 find the layer along with other Metadata it needs. 1827 find the layer along with other Metadata it needs.
2010 </para> 1828 </para>
2011 </section> 1829</section>
2012
2013 <section id='managing-kernel-patches-and-config-items-with-yocto-kernel'>
2014 <title>Managing Kernel Patches and Config Items with yocto-kernel</title>
2015
2016 <para>
2017 Assuming you have created a <link linkend='bsp-layers'>BSP Layer</link> using
2018 <link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>
2019 <filename>yocto-bsp</filename></link> and you added it to your
2020 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
2021 variable in the <filename>bblayers.conf</filename> file, you can now use
2022 the <filename>yocto-kernel</filename> script to add patches and configuration
2023 items to the BSP's kernel.
2024 </para>
2025
2026 <para>
2027 The <filename>yocto-kernel</filename> script allows you to add, remove, and list patches
2028 and kernel config settings to a BSP's kernel
2029 <filename>.bbappend</filename> file.
2030 All you need to do is use the appropriate sub-command.
2031 Recall that the easiest way to see exactly what sub-commands are available
2032 is to use the <filename>yocto-kernel</filename> built-in help as follows:
2033 <literallayout class='monospaced'>
2034 $ yocto-kernel --help
2035 Usage:
2036
2037 Modify and list Yocto BSP kernel config items and patches.
2038
2039 usage: yocto-kernel [--version] [--help] COMMAND [ARGS]
2040
2041 Current 'yocto-kernel' commands are:
2042 config list List the modifiable set of bare kernel config options for a BSP
2043 config add Add or modify bare kernel config options for a BSP
2044 config rm Remove bare kernel config options from a BSP
2045 patch list List the patches associated with a BSP
2046 patch add Patch the Yocto kernel for a BSP
2047 patch rm Remove patches from a BSP
2048 feature list List the features used by a BSP
2049 feature add Have a BSP use a feature
2050 feature rm Have a BSP stop using a feature
2051 features list List the features available to BSPs
2052 feature describe Describe a particular feature
2053 feature create Create a new BSP-local feature
2054 feature destroy Remove a BSP-local feature
2055
2056 See 'yocto-kernel help COMMAND' for more information on a specific command.
2057
2058
2059
2060 Options:
2061 --version show program's version number and exit
2062 -h, --help show this help message and exit
2063 -D, --debug output debug information
2064 </literallayout>
2065 </para>
2066
2067 <para>
2068 The <filename>yocto-kernel patch add</filename> sub-command allows you to add a
2069 patch to a BSP.
2070 The following example adds two patches to the <filename>myarm</filename> BSP:
2071 <literallayout class='monospaced'>
2072 $ yocto-kernel patch add myarm ~/test.patch
2073 Added patches:
2074 test.patch
2075
2076 $ yocto-kernel patch add myarm ~/yocto-testmod.patch
2077 Added patches:
2078 yocto-testmod.patch
2079 </literallayout>
2080 <note>Although the previous example adds patches one at a time, it is possible
2081 to add multiple patches at the same time.</note>
2082 </para>
2083
2084 <para>
2085 You can verify patches have been added by using the
2086 <filename>yocto-kernel patch list</filename> sub-command.
2087 Here is an example:
2088 <literallayout class='monospaced'>
2089 $ yocto-kernel patch list myarm
2090 The current set of machine-specific patches for myarm is:
2091 1) test.patch
2092 2) yocto-testmod.patch
2093 </literallayout>
2094 </para>
2095
2096 <para>
2097 You can also use the <filename>yocto-kernel</filename> script to
2098 remove a patch using the <filename>yocto-kernel patch rm</filename> sub-command.
2099 Here is an example:
2100 <literallayout class='monospaced'>
2101 $ yocto-kernel patch rm myarm
2102 Specify the patches to remove:
2103 1) test.patch
2104 2) yocto-testmod.patch
2105 1
2106 Removed patches:
2107 test.patch
2108 </literallayout>
2109 </para>
2110
2111 <para>
2112 Again, using the <filename>yocto-kernel patch list</filename> sub-command,
2113 you can verify that the patch was in fact removed:
2114 <literallayout class='monospaced'>
2115 $ yocto-kernel patch list myarm
2116 The current set of machine-specific patches for myarm is:
2117 1) yocto-testmod.patch
2118 </literallayout>
2119 </para>
2120
2121 <para>
2122 In a completely similar way, you can use the <filename>yocto-kernel config add</filename>
2123 sub-command to add one or more kernel config item settings to a BSP.
2124 The following commands add a couple of config items to the
2125 <filename>myarm</filename> BSP:
2126 <literallayout class='monospaced'>
2127 $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y
2128 Added item:
2129 CONFIG_MISC_DEVICES=y
2130
2131 $ yocto-kernel config add myarm CONFIG_YOCTO_TESTMOD=y
2132 Added item:
2133 CONFIG_YOCTO_TESTMOD=y
2134 </literallayout>
2135 <note>
2136 Although the previous example adds config items one at a time, it is possible
2137 to add multiple config items at the same time.
2138 </note>
2139 </para>
2140
2141 <para>
2142 You can list the config items now associated with the BSP.
2143 Doing so shows you the config items you added as well as others associated
2144 with the BSP:
2145 <literallayout class='monospaced'>
2146 $ yocto-kernel config list myarm
2147 The current set of machine-specific kernel config items for myarm is:
2148 1) CONFIG_MISC_DEVICES=y
2149 2) CONFIG_YOCTO_TESTMOD=y
2150 </literallayout>
2151 </para>
2152
2153 <para>
2154 Finally, you can remove one or more config items using the
2155 <filename>yocto-kernel config rm</filename> sub-command in a manner
2156 completely analogous to <filename>yocto-kernel patch rm</filename>.
2157 </para>
2158 </section>
2159 </section>
2160</chapter> 1830</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-12 15:29:08 +0000