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 @@ - -
- Debugging With the GNU Project Debugger (GDB) Remotely - - - GDB allows you to examine running programs, which in turn help you to understand and fix problems. - It also allows you to perform post-mortem style analysis of program crashes. - GDB is available as a package within the Yocto Project and by default is - installed in sdk images. - See the "Reference: Images" appendix for a description of these - images. - You can find information on GDB at . - - - - For best results, install -dbg packages for the applications - you are going to debug. - Doing so makes available extra debug symbols that give you more meaningful output. - - - - Sometimes, due to memory or disk space constraints, it is not possible - to use GDB directly on the remote target to debug applications. - These constraints arise because GDB needs to load the debugging information and the - binaries of the process being debugged. - Additionally, GDB needs to perform many computations to locate information such as function - names, variable names and values, stack traces and so forth - even before starting the - debugging process. - These extra computations place more load on the target system and can alter the - characteristics of the program being debugged. - - - - To help get past the previously mentioned constraints, you can use Gdbserver. - Gdbserver runs on the remote target and does not load any debugging information - from the debugged process. - Instead, a GDB instance processes the debugging information that is run on a - remote computer - the host GDB. - The host GDB then sends control commands to Gdbserver to make it stop or start the debugged - program, as well as read or write memory regions of that debugged program. - All the debugging information loaded and processed as well - as all the heavy debugging is done by the host GDB. - Offloading these processes gives the Gdbserver running on the target a chance to remain - small and fast. - - - - Because the host GDB is responsible for loading the debugging information and - for doing the necessary processing to make actual debugging happen, the - user has to make sure the host can access the unstripped binaries complete - with their debugging information and also be sure the target is compiled with no optimizations. - The host GDB must also have local access to all the libraries used by the - debugged program. - Because Gdbserver does not need any local debugging information, the binaries on - the remote target can remain stripped. - However, the binaries must also be compiled without optimization - so they match the host's binaries. - - - - To remain consistent with GDB documentation and terminology, the binary being debugged - on the remote target machine is referred to as the "inferior" binary. - For documentation on GDB see the - GDB site. - - -
- Launching Gdbserver on the Target - - - First, make sure Gdbserver is installed on the target. - If it is not, install the package gdbserver, which needs the - libthread-db1 package. - - - - As an example, to launch Gdbserver on the target and make it ready to "debug" a - program located at /path/to/inferior, connect - to the target and launch: - - $ gdbserver localhost:2345 /path/to/inferior - - Gdbserver should now be listening on port 2345 for debugging - commands coming from a remote GDB process that is running on the host computer. - Communication between Gdbserver and the host GDB are done using TCP. - To use other communication protocols, please refer to the - Gdbserver documentation. - -
- -
- Launching GDB on the Host Computer - - - Running GDB on the host computer takes a number of stages. - This section describes those stages. - - -
- Building the Cross-GDB Package - - A suitable GDB cross-binary is required that runs on your host computer but - also knows about the the ABI of the remote target. - You can get this binary from the the Yocto Project meta-toolchain. - Here is an example: - - /usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb - - where arm is the target architecture and - linux-gnueabi the target ABI. - - - - Alternatively, the Yocto Project can build the gdb-cross binary. - Here is an example: - - $ bitbake gdb-cross - - Once the binary is built, you can find it here: - - tmp/sysroots/<host-arch>/usr/bin/<target-abi>-gdb - - -
- -
- Making the Inferior Binaries Available - - - The inferior binary (complete with all debugging symbols) as well as any - libraries (and their debugging symbols) on which the inferior binary depends - need to be available. - There are a number of ways you can make these available. - - - - Perhaps the easiest way is to have an 'sdk' image that corresponds to the plain - image installed on the device. - In the case of core-image-sato, - core-image-sato-sdk would contain suitable symbols. - Because the sdk images already have the debugging symbols installed, it is just a - question of expanding the archive to some location and then informing GDB. - - - - Alternatively, Yocto Project can build a custom directory of files for a specific - debugging purpose by reusing its tmp/rootfs directory. - This directory contains the contents of the last built image. - This process assumes two things: - - The image running on the target was the last image to - be built by the Yocto Project. - The package (foo in the following - example) that contains the inferior binary to be debugged has been built - without optimization and has debugging information available. - - - - - The following steps show how to build the custom directory of files: - - Install the package (foo in this case) to - tmp/rootfs: - - $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ - tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf -o \ - tmp/rootfs/ update - - Install the debugging information: - - $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ - tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf \ - -o tmp/rootfs install foo - - $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ - tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf \ - -o tmp/rootfs install foo-dbg - - - -
- -
- Launch the Host GDB - - - To launch the host GDB, you run the cross-gdb binary and provide - the inferior binary as part of the command line. - For example, the following command form continues with the example used in - the previous section. - This command form loads the foo binary - as well as the debugging information: - - $ <target-abi>-gdb rootfs/usr/bin/foo - - Once the GDB prompt appears, you must instruct GDB to load all the libraries - of the inferior binary from tmp/rootfs as follows: - - $ set solib-absolute-prefix /path/to/tmp/rootfs - - The pathname /path/to/tmp/rootfs must either be - the absolute path to tmp/rootfs or the location at which - binaries with debugging information reside. - - - - At this point you can have GDB connect to the Gdbserver that is running - on the remote target by using the following command form: - - $ target remote remote-target-ip-address:2345 - - The remote-target-ip-address is the IP address of the - remote target where the Gdbserver is running. - Port 2345 is the port on which the GDBSERVER is running. - -
- -
- Using the Debugger - - - You can now proceed with debugging as normal - as if you were debugging - on the local machine. - For example, to instruct GDB to break in the "main" function and then - continue with execution of the inferior binary use the following commands - from within GDB: - - (gdb) break main - (gdb) continue - - - - - For more information about using GDB, see the project's online documentation at - . - -
-
-
- -
- Profiling with OProfile - - - OProfile is a - statistical profiler well suited for finding performance - bottlenecks in both userspace software and in the kernel. - This profiler provides answers to questions like "Which functions does my application spend - the most time in when doing X?" - Because the Yocto Project is well integrated with OProfile, it makes profiling applications on target - hardware straightforward. - - - - To use OProfile, you need an image that has OProfile installed. - The easiest way to do this is with tools-profile in the - IMAGE_FEATURES variable. - You also need debugging symbols to be available on the system where the analysis - takes place. - You can gain access to the symbols by using dbg-pkgs in the - IMAGE_FEATURES variable or by - installing the appropriate -dbg packages. - - - - For successful call graph analysis, the binaries must preserve the frame - pointer register and should also be compiled with the - -fno-omit-framepointer flag. - In the Yocto Project you can achieve this by setting the - SELECTED_OPTIMIZATION - variable to - -fexpensive-optimizations -fno-omit-framepointer -frename-registers -O2. - You can also achieve it by setting the - DEBUG_BUILD variable to "1" in - the local.conf configuration file. - If you use the DEBUG_BUILD variable you will also add extra debug information - that can make the debug packages large. - - -
- Profiling on the Target - - - Using OProfile you can perform all the profiling work on the target device. - A simple OProfile session might look like the following: - - - - - # opcontrol --reset - # opcontrol --start --separate=lib --no-vmlinux -c 5 - . - . - [do whatever is being profiled] - . - . - # opcontrol --stop - $ opreport -cl - - - - - In this example, the reset command clears any previously profiled data. - The next command starts OProfile. - The options used when starting the profiler separate dynamic library data - within applications, disable kernel profiling, and enable callgraphing up to - five levels deep. - - To profile the kernel, you would specify the - --vmlinux=/path/to/vmlinux option. - The vmlinux file is usually in the Yocto Project file's - /boot/ directory and must match the running kernel. - - - - - After you perform your profiling tasks, the next command stops the profiler. - After that, you can view results with the opreport command with options - to see the separate library symbols and callgraph information. - - - - Callgraphing logs information about time spent in functions and about a function's - calling function (parent) and called functions (children). - The higher the callgraphing depth, the more accurate the results. - However, higher depths also increase the logging overhead. - Consequently, you should take care when setting the callgraphing depth. - - On ARM, binaries need to have the frame pointer enabled for callgraphing to work. - To accomplish this use the -fno-omit-framepointer option - with gcc. - - - - - For more information on using OProfile, see the OProfile - online documentation at - . - -
- -
- Using OProfileUI - - - A graphical user interface for OProfile is also available. - You can download and build this interface from the Yocto Project at - . - If the "tools-profile" image feature is selected, all necessary binaries - are installed onto the target device for OProfileUI interaction. - - - - Even though the Yocto Project usually includes all needed patches on the target device, you - might find you need other OProfile patches for recent OProfileUI features. - If so, see the - OProfileUI README for the most recent information. - - -
- Online Mode - - - Using OProfile in online mode assumes a working network connection with the target - hardware. - With this connection, you just need to run "oprofile-server" on the device. - By default, OProfile listens on port 4224. - - You can change the port using the --port command-line - option. - - - - - The client program is called oprofile-viewer and its UI is relatively - straightforward. - You access key functionality through the buttons on the toolbar, which - are duplicated in the menus. - Here are the buttons: - - Connect: Connects to the remote host. - You can also supply the IP address or hostname. - Disconnect: Disconnects from the target. - - Start: Starts profiling on the device. - - Stop: Stops profiling on the device and - downloads the data to the local host. - Stopping the profiler generates the profile and displays it in the viewer. - - Download: Downloads the data from the - target and generates the profile, which appears in the viewer. - Reset: Resets the sample data on the device. - Resetting the data removes sample information collected from previous - sampling runs. - Be sure you reset the data if you do not want to include old sample information. - - Save: Saves the data downloaded from the - target to another directory for later examination. - Open: Loads previously saved data. - - - - - - The client downloads the complete 'profile archive' from - the target to the host for processing. - This archive is a directory that contains the sample data, the object files, - and the debug information for the object files. - The archive is then converted using the oparchconv script, which is - included in this distribution. - The script uses opimport to convert the archive from - the target to something that can be processed on the host. - - - - Downloaded archives reside in the Yocto Project's build directory in - /tmp and are cleared up when they are no longer in use. - - - - If you wish to perform kernel profiling, you need to be sure - a vmlinux file that matches the running kernel is available. - In the Yocto Project, that file is usually located in - /boot/vmlinux-KERNELVERSION, where - KERNEL-version is the version of the kernel. - The Yocto Project generates separate vmlinux packages for each kernel - it builds. - Thus, it should just be a question of making sure a matching package is - installed (e.g. opkg install kernel-vmlinux. - The files are automatically installed into development and profiling images - alongside OProfile. - A configuration option exists within the OProfileUI settings page that you can use to - enter the location of the vmlinux file. - - - - Waiting for debug symbols to transfer from the device can be slow, and it - is not always necessary to actually have them on the device for OProfile use. - All that is needed is a copy of the filesystem with the debug symbols present - on the viewer system. - The "Launching GDB on the Host Computer" - section covers how to create such a directory with - the Yocto Project and how to use the OProfileUI Settings dialog to specify the location. - If you specify the directory, it will be used when the file checksums - match those on the system you are profiling. - -
- -
- Offline Mode - - - If network access to the target is unavailable, you can generate - an archive for processing in oprofile-viewer as follows: - - # opcontrol --reset - # opcontrol --start --separate=lib --no-vmlinux -c 5 - . - . - [do whatever is being profiled] - . - . - # opcontrol --stop - # oparchive -o my_archive - - - - - In the above example, my_archive is the name of the - archive directory where you would like the profile archive to be kept. - After the directory is created, you can copy it to another host and load it - using oprofile-viewer open functionality. - If necessary, the archive is converted. - -
-
-
- - -