summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-08-18 10:45:23 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-08-23 18:47:03 -0700
commited4caadd136a4dfb62ccb0d464889b1b0882986f (patch)
tree243d388ed15ea01484fadfd02bcab1af87d83ebc
parent90d5834ad205a413d60baf11603f4e57153a88be (diff)
downloadpoky-ed4caadd136a4dfb62ccb0d464889b1b0882986f.tar.gz
documentation/poky-ref-manual/development.xml: updates for YP terms
I updated the profiling sections to reflect Yocto Project rather than Poky. (From yocto-docs rev: 4f2c3bc93d97a6a8676fdd14ff9061bb92bdf5c9) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/poky-ref-manual/development.xml402
1 files changed, 186 insertions, 216 deletions
diff --git a/documentation/poky-ref-manual/development.xml b/documentation/poky-ref-manual/development.xml
index 8a0cfd1be3..797d79f5ad 100644
--- a/documentation/poky-ref-manual/development.xml
+++ b/documentation/poky-ref-manual/development.xml
@@ -325,20 +325,23 @@
325 </section> 325 </section>
326 326
327<section id="platdev-gdb-remotedebug"> 327<section id="platdev-gdb-remotedebug">
328 <title>Debugging with GDB Remotely</title> 328 <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
329 329
330 <para> 330 <para>
331 GNU Project Debugger (GDB) 331 GDB allows you to examine running programs, which in turn help you to understand and fix problems.
332 allows you to examine running programs to understand and fix problems and 332 It also allows you to perform post-mortem style analysis of program crashes.
333 also to perform post-mortem style analysis of program crashes. 333 GDB is available as a package within the Yocto Project and by default is
334 GDB is available as a package within Poky and by default is installed in sdk images. 334 installed in sdk images.
335 See <ulink url="http://sourceware.org/gdb/"/> for the GDB source. 335 See <xref linkend='ref-images'>Reference: Images</xref> for a description of these
336 images.
337 You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
336 </para> 338 </para>
337 <tip><para> 339
338 For best results install <filename>-dbg</filename> packages for the applications 340 <tip>
341 For best results, install <filename>-dbg</filename> packages for the applications
339 you are going to debug. 342 you are going to debug.
340 Doing so makes available extra debug symbols that will give you more meaningful output. 343 Doing so makes available extra debug symbols that give you more meaningful output.
341 </para></tip> 344 </tip>
342 345
343 <para> 346 <para>
344 Sometimes, due to memory or disk space constraints, it is not possible 347 Sometimes, due to memory or disk space constraints, it is not possible
@@ -351,58 +354,62 @@
351 These extra computations place more load on the target system and can alter the 354 These extra computations place more load on the target system and can alter the
352 characteristics of the program being debugged. 355 characteristics of the program being debugged.
353 </para> 356 </para>
357
354 <para> 358 <para>
355 To help get past these constraints you can use GDBSERVER. 359 To help get past the previously mentioned constraints, you can use Gdbserver.
356 It runs on the remote target and does not load any debugging information 360 Gdbserver runs on the remote target and does not load any debugging information
357 from the debugged process. 361 from the debugged process.
358 Instead, a GDB instance processes the debugging information that is run on a 362 Instead, a GDB instance processes the debugging information that is run on a
359 remote computer - the host GDB. 363 remote computer - the host GDB.
360 The host GDB then sends control commands to GDBSERVER to make it stop or start the debugged 364 The host GDB then sends control commands to Gdbserver to make it stop or start the debugged
361 program, as well as read or write memory regions of that debugged 365 program, as well as read or write memory regions of that debugged program.
362 program.
363 All the debugging information loaded and processed as well 366 All the debugging information loaded and processed as well
364 as all the heavy debugging is done by the host GDB. 367 as all the heavy debugging is done by the host GDB.
365 Offloading these processes gives the GDBSERVER running on the target a chance to remain 368 Offloading these processes gives the Gdbserver running on the target a chance to remain
366 small and fast. 369 small and fast.
367 </para> 370 </para>
371
368 <para> 372 <para>
369 Because the host GDB is responsible for loading the debugging information and 373 Because the host GDB is responsible for loading the debugging information and
370 for doing the necessary processing to make actual debugging happen, the 374 for doing the necessary processing to make actual debugging happen, the
371 user has to make sure the host can access the unstripped binaries complete 375 user has to make sure the host can access the unstripped binaries complete
372 with their debugging information and also compiled with no optimizations. 376 with their debugging information and also be sure the target is compiled with no optimizations.
373 The host GDB must also have local access to all the libraries used by the 377 The host GDB must also have local access to all the libraries used by the
374 debugged program. 378 debugged program.
375 Because GDBSERVER does not need any local debugging information the binaries on 379 Because Gdbserver does not need any local debugging information, the binaries on
376 the remote target can remain stripped. 380 the remote target can remain stripped.
377 However, the binaries must also be compiled without optimization 381 However, the binaries must also be compiled without optimization
378 so they match the host's binaries. 382 so they match the host's binaries.
379 </para> 383 </para>
380 384
381 <para> 385 <para>
382 To remain consistent with GDB documentation and terminology the binary being debugged 386 To remain consistent with GDB documentation and terminology, the binary being debugged
383 on the remote target machine is referred to as the 'inferior' binary. 387 on the remote target machine is referred to as the "inferior" binary.
384 For documentation on GDB see the GDB site at 388 For documentation on GDB see the
385 <ulink url="http://sourceware.org/gdb/documentation/">on their site</ulink>. 389 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
386 </para> 390 </para>
387 391
388 <section id="platdev-gdb-remotedebug-launch-gdbserver"> 392 <section id="platdev-gdb-remotedebug-launch-gdbserver">
389 <title>Launching GDBSERVER on the Target</title> 393 <title>Launching Gdbserver on the Target</title>
394
390 <para> 395 <para>
391 First, make sure GDBSERVER is installed on the target. If not, 396 First, make sure Gdbserver is installed on the target.
392 install the package <filename>gdbserver</filename>, which needs the 397 If it is not, install the package <filename>gdbserver</filename>, which needs the
393 <filename>libthread-db1</filename> package. 398 <filename>libthread-db1</filename> package.
394 </para> 399 </para>
400
395 <para> 401 <para>
396 As an example, to launch GDBSERVER on the target and make it ready to "debug" a 402 As an example, to launch Gdbserver on the target and make it ready to "debug" a
397 program located at <filename>/path/to/inferior</filename>, connect 403 program located at <filename>/path/to/inferior</filename>, connect
398 to the target and launch: 404 to the target and launch:
399 <literallayout class='monospaced'> 405 <literallayout class='monospaced'>
400 $ gdbserver localhost:2345 /path/to/inferior 406 $ gdbserver localhost:2345 /path/to/inferior
401 </literallayout> 407 </literallayout>
402 GDBSERVER should now be listening on port 2345 for debugging 408 Gdbserver should now be listening on port 2345 for debugging
403 commands coming from a remote GDB process that is running on the host computer. 409 commands coming from a remote GDB process that is running on the host computer.
404 Communication between GDBSERVER and the host GDB are done using TCP. 410 Communication between Gdbserver and the host GDB are done using TCP.
405 To use other communication protocols please refer to the GDBSERVER documentation. 411 To use other communication protocols, please refer to the
412 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
406 </para> 413 </para>
407 </section> 414 </section>
408 415
@@ -419,28 +426,29 @@
419 <para> 426 <para>
420 A suitable GDB cross-binary is required that runs on your host computer but 427 A suitable GDB cross-binary is required that runs on your host computer but
421 also knows about the the ABI of the remote target. 428 also knows about the the ABI of the remote target.
422 You can get this binary from the the Poky toolchain - for example: 429 You can get this binary from the the Yocto Project meta-toolchain.
423 <programlisting> 430 Here is an example:
424/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb 431 <literallayout class='monospaced'>
425 </programlisting> 432 /usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb
426 where "arm" is the target architecture and "linux-gnueabi" the target ABI. 433 </literallayout>
434 where <filename>arm</filename> is the target architecture and
435 <filename>linux-gnueabi</filename> the target ABI.
427 </para> 436 </para>
428 437
429 <para> 438 <para>
430 Alternatively, Poky can build the <filename>gdb-cross</filename> binary. 439 Alternatively, the Yocto Project can build the <filename>gdb-cross</filename> binary.
431 For example, the following command builds it: 440 Here is an example:
432 <literallayout class='monospaced'> 441 <literallayout class='monospaced'>
433 $ bitbake gdb-cross 442 $ bitbake gdb-cross
434 </literallayout> 443 </literallayout>
435 Once the binary is built you can find it here: 444 Once the binary is built, you can find it here:
436 <programlisting> 445 <literallayout class='monospaced'>
437tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-abi&gt;-gdb 446 tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-abi&gt;-gdb
438 </programlisting> 447 </literallayout>
439 </para> 448 </para>
440
441 </section> 449 </section>
442 <section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins">
443 450
451 <section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins">
444 <title>Making the Inferior Binaries Available</title> 452 <title>Making the Inferior Binaries Available</title>
445 453
446 <para> 454 <para>
@@ -451,56 +459,58 @@ tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-abi&gt;-gdb
451 </para> 459 </para>
452 460
453 <para> 461 <para>
454 Perhaps the easiest is to have an 'sdk' image that corresponds to the plain 462 Perhaps the easiest way is to have an 'sdk' image that corresponds to the plain
455 image installed on the device. 463 image installed on the device.
456 In the case of 'core-image-sato', 'core-image-sdk' would contain suitable symbols. 464 In the case of <filename>core-image-sato</filename>,
457 Because the sdk images already have the debugging symbols installed it is just a 465 <filename>core-image-sdk</filename> would contain suitable symbols.
466 Because the sdk images already have the debugging symbols installed, it is just a
458 question of expanding the archive to some location and then informing GDB. 467 question of expanding the archive to some location and then informing GDB.
459 </para> 468 </para>
460 469
461 <para> 470 <para>
462 Alternatively, Poky can build a custom directory of files for a specific 471 Alternatively, Yocto Project can build a custom directory of files for a specific
463 debugging purpose by reusing its <filename>tmp/rootfs</filename> directory. 472 debugging purpose by reusing its <filename>tmp/rootfs</filename> directory.
464 This directory contains the contents of the last built image. 473 This directory contains the contents of the last built image.
465 This process assumes two things: 474 This process assumes two things:
466 <itemizedlist> 475 <itemizedlist>
467 <listitem><para>The image running on the target was the last image to 476 <listitem><para>The image running on the target was the last image to
468 be built by Poky.</para></listitem> 477 be built by the Yocto Project.</para></listitem>
469 <listitem><para>The package (<filename>foo</filename> in the following 478 <listitem><para>The package (<filename>foo</filename> in the following
470 example) that contains the inferior binary to be debugged has been built 479 example) that contains the inferior binary to be debugged has been built
471 without optimization and has debugging information available.</para></listitem> 480 without optimization and has debugging information available.</para></listitem>
472 </itemizedlist> 481 </itemizedlist>
473 </para> 482 </para>
483
474 <para> 484 <para>
475 These steps show how to build the custom directory of files: 485 The following steps show how to build the custom directory of files:
486 <orderedlist>
487 <listitem><para>Install the package (<filename>foo</filename> in this case) to
488 <filename>tmp/rootfs</filename>:
489 <literallayout class='monospaced'>
490 $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
491 tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf -o \
492 tmp/rootfs/ update
493 </literallayout></para></listitem>
494 <listitem><para>Install the debugging information:
495 <literallayout class='monospaced'>
496 $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
497 tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
498 -o tmp/rootfs install foo
499
500 $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
501 tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
502 -o tmp/rootfs install foo-dbg
503 </literallayout></para></listitem>
504 </orderedlist>
476 </para> 505 </para>
477 <orderedlist>
478 <listitem><para>Install the package (<filename>foo</filename> in this case) to
479 <filename>tmp/rootfs</filename>:
480 <programlisting>
481tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
482tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf -o \
483tmp/rootfs/ update
484 </programlisting></para></listitem>
485 <listitem><para>Install the debugging information:
486 <programlisting>
487tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
488tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
489-o tmp/rootfs install foo
490
491tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
492tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
493-o tmp/rootfs install foo-dbg
494 </programlisting></para></listitem>
495 </orderedlist>
496
497 </section> 506 </section>
498 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
499 507
508 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
500 <title>Launch the Host GDB</title> 509 <title>Launch the Host GDB</title>
510
501 <para> 511 <para>
502 To launch the host GDB, you run the cross-gdb binary and provide the inferior 512 To launch the host GDB, you run the <filename>cross-gdb</filename> binary and provide
503 binary as part of the command line. 513 the inferior binary as part of the command line.
504 For example, the following command form continues with the example used in 514 For example, the following command form continues with the example used in
505 the previous section. 515 the previous section.
506 This command form loads the <filename>foo</filename> binary 516 This command form loads the <filename>foo</filename> binary
@@ -517,21 +527,22 @@ tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
517 the absolute path to <filename>tmp/rootfs</filename> or the location at which 527 the absolute path to <filename>tmp/rootfs</filename> or the location at which
518 binaries with debugging information reside. 528 binaries with debugging information reside.
519 </para> 529 </para>
530
520 <para> 531 <para>
521 At this point you can have GDB connect to the GDBSERVER that is running 532 At this point you can have GDB connect to the Gdbserver that is running
522 on the remote target by using the following command form: 533 on the remote target by using the following command form:
523 <literallayout class='monospaced'> 534 <literallayout class='monospaced'>
524 $ target remote remote-target-ip-address:2345 535 $ target remote remote-target-ip-address:2345
525 </literallayout> 536 </literallayout>
526 The <filename>remote-target-ip-address</filename> is the IP address of the 537 The <filename>remote-target-ip-address</filename> is the IP address of the
527 remote target where the GDBSERVER is running. 538 remote target where the Gdbserver is running.
528 Port 2345 is the port on which the GDBSERVER is running. 539 Port 2345 is the port on which the GDBSERVER is running.
529 </para> 540 </para>
530
531 </section> 541 </section>
532 <section id="platdev-gdb-remotedebug-launch-gdb-using">
533 542
543 <section id="platdev-gdb-remotedebug-launch-gdb-using">
534 <title>Using the Debugger</title> 544 <title>Using the Debugger</title>
545
535 <para> 546 <para>
536 You can now proceed with debugging as normal - as if you were debugging 547 You can now proceed with debugging as normal - as if you were debugging
537 on the local machine. 548 on the local machine.
@@ -543,13 +554,13 @@ tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
543 (gdb) continue 554 (gdb) continue
544 </literallayout> 555 </literallayout>
545 </para> 556 </para>
557
546 <para> 558 <para>
547 For more information about using GDB, see the project's online documentation at 559 For more information about using GDB, see the project's online documentation at
548 <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>. 560 <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
549 </para> 561 </para>
550 </section> 562 </section>
551 </section> 563 </section>
552
553</section> 564</section>
554 565
555<section id="platdev-oprofile"> 566<section id="platdev-oprofile">
@@ -561,32 +572,33 @@ tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
561 bottlenecks in both userspace software and in the kernel. 572 bottlenecks in both userspace software and in the kernel.
562 This profiler provides answers to questions like "Which functions does my application spend 573 This profiler provides answers to questions like "Which functions does my application spend
563 the most time in when doing X?" 574 the most time in when doing X?"
564 Because Poky is well integrated with OProfile it makes profiling applications on target 575 Because the Yocto Project is well integrated with OProfile, it makes profiling applications on target
565 hardware straightforward. 576 hardware straightforward.
566 </para> 577 </para>
567 578
568 <para> 579 <para>
569 To use OProfile you need an image that has OProfile installed. 580 To use OProfile, you need an image that has OProfile installed.
570 The easiest way to do this is with "tools-profile" in 581 The easiest way to do this is with <filename>tools-profile</filename> in the
571 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>. 582 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> variable.
572 You also need debugging symbols to be available on the system where the analysis 583 You also need debugging symbols to be available on the system where the analysis
573 takes place. 584 takes place.
574 You can gain access to the symbols by using "dbg-pkgs" in 585 You can gain access to the symbols by using <filename>dbg-pkgs</filename> in the
575 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> or by 586 <filename>IMAGE_FEATURES</filename> variable or by
576 installing the appropriate <filename>-dbg</filename> packages. 587 installing the appropriate <filename>-dbg</filename> packages.
577 </para> 588 </para>
589
578 <para> 590 <para>
579 For successful call graph analysis the binaries must preserve the frame 591 For successful call graph analysis, the binaries must preserve the frame
580 pointer register and should also be compiled with the 592 pointer register and should also be compiled with the
581 "-fno-omit-framepointer" flag. 593 <filename>-fno-omit-framepointer</filename> flag.
582 In Poky you can achieve this by setting 594 In the Yocto Project you can achieve this by setting the
583 <glossterm><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION 595 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION
584 </link></glossterm> to "-fexpensive-optimizations -fno-omit-framepointer 596 </link></filename> variable to
585 -frename-registers -O2". 597 <filename>-fexpensive-optimizations -fno-omit-framepointer -frename-registers -O2</filename>.
586 You can also achieve it by setting 598 You can also achieve it by setting the
587 <glossterm><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></glossterm> to "1" in 599 <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> variable to "1" in
588 <filename>local.conf</filename>. 600 the <filename>local.conf</filename> configuration file.
589 If you use the DEBUG_BUILD variable you will also add extra debug information 601 If you use the <filename>DEBUG_BUILD</filename> variable you will also add extra debug information
590 that can make the debug packages large. 602 that can make the debug packages large.
591 </para> 603 </para>
592 604
@@ -600,46 +612,51 @@ tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
600 612
601 <para> 613 <para>
602 <literallayout class='monospaced'> 614 <literallayout class='monospaced'>
603# opcontrol --reset 615 # opcontrol --reset
604# opcontrol --start --separate=lib --no-vmlinux -c 5 616 # opcontrol --start --separate=lib --no-vmlinux -c 5
605[do whatever is being profiled] 617 .
606# opcontrol --stop 618 .
607$ opreport -cl 619 [do whatever is being profiled]
620 .
621 .
622 # opcontrol --stop
623 $ opreport -cl
608 </literallayout> 624 </literallayout>
609 </para> 625 </para>
610 626
611 <para> 627 <para>
612 In this example, the reset command clears any previously profiled data. 628 In this example, the <filename>reset</filename> command clears any previously profiled data.
613 The next command starts OProfile. 629 The next command starts OProfile.
614 The options used when starting the profiler separate dynamic library data 630 The options used when starting the profiler separate dynamic library data
615 within applications, disable kernel profiling, and enable callgraphing up to 631 within applications, disable kernel profiling, and enable callgraphing up to
616 five levels deep. 632 five levels deep.
633 <note>
634 To profile the kernel, you would specify the
635 <filename>--vmlinux=/path/to/vmlinux</filename> option.
636 The <filename>vmlinux</filename> file is usually in the Yocto Project file's
637 <filename>/boot/</filename> directory and must match the running kernel.
638 </note>
617 </para> 639 </para>
618 <note><para> 640
619 To profile the kernel, you would specify the
620 <parameter>--vmlinux=/path/to/vmlinux</parameter> option.
621 The vmlinux file is usually in <filename class="directory">/boot/</filename>
622 in Poky and must match the running kernel.
623 </para></note>
624 <para> 641 <para>
625 After you perform your profiling tasks, the next command stops the profiler. 642 After you perform your profiling tasks, the next command stops the profiler.
626 After that you can view results with the "opreport" command with options 643 After that, you can view results with the <filename>opreport</filename> command with options
627 to see the separate library symbols and callgraph information. 644 to see the separate library symbols and callgraph information.
628 </para> 645 </para>
646
629 <para> 647 <para>
630 Callgraphing logs information about time spent in functions and about a function's 648 Callgraphing logs information about time spent in functions and about a function's
631 calling function (parent) and called functions (children). 649 calling function (parent) and called functions (children).
632 The higher the callgraphing depth, 650 The higher the callgraphing depth, the more accurate the results.
633 the more accurate the results. 651 However, higher depths also increase the logging overhead.
634 However, higher depths also increase the logging
635 overhead.
636 Consequently, you should take care when setting the callgraphing depth. 652 Consequently, you should take care when setting the callgraphing depth.
653 <note>
654 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
655 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
656 with <filename>gcc</filename>.
657 </note>
637 </para> 658 </para>
638 <note><para> 659
639 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
640 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
641 with <filename>gcc</filename>.
642 </para></note>
643 <para> 660 <para>
644 For more information on using OProfile, see the OProfile 661 For more information on using OProfile, see the OProfile
645 online documentation at 662 online documentation at
@@ -652,35 +669,14 @@ $ opreport -cl
652 669
653 <para> 670 <para>
654 A graphical user interface for OProfile is also available. 671 A graphical user interface for OProfile is also available.
655 You can download and build it from the Yocto Project at 672 You can download and build this interface from the Yocto Project at
656 <ulink url="http://git.yoctoproject.org/cgit.cgi/oprofileui/"></ulink>. 673 <ulink url="http://git.yoctoproject.org/cgit.cgi/oprofileui/"></ulink>.
657 If the "tools-profile" image feature is selected, all necessary binaries 674 If the "tools-profile" image feature is selected, all necessary binaries
658 are installed onto the target device for OProfileUI interaction. 675 are installed onto the target device for OProfileUI interaction.
659 </para> 676 </para>
660 677
661<!-- DISABLED, Need a more 'contextual' shot?
662 <screenshot>
663 <mediaobject>
664 <imageobject>
665 <imagedata fileref="screenshots/ss-oprofile-viewer.png" format="PNG"/>
666 </imageobject>
667 <caption>
668 <para>OProfileUI Viewer showing an application being profiled on a remote device</para>
669 </caption>
670 </mediaobject>
671 </screenshot>
672
673 <para>
674 In order to convert the data in the sample format from the target
675 to the host you need the <filename>opimport</filename> program.
676 This program is not included in standard Debian OProfile packages.
677 However, an OProfile package with this addition is available from the
678 <ulink url='http://debian.o-hand.com/'>OpenedHand repository</ulink>.
679 We recommend using OProfile 0.9.3 or greater.
680 </para>
681-->
682 <para> 678 <para>
683 Even though Poky usually includes all needed patches on the target device, you 679 Even though the Yocto Project usually includes all needed patches on the target device, you
684 might find you need other OProfile patches for recent OProfileUI features. 680 might find you need other OProfile patches for recent OProfileUI features.
685 If so, see the <ulink url='http://git.yoctoproject.org/cgit.cgi/oprofileui/tree/README'> 681 If so, see the <ulink url='http://git.yoctoproject.org/cgit.cgi/oprofileui/tree/README'>
686 OProfileUI README</ulink> for the most recent information. 682 OProfileUI README</ulink> for the most recent information.
@@ -693,101 +689,74 @@ $ opreport -cl
693 Using OProfile in online mode assumes a working network connection with the target 689 Using OProfile in online mode assumes a working network connection with the target
694 hardware. 690 hardware.
695 With this connection, you just need to run "oprofile-server" on the device. 691 With this connection, you just need to run "oprofile-server" on the device.
696 By default OProfile listens on port 4224. 692 By default, OProfile listens on port 4224.
693 <note>
694 You can change the port using the <filename>--port</filename> command-line
695 option.
696 </note>
697 </para> 697 </para>
698 <note><para>
699 You can change the port using the <filename>--port</filename> command-line
700 option.
701 </para></note>
702 698
703 <para> 699 <para>
704 The client program is called "oprofile-viewer" and its UI is relatively 700 The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
705 straightforward. 701 straightforward.
706 You access key functionality through the buttons on the toolbar, which 702 You access key functionality through the buttons on the toolbar, which
707 are duplicated in the menus. 703 are duplicated in the menus.
708 The buttons are: 704 Here are the buttons:
709 </para> 705 <itemizedlist>
710 706 <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
711 <itemizedlist> 707 You can also supply the IP address or hostname.</para></listitem>
712 <listitem> 708 <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
713 <para> 709 </para></listitem>
714 Connect - Connects to the remote host. 710 <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
715 You can also supply the IP address or hostname. 711 </para></listitem>
716 </para> 712 <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
717 </listitem> 713 downloads the data to the local host.
718 <listitem>
719 <para>
720 Disconnect - Disconnects from the target.
721 </para>
722 </listitem>
723 <listitem>
724 <para>
725 Start - Starts profiling on the device.
726 </para>
727 </listitem>
728 <listitem>
729 <para>
730 Stop - Stops profiling on the device and downloads the data to the local
731 host.
732 Stopping the profiler generates the profile and displays it in the viewer. 714 Stopping the profiler generates the profile and displays it in the viewer.
733 </para> 715 </para></listitem>
734 </listitem> 716 <listitem><para><emphasis>Download:</emphasis> Downloads the data from the
735 <listitem> 717 target and generates the profile, which appears in the viewer.</para></listitem>
736 <para> 718 <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
737 Download - Downloads the data from the target and generates the profile,
738 which appears in the viewer.
739 </para>
740 </listitem>
741 <listitem>
742 <para>
743 Reset - Resets the sample data on the device.
744 Resetting the data removes sample information collected from previous 719 Resetting the data removes sample information collected from previous
745 sampling runs. 720 sampling runs.
746 Be sure you reset the data if you do not want to include old sample information. 721 Be sure you reset the data if you do not want to include old sample information.
747 </para> 722 </para></listitem>
748 </listitem> 723 <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
749 <listitem> 724 target to another directory for later examination.</para></listitem>
750 <para> 725 <listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
751 Save - Saves the data downloaded from the target to another directory for later 726 </para></listitem>
752 examination. 727 </itemizedlist>
753 </para> 728 </para>
754 </listitem>
755 <listitem>
756 <para>
757 Open - Loads previously saved data.
758 </para>
759 </listitem>
760 </itemizedlist>
761 729
762 <para> 730 <para>
763 The client downloads the complete 'profile archive' from 731 The client downloads the complete 'profile archive' from
764 the target to the host for processing. 732 the target to the host for processing.
765 This archive is a directory that contains the sample data, the object files 733 This archive is a directory that contains the sample data, the object files,
766 and the debug information for the object files. 734 and the debug information for the object files.
767 The archive is then converted using the "oparchconv" script, which is 735 The archive is then converted using the <filename>oparchconv</filename> script, which is
768 included in this distribution. 736 included in this distribution.
769 The script uses "opimport" to convert the archive from 737 The script uses <filename>opimport</filename> to convert the archive from
770 the target to something that can be processed on the host. 738 the target to something that can be processed on the host.
771 </para> 739 </para>
772 740
773 <para> 741 <para>
774 Downloaded archives reside in <filename>/tmp</filename> and are cleared up 742 Downloaded archives reside in the Yocto Project's build directory in
775 when they are no longer in use. 743 <filename>/tmp</filename> and are cleared up when they are no longer in use.
776 </para> 744 </para>
777 745
778 <para> 746 <para>
779 If you wish to perform kernel profiling you need to be sure 747 If you wish to perform kernel profiling, you need to be sure
780 a "vmlinux" file that matches the running kernel is available. 748 a <filename>vmlinux</filename> file that matches the running kernel is available.
781 In Poky, that file is usually located in 749 In the Yocto Project, that file is usually located in
782 <filename>/boot/vmlinux-KERNELVERSION</filename>, where KERNEL-version is the 750 <filename>/boot/vmlinux-KERNELVERSION</filename>, where
783 version of the kernel. 751 <filename>KERNEL-version</filename> is the version of the kernel.
784 Poky generates separate vmlinux packages for each kernel 752 The Yocto Project generates separate <filename>vmlinux</filename> packages for each kernel
785 it builds so it should be a question of just making sure a matching package is 753 it builds.
786 installed - for example: <filename>opkg install kernel-vmlinux</filename>. 754 Thus, it should just be a question of making sure a matching package is
755 installed (e.g. <filename>opkg install kernel-vmlinux</filename>.
787 The files are automatically installed into development and profiling images 756 The files are automatically installed into development and profiling images
788 alongside OProfile. 757 alongside OProfile.
789 There is a configuration option within the OProfileUI settings page where 758 A configuration option exists within the OProfileUI settings page that you can use to
790 you can enter the location of the vmlinux file. 759 enter the location of the <filename>vmlinux</filename> file.
791 </para> 760 </para>
792 761
793 <para> 762 <para>
@@ -795,9 +764,9 @@ $ opreport -cl
795 is not always necessary to actually have them on the device for OProfile use. 764 is not always necessary to actually have them on the device for OProfile use.
796 All that is needed is a copy of the filesystem with the debug symbols present 765 All that is needed is a copy of the filesystem with the debug symbols present
797 on the viewer system. 766 on the viewer system.
798 The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launching GDB 767 The <link linkend='platdev-gdb-remotedebug-launch-gdb'>Launching GDB
799 on the Host Computer</link>" section covers how to create such a directory with Poky and 768 on the Host Computer</link> section covers how to create such a directory with
800 how to use the OProfileUI Settings dialog to specify the location. 769 the Yocto Project and how to use the OProfileUI Settings dialog to specify the location.
801 If you specify the directory, it will be used when the file checksums 770 If you specify the directory, it will be used when the file checksums
802 match those on the system you are profiling. 771 match those on the system you are profiling.
803 </para> 772 </para>
@@ -808,24 +777,25 @@ $ opreport -cl
808 777
809 <para> 778 <para>
810 If network access to the target is unavailable, you can generate 779 If network access to the target is unavailable, you can generate
811 an archive for processing in "oprofile-viewer" as follows: 780 an archive for processing in <filename>oprofile-viewer</filename> as follows:
812 </para>
813
814 <para>
815 <literallayout class='monospaced'> 781 <literallayout class='monospaced'>
816 # opcontrol --reset 782 # opcontrol --reset
817 # opcontrol --start --separate=lib --no-vmlinux -c 5 783 # opcontrol --start --separate=lib --no-vmlinux -c 5
784 .
785 .
818 [do whatever is being profiled] 786 [do whatever is being profiled]
787 .
788 .
819 # opcontrol --stop 789 # opcontrol --stop
820 # oparchive -o my_archive 790 # oparchive -o my_archive
821 </literallayout> 791 </literallayout>
822 </para> 792 </para>
823 793
824 <para> 794 <para>
825 In the above example <filename>my_archive</filename> is the name of the 795 In the above example, <filename>my_archive</filename> is the name of the
826 archive directory where you would like the profile archive to be kept. 796 archive directory where you would like the profile archive to be kept.
827 After the directory is created, you can copy it to another host and load it 797 After the directory is created, you can copy it to another host and load it
828 using "oprofile-viewer" open functionality. 798 using <filename>oprofile-viewer</filename> open functionality.
829 If necessary, the archive is converted. 799 If necessary, the archive is converted.
830 </para> 800 </para>
831 </section> 801 </section>