summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--documentation/dev-manual/dev-manual-bsp-appendix.xml1658
1 files changed, 577 insertions, 1081 deletions
diff --git a/documentation/dev-manual/dev-manual-bsp-appendix.xml b/documentation/dev-manual/dev-manual-bsp-appendix.xml
index cf1033e530..f3927c35d2 100644
--- a/documentation/dev-manual/dev-manual-bsp-appendix.xml
+++ b/documentation/dev-manual/dev-manual-bsp-appendix.xml
@@ -3,129 +3,62 @@
3 3
4<appendix id='dev-manual-bsp-appendix'> 4<appendix id='dev-manual-bsp-appendix'>
5 5
6<title>Development Cases</title> 6<title>BSP Development Case</title>
7 7
8<para> 8<para>
9 Many development cases exist for which you can use the Yocto Project. 9 This appendix provides a complete BSP example.
10 However, for the purposes of this manual we are going to focus on two common development cases or groupings: 10 The example assumes the following:
11 System Development and User Application Development. 11 <itemizedlist>
12 System Development covers Board Support Package (BSP) development and kernel modification. 12 <listitem><para>No previous preparation or use of the Yocto Project.</para></listitem>
13 User Application Development covers development of applications that you intend to run on some 13 <listitem><para>Use of the Crown Bay Board Support Package (BSP) as a base BSP from
14 target hardware. 14 which to work from.</para></listitem>
15 <listitem><para>Shell commands assume <filename>bash</filename></para></listitem>
16 <listitem><para>Example was developed on an Intel-based Core i7 platform running
17 Ubuntu 10.04 LTS released in April of 2010.</para></listitem>
18 </itemizedlist>
15</para> 19</para>
16 20
17<para> 21<section id='setting-up-yocto-project-app'>
18 [WRITERS NOTE: What is undetermined at this point is how much of the entire development process 22 <title>Setting Up Yocto Project</title>
19 we include in this particular chapter.
20 In other words, do we cover debugging and emulation steps here on a case-specific basis?
21 Or, do we capture that information in the appropriate subsequent chapter by case?]
22</para>
23 23
24<section id='system-development-app'> 24 <para>
25 <title>System Development</title> 25 You need to have the Yocto Project files available on your host system.
26 You can get files through tarball extraction or by cloning the <filename>poky</filename>
27 Git repository.
28 Typically, cloning the Git repository is the method to use.
29 This allows you to maintain a complete history of changes and facilitates you
30 contributing back to the Yocto Project.
31 However, if you just want a hierarchical file structure that contains the recipes
32 and metadata that let you develop you can download tarballs from the
33 <ulink url='http://yoctoproject.org/download'>download page</ulink>.
34 </para>
26 35
27 <para> 36 <para>
28 System development involves modification or creation of an image that you want to run on 37 Regardless of the method you use this manual will refer to the resulting
29 a specific hardware target. 38 hierarchical set of files as "the local Yocto Project files."
30 Usually when you want to create an image that runs on embedded hardware the image does
31 not require the same amount of features that a full-fledged Linux distribution provides.
32 Thus, you can create a much smaller image that is designed to just use the hardware
33 features for your particular hardware.
34 </para> 39 </para>
35 40
36 <para> 41 <para>
37 To help you understand how system development works in the Yocto Project, this section 42 [WRITER'S NOTE: I need to substitute correct and actual filenames for the
38 covers two types of image development: BSP creation and kernel modification. 43 1.1 release throughout this example once they become available.]
39 </para> 44 </para>
40 45
41 <section id='developing-a-board-support-package-bsp-app'> 46 <para>
42 <title>Developing a Board Support Package (BSP)</title> 47 If you download a tarball you can extract it into any directory you want using the
43 48 tar command.
44 <para> 49 For example, the following command extracts the Yocto Project 1.1 release tarball
45 A BSP is a package of recipes that when applied while building an image results in 50 into the current working directory and sets up a file structure whose top-level
46 an image you can run on a particular board. 51 directory is named <filename>poky-1.1</filename>:
47 Thus, the package, when compiled into the new image, supports the operation of the board. 52 <literallayout class='monospaced'>
48 </para>
49
50 <note>
51 For a brief list of terms used when describing the development process in the Yocto Project,
52 see <xref linkend='yocto-project-terms'>Yocto Project Terms</xref> in this manual.
53 </note>
54
55 <para>
56 Here are the basic steps involved in creating a BSP:
57 <orderedlist>
58 <listitem><para>Be sure your host development system is set up to support
59 development using the Yocto Project.
60 See
61 <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
63 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'>
64 The Packages</ulink> section both
65 in the Yocto Project Quick Start for requirements.
66 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
68 your hardware.</para></listitem>
69 <listitem><para>Get set up with a base BSP.</para></listitem>
70 <listitem><para>Make a copy of the existing BSP and isolate your work by creating a layer
71 for your recipes.</para></listitem>
72 <listitem><para>Make configuration and recipe changes to your new BSP layer.</para></listitem>
73 <listitem><para>Prepare for the build.</para></listitem>
74 <listitem><para>Select and configure the kernel.</para></listitem>
75 <listitem><para>Identify the machine branch.</para></listitem>
76 <listitem><para>Build the image.</para></listitem>
77 </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>
87
88 <section id='setting-up-yocto-project-app'>
89 <title>Setting Up Yocto Project</title>
90
91 <para>
92 You need to have the Yocto Project files available on your host system.
93 You can get files through tarball extraction or by cloning the <filename>poky</filename>
94 Git repository.
95 Typically, cloning the Git repository is the method to use.
96 This allows you to maintain a complete history of changes and facilitates you
97 contributing back to the Yocto Project.
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 53 $ tar xfj poky-1.1.tar.bz2
121 </literallayout> 54 </literallayout>
122 </para> 55 </para>
123 56
124 <para> 57 <para>
125 The following transcript shows how to clone the <filename>poky</filename> Git repository 58 The following transcript shows how to clone the <filename>poky</filename> Git repository
126 into the current working directory. 59 into the current working directory.
127 The command creates the repository in a directory named <filename>poky</filename>: 60 The command creates the repository in a directory named <filename>poky</filename>:
128 <literallayout class='monospaced'> 61 <literallayout class='monospaced'>
129 $ git clone git://git.yoctoproject.org/poky 62 $ git clone git://git.yoctoproject.org/poky
130 Initialized empty Git repository in /home/scottrif/poky/.git/ 63 Initialized empty Git repository in /home/scottrif/poky/.git/
131 remote: Counting objects: 107624, done. 64 remote: Counting objects: 107624, done.
@@ -133,103 +66,102 @@
133 remote: Total 107624 (delta 73393), reused 99851 (delta 67287) 66 remote: Total 107624 (delta 73393), reused 99851 (delta 67287)
134 Receiving objects: 100% (107624/107624), 69.74 MiB | 483 KiB/s, done. 67 Receiving objects: 100% (107624/107624), 69.74 MiB | 483 KiB/s, done.
135 Resolving deltas: 100% (73393/73393), done. 68 Resolving deltas: 100% (73393/73393), done.
136 </literallayout> 69 </literallayout>
137 </para> 70 </para>
138 71
139 <para> 72 <para>
140 Once you have the local <filename>poky</filename> Git repository set up, 73 Once you have the local <filename>poky</filename> Git repository set up,
141 you have many development branches from which you can work. 74 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 75 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: 76 in the Git repository using either of the following two commands:
144 <literallayout class='monospaced'> 77 <literallayout class='monospaced'>
145 $ git branch -a 78 $ git branch -a
146 $ git tag -l 79 $ git tag -l
147 </literallayout> 80 </literallayout>
148 For this example we are going to use the Yocto Project 1.1 Release, 81 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. 82 which maps to the <filename>1.1</filename> branch in the repository.
150 These commands create a local branch named <filename>1.1</filename> 83 These commands create a local branch named <filename>1.1</filename>
151 that tracks the remote branch of the same name. 84 that tracks the remote branch of the same name.
152 <literallayout class='monospaced'> 85 <literallayout class='monospaced'>
153
154 $ cd poky 86 $ cd poky
155 $ git checkout -b 1.1 origin/1.1 87 $ git checkout -b 1.1 origin/1.1
156 Switched to a new branch '1.1' 88 Switched to a new branch '1.1'
157 </literallayout> 89 </literallayout>
158 </para> 90 </para>
159 </section> 91</section>
160 92
161 <section id='choosing-a-base-bsp-app'> 93<section id='choosing-a-base-bsp-app'>
162 <title>Choosing a Base BSP</title> 94 <title>Choosing a Base BSP</title>
163 95
164 <para> 96 <para>
165 The Yocto Project ships with several BSPs that support various hardware. 97 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 98 It is best to base your new BSP on an existing BSP rather than create all the
167 recipes and configuration files from scratch. 99 recipes and configuration files from scratch.
168 While it is possible to create everything from scratch, basing your new BSP 100 While it is possible to create everything from scratch, basing your new BSP
169 on something that is close is much easier. 101 on something that is close is much easier.
170 Or, at a minimum, it gives you some structure with which to start. 102 Or, at a minimum, it gives you some structure with which to start.
171 </para> 103 </para>
172 104
173 <para> 105 <para>
174 At this point you need to understand your target hardware well enough to determine which 106 At this point you need to understand your target hardware well enough to determine which
175 existing BSP it most closely matches. 107 existing BSP it most closely matches.
176 Things to consider are your hardware’s on-board features such as CPU type and graphics support. 108 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 109 You should look at the README files for supported BSPs to get an idea of which one
178 you could use. 110 you could use.
179 A generic Atom-based BSP to consider is the Crown Bay that does not support 111 A generic Atom-based BSP to consider is the Crown Bay that does not support
180 the Intel® Embedded Media Graphics Driver (EMGD). 112 the Intel® Embedded Media Graphics Driver (EMGD).
181 The remainder of this example uses that base BSP. 113 The remainder of this example uses that base BSP.
182 </para> 114 </para>
183 115
184 <para> 116 <para>
185 To see the supported BSPs, go to the Yocto Project 117 To see the supported BSPs, go to the Yocto Project
186 <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click 118 <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click
187 on “BSP Downloads.” 119 on “BSP Downloads.”
188 </para> 120 </para>
189 </section> 121</section>
190 122
191 <section id='getting-your-base-bsp-app'> 123<section id='getting-your-base-bsp-app'>
192 <title>Getting Your Base BSP</title> 124 <title>Getting Your Base BSP</title>
193 125
194 <para> 126 <para>
195 You need to have the base BSP layer on your development system. 127 You need to have the base BSP layer on your development system.
196 Like the local Yocto Project files, you can get the BSP 128 Like the local Yocto Project files, you can get the BSP
197 layer one of two ways: 129 layer one of two ways:
198 download the BSP tarball and extract it, or set up a local Git repository that 130 download the BSP tarball and extract it, or set up a local Git repository that
199 has the Yocto Project BSP layers. 131 has the Yocto Project BSP layers.
200 You should use the same method that you used to get the local Yocto Project files earlier. 132 You should use the same method that you used to get the local Yocto Project files earlier.
201 </para> 133 </para>
202 134
203 <para> 135 <para>
204 If you are using tarball extraction, simply download the tarball for the base 136 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 137 BSP you chose in the previous step and then extract it into any directory
206 you choose using the tar command. 138 you choose using the tar command.
207 Upon extraction, the BSP source directory (layer) will be named 139 Upon extraction, the BSP source directory (layer) will be named
208 <filename>meta-&lt;BSP_name&gt;</filename>. 140 <filename>meta-&lt;BSP_name&gt;</filename>.
209 The following command extracts the Crown Bay BSP into the current directory and names it 141 The following command extracts the Crown Bay BSP into the current directory and names it
210 <filename>meta-crownbay</filename>: 142 <filename>meta-crownbay</filename>:
211 <literallayout class='monospaced'> 143 <literallayout class='monospaced'>
212 $ tar xjf crownbay-noemgd-1.1.tar.bz2 144 $ tar xjf crownbay-noemgd-1.1.tar.bz2
213 </literallayout> 145 </literallayout>
214 </para> 146 </para>
215 147
216 <para> 148 <para>
217 If you cloned a <filename>poky</filename> Git repository 149 If you cloned a <filename>poky</filename> Git repository
218 then you need to set up a different local Git repository 150 then you need to set up a different local Git repository
219 (<filename>meta-intel</filename>) for the BSP. 151 (<filename>meta-intel</filename>) for the BSP.
220 The <filename>meta-intel</filename> Git repository contains all the metadata 152 The <filename>meta-intel</filename> Git repository contains all the metadata
221 that supports BSP creation. 153 that supports BSP creation.
222 When you set up the <filename>meta-intel</filename> Git repository you can 154 When you set up the <filename>meta-intel</filename> Git repository you can
223 set it up anywhere you want. 155 set it up anywhere you want.
224 We will set up the repository inside the 156 We will set up the repository inside the
225 <filename>poky</filename> Git repository in this example. 157 <filename>poky</filename> Git repository in this example.
226 </para> 158 </para>
227 159
228 <para> 160 <para>
229 The following transcript shows the steps to clone the <filename>meta-intel</filename> 161 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 162 Git repository inside the <filename>poky</filename> Git repository created earlier in this
231 example. 163 example.
232 <literallayout class='monospaced'> 164 <literallayout class='monospaced'>
233 $cd poky 165 $cd poky
234 $ git clone git://git.yoctoproject.org/meta-intel.git 166 $ git clone git://git.yoctoproject.org/meta-intel.git
235 Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/ 167 Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/
@@ -238,251 +170,251 @@
238 remote: Total 1325 (delta 546), reused 85 (delta 27) 170 remote: Total 1325 (delta 546), reused 85 (delta 27)
239 Receiving objects: 100% (1325/1325), 1.56 MiB | 330 KiB/s, done. 171 Receiving objects: 100% (1325/1325), 1.56 MiB | 330 KiB/s, done.
240 Resolving deltas: 100% (546/546), done. 172 Resolving deltas: 100% (546/546), done.
241 </literallayout> 173 </literallayout>
242 </para> 174 </para>
243 175
244 <para> 176 <para>
245 Because <filename>meta-intel</filename> is its own Git repository you will want 177 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. 178 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. 179 For this example we are going to use the <filename>1.1</filename> branch.
248 <literallayout class='monospaced'> 180 <literallayout class='monospaced'>
249 $ cd meta-intel 181 $ cd meta-intel
250 $ git checkout -b 1.1 origin/1.1 182 $ git checkout -b 1.1 origin/1.1
251 Switched to a new branch 'bernard' 183 Switched to a new branch 'bernard'
252 </literallayout> 184 </literallayout>
253 </para> 185 </para>
254 </section> 186</section>
255 187
256 <section id='making-a-copy-of-the-base bsp-to-create-your-new-bsp-layer-app'> 188<section id='making-a-copy-of-the-base bsp-to-create-your-new-bsp-layer-app'>
257 <title>Making a Copy of the Base BSP to Create Your New BSP Layer</title> 189 <title>Making a Copy of the Base BSP to Create Your New BSP Layer</title>
258 190
259 <para> 191 <para>
260 Now that you have the local Yocto Project files and the base BSP files you need to create a 192 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. 193 new layer for your BSP.
262 </para> 194 </para>
263 195
264 <para> 196 <para>
265 Layers are ideal for isolating and storing work for a given piece of hardware. 197 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. 198 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. 199 In fact, a BSP is, in itself, a special type of layer.
268 Consider an application as another example that illustrates a layer. 200 Consider an application as another example that illustrates a layer.
269 Suppose you are creating an application that has library or other dependencies in 201 Suppose you are creating an application that has library or other dependencies in
270 order for it to compile and run. 202 order for it to compile and run.
271 The layer, in this case, would be where all the recipes that define those dependencies 203 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 204 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. 205 all the relevant information for the project that the Yocto Project build system knows about.
274 </para> 206 </para>
275 207
276 <note> 208 <note>
277 The Yocto Project supports four BSPs that are part of the 209 The Yocto Project supports four BSPs that are part of the
278 Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>, 210 Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>,
279 <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>. 211 <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>.
280 The recipes and configurations for these four BSPs are located and dispersed 212 The recipes and configurations for these four BSPs are located and dispersed
281 within local Yocto Project files. 213 within local Yocto Project files.
282 Consequently, they are not totally isolated in the spirit of layers unless you think 214 Consequently, they are not totally isolated in the spirit of layers unless you think
283 of <filename>meta-yocto</filename> as a layer itself. 215 of <filename>meta-yocto</filename> as a layer itself.
284 On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest, 216 On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest,
285 N450, and Sugar Bay are isolated. 217 N450, and Sugar Bay are isolated.
286 </note> 218 </note>
287 219
288 <para> 220 <para>
289 When you set up a layer for a new BSP you should follow a standard layout. 221 When you set up a layer for a new BSP you should follow a standard layout.
290 This layout is described in the 222 This layout is described in the
291 <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'> 223 <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 224 Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
293 Guide. 225 Guide.
294 In the standard layout you will notice a suggested structure for recipes and 226 In the standard layout you will notice a suggested structure for recipes and
295 configuration information. 227 configuration information.
296 You can see the standard layout for the Crown Bay BSP in this example by examining the 228 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 229 directory structure of the <filename>meta-crownbay</filename> layer inside the
298 local Yocto Project files. 230 local Yocto Project files.
299 </para> 231 </para>
300 232
301 <para> 233 <para>
302 To create your BSP layer you simply copy the <filename>meta-crownbay</filename> 234 To create your BSP layer you simply copy the <filename>meta-crownbay</filename>
303 layer to a new layer. 235 layer to a new layer.
304 For this example the new layer will be named <filename>meta-mymachine</filename>. 236 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 237 The name must follow the BSP layer naming convention, which is
306 <filename>meta-&lt;name&gt;</filename>. 238 <filename>meta-&lt;name&gt;</filename>.
307 The following example assumes your working directory is <filename>meta-intel</filename> 239 The following example assumes your working directory is <filename>meta-intel</filename>
308 inside the local Yocto Project files. 240 inside the local Yocto Project files.
309 If you downloaded and expanded a Crown Bay tarball then you simply copy the resulting 241 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. 242 <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 243 Good practice for a Git repository, however, is to just copy the new layer alongside
312 the existing 244 the existing
313 BSP layers in the <filename>meta-intel</filename> Git repository: 245 BSP layers in the <filename>meta-intel</filename> Git repository:
314 <literallayout class='monospaced'> 246 <literallayout class='monospaced'>
315 $ cp -a meta-crownbay/ meta-mymachine 247 $ cp -a meta-crownbay/ meta-mymachine
316 </literallayout> 248 </literallayout>
317 </para> 249 </para>
318 </section> 250</section>
319 251
320 <section id='making-changes-to-your-bsp-app'> 252<section id='making-changes-to-your-bsp-app'>
321 <title>Making Changes to Your BSP</title> 253 <title>Making Changes to Your BSP</title>
322 254
323 <para> 255 <para>
324 Right now you have two identical BSP layers with different names: 256 Right now you have two identical BSP layers with different names:
325 <filename>meta-crownbay</filename> and <filename>meta-mymachine</filename>. 257 <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 258 You need to change your configurations so that they work for your new BSP and
327 your particular hardware. 259 your particular hardware.
328 We will look first at the configurations, which are all done in the layer’s 260 We will look first at the configurations, which are all done in the layer’s
329 <filename>conf</filename> directory. 261 <filename>conf</filename> directory.
330 </para> 262 </para>
331 263
332 <para> 264 <para>
333 First, since in this example the new BSP will not support EMGD we will get rid of the 265 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 266 <filename>crownbay.conf</filename> file and then rename the
335 <filename>crownbay-noemgd.conf</filename> file to <filename>mymachine.conf</filename>. 267 <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 268 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. 269 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 270 The following two commands result in a single machine configuration file named
339 <filename>mymachine.conf</filename>. 271 <filename>mymachine.conf</filename>.
340 <literallayout class='monospaced'> 272 <literallayout class='monospaced'>
341 $ rm meta-mymachine/conf/machine/crownbay.conf 273 $ rm meta-mymachine/conf/machine/crownbay.conf
342 $ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \ 274 $ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \
343 meta-mymachine/conf/machine/mymachine.conf 275 meta-mymachine/conf/machine/mymachine.conf
344 </literallayout> 276 </literallayout>
345 </para> 277 </para>
346 278
347 <para> 279 <para>
348 The next step makes changes to <filename>mymachine.conf</filename> itself. 280 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. 281 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. 282 Here we simply substitute the Crown Bay name with an appropriate name.
351 </para> 283 </para>
352 284
353 <para> 285 <para>
354 Note that inside the <filename>mymachine.conf</filename> is the 286 Note that inside the <filename>mymachine.conf</filename> is the
355 <filename>PREFERRED_PROVIDER_virtual/kernel</filename> statement. 287 <filename>PREFERRED_PROVIDER_virtual/kernel</filename> statement.
356 This statement identifies the kernel that the BSP is going to use. 288 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 289 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. 290 current Linux Yocto kernel based on the Linux 2.6.37 release.
359 </para> 291 </para>
360 292
361 <para> 293 <para>
362 The next configuration file in the new BSP layer we need to edit is <filename>layer.conf</filename>. 294 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. 295 This file identifies build information needed for the new layer.
364 You can see the 296 You can see the
365 <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout-layer'> 297 <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 298 Layer Configuration File</ulink> section in the Board Support Packages (BSP) Development Guide
367 for more information on this configuration file. 299 for more information on this configuration file.
368 Basically, we are changing the existing statements to work with our BSP. 300 Basically, we are changing the existing statements to work with our BSP.
369 </para> 301 </para>
370 302
371 <para> 303 <para>
372 The file contains these statements that reference the Crown Bay BSP: 304 The file contains these statements that reference the Crown Bay BSP:
373 <literallayout class='monospaced'> 305 <literallayout class='monospaced'>
374 BBFILE_COLLECTIONS += "crownbay" 306 BBFILE_COLLECTIONS += "crownbay"
375 BBFILE_PATTERN_crownbay := "^${LAYERDIR}/" 307 BBFILE_PATTERN_crownbay := "^${LAYERDIR}/"
376 BBFILE_PRIORITY_crownbay = "6" 308 BBFILE_PRIORITY_crownbay = "6"
377 </literallayout> 309 </literallayout>
378 </para> 310 </para>
379 311
380 <para> 312 <para>
381 Simply substitute the machine string name <filename>crownbay</filename> 313 Simply substitute the machine string name <filename>crownbay</filename>
382 with the new machine name <filename>mymachine</filename> to get the following: 314 with the new machine name <filename>mymachine</filename> to get the following:
383 <literallayout class='monospaced'> 315 <literallayout class='monospaced'>
384 BBFILE_COLLECTIONS_mymachine += "mymachine" 316 BBFILE_COLLECTIONS_mymachine += "mymachine"
385 BBFILE_PATTERN_mymachine := "^${LAYERDIR}/" 317 BBFILE_PATTERN_mymachine := "^${LAYERDIR}/"
386 BBFILE_PRIORITY_mymachine = "6" 318 BBFILE_PRIORITY_mymachine = "6"
387 </literallayout> 319 </literallayout>
388 </para> 320 </para>
389 321
390 <para> 322 <para>
391 Now we will take a look at the recipes in your new layer. 323 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. 324 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. 325 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. 326 Recipes take the form of <filename>.bb</filename> files.
395 If you want to leverage the existing recipes the Yocto Project build system uses 327 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. 328 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 329 All new recipes and append files for your layer must go in the layer’s
398 <filename>recipes-bsp</filename>, <filename>recipes-kernel</filename>, 330 <filename>recipes-bsp</filename>, <filename>recipes-kernel</filename>,
399 <filename>recipes-core</filename>, and 331 <filename>recipes-core</filename>, and
400 <filename>recipes-graphics</filename> directories. 332 <filename>recipes-graphics</filename> directories.
401 </para> 333 </para>
402 334
403 <para> 335 <para>
404 First, let's look at <filename>recipes-bsp</filename>. 336 First, let's look at <filename>recipes-bsp</filename>.
405 For this example we are not adding any new BSP recipes. 337 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 338 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. 339 the remaining one that doesn't support EMGD.
408 These commands take care of the <filename>recipes-bsp</filename> recipes: 340 These commands take care of the <filename>recipes-bsp</filename> recipes:
409 <literallayout class='monospaced'> 341 <literallayout class='monospaced'>
410 $ rm &dash;rf meta-mymachine/recipes-graphics/xorg-xserver/*emgd* 342 $ rm &dash;rf meta-mymachine/recipes-graphics/xorg-xserver/*emgd*
411 $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \ 343 $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \
412 meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine 344 meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine
413 </literallayout> 345 </literallayout>
414 </para> 346 </para>
415 347
416 <para> 348 <para>
417 Now let's look at <filename>recipes-graphics</filename>. 349 Now let's look at <filename>recipes-graphics</filename>.
418 For this example we want to remove anything that supports EMGD and 350 For this example we want to remove anything that supports EMGD and
419 be sure to rename remaining directories appropriately. 351 be sure to rename remaining directories appropriately.
420 The following commands clean up the <filename>recipes-graphics</filename> directory: 352 The following commands clean up the <filename>recipes-graphics</filename> directory:
421 <literallayout class='monospaced'> 353 <literallayout class='monospaced'>
422 $ rm &dash;rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-emgd* 354 $ 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 355 $ 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 \ 356 $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd \
425 meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine 357 meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine
426 </literallayout> 358 </literallayout>
427 </para> 359 </para>
428 360
429 <para> 361 <para>
430 At this point the <filename>recipes-graphics</filename> directory just has files that 362 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. 363 support Video Electronics Standards Association (VESA) graphics modes and not EMGD.
432 </para> 364 </para>
433 365
434 <para> 366 <para>
435 Now let's look at changes in <filename>recipes-core</filename>. 367 Now let's look at changes in <filename>recipes-core</filename>.
436 The file <filename>task-core-tools.bbappend</filename> in 368 The file <filename>task-core-tools.bbappend</filename> in
437 <filename>recipes-core/tasks</filename> appends the similarly named recipe 369 <filename>recipes-core/tasks</filename> appends the similarly named recipe
438 located in the local Yocto Project files at 370 located in the local Yocto Project files at
439 <filename>meta/recipes-core/tasks</filename>. 371 <filename>meta/recipes-core/tasks</filename>.
440 The "append" file in our layer right now is Crown Bay-specific and supports 372 The "append" file in our layer right now is Crown Bay-specific and supports
441 EMGD and non-EMGD. 373 EMGD and non-EMGD.
442 Here are the contents of the file: 374 Here are the contents of the file:
443 <literallayout class='monospaced'> 375 <literallayout class='monospaced'>
444 RRECOMMENDS_task-core-tools-profile_append_crownbay = " systemtap" 376 RRECOMMENDS_task-core-tools-profile_append_crownbay = " systemtap"
445 RRECOMMENDS_task-core-tools-profile_append_crownbay-noemgd = " systemtap" 377 RRECOMMENDS_task-core-tools-profile_append_crownbay-noemgd = " systemtap"
446 </literallayout> 378 </literallayout>
447 </para> 379 </para>
448 380
449 <para> 381 <para>
450 The <filename>RRECOMMENDS</filename> statements list packages that 382 The <filename>RRECOMMENDS</filename> statements list packages that
451 extend usability. 383 extend usability.
452 The first <filename>RRECOMMENDS</filename> statement can be removed, while the 384 The first <filename>RRECOMMENDS</filename> statement can be removed, while the
453 second one can be changed to reflect <filename>meta-mymachine</filename>: 385 second one can be changed to reflect <filename>meta-mymachine</filename>:
454 <literallayout class='monospaced'> 386 <literallayout class='monospaced'>
455 RRECOMMENDS_task-core-tools-profile_append_mymachine = " systemtap" 387 RRECOMMENDS_task-core-tools-profile_append_mymachine = " systemtap"
456 </literallayout> 388 </literallayout>
457 </para> 389 </para>
458 390
459 <para> 391 <para>
460 Finally, let's look at <filename>recipes-kernel</filename> changes. 392 Finally, let's look at <filename>recipes-kernel</filename> changes.
461 Recall that the BSP uses the <filename>linux-yocto</filename> kernel as determined 393 Recall that the BSP uses the <filename>linux-yocto</filename> kernel as determined
462 earlier in the <filename>mymachine.conf</filename>. 394 earlier in the <filename>mymachine.conf</filename>.
463 The recipe for that kernel is not located in the 395 The recipe for that kernel is not located in the
464 BSP layer but rather in the local Yocto Project files at 396 BSP layer but rather in the local Yocto Project files at
465 <filename>meta/recipes-kernel/linux</filename> and is 397 <filename>meta/recipes-kernel/linux</filename> and is
466 named <filename>linux-yocto-2.6.37.bb</filename>. 398 named <filename>linux-yocto-2.6.37.bb</filename>.
467 The <filename>SRCREV_machine</filename> and <filename>SRCREV_meta</filename> 399 The <filename>SRCREV_machine</filename> and <filename>SRCREV_meta</filename>
468 statements point to the exact commits used by the Yocto Project development team 400 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. 401 in their source repositories that identify the right kernel for our hardware.
470 </para> 402 </para>
471 403
472 <para> 404 <para>
473 However, in the <filename>meta-mymachine</filename> layer in 405 However, in the <filename>meta-mymachine</filename> layer in
474 <filename>recipes-kernel/linux</filename> resides a <filename>.bbappend</filename> 406 <filename>recipes-kernel/linux</filename> resides a <filename>.bbappend</filename>
475 file named <filename>linux-yocto-2.6.37.bbappend</filename> that 407 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>. 408 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 409 Thus, the <filename>SRCREV</filename> statements in the "append" file override
478 the more general statements found in <filename>meta</filename>. 410 the more general statements found in <filename>meta</filename>.
479 </para> 411 </para>
480 412
481 <para> 413 <para>
482 The <filename>SRCREV</filename> statements in the "append" file currently identify 414 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. 415 the kernel that supports the Crown Bay BSP with and without EMGD support.
484 Here are the statements: 416 Here are the statements:
485 <literallayout class='monospaced'> 417 <literallayout class='monospaced'>
486 SRCREV_machine_pn-linux-yocto_crownbay ?= \ 418 SRCREV_machine_pn-linux-yocto_crownbay ?= \
487 "372c0ab135978bd8ca3a77c88816a25c5ed8f303" 419 "372c0ab135978bd8ca3a77c88816a25c5ed8f303"
488 SRCREV_meta_pn-linux-yocto_crownbay ?= \ 420 SRCREV_meta_pn-linux-yocto_crownbay ?= \
@@ -492,74 +424,74 @@
492 "372c0ab135978bd8ca3a77c88816a25c5ed8f303" 424 "372c0ab135978bd8ca3a77c88816a25c5ed8f303"
493 SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= \ 425 SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= \
494 "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b" 426 "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b"
495 </literallayout> 427 </literallayout>
496 </para> 428 </para>
497 429
498 <para> 430 <para>
499 You will notice that there are two pairs of <filename>SRCREV</filename> statements. 431 You will notice that there are two pairs of <filename>SRCREV</filename> statements.
500 The top pair identifies the kernel that supports 432 The top pair identifies the kernel that supports
501 EMGD, which we don’t care about in this example. 433 EMGD, which we don’t care about in this example.
502 The bottom pair identifies the kernel that we will use: 434 The bottom pair identifies the kernel that we will use:
503 <filename>linux-yocto</filename>. 435 <filename>linux-yocto</filename>.
504 At this point though, the unique commit strings all are still associated with 436 At this point though, the unique commit strings all are still associated with
505 Crown Bay and not <filename>meta-mymachine</filename>. 437 Crown Bay and not <filename>meta-mymachine</filename>.
506 </para> 438 </para>
507 439
508 <para> 440 <para>
509 To fix this situation in <filename>linux-yocto-2.6.37.bbappend</filename> 441 To fix this situation in <filename>linux-yocto-2.6.37.bbappend</filename>
510 we delete the two <filename>SRCREV</filename> statements that support 442 we delete the two <filename>SRCREV</filename> statements that support
511 EMGD (the top pair). 443 EMGD (the top pair).
512 We also change the remaining pair to specify <filename>mymachine</filename> 444 We also change the remaining pair to specify <filename>mymachine</filename>
513 and insert the commit identifiers to identify the kernel in which we 445 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> 446 are interested, which will be based on the <filename>atom-pc-standard</filename>
515 kernel. 447 kernel.
516 Here are the final <filename>SRCREV</filename> statements: 448 Here are the final <filename>SRCREV</filename> statements:
517 <literallayout class='monospaced'> 449 <literallayout class='monospaced'>
518 SRCREV_machine_pn-linux-yocto-_mymachine ?= \ 450 SRCREV_machine_pn-linux-yocto-_mymachine ?= \
519 "fce17f046d3756045e4dfb49221d1cf60fcae329" 451 "fce17f046d3756045e4dfb49221d1cf60fcae329"
520 SRCREV_meta_pn-linux-yocto-stable_mymachine ?= \ 452 SRCREV_meta_pn-linux-yocto-stable_mymachine ?= \
521 "84f1a422d7e21fbc23a687035bdf9d42471f19e0" 453 "84f1a422d7e21fbc23a687035bdf9d42471f19e0"
522 </literallayout> 454 </literallayout>
523 </para> 455 </para>
524 456
525 <para> 457 <para>
526 If you are familiar with Git repositories you probably won’t have trouble locating the 458 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 459 exact commit strings in the Yocto Project source repositories you need to change
528 the <filename>SRCREV</filename> statements. 460 the <filename>SRCREV</filename> statements.
529 You can find all the <filename>machine</filename> and <filename>meta</filename> 461 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 462 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>. 463 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-2.6.37'>here</ulink>.
532 </para> 464 </para>
533 465
534 <para> 466 <para>
535 If you need a little more assistance after going to the link then do the following: 467 If you need a little more assistance after going to the link then do the following:
536 <orderedlist> 468 <orderedlist>
537 <listitem><para>Expand the list of branches by clicking <filename>[…]</filename></para></listitem> 469 <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> 470 <listitem><para>Click on the <filename>yocto/standard/common-pc/atom-pc</filename>
539 branch</para></listitem> 471 branch</para></listitem>
540 <listitem><para>Click on the commit column header to view the top commit</para></listitem> 472 <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 473 <listitem><para>Copy the commit string for use in the
542 <filename>linux-yocto-2.6.37.bbappend</filename> file</para></listitem> 474 <filename>linux-yocto-2.6.37.bbappend</filename> file</para></listitem>
543 </orderedlist> 475 </orderedlist>
544 </para> 476 </para>
545 477
546 <para> 478 <para>
547 For the <filename>SRCREV</filename> statement that points to the <filename>meta</filename> 479 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> 480 branch use the same procedure except expand the <filename>meta</filename>
549 branch in step 2 above. 481 branch in step 2 above.
550 </para> 482 </para>
551 483
552 <para> 484 <para>
553 Also in the <filename>linux-yocto-2.6.37.bbappend</filename> file are 485 Also in the <filename>linux-yocto-2.6.37.bbappend</filename> file are
554 <filename>COMPATIBLE_MACHINE</filename>, <filename>KMACHINE</filename>, 486 <filename>COMPATIBLE_MACHINE</filename>, <filename>KMACHINE</filename>,
555 and <filename>KERNEL_FEATURES</filename> statements. 487 and <filename>KERNEL_FEATURES</filename> statements.
556 Two sets of these exist: one set supports EMGD and one set does not. 488 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. 489 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 490 The remaining three must be changed so that <filename>mymachine</filename> replaces
559 <filename>crownbay-noemgd</filename> and <filename>crownbay</filename>. 491 <filename>crownbay-noemgd</filename> and <filename>crownbay</filename>.
560 Here is the final <filename>linux-yocto-2.6.37.bbappend</filename> file after all 492 Here is the final <filename>linux-yocto-2.6.37.bbappend</filename> file after all
561 the edits: 493 the edits:
562 <literallayout class='monospaced'> 494 <literallayout class='monospaced'>
563 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 495 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
564 496
565 COMPATIBLE_MACHINE_mymachine = "mymachine" 497 COMPATIBLE_MACHINE_mymachine = "mymachine"
@@ -570,622 +502,186 @@
570 "fce17f046d3756045e4dfb49221d1cf60fcae329" 502 "fce17f046d3756045e4dfb49221d1cf60fcae329"
571 SRCREV_meta_pn-linux-yocto_mymachine ?= \ 503 SRCREV_meta_pn-linux-yocto_mymachine ?= \
572 "84f1a422d7e21fbc23a687035bdf9d42471f19e0" 504 "84f1a422d7e21fbc23a687035bdf9d42471f19e0"
573 </literallayout> 505 </literallayout>
574 </para> 506 </para>
575 507
576 <para> 508 <para>
577 In summary, the edits to the layer’s recipe files result in removal of any files and 509 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 510 statements that do not support your targeted hardware in addition to the inclusion
579 of any new recipes you might need. 511 of any new recipes you might need.
580 In this example, it was simply a matter of ridding the new layer 512 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 513 <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 514 and making sure we were identifying the kernel that supports our example, which
583 is the <filename>atom-pc-standard</filename> kernel. 515 is the <filename>atom-pc-standard</filename> kernel.
584 We did not introduce any new recipes to the layer. 516 We did not introduce any new recipes to the layer.
585 </para> 517 </para>
586 518
587 <para> 519 <para>
588 Finally, it is also important to update the layer’s <filename>README</filename> 520 Finally, it is also important to update the layer’s <filename>README</filename>
589 file so that the information in it reflects your BSP. 521 file so that the information in it reflects your BSP.
590 </para> 522 </para>
591 </section> 523</section>
592 524
593 <section id='preparing-for-the-build-app'> 525<section id='preparing-for-the-build-app'>
594 <title>Preparing for the Build</title> 526 <title>Preparing for the Build</title>
595 527
596 <para> 528 <para>
597 Once you have made all the changes to your BSP layer there remains a few things 529 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. 530 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 531 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. 532 and you need to be sure two key configuration files are configured appropriately.
601 </para> 533 </para>
602 534
603 <para> 535 <para>
604 The entire process for building an image is overviewed in the 536 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'> 537 <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. 538 Building an Image</ulink> section of the Yocto Project Quick Start.
607 You might want to reference this information. 539 You might want to reference this information.
608 The remainder of this section will apply to our example of the 540 The remainder of this section will apply to our example of the
609 <filename>meta-mymachine</filename> layer. 541 <filename>meta-mymachine</filename> layer.
610 </para> 542 </para>
611 543
612 <para> 544 <para>
613 To get ready to build your image that uses the new layer you need to do the following: 545 To get ready to build your image that uses the new layer you need to do the following:
614 <orderedlist> 546 <orderedlist>
615 <listitem><para>Get the environment ready for the build by sourcing the environment 547 <listitem><para>Get the environment ready for the build by sourcing the environment
616 script. 548 script.
617 The environment script is in the top-level of the local Yocto Project files 549 The environment script is in the top-level of the local Yocto Project files
618 directory structure. 550 directory structure.
619 The script has the string 551 The script has the string
620 <filename>init-build-env</filename> in the file’s name. 552 <filename>init-build-env</filename> in the file’s name.
621 For this example, the following command gets the build environment ready: 553 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-app'>
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'> 554 <literallayout class='monospaced'>
738 $ bitbake –k core-image-sato-live 555 $ source oe-init-build-env yocto-build
739 </literallayout> 556 </literallayout>
740 </para> 557 When you source the script a build directory is created in the current
741 558 working directory.
742 <para> 559 In our example we were in the <filename>poky</filename> directory.
743 This command specifies an image that has Sato support and that can be run from a USB device or 560 Thus, entering the previous command created the <filename>yocto-build</filename> directory.
744 from a CD without having to first install anything. 561 If you do not provide a name for the build directory it defaults to
745 The build process takes significant time and includes thousands of tasks, which are reported 562 <filename>build</filename>.
746 at the console. 563 The <filename>yocot-build</filename> directory contains a
747 If the build results in any type of error you should check for misspellings in the 564 <filename>conf</filename> directory that has
748 files you changed or problems with your host development environment such as missing packages. 565 two configuration files you will need to check: <filename>bblayers.conf</filename>
749 </para> 566 and <filename>local.conf</filename>.</para></listitem>
750 </section> 567 <listitem><para>Check and edit the resulting <filename>local.conf</filename> file.
751 </section> 568 This file minimally identifies the machine for which to build the image by
752 569 configuring the <filename>MACHINE</filename> variable.
753 <section id='modifying-a-kernel-kernel-example-app'> 570 For this example you must set the variable to mymachine as follows:
754 <title>Modifying a Kernel</title> 571 <literallayout class='monospaced'>
755 572 MACHINE ??= “mymachine”
756 <para>
757 Kernel modification involves changing or adding configurations to an existing kernel, or
758 adding recipes to the kernel that are needed to support specific hardware features.
759 The process is similar to creating a Board Support Package (BSP) except that it does not
760 involve a BSP layer.
761 </para>
762
763 <para>
764 This section presents a brief overview of the kernel structure and then provides a simple
765 example that shows how to modify the kernel.
766 </para>
767
768 <section id='yocto-project-kernel-app'>
769 <title>Yocto Project Kernel Overview</title>
770
771 <para>
772 When one thinks of the source files for a kernel they usually think of a fixed structure
773 of files that contain kernel patches.
774 The Yocto Project, however, employs mechanisims that in a sense result in a kernel source
775 generator.
776 </para>
777
778 <para>
779 The Yocto Project uses the source code management (SCM) tool Git to manage and track Yocto
780 Project files.
781 Git employs branching strategies that effectively produce a tree-like structure whose
782 branches represent diversions from more general code.
783 For example, suppose two kernels are basically identical with the exception of a couple
784 different features in each.
785 In the Yocto Project source repositories managed by Git a main branch can contain the
786 common or shared
787 parts of the kernel source and two branches that diverge from that common branch can
788 each contain the features specific to the respective kernel.
789 The result is a managed tree whose "leaves" represent the end of a specific path that yields
790 a set of kernel source files necessary for a specific piece of hardware and its features.
791 </para>
792
793 <para>
794 A big advantage to this scheme is the sharing of common features by keeping them in
795 "larger" branches that are further up the tree.
796 This practice eliminates redundant storage of similar features shared among kernels.
797 </para>
798
799 <para>
800 When you build the kernel on your development system all files needed for the build
801 are taken from the Yocto Project source repositories pointed to by the
802 <filename>SRC_URI</filename> variable and gathered in a temporary work area
803 where they are subsequently used to create the unique kernel.
804 Thus, in a sense, the process constructs a local source tree specific to your
805 kernel to generate the new kernel image - a source generator if you will.
806 </para>
807
808 <para>
809 For a complete discussion of the Yocto Project kernel's architcture and its branching strategy,
810 see the <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'>
811 The Yocto Project Kernel Architecture and Use Manual</ulink>.
812 </para>
813
814 <para>
815 You can find a web interface to the Yocto Project source repository at
816 <ulink url='http://git.yoctoproject.org/'></ulink>.
817 Within the interface you will see groups of related source code, each of which can
818 be cloned using Git to result in a working Git repository on your local system
819 (referred to as the "local Yocto Project files" in this manual).
820 The Yocto Project supports four types of kernels in its source repositories at
821 <ulink url='http://git.yoctoproject.org/'></ulink>:
822 <itemizedlist>
823 <listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The
824 stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem>
825 <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The current
826 Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem>
827 <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
828 kernel based on the Linux 2.6.39-rc1 release.</para></listitem>
829 <listitem><para><emphasis><filename>linux-2.6</filename></emphasis> - A kernel based on
830 minimal Linux mainline tracking.
831 [WRITER'S NOTE: I don't know which Git repository the user needs to clone to get this
832 repository on their development system.]</para></listitem>
833 </itemizedlist>
834 </para>
835 </section>
836
837 <section id='modifying-a-kernel-example-app'>
838 <title>Modifying a Kernel Example</title>
839
840 <para>
841 This section presents a simple example that illustrates kernel modification
842 based on the <filename>linux-yocto-2.6.37</filename> kernel.
843 The example uses the audio and mixer capabilities supported by the
844 <ulink url='http://www.alsa-project.org/main/index.php/Main_Page'>Advanced Linux
845 Sound Architecture (ALSA) Project</ulink>.
846 As the example progresses you will see how to do the following:
847 <itemizedlist>
848 <listitem><para>Iteratively modify a base kernel locally.</para></listitem>
849 <listitem><para>Provide a recipe-based solution for your modified kernel.
850 </para></listitem>
851 <listitem><para>Proved an "in-tree" solution for your modified kernel
852 (i.e. make the modifcations part of the Yocto Project).</para></listitem>
853 </itemizedlist>
854 </para>
855
856 <para>
857 The example flows as follows:
858 </para>
859
860 <para>
861 <itemizedlist>
862 <listitem><para>Be sure your host development system is set up to support
863 development using the Yocto Project.
864 See
865 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>
866 The Linux Distributions</ulink> section and
867 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'>
868 The Packages</ulink> section both
869 in the Yocto Project Quick Start for requirements.
870 You will also need a release of Yocto Project installed on the host.</para></listitem>
871 <listitem><para>Set up your environment for optimal local kernel development.
872 </para></listitem>
873 <listitem><para>Create a layer to isolate your kernel work.</para></listitem>
874 <listitem><para>Next item.</para></listitem>
875 <listitem><para>Next item.</para></listitem>
876 <listitem><para>Next item.</para></listitem>
877 <listitem><para>Next item.</para></listitem>
878 </itemizedlist>
879 </para>
880
881 <section id='setting-up-yocto-project-kernel-example-app'>
882 <title>Setting Up Yocto Project</title>
883
884 <para>
885 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
887 <xref linkend='setting-up-yocto-project-app'>"Setting Up Yocto Project"</xref> for
888 the BSP development case.
889 Be sure to either set up a local Git repository for <filename>poky</filename>
890 or download and unpack the Yocto Project release tarball.
891 </para>
892 </section>
893
894 <section id='create-a-git-repository-of-poky-extras-app'>
895 <title>Create a Git Repository of <filename>poky-extras</filename></title>
896
897 <para>
898 Everytime you change a configuration or add a recipe to the kernel you need to
899 do a fetch from the Linux Yocto kernel source repositories.
900 This can get tedious and time consuming if you need to fetch the entire
901 Linux Yocto 2.6.37 Git repository down from the Internet everytime you make a change
902 to the kernel.
903 </para>
904
905 <para>
906 You can get around this by setting up a <filename>meta-kernel-dev</filename>
907 area on your local system.
908 This area contains "append" files for every kernel recipe, which also include
909 a <filename>KSRC</filename> statement that points to the kernel source files.
910 You can set up the environment so that the <filename>KSRC</filename> points to the
911 <filename>meta-kernel-dev</filename>, thus pulling source from a local area.
912 This setup can speed up development time.
913 </para>
914
915 <para>
916 To get set up you need to do two things: create a local Git repository
917 of the <filename>poky-extras</filename> repository, and create a bare clone of the
918 Linux Yocto 2.6.37 kernel Git repository.
919 </para>
920
921 <para>
922 The following transcript shows how to clone the <filename>poky-extras</filename>
923 Git repository into the current working directory, which is <filename>poky</filename>
924 in this example.
925 The command creates the repository in a directory named <filename>poky-extras</filename>:
926 <literallayout class='monospaced'>
927 $ git clone git://git.yoctoproject.org/poky-extras
928 Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
929 remote: Counting objects: 532, done.
930 remote: Compressing objects: 100% (472/472), done.
931 remote: Total 532 (delta 138), reused 307 (delta 39)
932 Receiving objects: 100% (532/532), 534.28 KiB | 362 KiB/s, done.
933 Resolving deltas: 100% (138/138), done.
934 </literallayout>
935 </para>
936
937 <para>
938 This transcript shows how to clone a bare Git repository of the Linux Yocto
939 2.6.37 kernel:
940 <literallayout class='monospaced'>
941 $ git clone --bare git://git.yoctoproject.org/linux-yocto-2.6.37
942 Initialized empty Git repository in /home/scottrif/linux-yocto-2.6.37.git/
943 remote: Counting objects: 1886034, done.
944 remote: Compressing objects: 100% (314326/314326), done.
945 remote: Total 1886034 (delta 1570202), reused 1870335 (delta 1554798)
946 Receiving objects: 100% (1886034/1886034), 401.51 MiB | 714 KiB/s, done.
947 Resolving deltas: 100% (1570202/1570202), done.
948 </literallayout>
949 </para>
950
951 <para>
952 The bare clone of the Linux Yocto 2.6.37 kernel on your local system mirrors
953 the upstream repository of the kernel.
954 You can effectively point to this local clone now during development to avoid
955 having to fetch the entire Linux Yocto 2.6.37 kernel every time you make a
956 kernel change.
957 </para>
958 </section>
959
960 <section id='create-a-layer-for-your-kernel-work-app'>
961 <title>Create a Layer for Your Kernel Work</title>
962
963 <para>
964 It is always good to isolate your work using your own layer.
965 Doing so allows you to experiment and easily start over should things go wrong.
966 This example uses a layer named <filename>meta-amixer</filename>.
967 </para>
968
969 <para>
970 When you set up a layer for kernel work you should follow the general layout
971 guidelines as described for BSP layers.
972 This layout is described in the
973 <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>
974 Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
975 Guide.
976 In the standard layout you will notice a suggested structure for recipes and
977 configuration information.
978 [WRITER'S NOTE: The <filename>meta-elc</filename> example uses an
979 <filename>images</filename> directory.
980 Currently, <filename>images</filename> is not part of the standard BSP layout.
981 I need to find out from Darren if this directory is required for kernel work.]
982 </para>
983
984 <para>
985 [WRITER'S NOTE: I need a paragraph here describing how to set up the layer.
986 I am not sure if you should copy an existing BSP layer and modify from there.
987 Or, if you should just look at a BSP layer and then create your own files.
988 Email to Darren on this but no answer yet.]
989 </para>
990 </section>
991
992 <section id='making-changes-to-your-kernel-layer-app'>
993 <title>Making Changes to Your Kernel Layer</title>
994
995 <para>
996 In the standard layer structure you have several areas that you need to examine or
997 modify.
998 For this example the layer contains four areas:
999 <itemizedlist>
1000 <listitem><para><emphasis><filename>conf</filename></emphasis> - Contains the
1001 <filename>layer.conf</filename> that identifies the location of the recipe files.
1002 </para></listitem>
1003 <listitem><para><emphasis><filename>images</filename></emphasis> - Contains the
1004 image recipe file.
1005 This recipe includes the base image you will be using and specifies other
1006 packages the image might need.</para></listitem>
1007 <listitem><para><emphasis><filename>recipes-bsp</filename></emphasis> - Contains
1008 recipes specific to the hardware for which you are developing the kernel.
1009 </para></listitem>
1010 <listitem><para><emphasis><filename>recipes-kernel</filename></emphasis> - Contains the
1011 "append" files that add information to the main recipe kernel.
1012 </para></listitem>
1013 </itemizedlist>
1014 </para>
1015
1016 <para>
1017 Let's take a look at the <filename>layer.conf</filename> in the
1018 <filename>conf</filename> directory first.
1019 This configuration file enables the Yocto Project build system to locate and
1020 use the information in your new layer.
1021 </para>
1022
1023 <para>
1024 The variable <filename>BBPATH</filename> needs to include the path to your layer
1025 as follows:
1026 <literallayout class='monospaced'>
1027 BBPATH := "${BBPATH}:${LAYERDIR}"
1028 </literallayout>
1029 And, the variable <filename>BBFILES</filename> needs to be modified to include your
1030 recipe and append files:
1031 <literallayout class='monospaced'>
1032 BBFILES := "${BBFILES} ${LAYERDIR}/images/*.bb \
1033 ${LAYERDIR}/images/*.bbappend \
1034 ${LAYERDIR}/recipes-*/*/*.bb \
1035 ${LAYERDIR}/recipes-*/*/*.bbappend"
1036 </literallayout>
1037 Finally, you need to be sure to use your layer name in these variables at the
1038 end of the file:
1039 <literallayout class='monospaced'>
1040 BBFILE_COLLECTIONS += "elc"
1041 BBFILE_PATTERN_elc := "^${LAYERDIR}/"
1042 BBFILE_PRIORITY_elc = "9"
1043 </literallayout>
1044 </para>
1045
1046 <para>
1047 The <filename>images</filename> directory contains an append file that helps
1048 further define the image.
1049 In our example, the base image is <filename>core-image-minimal</filename>.
1050 The image does, however, need some additional modules that we are using
1051 for this example.
1052 These modules support the amixer functionality.
1053 Here is the append file:
1054 <literallayout class='monospaced'>
1055 require recipes-core/images/poky-image-minimal.bb
1056
1057 IMAGE_INSTALL += "dropbear alsa-utils-aplay alsa-utils-alsamixer"
1058 IMAGE_INSTALL_append_qemux86 += " kernel-module-snd-ens1370 \
1059 kernel-module-snd-rawmidi kernel-module-loop kernel-module-nls-cp437 \
1060 kernel-module-nls-iso8859-1 qemux86-audio alsa-utils-amixer"
1061
1062 LICENSE = "MIT"
1063 </literallayout>
1064 </para>
1065
1066 <para>
1067 While the focus of this example is not on the BSP, it is worth mentioning that the
1068 <filename>recipes-bsp</filename> directory has the recipes and append files for
1069 features that the hardware requires.
1070 In this example, there is a script and a recipe to support the
1071 <filename>amixer</filename> functionality in QEMU.
1072 It is beyond the scope of this manual to go too deeply into the script.
1073 Suffice it to say that the script tests for the presence of the mixer, sets up
1074 default mixer values, enables the mixer, unmutes master and then
1075 sets the volume to 100.
1076 </para>
1077
1078 <para>
1079 The recipe <filename>qemu86-audio.bb</filename> installs and runs the
1080 <filename>amixer</filename> when the system boots.
1081 Here is the recipe:
1082 <literallayout class='monospaced'>
1083 SUMMARY = "Provide a basic init script to enable audio"
1084 DESCRIPTION = "Set the volume and unmute the Front mixer setting during boot."
1085 SECTION = "base"
1086 LICENSE = "MIT"
1087 LIC_FILES_CHKSUM = "file://${POKYBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58"
1088
1089 PR = "r4"
1090
1091 inherit update-rc.d
1092
1093 RDEPENDS = "alsa-utils-amixer"
1094
1095 SRC_URI = "file://qemux86-audio"
1096
1097 INITSCRIPT_NAME = "qemux86-audio"
1098 INITSCRIPT_PARAMS = "defaults 90"
1099
1100 do_install() {
1101 install -d ${D}${sysconfdir} \
1102 ${D}${sysconfdir}/init.d
1103 install -m 0755 ${WORKDIR}/qemux86-audio ${D}${sysconfdir}/init.d
1104 cat ${WORKDIR}/${INITSCRIPT_NAME} | \
1105 sed -e 's,/etc,${sysconfdir},g' \
1106 -e 's,/usr/sbin,${sbindir},g' \
1107 -e 's,/var,${localstatedir},g' \
1108 -e 's,/usr/bin,${bindir},g' \
1109 -e 's,/usr,${prefix},g' > ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME}
1110 chmod 755 ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME}
1111 }
1112 </literallayout> 573 </literallayout>
1113 </para> 574 You should also be sure any other variables in which you are interested are set.
1114 575 Some variables to consider are <filename>BB_NUMBER_THREADS</filename>
1115 <para> 576 and <filename>PARALLEL_MAKE</filename>, both of which can greatly reduce your build time
1116 The last area to look at is <filename>recipes-kernel</filename>. 577 if you are using a multi-threaded development system (e.g. values of
1117 This area holds configuration fragments and kernel append files. 578 <filename>8</filename> and <filename>j 6</filename>, respectively are optimal
1118 The append file must have the same name as the kernel recipe, which is 579 for a development machine that has four available cores).</para></listitem>
1119 <filename>linux-yocto-2.6.37</filename> in this example. 580 <listitem><para>Update the <filename>bblayers.conf</filename> file so that it includes
1120 The file can <filename>SRC_URI</filename> statements to point to configuration 581 the path to your new BSP layer.
1121 fragments you might have in the layer. 582 In this example you need to include the pathname to <filename>meta-mymachine</filename>.
1122 The file can also contain <filename>KERNEL_FEATURES</filename> statements that specify 583 For this example the
1123 included kernel configurations that ship with the Yocto Project. 584 <filename>BBLAYERS</filename> variable in the file would need to include the following path:
1124 </para> 585 <literallayout class='monospaced'>
1125 </section> 586 $HOME/poky/meta-intel/meta-mymachine
1126 </section> 587 </literallayout></para></listitem>
1127 </section> 588 </orderedlist>
589 </para>
590
591 <para>
592 The appendix
593 <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#ref-variables-glos'>
594 Reference: Variables Glossary</ulink> in the Yocto Project Reference Manual has more information
595 on configuration variables.
596 </para>
1128</section> 597</section>
1129 598
1130</appendix> 599<section id='building-the-image-app'>
600 <title>Building the Image</title>
1131 601
602 <para>
603 The Yocto Project uses the BitBake tool to build images based on the type of image
604 you want to create.
605 You can find more information on BitBake
606 <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.
607 </para>
1132 608
1133 609 <para>
1134 610 The build process supports several types of images to satisfy different needs.
611 When you issue the BitBake command you provide a “top-level” recipe that essentially
612 starts the process off of building the type of image you want.
613 </para>
1135 614
1136<!-- 615 <para>
616 [WRITER'S NOTE: Consider moving this to the Poky Reference Manual.]
617 </para>
1137 618
619 <para>
620 You can find these recipes in the <filename>meta/recipes-core/images</filename> and
621 <filename>meta/recipes-sato/images</filename> directories of your local Yocto Project
622 file structure (Git repository or extracted release tarball).
623 Although the recipe names are somewhat explanatory, here is a list that describes them:
624 <itemizedlist>
625 <listitem><para><emphasis>Base</emphasis> – A foundational basic image without support
626 for X that can be reasonably used for customization.</para></listitem>
627 <listitem><para><emphasis>Core</emphasis> – A foundational basic image with support for
628 X that can be reasonably used for customization.</para></listitem>
629 <listitem><para><emphasis>Direct Disk</emphasis> – An image that you can copy directory to
630 the disk of the target device.</para></listitem>
631 <listitem><para><emphasis>Live</emphasis> – An image you can run from a USB device or from
632 a CD without having to first install something.</para></listitem>
633 <listitem><para><emphasis>Minimal</emphasis> – A small image without a GUI.
634 This image is not much more than a kernel with a shell.</para></listitem>
635 <listitem><para><emphasis>Minimal Development</emphasis> – A Minimal image suitable for
636 development work.</para></listitem>
637 <listitem><para><emphasis>Minimal Direct Disk</emphasis> – A Minimal Direct Disk image.</para></listitem>
638 <listitem><para><emphasis>Minimal RAM-based Initial Root Filesystem</emphasis> – A minimal image
639 that has the <filename>initramfs</filename> as part of the kernel, which allows the
640 system to find the first “init” program more efficiently.</para></listitem>
641 <listitem><para><emphasis>Minimal Live</emphasis> – A Minimal Live image.</para></listitem>
642 <listitem><para><emphasis>Minimal MTD Utilities</emphasis> – A minimal image that has support
643 for the MTD utilities, which let the user interact with the MTD subsystem in
644 the kernel to perform operations on flash devices.</para></listitem>
645 <listitem><para><emphasis>Sato</emphasis> – An image with Sato support, a mobile environment
646 and visual style that works well with mobile devices.</para></listitem>
647 <listitem><para><emphasis>Sato Development</emphasis> – A Sato image suitable for
648 development work.</para></listitem>
649 <listitem><para><emphasis>Sato Direct Disk</emphasis> – A Sato Direct Disk image.</para></listitem>
650 <listitem><para><emphasis>Sato Live</emphasis> – A Sato Live image.</para></listitem>
651 <listitem><para><emphasis>Sato SDK</emphasis> – A Sato image that includes the Yocto Project
652 toolchain and development libraries.</para></listitem>
653 <listitem><para><emphasis>Sato SDK Direct Disk</emphasis> – A Sato SDK Direct
654 Disk image.</para></listitem>
655 <listitem><para><emphasis>Sato SDK Live</emphasis> – A Sato SDK Live image.</para></listitem>
656 </itemizedlist>
657 </para>
1138 658
1139 <para> 659 <para>
1140 [WRITER'S NOTE: This section is a second example that focuses on just modifying the kernel. 660 The remainder of this section applies to our example of the <filename>meta-mymachine</filename> layer.
1141 I don't have any information on this yet. 661 </para>
1142 </para>
1143
1144 <para>
1145 Here are some points to consider though:
1146 <itemizedlist>
1147 <listitem><para>Reference Darren's presentation
1148 <ulink url='http://events.linuxfoundation.org/events/embedded-linux-conference/hart'>
1149 here</ulink></para></listitem>
1150 <listitem><para>Reference <xref linkend='dev-manual-start'>Getting Started with the Yocto Project</xref>
1151 section to get set up at minimum.</para></listitem>
1152 <listitem><para>Are there extra steps I need specific to kernel development to get started?</para></listitem>
1153 <listitem><para>What do I do to get set up?
1154 Is it a matter of just installing YP and having some pieces together?
1155 What are the pieces?</para></listitem>
1156 <listitem><para>Where do I get the base kernel to start with?</para></listitem>
1157 <listitem><para>Do I install the appropriate toolchain?</para></listitem>
1158 <listitem><para>What kernel git repository do I use?</para></listitem>
1159 <listitem><para>What is the conversion script?
1160 What does it do?</para></listitem>
1161 <listitem><para>What do I have to do to integrate the kernel layer?</para></listitem>
1162 <listitem><para>What do I use to integrate the kernel layer?
1163 HOB?
1164 Do I just Bitbake it?</para></listitem>
1165 <listitem><para>Using the System Image Creator.]</para></listitem>
1166 </itemizedlist>
1167 </para>
1168 </section>
1169 </section>
1170</section>
1171 662
1172<section id='user-application-development'> 663 <para>
1173 <title>User Application Development</title> 664 To build the image for our <filename>meta-mymachine</filename> BSP enter the following command
665 from the same shell from which you ran the setup script.
666 You should run the <filename>bitbake</filename> command without any intervening shell commands.
667 For example, moving your working directory around could cause problems.
668 Here is the command for this example:
669 <literallayout class='monospaced'>
670 $ bitbake –k core-image-sato-live
671 </literallayout>
672 </para>
1174 673
1175 <para> 674 <para>
1176 [WRITER'S NOTE: This section is the second major development case - developing an application. 675 This command specifies an image that has Sato support and that can be run from a USB device or
1177 Here are points to consider: 676 from a CD without having to first install anything.
1178 <itemizedlist> 677 The build process takes significant time and includes thousands of tasks, which are reported
1179 <listitem><para>User-space Application Development scenario overview.</para></listitem> 678 at the console.
1180 <listitem><para>Using the Yocto Eclipse Plug-in.</para></listitem> 679 If the build results in any type of error you should check for misspellings in the
1181 <listitem><para>Back-door support.</para></listitem> 680 files you changed or problems with your host development environment such as missing packages.
1182 <listitem><para>I feel there is more to this area than we have captured during our two
1183 review meetings.]</para></listitem>
1184 </itemizedlist>
1185 </para> 681 </para>
1186</section> 682</section>
1187</chapter> 683</appendix>
1188--> 684
1189 685
1190<!-- 686<!--
1191vim: expandtab tw=80 ts=4 687vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-12 17:34:52 +0000