From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 24009 invoked by alias); 27 May 2010 12:59:33 -0000 Received: (qmail 23708 invoked by uid 22791); 27 May 2010 12:59:14 -0000 X-SWARE-Spam-Status: No, hits=-2.1 required=5.0 tests=AWL,BAYES_00,T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from mail.codesourcery.com (HELO mail.codesourcery.com) (38.113.113.100) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 27 May 2010 12:58:45 +0000 Received: (qmail 26522 invoked from network); 27 May 2010 12:58:35 -0000 Received: from unknown (HELO orlando.localnet) (pedro@127.0.0.2) by mail.codesourcery.com with ESMTPA; 27 May 2010 12:58:35 -0000 From: Pedro Alves To: gdb-patches@sourceware.org Subject: [RFA] Document GDBserver fast tracepoints support in the manual Date: Thu, 27 May 2010 14:50:00 -0000 User-Agent: KMail/1.12.2 (Linux/2.6.31-21-generic; KDE/4.3.2; x86_64; ; ) MIME-Version: 1.0 Content-Type: Text/Plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Message-Id: <201005271358.32190.pedro@codesourcery.com> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2010-05/txt/msg00632.txt.bz2 Hi, These are documentation bits originally posted along with this larger patch: [GDBserver fast tracepoints support] A few minor tweaks in the wording since the previous version, but largely the same. Okay? gdb/ 2010-05-27 Pedro Alves * NEWS: Mention fast tracepoints support. gdb/doc/ 2010-05-27 Pedro Alves * gdb.texinfo (Set Tracepoints): Mention tracepoints support in gdbserver, and add cross reference. (Tracepoints support in gdbserver): New subsection. -- Pedro Alves Index: src/gdb/NEWS =================================================================== --- src.orig/gdb/NEWS 2010-05-27 10:44:15.000000000 +0100 +++ src/gdb/NEWS 2010-05-27 10:58:26.000000000 +0100 @@ -33,8 +33,10 @@ qRelocInsn * New features in the GDB remote stub, GDBserver - - GDBserver now support tracepoints. The feature is currently - supported by the i386-linux and amd64-linux builds. + - GDBserver now support tracepoints (including fast tracepoints). + The feature is currently supported by the i386-linux and + amd64-linux builds. See the "Tracepoints support in gdbserver" + section in the manual for more information. - GDBserver now supports x86_64 Windows 64-bit debugging. Index: src/gdb/doc/gdb.texinfo =================================================================== --- src.orig/gdb/doc/gdb.texinfo 2010-05-27 10:44:15.000000000 +0100 +++ src/gdb/doc/gdb.texinfo 2010-05-27 13:51:10.000000000 +0100 @@ -9440,6 +9440,9 @@ Some targets may support @dfn{fast trace a different way (such as with a jump instead of a trap), that is faster but possibly restricted in where they may be installed. +@code{gdbserver} supports tracepoints on some target systems. See +@ref{Tracepoints support in gdbserver}. + This section describes commands to set tracepoints and associated conditions and actions. @@ -15692,6 +15695,83 @@ of a multi-process mode debug session. @end table +@subsection Tracepoints support in @code{gdbserver} +@cindex tracepoints support in @code{gdbserver} +@anchor{Tracepoints support in gdbserver} + +On some targets, @code{gdbserver} supports tracepoints and fast +tracepoints. + +For fast tracepoints to work, a special library called the +@dfn{in-process agent} (IPA), must be loaded in the inferior process. +This library is built and distributed as an integral part of +@code{gdbserver}. + +There are several ways to load the in-process agent in your program: + +@table @code +@item Specifying it as dependency at link time + +You can link your program dynamically with the in-process agent +library. On most systems, this is accomplished by adding +@code{-linproctrace} to the link command. + +@item Using the system's preloading mechanisms + +You can force loading the in-process agent at startup time by using +your system's support for preloading shared libraries. Many Unixes +support the concept of preloading user defined libraries. In most +cases, you do that by specifying @code{'LD_PRELOAD=libinproctrace.so'} +in the environment. See also the description of @code{gdbserver}'s +@option{--wrapper} command line option. + +@item Using @value{GDBN} to force loading the agent at run time + +On some systems, you can force the inferior to load a shared library, +by calling a dynamic loader function in the inferior that takes care +of dynamically looking up and loading a shared library. On most Unix +systems, the function is @code{dlopen}. You'll use the @code{call} +command for that. For example: + +@smallexample +(@value{GDBP}) call dlopen ("libinproctrace.so", ...) +@end smallexample + +Note that on most Unix systems, for the @code{dlopen} function be +available, the program needs to be linked with @code{-ldl}. +@end table + +On systems that have a userspace dynamic loader, like most Unix +systems, when you connect to @code{gdbserver} using @code{target +remote}, you'll find that the program is stopped at the dynamic +loader's entry point, and no shared library has been loaded in the +program's address space yet, including the in-process agent. In that +case, before being able to use any of the fast tracepoints features, +you need to let the loader run and load the shared libraries. The +most simple way to do that is to run the program to the main +procedure. E.g., if debugging a C or C@t{++} program, start +@code{gdbserver} like so: + +@smallexample +$ gdbserver :9999 myprogram +@end smallexample + +Start GDB and connect to @code{gdbserver} like so, and run to main: + +@smallexample +$ gdb myprogram +(@value{GDBP}) target remote myhost:9999 +0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 +(@value{GDBP}) b main +(@value{GDBP}) continue +@end smallexample + +The in-process tracing agent library should now be loaded into the +process; you can confirm it with the @code{info sharedlibrary} +command, which will list @file{libinproctrace.so} as loaded in the +process. You are now ready to install fast tracepoints and start +tracing. + @node Remote Configuration @section Remote Configuration