summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-06-18 09:23:29 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-06-21 13:03:06 +0100
commitb2f4ddd6b43f4dfeb87dbdbd4a9d248c624bdb41 (patch)
tree6eb8a5a8bd98f307832cd85c0fd0bef0a166024a /documentation/dev-manual/dev-manual-common-tasks.xml
parent6b8922dbcff7545a994ed6415cab60f1f5a457a3 (diff)
downloadpoky-b2f4ddd6b43f4dfeb87dbdbd4a9d248c624bdb41.tar.gz
documentation/dev-manual/dev-manual-common-tasks.xml: Moved dbg and profile
Moved the sections on remote debugging and using the profile out of the YP Reference Manual and into the YP Development Manual. These are now two sections in the "Common Tasks" chapter. (From yocto-docs rev: 42640bf69aa05c56eb112c10b6d7b96069173785) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml478
1 files changed, 478 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index f792c7694f..067b5dfcc2 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1726,6 +1726,484 @@ so that there are some definite steps on how to do this. I need more detail her
1726 process. 1726 process.
1727 </para> 1727 </para>
1728 </section> 1728 </section>
1729
1730 <section id="platdev-gdb-remotedebug">
1731 <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
1732
1733 <para>
1734 GDB allows you to examine running programs, which in turn help you to understand and fix problems.
1735 It also allows you to perform post-mortem style analysis of program crashes.
1736 GDB is available as a package within the Yocto Project and by default is
1737 installed in sdk images.
1738 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Reference: Images</ulink>" appendix
1739 in the Yocto Project Reference Manual for a description of these images.
1740 You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
1741 </para>
1742
1743 <tip>
1744 For best results, install <filename>-dbg</filename> packages for the applications
1745 you are going to debug.
1746 Doing so makes available extra debug symbols that give you more meaningful output.
1747 </tip>
1748
1749 <para>
1750 Sometimes, due to memory or disk space constraints, it is not possible
1751 to use GDB directly on the remote target to debug applications.
1752 These constraints arise because GDB needs to load the debugging information and the
1753 binaries of the process being debugged.
1754 Additionally, GDB needs to perform many computations to locate information such as function
1755 names, variable names and values, stack traces and so forth - even before starting the
1756 debugging process.
1757 These extra computations place more load on the target system and can alter the
1758 characteristics of the program being debugged.
1759 </para>
1760
1761 <para>
1762 To help get past the previously mentioned constraints, you can use Gdbserver.
1763 Gdbserver runs on the remote target and does not load any debugging information
1764 from the debugged process.
1765 Instead, a GDB instance processes the debugging information that is run on a
1766 remote computer - the host GDB.
1767 The host GDB then sends control commands to Gdbserver to make it stop or start the debugged
1768 program, as well as read or write memory regions of that debugged program.
1769 All the debugging information loaded and processed as well
1770 as all the heavy debugging is done by the host GDB.
1771 Offloading these processes gives the Gdbserver running on the target a chance to remain
1772 small and fast.
1773 </para>
1774
1775 <para>
1776 Because the host GDB is responsible for loading the debugging information and
1777 for doing the necessary processing to make actual debugging happen, the
1778 user has to make sure the host can access the unstripped binaries complete
1779 with their debugging information and also be sure the target is compiled with no optimizations.
1780 The host GDB must also have local access to all the libraries used by the
1781 debugged program.
1782 Because Gdbserver does not need any local debugging information, the binaries on
1783 the remote target can remain stripped.
1784 However, the binaries must also be compiled without optimization
1785 so they match the host's binaries.
1786 </para>
1787
1788 <para>
1789 To remain consistent with GDB documentation and terminology, the binary being debugged
1790 on the remote target machine is referred to as the "inferior" binary.
1791 For documentation on GDB see the
1792 <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
1793 </para>
1794
1795 <section id="platdev-gdb-remotedebug-launch-gdbserver">
1796 <title>Launching Gdbserver on the Target</title>
1797
1798 <para>
1799 First, make sure Gdbserver is installed on the target.
1800 If it is not, install the package <filename>gdbserver</filename>, which needs the
1801 <filename>libthread-db1</filename> package.
1802 </para>
1803
1804 <para>
1805 As an example, to launch Gdbserver on the target and make it ready to "debug" a
1806 program located at <filename>/path/to/inferior</filename>, connect
1807 to the target and launch:
1808 <literallayout class='monospaced'>
1809 $ gdbserver localhost:2345 /path/to/inferior
1810 </literallayout>
1811 Gdbserver should now be listening on port 2345 for debugging
1812 commands coming from a remote GDB process that is running on the host computer.
1813 Communication between Gdbserver and the host GDB are done using TCP.
1814 To use other communication protocols, please refer to the
1815 <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
1816 </para>
1817 </section>
1818
1819 <section id="platdev-gdb-remotedebug-launch-gdb">
1820 <title>Launching GDB on the Host Computer</title>
1821
1822 <para>
1823 Running GDB on the host computer takes a number of stages.
1824 This section describes those stages.
1825 </para>
1826
1827 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
1828 <title>Building the Cross-GDB Package</title>
1829 <para>
1830 A suitable GDB cross-binary is required that runs on your host computer but
1831 also knows about the the ABI of the remote target.
1832 You can get this binary from the the Yocto Project meta-toolchain.
1833 Here is an example:
1834 <literallayout class='monospaced'>
1835 /usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb
1836 </literallayout>
1837 where <filename>arm</filename> is the target architecture and
1838 <filename>linux-gnueabi</filename> the target ABI.
1839 </para>
1840
1841 <para>
1842 Alternatively, the Yocto Project can build the <filename>gdb-cross</filename> binary.
1843 Here is an example:
1844 <literallayout class='monospaced'>
1845 $ bitbake gdb-cross
1846 </literallayout>
1847 Once the binary is built, you can find it here:
1848 <literallayout class='monospaced'>
1849 tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-abi&gt;-gdb
1850 </literallayout>
1851 </para>
1852 </section>
1853
1854 <section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins">
1855 <title>Making the Inferior Binaries Available</title>
1856
1857 <para>
1858 The inferior binary (complete with all debugging symbols) as well as any
1859 libraries (and their debugging symbols) on which the inferior binary depends
1860 need to be available.
1861 There are a number of ways you can make these available.
1862 </para>
1863
1864 <para>
1865 Perhaps the easiest way is to have an 'sdk' image that corresponds to the plain
1866 image installed on the device.
1867 In the case of <filename>core-image-sato</filename>,
1868 <filename>core-image-sato-sdk</filename> would contain suitable symbols.
1869 Because the sdk images already have the debugging symbols installed, it is just a
1870 question of expanding the archive to some location and then informing GDB.
1871 </para>
1872
1873 <para>
1874 Alternatively, Yocto Project can build a custom directory of files for a specific
1875 debugging purpose by reusing its <filename>tmp/rootfs</filename> directory.
1876 This directory contains the contents of the last built image.
1877 This process assumes two things:
1878 <itemizedlist>
1879 <listitem><para>The image running on the target was the last image to
1880 be built by the Yocto Project.</para></listitem>
1881 <listitem><para>The package (<filename>foo</filename> in the following
1882 example) that contains the inferior binary to be debugged has been built
1883 without optimization and has debugging information available.</para></listitem>
1884 </itemizedlist>
1885 </para>
1886
1887 <para>
1888 The following steps show how to build the custom directory of files:
1889 <orderedlist>
1890 <listitem><para>Install the package (<filename>foo</filename> in this case) to
1891 <filename>tmp/rootfs</filename>:
1892 <literallayout class='monospaced'>
1893 $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
1894 tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf -o \
1895 tmp/rootfs/ update
1896 </literallayout></para></listitem>
1897 <listitem><para>Install the debugging information:
1898 <literallayout class='monospaced'>
1899 $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
1900 tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
1901 -o tmp/rootfs install foo
1902
1903 $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
1904 tmp/work/&lt;target-abi&gt;/core-image-sato-1.0-r0/temp/opkg.conf \
1905 -o tmp/rootfs install foo-dbg
1906 </literallayout></para></listitem>
1907 </orderedlist>
1908 </para>
1909 </section>
1910
1911 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
1912 <title>Launch the Host GDB</title>
1913
1914 <para>
1915 To launch the host GDB, you run the <filename>cross-gdb</filename> binary and provide
1916 the inferior binary as part of the command line.
1917 For example, the following command form continues with the example used in
1918 the previous section.
1919 This command form loads the <filename>foo</filename> binary
1920 as well as the debugging information:
1921 <literallayout class='monospaced'>
1922 $ &lt;target-abi&gt;-gdb rootfs/usr/bin/foo
1923 </literallayout>
1924 Once the GDB prompt appears, you must instruct GDB to load all the libraries
1925 of the inferior binary from <filename>tmp/rootfs</filename> as follows:
1926 <literallayout class='monospaced'>
1927 $ set solib-absolute-prefix /path/to/tmp/rootfs
1928 </literallayout>
1929 The pathname <filename>/path/to/tmp/rootfs</filename> must either be
1930 the absolute path to <filename>tmp/rootfs</filename> or the location at which
1931 binaries with debugging information reside.
1932 </para>
1933
1934 <para>
1935 At this point you can have GDB connect to the Gdbserver that is running
1936 on the remote target by using the following command form:
1937 <literallayout class='monospaced'>
1938 $ target remote remote-target-ip-address:2345
1939 </literallayout>
1940 The <filename>remote-target-ip-address</filename> is the IP address of the
1941 remote target where the Gdbserver is running.
1942 Port 2345 is the port on which the GDBSERVER is running.
1943 </para>
1944 </section>
1945
1946 <section id="platdev-gdb-remotedebug-launch-gdb-using">
1947 <title>Using the Debugger</title>
1948
1949 <para>
1950 You can now proceed with debugging as normal - as if you were debugging
1951 on the local machine.
1952 For example, to instruct GDB to break in the "main" function and then
1953 continue with execution of the inferior binary use the following commands
1954 from within GDB:
1955 <literallayout class='monospaced'>
1956 (gdb) break main
1957 (gdb) continue
1958 </literallayout>
1959 </para>
1960
1961 <para>
1962 For more information about using GDB, see the project's online documentation at
1963 <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
1964 </para>
1965 </section>
1966 </section>
1967 </section>
1968
1969 <section id="platdev-oprofile">
1970 <title>Profiling with OProfile</title>
1971
1972 <para>
1973 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
1974 statistical profiler well suited for finding performance
1975 bottlenecks in both userspace software and in the kernel.
1976 This profiler provides answers to questions like "Which functions does my application spend
1977 the most time in when doing X?"
1978 Because the Yocto Project is well integrated with OProfile, it makes profiling applications on target
1979 hardware straightforward.
1980 </para>
1981
1982 <para>
1983 To use OProfile, you need an image that has OProfile installed.
1984 The easiest way to do this is with <filename>tools-profile</filename> in the
1985 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable.
1986 You also need debugging symbols to be available on the system where the analysis
1987 takes place.
1988 You can gain access to the symbols by using <filename>dbg-pkgs</filename> in the
1989 <filename>IMAGE_FEATURES</filename> variable or by
1990 installing the appropriate <filename>-dbg</filename> packages.
1991 </para>
1992
1993 <para>
1994 For successful call graph analysis, the binaries must preserve the frame
1995 pointer register and should also be compiled with the
1996 <filename>-fno-omit-framepointer</filename> flag.
1997 In the Yocto Project you can achieve this by setting the
1998 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename>
1999 variable to
2000 <filename>-fexpensive-optimizations -fno-omit-framepointer -frename-registers -O2</filename>.
2001 You can also achieve it by setting the
2002 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename>
2003 variable to "1" in the <filename>local.conf</filename> configuration file.
2004 If you use the <filename>DEBUG_BUILD</filename> variable you will also add extra debug information
2005 that can make the debug packages large.
2006 </para>
2007
2008 <section id="platdev-oprofile-target">
2009 <title>Profiling on the Target</title>
2010
2011 <para>
2012 Using OProfile you can perform all the profiling work on the target device.
2013 A simple OProfile session might look like the following:
2014 </para>
2015
2016 <para>
2017 <literallayout class='monospaced'>
2018 # opcontrol --reset
2019 # opcontrol --start --separate=lib --no-vmlinux -c 5
2020 .
2021 .
2022 [do whatever is being profiled]
2023 .
2024 .
2025 # opcontrol --stop
2026 $ opreport -cl
2027 </literallayout>
2028 </para>
2029
2030 <para>
2031 In this example, the <filename>reset</filename> command clears any previously profiled data.
2032 The next command starts OProfile.
2033 The options used when starting the profiler separate dynamic library data
2034 within applications, disable kernel profiling, and enable callgraphing up to
2035 five levels deep.
2036 <note>
2037 To profile the kernel, you would specify the
2038 <filename>--vmlinux=/path/to/vmlinux</filename> option.
2039 The <filename>vmlinux</filename> file is usually in the Yocto Project file's
2040 <filename>/boot/</filename> directory and must match the running kernel.
2041 </note>
2042 </para>
2043
2044 <para>
2045 After you perform your profiling tasks, the next command stops the profiler.
2046 After that, you can view results with the <filename>opreport</filename> command with options
2047 to see the separate library symbols and callgraph information.
2048 </para>
2049
2050 <para>
2051 Callgraphing logs information about time spent in functions and about a function's
2052 calling function (parent) and called functions (children).
2053 The higher the callgraphing depth, the more accurate the results.
2054 However, higher depths also increase the logging overhead.
2055 Consequently, you should take care when setting the callgraphing depth.
2056 <note>
2057 On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
2058 To accomplish this use the <filename>-fno-omit-framepointer</filename> option
2059 with <filename>gcc</filename>.
2060 </note>
2061 </para>
2062
2063 <para>
2064 For more information on using OProfile, see the OProfile
2065 online documentation at
2066 <ulink url="http://oprofile.sourceforge.net/docs/"/>.
2067 </para>
2068 </section>
2069
2070 <section id="platdev-oprofile-oprofileui">
2071 <title>Using OProfileUI</title>
2072
2073 <para>
2074 A graphical user interface for OProfile is also available.
2075 You can download and build this interface from the Yocto Project at
2076 <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
2077 If the "tools-profile" image feature is selected, all necessary binaries
2078 are installed onto the target device for OProfileUI interaction.
2079 </para>
2080
2081 <para>
2082 Even though the Yocto Project usually includes all needed patches on the target device, you
2083 might find you need other OProfile patches for recent OProfileUI features.
2084 If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
2085 OProfileUI README</ulink> for the most recent information.
2086 </para>
2087
2088 <section id="platdev-oprofile-oprofileui-online">
2089 <title>Online Mode</title>
2090
2091 <para>
2092 Using OProfile in online mode assumes a working network connection with the target
2093 hardware.
2094 With this connection, you just need to run "oprofile-server" on the device.
2095 By default, OProfile listens on port 4224.
2096 <note>
2097 You can change the port using the <filename>--port</filename> command-line
2098 option.
2099 </note>
2100 </para>
2101
2102 <para>
2103 The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
2104 straightforward.
2105 You access key functionality through the buttons on the toolbar, which
2106 are duplicated in the menus.
2107 Here are the buttons:
2108 <itemizedlist>
2109 <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
2110 You can also supply the IP address or hostname.</para></listitem>
2111 <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
2112 </para></listitem>
2113 <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
2114 </para></listitem>
2115 <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
2116 downloads the data to the local host.
2117 Stopping the profiler generates the profile and displays it in the viewer.
2118 </para></listitem>
2119 <listitem><para><emphasis>Download:</emphasis> Downloads the data from the
2120 target and generates the profile, which appears in the viewer.</para></listitem>
2121 <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
2122 Resetting the data removes sample information collected from previous
2123 sampling runs.
2124 Be sure you reset the data if you do not want to include old sample information.
2125 </para></listitem>
2126 <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
2127 target to another directory for later examination.</para></listitem>
2128 <listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
2129 </para></listitem>
2130 </itemizedlist>
2131 </para>
2132
2133 <para>
2134 The client downloads the complete 'profile archive' from
2135 the target to the host for processing.
2136 This archive is a directory that contains the sample data, the object files,
2137 and the debug information for the object files.
2138 The archive is then converted using the <filename>oparchconv</filename> script, which is
2139 included in this distribution.
2140 The script uses <filename>opimport</filename> to convert the archive from
2141 the target to something that can be processed on the host.
2142 </para>
2143
2144 <para>
2145 Downloaded archives reside in the Yocto Project's build directory in
2146 <filename>/tmp</filename> and are cleared up when they are no longer in use.
2147 </para>
2148
2149 <para>
2150 If you wish to perform kernel profiling, you need to be sure
2151 a <filename>vmlinux</filename> file that matches the running kernel is available.
2152 In the Yocto Project, that file is usually located in
2153 <filename>/boot/vmlinux-KERNELVERSION</filename>, where
2154 <filename>KERNEL-version</filename> is the version of the kernel.
2155 The Yocto Project generates separate <filename>vmlinux</filename> packages for each kernel
2156 it builds.
2157 Thus, it should just be a question of making sure a matching package is
2158 installed (e.g. <filename>opkg install kernel-vmlinux</filename>.
2159 The files are automatically installed into development and profiling images
2160 alongside OProfile.
2161 A configuration option exists within the OProfileUI settings page that you can use to
2162 enter the location of the <filename>vmlinux</filename> file.
2163 </para>
2164
2165 <para>
2166 Waiting for debug symbols to transfer from the device can be slow, and it
2167 is not always necessary to actually have them on the device for OProfile use.
2168 All that is needed is a copy of the filesystem with the debug symbols present
2169 on the viewer system.
2170 The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launching GDB on the Host Computer</link>"
2171 section covers how to create such a directory with
2172 the Yocto Project and how to use the OProfileUI Settings dialog to specify the location.
2173 If you specify the directory, it will be used when the file checksums
2174 match those on the system you are profiling.
2175 </para>
2176 </section>
2177
2178 <section id="platdev-oprofile-oprofileui-offline">
2179 <title>Offline Mode</title>
2180
2181 <para>
2182 If network access to the target is unavailable, you can generate
2183 an archive for processing in <filename>oprofile-viewer</filename> as follows:
2184 <literallayout class='monospaced'>
2185 # opcontrol --reset
2186 # opcontrol --start --separate=lib --no-vmlinux -c 5
2187 .
2188 .
2189 [do whatever is being profiled]
2190 .
2191 .
2192 # opcontrol --stop
2193 # oparchive -o my_archive
2194 </literallayout>
2195 </para>
2196
2197 <para>
2198 In the above example, <filename>my_archive</filename> is the name of the
2199 archive directory where you would like the profile archive to be kept.
2200 After the directory is created, you can copy it to another host and load it
2201 using <filename>oprofile-viewer</filename> open functionality.
2202 If necessary, the archive is converted.
2203 </para>
2204 </section>
2205 </section>
2206 </section>
1729</chapter> 2207</chapter>
1730 2208
1731<!-- 2209<!--