summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-07-27 10:39:56 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-08-04 15:06:46 +0100
commit5b8301a3b835890808e22d0fe34caac5ae5071d6 (patch)
treee1b9f6fd39a7379e6fe6fc1ac581fe88c3642844
parentb67922f0c3ef71629a880ec618e632c7c2bf4c13 (diff)
downloadpoky-5b8301a3b835890808e22d0fe34caac5ae5071d6.tar.gz
documentation/dev-manual/dev-manual-cases.xml: generalized the BSP case
Because the BSP example is now in an appendix, I re-wrote this section to overview the case. (From yocto-docs rev: c0d88c6050bd17d65d8fe8c8abb227998fd4c11e) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat
-rw-r--r--documentation/dev-manual/dev-manual-cases.xml842
1 files changed, 155 insertions, 687 deletions
diff --git a/documentation/dev-manual/dev-manual-cases.xml b/documentation/dev-manual/dev-manual-cases.xml
index 28d48d0c9e..ebc8eeca1e 100644
--- a/documentation/dev-manual/dev-manual-cases.xml
+++ b/documentation/dev-manual/dev-manual-cases.xml
@@ -15,6 +15,11 @@
15</para> 15</para>
16 16
17<para> 17<para>
18 This chapter presents an overview of the primary cases.
19 Supsequent appendices in the manual provide detailed explanations of the examples.
20</para>
21
22<para>
18 [WRITERS NOTE: What is undetermined at this point is how much of the entire development process 23 [WRITERS NOTE: What is undetermined at this point is how much of the entire development process
19 we include in this particular chapter. 24 we include in this particular chapter.
20 In other words, do we cover debugging and emulation steps here on a case-specific basis? 25 In other words, do we cover debugging and emulation steps here on a case-specific basis?
@@ -53,701 +58,164 @@
53 </note> 58 </note>
54 59
55 <para> 60 <para>
61 The remainder of this section presents the basic steps to create a BSP basing it on an
62 existing BSP that ships with the Yocto Project.
63 You can reference <xref linkend='dev-manual-bsp-appendix'>BSP Development Case</xref>
64 for a detailed example that uses the Crown Bay BSP as a base BSP from which to start.
65 </para>
66
67 <para>
56 Here are the basic steps involved in creating a BSP: 68 Here are the basic steps involved in creating a BSP:
57 <orderedlist> 69 <orderedlist>
58 <listitem><para>Be sure your host development system is set up to support 70 <listitem><para><emphasis>Set up your host development system to support
59 development using the Yocto Project. 71 development using the Yocto Project</emphasis>: See
60 See
61 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'> 72 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>
62 The Linux Distributions</ulink> section and 73 The Linux Distributions</ulink> section and
63 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'> 74 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'>
64 The Packages</ulink> section both 75 The Packages</ulink> section both
65 in the Yocto Project Quick Start for requirements. 76 in the Yocto Project Quick Start for requirements.
66 You will also need a release of Yocto Project installed on the host.</para></listitem> 77 You will also need a release of Yocto Project installed on the host.</para></listitem>
67 <listitem><para>Choose a BSP available with Yocto Project that most closely represents 78 <listitem><para><emphasis>Establish a local copy of the Yocto Project files on your
68 your hardware.</para></listitem> 79 system</emphasis>: You need to have the Yocto Project files available on your host system.
69 <listitem><para>Get set up with a base BSP.</para></listitem> 80 Having the Yocto Project files on your system gives you access to the build
70 <listitem><para>Make a copy of the existing BSP and isolate your work by creating a layer 81 process and tools you need.
71 for your recipes.</para></listitem> 82 For information on how to get these files, see the
72 <listitem><para>Make configuration and recipe changes to your new BSP layer.</para></listitem> 83 <xref linkend='getting-setup'>Getting Setup</xref> section in this manual.</para></listitem>
73 <listitem><para>Prepare for the build.</para></listitem> 84 <listitem><para><emphasis>Choose a Yocto Project-supported BSP as your base BSP</emphasis>:
74 <listitem><para>Select and configure the kernel.</para></listitem> 85 The Yocto Project ships with several BSPs that support various hardware.
75 <listitem><para>Identify the machine branch.</para></listitem> 86 It is best to base your new BSP on an existing BSP rather than create all the
76 <listitem><para>Build the image.</para></listitem> 87 recipes and configuration files from scratch.
88 While it is possible to create everything from scratch, basing your new BSP
89 on something that is close is much easier.
90 Or, at a minimum, it gives you some structure with which to start.</para>
91 <para>At this point you need to understand your target hardware well enough to determine which
92 existing BSP it most closely matches.
93 Things to consider are your hardware’s on-board features such as CPU type and graphics support.
94 You should look at the README files for supported BSPs to get an idea of which one
95 you could use.
96 A generic Atom-based BSP to consider is the Crown Bay that does not support
97 the Intel® Embedded Media Graphics Driver (EMGD).
98 The remainder of this example uses that base BSP.</para>
99 <para>To see the supported BSPs, go to the Yocto Project
100 <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click
101 on “BSP Downloads.”</para></listitem>
102 <listitem><para><emphasis>Establish a local copy of the base BSP files</emphasis>: Having
103 the BSP files on your system gives you access to the build
104 process and tools you need.
105 For information on how to get these files, see
106 <xref linkend='getting-setup'>Getting Setup</xref> earlier in this manual.</para></listitem>
107 <listitem><para><emphasis>Create your own BSP layer</emphasis>: Layers are ideal for
108 isolating and storing work for a given piece of hardware.
109 A layer is really just a location or area in which you place the recipes for your BSP.
110 In fact, a BSP is, in itself, a special type of layer.
111 Consider an application as another example that illustrates a layer.
112 Suppose you are creating an application that has library or other dependencies in
113 order for it to compile and run.
114 The layer, in this case, would be where all the recipes that define those dependencies
115 are kept. The key point for a layer is that it is an isolated area that contains
116 all the relevant information for the project that the Yocto Project build
117 system knows about.</para>
118 <note>The Yocto Project supports four BSPs that are part of the
119 Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>,
120 <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>.
121 The recipes and configurations for these four BSPs are located and dispersed
122 within local Yocto Project files.
123 Consequently, they are not totally isolated in the spirit of layers unless you think
124 of <filename>meta-yocto</filename> as a layer itself.
125 On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest,
126 N450, and Sugar Bay are isolated.</note>
127 <para>When you set up a layer for a new BSP you should follow a standard layout.
128 This layout is described in the
129 <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>
130 Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
131 Guide.
132 In the standard layout you will notice a suggested structure for recipes and
133 configuration information.
134 You can see the standard layout for the Crown Bay BSP in this example by examining the
135 directory structure of the <filename>meta-crownbay</filename> layer inside the
136 local Yocto Project files.</para></listitem>
137 <listitem><para><emphasis>Make configuration and recipe changes to your new BSP
138 layer</emphasis>: The standard BSP layer structure organizes the files you need to edit in
139 <filename>conf</filename> and several <filename>recipes-*</filename> within the
140 BSP layer.</para>
141 <para>Configuration changes identify where your new layer is on the local system
142 and identify which kernel you are going to use.
143 Recipe changes include altering recipes (<filename>.bb</filename> files), removing
144 recipes you don't use, and adding new recipes that you need to support your hardware.
145 </para></listitem>
146 <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the
147 changes to your BSP layer there remains a few things
148 you need to do for the Yocto Project build system in order for it to create your image.
149 You need to get the build environment ready by sourcing an environment setup script
150 and you need to be sure two key configuration files are configured appropriately.</para>
151 <para>The entire process for building an image is overviewed in the
152 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'>
153 Building an Image</ulink> section of the Yocto Project Quick Start.
154 You might want to reference this information.</para></listitem>
155 <listitem><para><emphasis>Build the image</emphasis>: The Yocto Project uses the BitBake
156 tool to build images based on the type of image
157 you want to create.
158 You can find more information on BitBake
159 <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para>
160 <para>The build process supports several types of images to satisfy different needs.
161 When you issue the BitBake command you provide a “top-level” recipe that essentially
162 starts the process off of building the type of image you want.</para>
163 <para>[WRITER'S NOTE: Consider moving this to the Poky Reference Manual.]</para>
164 <para>You can find these recipes in the <filename>meta/recipes-core/images</filename> and
165 <filename>meta/recipes-sato/images</filename> directories of your local Yocto Project
166 file structure (Git repository or extracted release tarball).
167 Although the recipe names are somewhat explanatory, here is a list that describes them:
168 <itemizedlist>
169 <listitem><para><emphasis>Base</emphasis> – A foundational basic image without support
170 for X that can be reasonably used for customization.</para></listitem>
171 <listitem><para><emphasis>Core</emphasis> – A foundational basic image with support for
172 X that can be reasonably used for customization.</para></listitem>
173 <listitem><para><emphasis>Direct Disk</emphasis> – An image that you can copy directory to
174 the disk of the target device.</para></listitem>
175 <listitem><para><emphasis>Live</emphasis> – An image you can run from a USB device or from
176 a CD without having to first install something.</para></listitem>
177 <listitem><para><emphasis>Minimal</emphasis> – A small image without a GUI.
178 This image is not much more than a kernel with a shell.</para></listitem>
179 <listitem><para><emphasis>Minimal Development</emphasis> – A Minimal image suitable for
180 development work.</para></listitem>
181 <listitem><para><emphasis>Minimal Direct Disk</emphasis> – A Minimal Direct
182 Disk image.</para></listitem>
183 <listitem><para><emphasis>Minimal RAM-based Initial Root Filesystem</emphasis> –
184 A minimal image
185 that has the <filename>initramfs</filename> as part of the kernel, which allows the
186 system to find the first “init” program more efficiently.</para></listitem>
187 <listitem><para><emphasis>Minimal Live</emphasis> – A Minimal Live image.</para></listitem>
188 <listitem><para><emphasis>Minimal MTD Utilities</emphasis> – A minimal image that has support
189 for the MTD utilities, which let the user interact with the MTD subsystem in
190 the kernel to perform operations on flash devices.</para></listitem>
191 <listitem><para><emphasis>Sato</emphasis> – An image with Sato support, a mobile environment
192 and visual style that works well with mobile devices.</para></listitem>
193 <listitem><para><emphasis>Sato Development</emphasis> – A Sato image suitable for
194 development work.</para></listitem>
195 <listitem><para><emphasis>Sato Direct Disk</emphasis> – A Sato Direct
196 Disk image.</para></listitem>
197 <listitem><para><emphasis>Sato Live</emphasis> – A Sato Live image.</para></listitem>
198 <listitem><para><emphasis>Sato SDK</emphasis> – A Sato image that includes the Yocto Project
199 toolchain and development libraries.</para></listitem>
200 <listitem><para><emphasis>Sato SDK Direct Disk</emphasis> – A Sato SDK Direct
201 Disk image.</para></listitem>
202 <listitem><para><emphasis>Sato SDK Live</emphasis> – A Sato SDK Live
203 image.</para></listitem>
204 </itemizedlist>
205 </para></listitem>
77 </orderedlist> 206 </orderedlist>
78 You can view a video presentation of the BSP creation process
79 <ulink url='http://free-electrons.com/blog/elc-2011-videos'>here</ulink>.
80 You can also find supplemental information in the
81 <ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'>
82 Board Support Package (BSP) Development Guide</ulink>.
83 Finally, there is wiki page write up of the example located
84 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
85 here</ulink> you might find helpful.
86 </para> 207 </para>
87 208
88 <section id='setting-up-yocto-project'> 209 <para>
89 <title>Setting Up Yocto Project</title> 210 You can view a video presentation of the BSP creation process
90 211 <ulink url='http://free-electrons.com/blog/elc-2011-videos'>here</ulink>.
91 <para> 212 You can also find supplemental information in the
92 You need to have the Yocto Project files available on your host system. 213 <ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'>
93 You can get files through tarball extraction or by cloning the <filename>poky</filename> 214 Board Support Package (BSP) Development Guide</ulink>.
94 Git repository. 215 Finally, there is wiki page write up of the example located
95 Typically, cloning the Git repository is the method to use. 216 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
96 This allows you to maintain a complete history of changes and facilitates you 217 here</ulink> you might find helpful.
97 contributing back to the Yocto Project. 218 </para>
98 However, if you just want a hierarchical file structure that contains the recipes
99 and metadata that let you develop you can download tarballs from the
100 <ulink url='http://yoctoproject.org/download'>download page</ulink>.
101 </para>
102
103 <para>
104 Regardless of the method you use this manual will refer to the resulting
105 hierarchical set of files as "the local Yocto Project files."
106 </para>
107
108 <para>
109 [WRITER'S NOTE: I need to substitute correct and actual filenames for the
110 1.1 release throughout this example once they become available.]
111 </para>
112
113 <para>
114 If you download a tarball you can extract it into any directory you want using the
115 tar command.
116 For example, the following command extracts the Yocto Project 1.1 release tarball
117 into the current working directory and sets up a file structure whose top-level
118 directory is named <filename>poky-1.1</filename>:
119 <literallayout class='monospaced'>
120 $ tar xfj poky-1.1.tar.bz2
121 </literallayout>
122 </para>
123
124 <para>
125 The following transcript shows how to clone the <filename>poky</filename> Git repository
126 into the current working directory.
127 The command creates the repository in a directory named <filename>poky</filename>:
128 <literallayout class='monospaced'>
129 $ git clone git://git.yoctoproject.org/poky
130 Initialized empty Git repository in /home/scottrif/poky/.git/
131 remote: Counting objects: 107624, done.
132 remote: Compressing objects: 100% (37128/37128), done.
133 remote: Total 107624 (delta 73393), reused 99851 (delta 67287)
134 Receiving objects: 100% (107624/107624), 69.74 MiB | 483 KiB/s, done.
135 Resolving deltas: 100% (73393/73393), done.
136 </literallayout>
137 </para>
138
139 <para>
140 Once you have the local <filename>poky</filename> Git repository set up,
141 you have many development branches from which you can work.
142 From inside the repository you can see the branch names and the tag names used
143 in the Git repository using either of the following two commands:
144 <literallayout class='monospaced'>
145 $ git branch -a
146 $ git tag -l
147 </literallayout>
148 For this example we are going to use the Yocto Project 1.1 Release,
149 which maps to the <filename>1.1</filename> branch in the repository.
150 These commands create a local branch named <filename>1.1</filename>
151 that tracks the remote branch of the same name.
152 <literallayout class='monospaced'>
153
154 $ cd poky
155 $ git checkout -b 1.1 origin/1.1
156 Switched to a new branch '1.1'
157 </literallayout>
158 </para>
159 </section>
160
161 <section id='choosing-a-base-bsp'>
162 <title>Choosing a Base BSP</title>
163
164 <para>
165 The Yocto Project ships with several BSPs that support various hardware.
166 It is best to base your new BSP on an existing BSP rather than create all the
167 recipes and configuration files from scratch.
168 While it is possible to create everything from scratch, basing your new BSP
169 on something that is close is much easier.
170 Or, at a minimum, it gives you some structure with which to start.
171 </para>
172
173 <para>
174 At this point you need to understand your target hardware well enough to determine which
175 existing BSP it most closely matches.
176 Things to consider are your hardware’s on-board features such as CPU type and graphics support.
177 You should look at the README files for supported BSPs to get an idea of which one
178 you could use.
179 A generic Atom-based BSP to consider is the Crown Bay that does not support
180 the Intel® Embedded Media Graphics Driver (EMGD).
181 The remainder of this example uses that base BSP.
182 </para>
183
184 <para>
185 To see the supported BSPs, go to the Yocto Project
186 <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click
187 on “BSP Downloads.”
188 </para>
189 </section>
190
191 <section id='getting-your-base-bsp'>
192 <title>Getting Your Base BSP</title>
193
194 <para>
195 You need to have the base BSP layer on your development system.
196 Like the local Yocto Project files, you can get the BSP
197 layer one of two ways:
198 download the BSP tarball and extract it, or set up a local Git repository that
199 has the Yocto Project BSP layers.
200 You should use the same method that you used to get the local Yocto Project files earlier.
201 </para>
202
203 <para>
204 If you are using tarball extraction, simply download the tarball for the base
205 BSP you chose in the previous step and then extract it into any directory
206 you choose using the tar command.
207 Upon extraction, the BSP source directory (layer) will be named
208 <filename>meta-&lt;BSP_name&gt;</filename>.
209 The following command extracts the Crown Bay BSP into the current directory and names it
210 <filename>meta-crownbay</filename>:
211 <literallayout class='monospaced'>
212 $ tar xjf crownbay-noemgd-1.1.tar.bz2
213 </literallayout>
214 </para>
215
216 <para>
217 If you cloned a <filename>poky</filename> Git repository
218 then you need to set up a different local Git repository
219 (<filename>meta-intel</filename>) for the BSP.
220 The <filename>meta-intel</filename> Git repository contains all the metadata
221 that supports BSP creation.
222 When you set up the <filename>meta-intel</filename> Git repository you can
223 set it up anywhere you want.
224 We will set up the repository inside the
225 <filename>poky</filename> Git repository in this example.
226 </para>
227
228 <para>
229 The following transcript shows the steps to clone the <filename>meta-intel</filename>
230 Git repository inside the <filename>poky</filename> Git repository created earlier in this
231 example.
232 <literallayout class='monospaced'>
233 $cd poky
234 $ git clone git://git.yoctoproject.org/meta-intel.git
235 Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/
236 remote: Counting objects: 1325, done.
237 remote: Compressing objects: 100% (1078/1078), done.
238 remote: Total 1325 (delta 546), reused 85 (delta 27)
239 Receiving objects: 100% (1325/1325), 1.56 MiB | 330 KiB/s, done.
240 Resolving deltas: 100% (546/546), done.
241 </literallayout>
242 </para>
243
244 <para>
245 Because <filename>meta-intel</filename> is its own Git repository you will want
246 to be sure you are in the appropriate branch for your work.
247 For this example we are going to use the <filename>1.1</filename> branch.
248 <literallayout class='monospaced'>
249 $ cd meta-intel
250 $ git checkout -b 1.1 origin/1.1
251 Switched to a new branch 'bernard'
252 </literallayout>
253 </para>
254 </section>
255
256 <section id='making-a-copy-of-the-base bsp-to-create-your-new-bsp-layer'>
257 <title>Making a Copy of the Base BSP to Create Your New BSP Layer</title>
258
259 <para>
260 Now that you have the local Yocto Project files and the base BSP files you need to create a
261 new layer for your BSP.
262 </para>
263
264 <para>
265 Layers are ideal for isolating and storing work for a given piece of hardware.
266 A layer is really just a location or area in which you place the recipes for your BSP.
267 In fact, a BSP is, in itself, a special type of layer.
268 Consider an application as another example that illustrates a layer.
269 Suppose you are creating an application that has library or other dependencies in
270 order for it to compile and run.
271 The layer, in this case, would be where all the recipes that define those dependencies
272 are kept. The key point for a layer is that it is an isolated area that contains
273 all the relevant information for the project that the Yocto Project build system knows about.
274 </para>
275
276 <note>
277 The Yocto Project supports four BSPs that are part of the
278 Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>,
279 <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>.
280 The recipes and configurations for these four BSPs are located and dispersed
281 within local Yocto Project files.
282 Consequently, they are not totally isolated in the spirit of layers unless you think
283 of <filename>meta-yocto</filename> as a layer itself.
284 On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest,
285 N450, and Sugar Bay are isolated.
286 </note>
287
288 <para>
289 When you set up a layer for a new BSP you should follow a standard layout.
290 This layout is described in the
291 <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>
292 Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
293 Guide.
294 In the standard layout you will notice a suggested structure for recipes and
295 configuration information.
296 You can see the standard layout for the Crown Bay BSP in this example by examining the
297 directory structure of the <filename>meta-crownbay</filename> layer inside the
298 local Yocto Project files.
299 </para>
300
301 <para>
302 To create your BSP layer you simply copy the <filename>meta-crownbay</filename>
303 layer to a new layer.
304 For this example the new layer will be named <filename>meta-mymachine</filename>.
305 The name must follow the BSP layer naming convention, which is
306 <filename>meta-&lt;name&gt;</filename>.
307 The following example assumes your working directory is <filename>meta-intel</filename>
308 inside the local Yocto Project files.
309 If you downloaded and expanded a Crown Bay tarball then you simply copy the resulting
310 <filename>meta-crownbay</filename> directory structure to a location of your choice.
311 Good practice for a Git repository, however, is to just copy the new layer alongside
312 the existing
313 BSP layers in the <filename>meta-intel</filename> Git repository:
314 <literallayout class='monospaced'>
315 $ cp -a meta-crownbay/ meta-mymachine
316 </literallayout>
317 </para>
318 </section>
319
320 <section id='making-changes-to-your-bsp'>
321 <title>Making Changes to Your BSP</title>
322
323 <para>
324 Right now you have two identical BSP layers with different names:
325 <filename>meta-crownbay</filename> and <filename>meta-mymachine</filename>.
326 You need to change your configurations so that they work for your new BSP and
327 your particular hardware.
328 We will look first at the configurations, which are all done in the layer’s
329 <filename>conf</filename> directory.
330 </para>
331
332 <para>
333 First, since in this example the new BSP will not support EMGD we will get rid of the
334 <filename>crownbay.conf</filename> file and then rename the
335 <filename>crownbay-noemgd.conf</filename> file to <filename>mymachine.conf</filename>.
336 Much of what we do in the configuration directory is designed to help the Yocto Project
337 build system work with the new layer and to be able to find and use the right software.
338 The following two commands result in a single machine configuration file named
339 <filename>mymachine.conf</filename>.
340 <literallayout class='monospaced'>
341 $ rm meta-mymachine/conf/machine/crownbay.conf
342 $ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \
343 meta-mymachine/conf/machine/mymachine.conf
344 </literallayout>
345 </para>
346
347 <para>
348 The next step makes changes to <filename>mymachine.conf</filename> itself.
349 The only changes needed for this example are changes to the comment lines.
350 Here we simply substitute the Crown Bay name with an appropriate name.
351 </para>
352
353 <para>
354 Note that inside the <filename>mymachine.conf</filename> is the
355 <filename>PREFERRED_PROVIDER_virtual/kernel</filename> statement.
356 This statement identifies the kernel that the BSP is going to use.
357 In this case the BSP is using <filename>linux-yocto</filename>, which is the
358 current Linux Yocto kernel based on the Linux 2.6.37 release.
359 </para>
360
361 <para>
362 The next configuration file in the new BSP layer we need to edit is <filename>layer.conf</filename>.
363 This file identifies build information needed for the new layer.
364 You can see the
365 <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout-layer'>
366 Layer Configuration File</ulink> section in the Board Support Packages (BSP) Development Guide
367 for more information on this configuration file.
368 Basically, we are changing the existing statements to work with our BSP.
369 </para>
370
371 <para>
372 The file contains these statements that reference the Crown Bay BSP:
373 <literallayout class='monospaced'>
374 BBFILE_COLLECTIONS += "crownbay"
375 BBFILE_PATTERN_crownbay := "^${LAYERDIR}/"
376 BBFILE_PRIORITY_crownbay = "6"
377 </literallayout>
378 </para>
379
380 <para>
381 Simply substitute the machine string name <filename>crownbay</filename>
382 with the new machine name <filename>mymachine</filename> to get the following:
383 <literallayout class='monospaced'>
384 BBFILE_COLLECTIONS_mymachine += "mymachine"
385 BBFILE_PATTERN_mymachine := "^${LAYERDIR}/"
386 BBFILE_PRIORITY_mymachine = "6"
387 </literallayout>
388 </para>
389
390 <para>
391 Now we will take a look at the recipes in your new layer.
392 The standard BSP structure has areas for BSP, graphics, core, and kernel recipes.
393 When you create a BSP you use these areas for appropriate recipes and append files.
394 Recipes take the form of <filename>.bb</filename> files.
395 If you want to leverage the existing recipes the Yocto Project build system uses
396 but change those recipes you can use <filename>.bbappend</filename> files.
397 All new recipes and append files for your layer must go in the layer’s
398 <filename>recipes-bsp</filename>, <filename>recipes-kernel</filename>,
399 <filename>recipes-core</filename>, and
400 <filename>recipes-graphics</filename> directories.
401 </para>
402
403 <para>
404 First, let's look at <filename>recipes-bsp</filename>.
405 For this example we are not adding any new BSP recipes.
406 And, we only need to remove the formfactor we do not want and change the name of
407 the remaining one that doesn't support EMGD.
408 These commands take care of the <filename>recipes-bsp</filename> recipes:
409 <literallayout class='monospaced'>
410 $ rm &dash;rf meta-mymachine/recipes-graphics/xorg-xserver/*emgd*
411 $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \
412 meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine
413 </literallayout>
414 </para>
415
416 <para>
417 Now let's look at <filename>recipes-graphics</filename>.
418 For this example we want to remove anything that supports EMGD and
419 be sure to rename remaining directories appropriately.
420 The following commands clean up the <filename>recipes-graphics</filename> directory:
421 <literallayout class='monospaced'>
422 $ rm &dash;rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-emgd*
423 $ rm &dash;rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay
424 $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd \
425 meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine
426 </literallayout>
427 </para>
428
429 <para>
430 At this point the <filename>recipes-graphics</filename> directory just has files that
431 support Video Electronics Standards Association (VESA) graphics modes and not EMGD.
432 </para>
433
434 <para>
435 Now let's look at changes in <filename>recipes-core</filename>.
436 The file <filename>task-core-tools.bbappend</filename> in
437 <filename>recipes-core/tasks</filename> appends the similarly named recipe
438 located in the local Yocto Project files at
439 <filename>meta/recipes-core/tasks</filename>.
440 The "append" file in our layer right now is Crown Bay-specific and supports
441 EMGD and non-EMGD.
442 Here are the contents of the file:
443 <literallayout class='monospaced'>
444 RRECOMMENDS_task-core-tools-profile_append_crownbay = " systemtap"
445 RRECOMMENDS_task-core-tools-profile_append_crownbay-noemgd = " systemtap"
446 </literallayout>
447 </para>
448
449 <para>
450 The <filename>RRECOMMENDS</filename> statements list packages that
451 extend usability.
452 The first <filename>RRECOMMENDS</filename> statement can be removed, while the
453 second one can be changed to reflect <filename>meta-mymachine</filename>:
454 <literallayout class='monospaced'>
455 RRECOMMENDS_task-core-tools-profile_append_mymachine = " systemtap"
456 </literallayout>
457 </para>
458
459 <para>
460 Finally, let's look at <filename>recipes-kernel</filename> changes.
461 Recall that the BSP uses the <filename>linux-yocto</filename> kernel as determined
462 earlier in the <filename>mymachine.conf</filename>.
463 The recipe for that kernel is not located in the
464 BSP layer but rather in the local Yocto Project files at
465 <filename>meta/recipes-kernel/linux</filename> and is
466 named <filename>linux-yocto-2.6.37.bb</filename>.
467 The <filename>SRCREV_machine</filename> and <filename>SRCREV_meta</filename>
468 statements point to the exact commits used by the Yocto Project development team
469 in their source repositories that identify the right kernel for our hardware.
470 </para>
471
472 <para>
473 However, in the <filename>meta-mymachine</filename> layer in
474 <filename>recipes-kernel/linux</filename> resides a <filename>.bbappend</filename>
475 file named <filename>linux-yocto-2.6.37.bbappend</filename> that
476 is appended to the recipe of the same name in <filename>meta/recipes-kernel/link</filename>.
477 Thus, the <filename>SRCREV</filename> statements in the "append" file override
478 the more general statements found in <filename>meta</filename>.
479 </para>
480
481 <para>
482 The <filename>SRCREV</filename> statements in the "append" file currently identify
483 the kernel that supports the Crown Bay BSP with and without EMGD support.
484 Here are the statements:
485 <literallayout class='monospaced'>
486 SRCREV_machine_pn-linux-yocto_crownbay ?= \
487 "372c0ab135978bd8ca3a77c88816a25c5ed8f303"
488 SRCREV_meta_pn-linux-yocto_crownbay ?= \
489 "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b"
490
491 SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= \
492 "372c0ab135978bd8ca3a77c88816a25c5ed8f303"
493 SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= \
494 "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b"
495 </literallayout>
496 </para>
497
498 <para>
499 You will notice that there are two pairs of <filename>SRCREV</filename> statements.
500 The top pair identifies the kernel that supports
501 EMGD, which we don’t care about in this example.
502 The bottom pair identifies the kernel that we will use:
503 <filename>linux-yocto</filename>.
504 At this point though, the unique commit strings all are still associated with
505 Crown Bay and not <filename>meta-mymachine</filename>.
506 </para>
507
508 <para>
509 To fix this situation in <filename>linux-yocto-2.6.37.bbappend</filename>
510 we delete the two <filename>SRCREV</filename> statements that support
511 EMGD (the top pair).
512 We also change the remaining pair to specify <filename>mymachine</filename>
513 and insert the commit identifiers to identify the kernel in which we
514 are interested, which will be based on the <filename>atom-pc-standard</filename>
515 kernel.
516 Here are the final <filename>SRCREV</filename> statements:
517 <literallayout class='monospaced'>
518 SRCREV_machine_pn-linux-yocto-_mymachine ?= \
519 "fce17f046d3756045e4dfb49221d1cf60fcae329"
520 SRCREV_meta_pn-linux-yocto-stable_mymachine ?= \
521 "84f1a422d7e21fbc23a687035bdf9d42471f19e0"
522 </literallayout>
523 </para>
524
525 <para>
526 If you are familiar with Git repositories you probably won’t have trouble locating the
527 exact commit strings in the Yocto Project source repositories you need to change
528 the <filename>SRCREV</filename> statements.
529 You can find all the <filename>machine</filename> and <filename>meta</filename>
530 branch points (commits) for the <filename>linux-yocto-2.6.37</filename> kernel
531 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-2.6.37'>here</ulink>.
532 </para>
533
534 <para>
535 If you need a little more assistance after going to the link then do the following:
536 <orderedlist>
537 <listitem><para>Expand the list of branches by clicking <filename>[…]</filename></para></listitem>
538 <listitem><para>Click on the <filename>yocto/standard/common-pc/atom-pc</filename>
539 branch</para></listitem>
540 <listitem><para>Click on the commit column header to view the top commit</para></listitem>
541 <listitem><para>Copy the commit string for use in the
542 <filename>linux-yocto-2.6.37.bbappend</filename> file</para></listitem>
543 </orderedlist>
544 </para>
545
546 <para>
547 For the <filename>SRCREV</filename> statement that points to the <filename>meta</filename>
548 branch use the same procedure except expand the <filename>meta</filename>
549 branch in step 2 above.
550 </para>
551
552 <para>
553 Also in the <filename>linux-yocto-2.6.37.bbappend</filename> file are
554 <filename>COMPATIBLE_MACHINE</filename>, <filename>KMACHINE</filename>,
555 and <filename>KERNEL_FEATURES</filename> statements.
556 Two sets of these exist: one set supports EMGD and one set does not.
557 Because we are not interested in supporting EMGD those three can be deleted.
558 The remaining three must be changed so that <filename>mymachine</filename> replaces
559 <filename>crownbay-noemgd</filename> and <filename>crownbay</filename>.
560 Here is the final <filename>linux-yocto-2.6.37.bbappend</filename> file after all
561 the edits:
562 <literallayout class='monospaced'>
563 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
564
565 COMPATIBLE_MACHINE_mymachine = "mymachine"
566 KMACHINE_mymachine = "yocto/standard/mymachine"
567 KERNEL_FEATURES_append_mymachine += " cfg/smp.scc"
568
569 SRCREV_machine_pn-linux-yocto_mymachine ?= \
570 "fce17f046d3756045e4dfb49221d1cf60fcae329"
571 SRCREV_meta_pn-linux-yocto_mymachine ?= \
572 "84f1a422d7e21fbc23a687035bdf9d42471f19e0"
573 </literallayout>
574 </para>
575
576 <para>
577 In summary, the edits to the layer’s recipe files result in removal of any files and
578 statements that do not support your targeted hardware in addition to the inclusion
579 of any new recipes you might need.
580 In this example, it was simply a matter of ridding the new layer
581 <filename>meta-machine</filename> of any code that supported the EMGD features
582 and making sure we were identifying the kernel that supports our example, which
583 is the <filename>atom-pc-standard</filename> kernel.
584 We did not introduce any new recipes to the layer.
585 </para>
586
587 <para>
588 Finally, it is also important to update the layer’s <filename>README</filename>
589 file so that the information in it reflects your BSP.
590 </para>
591 </section>
592
593 <section id='preparing-for-the-build'>
594 <title>Preparing for the Build</title>
595
596 <para>
597 Once you have made all the changes to your BSP layer there remains a few things
598 you need to do for the Yocto Project build system in order for it to create your image.
599 You need to get the build environment ready by sourcing an environment setup script
600 and you need to be sure two key configuration files are configured appropriately.
601 </para>
602
603 <para>
604 The entire process for building an image is overviewed in the
605 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'>
606 Building an Image</ulink> section of the Yocto Project Quick Start.
607 You might want to reference this information.
608 The remainder of this section will apply to our example of the
609 <filename>meta-mymachine</filename> layer.
610 </para>
611
612 <para>
613 To get ready to build your image that uses the new layer you need to do the following:
614 <orderedlist>
615 <listitem><para>Get the environment ready for the build by sourcing the environment
616 script.
617 The environment script is in the top-level of the local Yocto Project files
618 directory structure.
619 The script has the string
620 <filename>init-build-env</filename> in the file’s name.
621 For this example, the following command gets the build environment ready:
622 <literallayout class='monospaced'>
623 $ source oe-init-build-env yocto-build
624 </literallayout>
625 When you source the script a build directory is created in the current
626 working directory.
627 In our example we were in the <filename>poky</filename> directory.
628 Thus, entering the previous command created the <filename>yocto-build</filename> directory.
629 If you do not provide a name for the build directory it defaults to
630 <filename>build</filename>.
631 The <filename>yocot-build</filename> directory contains a
632 <filename>conf</filename> directory that has
633 two configuration files you will need to check: <filename>bblayers.conf</filename>
634 and <filename>local.conf</filename>.</para></listitem>
635 <listitem><para>Check and edit the resulting <filename>local.conf</filename> file.
636 This file minimally identifies the machine for which to build the image by
637 configuring the <filename>MACHINE</filename> variable.
638 For this example you must set the variable to mymachine as follows:
639 <literallayout class='monospaced'>
640 MACHINE ??= “mymachine”
641 </literallayout>
642 You should also be sure any other variables in which you are interested are set.
643 Some variables to consider are <filename>BB_NUMBER_THREADS</filename>
644 and <filename>PARALLEL_MAKE</filename>, both of which can greatly reduce your build time
645 if you are using a multi-threaded development system (e.g. values of
646 <filename>8</filename> and <filename>j 6</filename>, respectively are optimal
647 for a development machine that has four available cores).</para></listitem>
648 <listitem><para>Update the <filename>bblayers.conf</filename> file so that it includes
649 the path to your new BSP layer.
650 In this example you need to include the pathname to <filename>meta-mymachine</filename>.
651 For this example the
652 <filename>BBLAYERS</filename> variable in the file would need to include the following path:
653 <literallayout class='monospaced'>
654 $HOME/poky/meta-intel/meta-mymachine
655 </literallayout></para></listitem>
656 </orderedlist>
657 </para>
658
659 <para>
660 The appendix
661 <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#ref-variables-glos'>
662 Reference: Variables Glossary</ulink> in the Yocto Project Reference Manual has more information
663 on configuration variables.
664 </para>
665 </section>
666
667 <section id='building-the-image'>
668 <title>Building the Image</title>
669
670 <para>
671 The Yocto Project uses the BitBake tool to build images based on the type of image
672 you want to create.
673 You can find more information on BitBake
674 <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.
675 </para>
676
677 <para>
678 The build process supports several types of images to satisfy different needs.
679 When you issue the BitBake command you provide a “top-level” recipe that essentially
680 starts the process off of building the type of image you want.
681 </para>
682
683 <para>
684 [WRITER'S NOTE: Consider moving this to the Poky Reference Manual.]
685 </para>
686
687 <para>
688 You can find these recipes in the <filename>meta/recipes-core/images</filename> and
689 <filename>meta/recipes-sato/images</filename> directories of your local Yocto Project
690 file structure (Git repository or extracted release tarball).
691 Although the recipe names are somewhat explanatory, here is a list that describes them:
692 <itemizedlist>
693 <listitem><para><emphasis>Base</emphasis> – A foundational basic image without support
694 for X that can be reasonably used for customization.</para></listitem>
695 <listitem><para><emphasis>Core</emphasis> – A foundational basic image with support for
696 X that can be reasonably used for customization.</para></listitem>
697 <listitem><para><emphasis>Direct Disk</emphasis> – An image that you can copy directory to
698 the disk of the target device.</para></listitem>
699 <listitem><para><emphasis>Live</emphasis> – An image you can run from a USB device or from
700 a CD without having to first install something.</para></listitem>
701 <listitem><para><emphasis>Minimal</emphasis> – A small image without a GUI.
702 This image is not much more than a kernel with a shell.</para></listitem>
703 <listitem><para><emphasis>Minimal Development</emphasis> – A Minimal image suitable for
704 development work.</para></listitem>
705 <listitem><para><emphasis>Minimal Direct Disk</emphasis> – A Minimal Direct Disk image.</para></listitem>
706 <listitem><para><emphasis>Minimal RAM-based Initial Root Filesystem</emphasis> – A minimal image
707 that has the <filename>initramfs</filename> as part of the kernel, which allows the
708 system to find the first “init” program more efficiently.</para></listitem>
709 <listitem><para><emphasis>Minimal Live</emphasis> – A Minimal Live image.</para></listitem>
710 <listitem><para><emphasis>Minimal MTD Utilities</emphasis> – A minimal image that has support
711 for the MTD utilities, which let the user interact with the MTD subsystem in
712 the kernel to perform operations on flash devices.</para></listitem>
713 <listitem><para><emphasis>Sato</emphasis> – An image with Sato support, a mobile environment
714 and visual style that works well with mobile devices.</para></listitem>
715 <listitem><para><emphasis>Sato Development</emphasis> – A Sato image suitable for
716 development work.</para></listitem>
717 <listitem><para><emphasis>Sato Direct Disk</emphasis> – A Sato Direct Disk image.</para></listitem>
718 <listitem><para><emphasis>Sato Live</emphasis> – A Sato Live image.</para></listitem>
719 <listitem><para><emphasis>Sato SDK</emphasis> – A Sato image that includes the Yocto Project
720 toolchain and development libraries.</para></listitem>
721 <listitem><para><emphasis>Sato SDK Direct Disk</emphasis> – A Sato SDK Direct
722 Disk image.</para></listitem>
723 <listitem><para><emphasis>Sato SDK Live</emphasis> – A Sato SDK Live image.</para></listitem>
724 </itemizedlist>
725 </para>
726
727 <para>
728 The remainder of this section applies to our example of the <filename>meta-mymachine</filename> layer.
729 </para>
730
731 <para>
732 To build the image for our <filename>meta-mymachine</filename> BSP enter the following command
733 from the same shell from which you ran the setup script.
734 You should run the <filename>bitbake</filename> command without any intervening shell commands.
735 For example, moving your working directory around could cause problems.
736 Here is the command for this example:
737 <literallayout class='monospaced'>
738 $ bitbake –k core-image-sato-live
739 </literallayout>
740 </para>
741
742 <para>
743 This command specifies an image that has Sato support and that can be run from a USB device or
744 from a CD without having to first install anything.
745 The build process takes significant time and includes thousands of tasks, which are reported
746 at the console.
747 If the build results in any type of error you should check for misspellings in the
748 files you changed or problems with your host development environment such as missing packages.
749 </para>
750 </section>
751 </section> 219 </section>
752 220
753 <section id='modifying-a-kernel-kernel-example'> 221 <section id='modifying-a-kernel-kernel-example'>
@@ -883,9 +351,9 @@
883 351
884 <para> 352 <para>
885 You need to have the Yocto Project files available on your host system. 353 You need to have the Yocto Project files available on your host system.
886 The process is identical to that described in getting the files in section 354 The process is identical to that described in the
887 <xref linkend='setting-up-yocto-project'>"Setting Up Yocto Project"</xref> for 355 <xref linkend='getting-setup'>"Getting Setup"</xref> section earlier in this
888 the BSP development case. 356 manual.
889 Be sure to either set up a local Git repository for <filename>poky</filename> 357 Be sure to either set up a local Git repository for <filename>poky</filename>
890 or download and unpack the Yocto Project release tarball. 358 or download and unpack the Yocto Project release tarball.
891 </para> 359 </para>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-24 10:27:18 +0000