summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/profile-manual/profile-manual-arch.xml392
1 files changed, 23 insertions, 369 deletions
diff --git a/documentation/profile-manual/profile-manual-arch.xml b/documentation/profile-manual/profile-manual-arch.xml
index b9401e9017..a0ea3b2d0d 100644
--- a/documentation/profile-manual/profile-manual-arch.xml
+++ b/documentation/profile-manual/profile-manual-arch.xml
@@ -2,387 +2,41 @@
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > 3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4 4
5<chapter id='dev-manual-start'> 5<chapter id='profile-manual-arch'>
6 6
7<title>Getting Started with the Yocto Project</title> 7<title>Overall Architecture of the Linux Tracing and Profiling Tools</title>
8 8
9<para> 9<section id='architecture-of-the-tracing-and-profiling-tools'>
10 This chapter introduces the Yocto Project and gives you an idea of what you need to get started. 10 <title>Architecture of the Tracing and Profiling Tools</title>
11 You can find enough information to set up your development host and build or use images for
12 hardware supported by the Yocto Project by reading the
13 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
14</para>
15
16<para>
17 The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
18 some higher-level concepts you might want to consider.
19</para>
20
21<section id='introducing-the-yocto-project'>
22 <title>Introducing the Yocto Project</title>
23 11
24 <para> 12 <para>
25 The Yocto Project is an open-source collaboration project focused on embedded Linux development. 13 It may seem surprising to see a section covering an 'overall architecture'
26 The project currently provides a build system, which is 14 for what seems to be a random collection of tracing tools that together
27 referred to as the OpenEmbedded build system in the Yocto Project documentation. 15 make up the Linux tracing and profiling space.
28 The Yocto Project provides various ancillary tools suitable for the embedded developer 16 The fact is, however, that in recent years this seemingly disparate
29 and also features the Sato reference User Interface, which is optimized for 17 set of tools has started to converge on a 'core' set of underlying
30 stylus driven, low-resolution screens. 18 mechanisms:
31 </para> 19 </para>
32 20
33 <para> 21 <para>
34 You can use the OpenEmbedded build system, which uses
35 BitBake to develop complete Linux
36 images and associated user-space applications for architectures based on ARM, MIPS, PowerPC,
37 x86 and x86-64.
38 While the Yocto Project does not provide a strict testing framework,
39 it does provide or generate for you artifacts that let you perform target-level and
40 emulated testing and debugging.
41 Additionally, if you are an <trademark class='trade'>Eclipse</trademark>
42 IDE user, you can install an Eclipse Yocto Plug-in to allow you to
43 develop within that familiar environment.
44 </para>
45</section>
46
47<section id='getting-setup'>
48 <title>Getting Set Up</title>
49
50 <para>
51 Here is what you need to get set up to use the Yocto Project:
52 <itemizedlist> 22 <itemizedlist>
53 <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current 23 <listitem>static tracepoints</listitem>
54 Linux-based host system. 24 <listitem>dynamic tracepoints
55 You will have the best results with a recent release of Fedora, 25 <itemizedlist>
56 OpenSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project 26 <listitem>kprobes</listitem>
57 and officially supported. 27 <listitem>uprobes</listitem>
58 For a list of the distributions under validation and their status, see the 28 </itemizedlist>
59 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section 29 </listitem>
60 in the Yocto Project Reference Manual and the wiki page at 30 <listitem>the perf_events subsystem</listitem>
61 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para> 31 <listitem>debugfs</listitem>
62 <para>
63 You should also have about 100 gigabytes of free disk space for building images.
64 </para></listitem>
65 <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system
66 requires certain packages exist on your development system (e.g. Python 2.6 or 2.7).
67 See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
68 section in the Yocto Project Quick Start for the exact package
69 requirements and the installation commands to install them
70 for the supported distributions.</para></listitem>
71 <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
72 You need a release of the Yocto Project.
73 You set that up with a local <link linkend='source-directory'>Source Directory</link>
74 one of two ways depending on whether you
75 are going to contribute back into the Yocto Project or not.
76 <note>
77 Regardless of the method you use, this manual refers to the resulting local
78 hierarchical set of files as the "Source Directory."
79 </note>
80 <itemizedlist>
81 <listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute
82 back into the Yocto Project, you can simply download a Yocto Project release you want
83 from the website’s <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink>.
84 Once you have the tarball, just extract it into a directory of your choice.</para>
85 <para>For example, the following command extracts the Yocto Project &DISTRO;
86 release tarball
87 into the current working directory and sets up the local Source Directory
88 with a top-level folder named <filename>&YOCTO_POKY;</filename>:
89 <literallayout class='monospaced'>
90 $ tar xfj &YOCTO_POKY_TARBALL;
91 </literallayout></para>
92 <para>This method does not produce a local Git repository.
93 Instead, you simply end up with a snapshot of the release.</para></listitem>
94 <listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing
95 back into the Yocto Project or you simply want to keep up
96 with the latest developments, you should use Git commands to set up a local
97 Git repository of the upstream <filename>poky</filename> source repository.
98 Doing so creates a repository with a complete history of changes and allows
99 you to easily submit your changes upstream to the project.
100 Because you cloned the repository, you have access to all the Yocto Project development
101 branches and tag names used in the upstream repository.</para>
102 <para>The following transcript shows how to clone the <filename>poky</filename>
103 Git repository into the current working directory.
104 <note>You can view the Yocto Project Source Repositories at
105 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note>
106 The command creates the local repository in a directory named <filename>poky</filename>.
107 For information on Git used within the Yocto Project, see the
108 "<link linkend='git'>Git</link>" section.
109 <literallayout class='monospaced'>
110 $ git clone git://git.yoctoproject.org/poky
111 Initialized empty Git repository in /home/scottrif/poky/.git/
112 remote: Counting objects: 141863, done.
113 remote: Compressing objects: 100% (38624/38624), done.
114 remote: Total 141863 (delta 99661), reused 141816 (delta 99614)
115 Receiving objects: 100% (141863/141863), 76.64 MiB | 126 KiB/s, done.
116 Resolving deltas: 100% (99661/99661), done.
117 </literallayout></para>
118 <para>For another example of how to set up your own local Git repositories, see this
119 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
120 wiki page</ulink>, which describes how to create both <filename>poky</filename>
121 and <filename>meta-intel</filename> Git repositories.</para></listitem>
122 </itemizedlist></para></listitem>
123 <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
124 If you are going to be making modifications to a supported Yocto Project kernel, you
125 need to establish local copies of the source.
126 You can find Git repositories of supported Yocto Project Kernels organized under
127 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
128 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
129 <para>This setup can involve creating a bare clone of the Yocto Project kernel and then
130 copying that cloned repository.
131 You can create the bare clone and the copy of the bare clone anywhere you like.
132 For simplicity, it is recommended that you create these structures outside of the
133 Source Directory (usually <filename>poky</filename>).</para>
134 <para>As an example, the following transcript shows how to create the bare clone
135 of the <filename>linux-yocto-3.4</filename> kernel and then create a copy of
136 that clone.
137 <note>When you have a local Yocto Project kernel Git repository, you can
138 reference that repository rather than the upstream Git repository as
139 part of the <filename>clone</filename> command.
140 Doing so can speed up the process.</note></para>
141 <para>In the following example, the bare clone is named
142 <filename>linux-yocto-3.4.git</filename>, while the
143 copy is named <filename>my-linux-yocto-3.4-work</filename>:
144 <literallayout class='monospaced'>
145 $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.4 linux-yocto-3.4.git
146 Initialized empty Git repository in /home/scottrif/linux-yocto-3.4.git/
147 remote: Counting objects: 2468027, done.
148 remote: Compressing objects: 100% (392255/392255), done.
149 remote: Total 2468027 (delta 2071693), reused 2448773 (delta 2052498)
150 Receiving objects: 100% (2468027/2468027), 530.46 MiB | 129 KiB/s, done.
151 Resolving deltas: 100% (2071693/2071693), done.
152 </literallayout></para>
153 <para>Now create a clone of the bare clone just created:
154 <literallayout class='monospaced'>
155 $ git clone linux-yocto-3.4.git my-linux-yocto-3.4-work
156 Cloning into 'my-linux-yocto-3.4-work'...
157 done.
158 </literallayout></para></listitem>
159 <listitem id='poky-extras-repo'><para><emphasis>
160 The <filename>poky-extras</filename> Git Repository</emphasis>:
161 The <filename>poky-extras</filename> Git repository contains metadata needed
162 only if you are modifying and building the kernel image.
163 In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>)
164 files that you
165 edit to point to your locally modified kernel source files and to build the kernel
166 image.
167 Pointing to these local files is much more efficient than requiring a download of the
168 kernel's source files from upstream each time you make changes to the kernel.</para>
169 <para>You can find the <filename>poky-extras</filename> Git Repository in the
170 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
171 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
172 It is good practice to create this Git repository inside the Source Directory.</para>
173 <para>Following is an example that creates the <filename>poky-extras</filename> Git
174 repository inside the Source Directory, which is named <filename>poky</filename>
175 in this case:
176 <literallayout class='monospaced'>
177 $ cd ~/poky
178 $ git clone git://git.yoctoproject.org/poky-extras poky-extras
179 Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
180 remote: Counting objects: 618, done.
181 remote: Compressing objects: 100% (558/558), done.
182 remote: Total 618 (delta 192), reused 307 (delta 39)
183 Receiving objects: 100% (618/618), 526.26 KiB | 111 KiB/s, done.
184 Resolving deltas: 100% (192/192), done.
185 </literallayout></para></listitem>
186 <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board
187 Support Packages (BSPs):</emphasis>
188 The Yocto Project provides a layer called <filename>meta-intel</filename> and
189 it is maintained in its own separate Git repository.
190 The <filename>meta-intel</filename> layer contains many supported
191 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.</para>
192 <para>Similar considerations exist for setting up the <filename>meta-intel</filename>
193 layer.
194 You can get set up for BSP development one of two ways: tarball extraction or
195 with a local Git repository.
196 It is a good idea to use the same method that you used to set up the Source Directory.
197 Regardless of the method you use, the Yocto Project uses the following BSP layer
198 naming scheme:
199 <literallayout class='monospaced'>
200 meta-&lt;BSP_name&gt;
201 </literallayout>
202 where <filename>&lt;BSP_name&gt;</filename> is the recognized BSP name.
203 Here are some examples:
204 <literallayout class='monospaced'>
205 meta-crownbay
206 meta-emenlow
207 meta-n450
208 </literallayout>
209 See the
210 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
211 section in the Yocto Project Board Support Package (BSP) Developer's Guide for more
212 information on BSP Layers.
213 <itemizedlist>
214 <listitem><para><emphasis>Tarball Extraction:</emphasis> You can download any released
215 BSP tarball from the same
216 <ulink url='&YOCTO_HOME_URL;/download'>download site</ulink> used
217 to get the Yocto Project release.
218 Once you have the tarball, just extract it into a directory of your choice.
219 Again, this method just produces a snapshot of the BSP layer in the form
220 of a hierarchical directory structure.</para></listitem>
221 <listitem><para><emphasis>Git Repository Method:</emphasis> If you are working
222 with a local Git repository for your Source Directory, you should also use this method
223 to set up the <filename>meta-intel</filename> Git repository.
224 You can locate the <filename>meta-intel</filename> Git repository in the
225 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
226 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
227 <para>Typically, you set up the <filename>meta-intel</filename> Git repository inside
228 the Source Directory.
229 For example, the following transcript shows the steps to clone the
230 <filename>meta-intel</filename>
231 Git repository inside the local <filename>poky</filename> Git repository.
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: 3380, done.
237 remote: Compressing objects: 100% (2750/2750), done.
238 remote: Total 3380 (delta 1689), reused 227 (delta 113)
239 Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done.
240 Resolving deltas: 100% (1689/1689), done.
241 </literallayout></para>
242 <para>The same
243 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
244 wiki page</ulink> referenced earlier covers how to
245 set up the <filename>meta-intel</filename> Git repository.</para></listitem>
246 </itemizedlist></para></listitem>
247 <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing
248 applications using the Eclipse Integrated Development Environment (IDE),
249 you will need this plug-in.
250 See the
251 "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>"
252 section for more information.</para></listitem>
253 </itemizedlist> 32 </itemizedlist>
254 </para> 33 </para>
255</section>
256
257<section id='building-images'>
258 <title>Building Images</title>
259
260 <para>
261 The build process creates an entire Linux distribution, including the toolchain, from source.
262 For more information on this topic, see the
263 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
264 section in the Yocto Project Quick Start.
265 </para>
266
267 <para>
268 The build process is as follows:
269 <orderedlist>
270 <listitem><para>Make sure you have set up the Source Directory described in the
271 previous section.</para></listitem>
272 <listitem><para>Initialize the build environment by sourcing a build environment
273 script.</para></listitem>
274 <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file,
275 which is found in the
276 <link linkend='build-directory'>Build Directory</link>,
277 is set up how you want it.
278 This file defines many aspects of the build environment including
279 the target machine architecture through the
280 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
281 the development machine's processor use through the
282 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and
283 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and
284 a centralized tarball download directory through the
285 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem>
286 <listitem><para>Build the image using the <filename>bitbake</filename> command.
287 If you want information on BitBake, see the user manual inculded in the
288 <filename>bitbake/doc/manual</filename> directory of the
289 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
290 <listitem><para>Run the image either on the actual hardware or using the QEMU
291 emulator.</para></listitem>
292 </orderedlist>
293 </para>
294</section>
295
296<section id='using-pre-built-binaries-and-qemu'>
297 <title>Using Pre-Built Binaries and QEMU</title>
298
299 <para>
300 Another option you have to get started is to use pre-built binaries.
301 The Yocto Project provides many types of binaries with each release.
302 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
303 chapter in the Yocto Project Reference Manual
304 for descriptions of the types of binaries that ship with a Yocto Project
305 release.
306 </para>
307
308 <para>
309 Using a pre-built binary is ideal for developing software applications to run on your
310 target hardware.
311 To do this, you need to be able to access the appropriate cross-toolchain tarball for
312 the architecture on which you are developing.
313 If you are using an SDK type image, the image ships with the complete toolchain native to
314 the architecture.
315 If you are not using an SDK type image, you need to separately download and
316 install the stand-alone Yocto Project cross-toolchain tarball.
317 </para>
318
319 <para>
320 Regardless of the type of image you are using, you need to download the pre-built kernel
321 that you will boot in the QEMU emulator and then download and extract the target root
322 filesystem for your target machine’s architecture.
323 You can get architecture-specific binaries and filesystems from
324 <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>.
325 You can get installation scripts for stand-alone toolchains from
326 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>.
327 Once you have all your files, you set up the environment to emulate the hardware
328 by sourcing an environment setup script.
329 Finally, you start the QEMU emulator.
330 You can find details on all these steps in the
331 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
332 section of the Yocto Project Quick Start.
333 </para>
334
335 <para>
336 Using QEMU to emulate your hardware can result in speed issues
337 depending on the target and host architecture mix.
338 For example, using the <filename>qemux86</filename> image in the emulator
339 on an Intel-based 32-bit (x86) host machine is fast because the target and
340 host architectures match.
341 On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based
342 host can be slower.
343 But, you still achieve faithful emulation of ARM-specific issues.
344 </para>
345
346 <para>
347 To speed things up, the QEMU images support using <filename>distcc</filename>
348 to call a cross-compiler outside the emulated system.
349 If you used <filename>runqemu</filename> to start QEMU, and the
350 <filename>distccd</filename> application is present on the host system, any
351 BitBake cross-compiling toolchain available from the build system is automatically
352 used from within QEMU simply by calling <filename>distcc</filename>.
353 You can accomplish this by defining the cross-compiler variable
354 (e.g. <filename>export CC="distcc"</filename>).
355 Alternatively, if you are using a suitable SDK image or the appropriate
356 stand-alone toolchain is present in <filename>/opt/poky</filename>,
357 the toolchain is also automatically used.
358 </para>
359 34
360 <note> 35 <note>
361 Several mechanisms exist that let you connect to the system running on the 36 Tying It Together: Rather than enumerating here how each tool makes use of
362 QEMU emulator: 37 these common mechanisms, textboxes like this will make note of the
363 <itemizedlist> 38 specific usages in each tool as they come up in the course
364 <listitem><para>QEMU provides a framebuffer interface that makes standard 39 of the text.
365 consoles available.</para></listitem>
366 <listitem><para>Generally, headless embedded devices have a serial port.
367 If so, you can configure the operating system of the running image
368 to use that port to run a console.
369 The connection uses standard IP networking.</para></listitem>
370 <listitem><para>SSH servers exist in some QEMU images.
371 The <filename>core-image-sato</filename> QEMU image has a Dropbear secure
372 shell (ssh) server that runs with the root password disabled.
373 The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images
374 have OpenSSH instead of Dropbear.
375 Including these SSH servers allow you to use standard <filename>ssh</filename> and
376 <filename>scp</filename> commands.
377 The <filename>core-image-minimal</filename> QEMU image, however, contains no ssh
378 server.</para></listitem>
379 <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session
380 using a local copy of the root filesystem on the host.
381 In order to make this connection, you must extract a root filesystem tarball by using the
382 <filename>runqemu-extract-sdk</filename> command.
383 After running the command, you must then point the <filename>runqemu</filename>
384 script to the extracted directory instead of a root filesystem image file.</para></listitem>
385 </itemizedlist>
386 </note> 40 </note>
387</section> 41</section>
388</chapter> 42</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-03-20 22:49:30 +0000