[RFA] Document GDBserver fast tracepoints support in the manual

[Pedro Alves <pedro at codesourcery dot com>]

Hi,

These are documentation bits originally posted along with this
larger patch:

 [GDBserver fast tracepoints support]
 <http://sourceware.org/ml/gdb-patches/2010-05/msg00149.html>

A few minor tweaks in the wording since the previous version,
but largely the same.

Okay?

gdb/
2010-05-27  Pedro Alves  <pedro@codesourcery.com>

	* NEWS: Mention fast tracepoints support.

gdb/doc/
2010-05-27  Pedro Alves  <pedro@codesourcery.com>

	* 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