summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--documentation/poky-ref-manual/development.xml481
1 files changed, 0 insertions, 481 deletions
diff --git a/documentation/poky-ref-manual/development.xml b/documentation/poky-ref-manual/development.xml
index 3d2276f9ee..b897efd550 100644
--- a/documentation/poky-ref-manual/development.xml
+++ b/documentation/poky-ref-manual/development.xml
@@ -117,487 +117,6 @@
117 </para> 117 </para>
118 </section> 118 </section>
119 </section> 119 </section>
120
121<section id="platdev-gdb-remotedebug">
122 <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
123
124 <para>
125 GDB allows you to examine running programs, which in turn help you to understand and fix problems.
126 It also allows you to perform post-mortem style analysis of program crashes.
127 GDB is available as a package within the Yocto Project and by default is
128 installed in sdk images.
129 See the "<link linkend='ref-images'>Reference: Images</link>" appendix for a description of these
130 images.
131 You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
132 </para>
133
134 <tip>
135 For best results, install <filename>-dbg</filename> packages for the applications
136 you are going to debug.
137 Doing so makes available extra debug symbols that give you more meaningful output.
138 </tip>
139
140 <para>
141 Sometimes, due to memory or disk space constraints, it is not possible
142 to use GDB directly on the remote target to debug applications.
143 These constraints arise because GDB needs to load the debugging information and the
144 binaries of the process being debugged.
145 Additionally, GDB needs to perform many computations to locate information such as function
146 names, variable names and values, stack traces and so forth - even before starting the
147 debugging process.
148 These extra computations place more load on the target system and can alter the
149 characteristics of the program being debugged.
150 </para>
151
152 <para>
153 To help get past the previously mentioned constraints, you can use Gdbserver.
154 Gdbserver runs on the remote target and does not load any debugging information
155 from the debugged process.
156 Instead, a GDB instance processes the debugging information that is run on a
157 remote computer - the host GDB.
158 The host GDB then sends control commands to Gdbserver to make it stop or start the debugged
159 program, as well as read or write memory regions of that debugged program.
160 All the debugging information loaded and processed as well
161 as all the heavy debugging is done by the host GDB.
162 Offloading these processes gives the Gdbserver running on the target a chance to remain
163 small and fast.
164 </para>
165
166 <para>
167 Because the host GDB is responsible for loading the debugging information and
168 for doing the necessary processing to make actual debugging happen, the
169 user has to make sure the host can access the unstripped binaries complete
170 with their debugging information and also be sure the target is compiled with no optimizations.
171 The host GDB must also have local access to all the libraries used by the
172 debugged program.
173 Because Gdbserver does not need any local debugging information, the binaries on
174 the remote target can remain stripped.
175 However, the binaries must also be compiled without optimization
176 so they match the host's binaries.
177 </para>
178
179 <para>
180 To remain consistent with GDB documentation and terminology, the binary being debugged
181 on the remote target machine is referred to as the "inferior" binary.
182 For documentation on GDB see the
183 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
184 </para>
185
186 <section id="platdev-gdb-remotedebug-launch-gdbserver">
187 <title>Launching Gdbserver on the Target</title>
188
189 <para>
190 First, make sure Gdbserver is installed on the target.
191 If it is not, install the package <filename>gdbserver</filename>, which needs the
192 <filename>libthread-db1</filename> package.
193 </para>
194
195 <para>
196 As an example, to launch Gdbserver on the target and make it ready to "debug" a
197 program located at <filename>/path/to/inferior</filename>, connect
198 to the target and launch:
199 <literallayout class='monospaced'>
200 $ gdbserver localhost:2345 /path/to/inferior
201 </literallayout>
202 Gdbserver should now be listening on port 2345 for debugging
203 commands coming from a remote GDB process that is running on the host computer.
204 Communication between Gdbserver and the host GDB are done using TCP.
205 To use other communication protocols, please refer to the
206 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
207 </para>
208 </section>
209
210 <section id="platdev-gdb-remotedebug-launch-gdb">
211 <title>Launching GDB on the Host Computer</title>
212
213 <para>
214 Running GDB on the host computer takes a number of stages.
215 This section describes those stages.
216 </para>
217
218 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
219 <title>Building the Cross-GDB Package</title>
220 <para>
221 A suitable GDB cross-binary is required that runs on your host computer but
222 also knows about the the ABI of the remote target.
223 You can get this binary from the the Yocto Project meta-toolchain.
224 Here is an example:
225 <literallayout class='monospaced'>
226 /usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb
227 </literallayout>
228 where <filename>arm</filename> is the target architecture and
229 <filename>linux-gnueabi</filename> the target ABI.
230 </para>
231
232 <para>
233 Alternatively, the Yocto Project can build the <filename>gdb-cross</filename> binary.
234 Here is an example:
235 <literallayout class='monospaced'>
236 $ bitbake gdb-cross
237 </literallayout>
238 Once the binary is built, you can find it here:
239 <literallayout class='monospaced'>
240 tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-abi&gt;-gdb
241 </literallayout>
242 </para>
243 </section>
244
245 <section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins">
246 <title>Making the Inferior Binaries Available</title>
247
248 <para>
249 The inferior binary (complete with all debugging symbols) as well as any
250 libraries (and their debugging symbols) on which the inferior binary depends
251 need to be available.
252 There are a number of ways you can make these available.
253 </para>
254
255 <para>
256 Perhaps the easiest way is to have an 'sdk' image that corresponds to the plain
257 image installed on the device.
258 In the case of <filename>core-image-sato</filename>,
259 <filename>core-image-sato-sdk</filename> would contain suitable symbols.
260 Because the sdk images already have the debugging symbols installed, it is just a
261 question of expanding the archive to some location and then informing GDB.
262 </para>
263
264 <para>
265 Alternatively, Yocto Project can build a custom directory of files for a specific
266 debugging purpose by reusing its <filename>tmp/rootfs</filename> directory.
267 This directory contains the contents of the last built image.
268 This process assumes two things:
269 <itemizedlist>
270 <listitem><para>The image running on the target was the last image to
271 be built by the Yocto Project.</para></listitem>
272 <listitem><para>The package (<filename>foo</filename> in the following
273 example) that contains the inferior binary to be debugged has been built
274 without optimization and has debugging information available.</para></listitem>
275 </itemizedlist>
276 </para>
277
278 <para>
279 The following steps show how to build the custom directory of files:
280 <orderedlist>
281 <listitem><para>Install the package (<filename>foo</filename> in this case) to
282 <filename>tmp/rootfs</filename>:
283 <literallayout class='monospaced'>
284 $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
285 tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf -o \
286 tmp/rootfs/ update
287 </literallayout></para></listitem>
288 <listitem><para>Install the debugging information:
289 <literallayout class='monospaced'>
290 $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
291 tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
292 -o tmp/rootfs install foo
293
294 $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
295 tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
296 -o tmp/rootfs install foo-dbg
297 </literallayout></para></listitem>
298 </orderedlist>
299 </para>
300 </section>
301
302 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
303 <title>Launch the Host GDB</title>
304
305 <para>
306 To launch the host GDB, you run the <filename>cross-gdb</filename> binary and provide
307 the inferior binary as part of the command line.
308 For example, the following command form continues with the example used in
309 the previous section.
310 This command form loads the <filename>foo</filename> binary
311 as well as the debugging information:
312 <literallayout class='monospaced'>
313 $ &lt;target-abi&gt;-gdb rootfs/usr/bin/foo
314 </literallayout>
315 Once the GDB prompt appears, you must instruct GDB to load all the libraries
316 of the inferior binary from <filename>tmp/rootfs</filename> as follows:
317 <literallayout class='monospaced'>
318 $ set solib-absolute-prefix /path/to/tmp/rootfs
319 </literallayout>
320 The pathname <filename>/path/to/tmp/rootfs</filename> must either be
321 the absolute path to <filename>tmp/rootfs</filename> or the location at which
322 binaries with debugging information reside.
323 </para>
324
325 <para>
326 At this point you can have GDB connect to the Gdbserver that is running
327 on the remote target by using the following command form:
328 <literallayout class='monospaced'>
329 $ target remote remote-target-ip-address:2345
330 </literallayout>
331 The <filename>remote-target-ip-address</filename> is the IP address of the
332 remote target where the Gdbserver is running.
333 Port 2345 is the port on which the GDBSERVER is running.
334 </para>
335 </section>
336
337 <section id="platdev-gdb-remotedebug-launch-gdb-using">
338 <title>Using the Debugger</title>
339
340 <para>
341 You can now proceed with debugging as normal - as if you were debugging
342 on the local machine.
343 For example, to instruct GDB to break in the "main" function and then
344 continue with execution of the inferior binary use the following commands
345 from within GDB:
346 <literallayout class='monospaced'>
347 (gdb) break main
348 (gdb) continue
349 </literallayout>
350 </para>
351
352 <para>
353 For more information about using GDB, see the project's online documentation at
354 <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
355 </para>
356 </section>
357 </section>
358</section>
359
360<section id="platdev-oprofile">
361 <title>Profiling with OProfile</title>
362
363 <para>
364 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
365 statistical profiler well suited for finding performance
366 bottlenecks in both userspace software and in the kernel.
367 This profiler provides answers to questions like "Which functions does my application spend
368 the most time in when doing X?"
369 Because the Yocto Project is well integrated with OProfile, it makes profiling applications on target
370 hardware straightforward.
371 </para>
372
373 <para>
374 To use OProfile, you need an image that has OProfile installed.
375 The easiest way to do this is with <filename>tools-profile</filename> in the
376 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> variable.
377 You also need debugging symbols to be available on the system where the analysis
378 takes place.
379 You can gain access to the symbols by using <filename>dbg-pkgs</filename> in the
380 <filename>IMAGE_FEATURES</filename> variable or by
381 installing the appropriate <filename>-dbg</filename> packages.
382 </para>
383
384 <para>
385 For successful call graph analysis, the binaries must preserve the frame
386 pointer register and should also be compiled with the
387 <filename>-fno-omit-framepointer</filename> flag.
388 In the Yocto Project you can achieve this by setting the
389 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION
390 </link></filename> variable to
391 <filename>-fexpensive-optimizations -fno-omit-framepointer -frename-registers -O2</filename>.
392 You can also achieve it by setting the
393 <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> variable to "1" in
394 the <filename>local.conf</filename> configuration file.
395 If you use the <filename>DEBUG_BUILD</filename> variable you will also add extra debug information
396 that can make the debug packages large.
397 </para>
398
399 <section id="platdev-oprofile-target">
400 <title>Profiling on the Target</title>
401
402 <para>
403 Using OProfile you can perform all the profiling work on the target device.
404 A simple OProfile session might look like the following:
405 </para>
406
407 <para>
408 <literallayout class='monospaced'>
409 # opcontrol --reset
410 # opcontrol --start --separate=lib --no-vmlinux -c 5
411 .
412 .
413 [do whatever is being profiled]
414 .
415 .
416 # opcontrol --stop
417 $ opreport -cl
418 </literallayout>
419 </para>
420
421 <para>
422 In this example, the <filename>reset</filename> command clears any previously profiled data.
423 The next command starts OProfile.
424 The options used when starting the profiler separate dynamic library data
425 within applications, disable kernel profiling, and enable callgraphing up to
426 five levels deep.
427 <note>
428 To profile the kernel, you would specify the
429 <filename>--vmlinux=/path/to/vmlinux</filename> option.
430 The <filename>vmlinux</filename> file is usually in the Yocto Project file's
431 <filename>/boot/</filename> directory and must match the running kernel.
432 </note>
433 </para>
434
435 <para>
436 After you perform your profiling tasks, the next command stops the profiler.
437 After that, you can view results with the <filename>opreport</filename> command with options
438 to see the separate library symbols and callgraph information.
439 </para>
440
441 <para>
442 Callgraphing logs information about time spent in functions and about a function's
443 calling function (parent) and called functions (children).
444 The higher the callgraphing depth, the more accurate the results.
445 However, higher depths also increase the logging overhead.
446 Consequently, you should take care when setting the callgraphing depth.
447 <note>
448 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
449 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
450 with <filename>gcc</filename>.
451 </note>
452 </para>
453
454 <para>
455 For more information on using OProfile, see the OProfile
456 online documentation at
457 <ulink url="http://oprofile.sourceforge.net/docs/"/>.
458 </para>
459 </section>
460
461 <section id="platdev-oprofile-oprofileui">
462 <title>Using OProfileUI</title>
463
464 <para>
465 A graphical user interface for OProfile is also available.
466 You can download and build this interface from the Yocto Project at
467 <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
468 If the "tools-profile" image feature is selected, all necessary binaries
469 are installed onto the target device for OProfileUI interaction.
470 </para>
471
472 <para>
473 Even though the Yocto Project usually includes all needed patches on the target device, you
474 might find you need other OProfile patches for recent OProfileUI features.
475 If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
476 OProfileUI README</ulink> for the most recent information.
477 </para>
478
479 <section id="platdev-oprofile-oprofileui-online">
480 <title>Online Mode</title>
481
482 <para>
483 Using OProfile in online mode assumes a working network connection with the target
484 hardware.
485 With this connection, you just need to run "oprofile-server" on the device.
486 By default, OProfile listens on port 4224.
487 <note>
488 You can change the port using the <filename>--port</filename> command-line
489 option.
490 </note>
491 </para>
492
493 <para>
494 The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
495 straightforward.
496 You access key functionality through the buttons on the toolbar, which
497 are duplicated in the menus.
498 Here are the buttons:
499 <itemizedlist>
500 <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
501 You can also supply the IP address or hostname.</para></listitem>
502 <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
503 </para></listitem>
504 <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
505 </para></listitem>
506 <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
507 downloads the data to the local host.
508 Stopping the profiler generates the profile and displays it in the viewer.
509 </para></listitem>
510 <listitem><para><emphasis>Download:</emphasis> Downloads the data from the
511 target and generates the profile, which appears in the viewer.</para></listitem>
512 <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
513 Resetting the data removes sample information collected from previous
514 sampling runs.
515 Be sure you reset the data if you do not want to include old sample information.
516 </para></listitem>
517 <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
518 target to another directory for later examination.</para></listitem>
519 <listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
520 </para></listitem>
521 </itemizedlist>
522 </para>
523
524 <para>
525 The client downloads the complete 'profile archive' from
526 the target to the host for processing.
527 This archive is a directory that contains the sample data, the object files,
528 and the debug information for the object files.
529 The archive is then converted using the <filename>oparchconv</filename> script, which is
530 included in this distribution.
531 The script uses <filename>opimport</filename> to convert the archive from
532 the target to something that can be processed on the host.
533 </para>
534
535 <para>
536 Downloaded archives reside in the Yocto Project's build directory in
537 <filename>/tmp</filename> and are cleared up when they are no longer in use.
538 </para>
539
540 <para>
541 If you wish to perform kernel profiling, you need to be sure
542 a <filename>vmlinux</filename> file that matches the running kernel is available.
543 In the Yocto Project, that file is usually located in
544 <filename>/boot/vmlinux-KERNELVERSION</filename>, where
545 <filename>KERNEL-version</filename> is the version of the kernel.
546 The Yocto Project generates separate <filename>vmlinux</filename> packages for each kernel
547 it builds.
548 Thus, it should just be a question of making sure a matching package is
549 installed (e.g. <filename>opkg install kernel-vmlinux</filename>.
550 The files are automatically installed into development and profiling images
551 alongside OProfile.
552 A configuration option exists within the OProfileUI settings page that you can use to
553 enter the location of the <filename>vmlinux</filename> file.
554 </para>
555
556 <para>
557 Waiting for debug symbols to transfer from the device can be slow, and it
558 is not always necessary to actually have them on the device for OProfile use.
559 All that is needed is a copy of the filesystem with the debug symbols present
560 on the viewer system.
561 The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launching GDB on the Host Computer</link>"
562 section covers how to create such a directory with
563 the Yocto Project and how to use the OProfileUI Settings dialog to specify the location.
564 If you specify the directory, it will be used when the file checksums
565 match those on the system you are profiling.
566 </para>
567 </section>
568
569 <section id="platdev-oprofile-oprofileui-offline">
570 <title>Offline Mode</title>
571
572 <para>
573 If network access to the target is unavailable, you can generate
574 an archive for processing in <filename>oprofile-viewer</filename> as follows:
575 <literallayout class='monospaced'>
576 # opcontrol --reset
577 # opcontrol --start --separate=lib --no-vmlinux -c 5
578 .
579 .
580 [do whatever is being profiled]
581 .
582 .
583 # opcontrol --stop
584 # oparchive -o my_archive
585 </literallayout>
586 </para>
587
588 <para>
589 In the above example, <filename>my_archive</filename> is the name of the
590 archive directory where you would like the profile archive to be kept.
591 After the directory is created, you can copy it to another host and load it
592 using <filename>oprofile-viewer</filename> open functionality.
593 If necessary, the archive is converted.
594 </para>
595 </section>
596 </section>
597</section>
598
599
600
601</chapter> 120</chapter>
602<!-- 121<!--
603vim: expandtab tw=80 ts=4 122vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-11-18 03:55:12 +0000