From 0fb4aa4bfcc2aa61c27132f94cf1656dca137dc9 Mon Sep 17 00:00:00 2001 From: Pedro Alves Date: Thu, 1 Jul 2010 10:36:12 +0000 Subject: Static tracepoints support, and UST integration. gdb/gdbserver/ * configure.ac: Handle --with-ust. substitute ustlibs and ustinc. * mem-break.c (uninsert_all_breakpoints) (reinsert_all_breakpoints): New. * mem-break.h (reinsert_all_breakpoints, uninsert_all_breakpoints): * tracepoint.c (ust_loaded, helper_thread_id, cmd_buf): New. (gdb_agent_ust_loaded, helper_thread_id) (gdb_agent_helper_thread_id): New macros. (struct ipa_sym_addresses): Add addr_ust_loaded, addr_helper_thread_id, addr_cmd_buf. (symbol_list): Add ust_loaded, helper_thread_id, cmd_buf. (in_process_agent_loaded_ust): New. (write_e_ust_not_loaded): New. (maybe_write_ipa_ust_not_loaded): New. (struct collect_static_trace_data_action): New. (enum tracepoint_type) : New. (struct tracepoint) : Mention static tracepoints. (struct static_tracepoint_ctx): New. (CMD_BUF_SIZE): New. (add_tracepoint_action): Handle static tracepoint actions. (unprobe_marker_at): New. (clear_installed_tracepoints): Handle static tracepoints. (cmd_qtdp): Handle static tracepoints. (probe_marker_at): New. (cmd_qtstart): Handle static tracepoints. (response_tracepoint): Handle static tracepoints. (cmd_qtfstm, cmd_qtsstm, cmd_qtstmat): New. (handle_tracepoint_query): Handle qTfSTM, qTsSTM and qTSTMat. (get_context_regcache): Handle static tracepoints. (do_action_at_tracepoint): Handle static tracepoint actions. (traceframe_find_block_type): Handle static trace data blocks. (traceframe_read_sdata): New. (download_tracepoints): Download static tracepoint actions. [HAVE_UST] Include ust/ust.h, dlfcn.h, sys/socket.h, and sys/un.h. (GDB_PROBE_NAME): New. (ust_ops): New. (GET_UST_SYM): New. (USTF): New. (dlsym_ust): New. (ust_marker_to_static_tracepoint): New. (gdb_probe): New. (collect_ust_data_at_tracepoint): New. (gdb_ust_probe): New. (UNIX_PATH_MAX, SOCK_DIR): New. (gdb_ust_connect_sync_socket): New. (resume_thread, stop_thread): New. (run_inferior_command): New. (init_named_socket): New. (gdb_ust_socket_init): New. (cstr_to_hexstr): New. (next_st): New. (first_marker, next_marker): New. (response_ust_marker): New. (cmd_qtfstm, cmd_qtsstm): New. (unprobe_marker_at, probe_marker_at): New. (cmd_qtstmat, gdb_ust_thread): New. (gdb_ust_init): New. (initialize_tracepoint_ftlib): Call gdb_ust_init. * linux-amd64-ipa.c [HAVE_UST]: Include ust/processor.h (ST_REGENTRY): New. (x86_64_st_collect_regmap): New. (X86_64_NUM_ST_COLLECT_GREGS): New. (AMD64_RIP_REGNUM): New. (supply_static_tracepoint_registers): New. * linux-i386-ipa.c [HAVE_UST]: Include ust/processor.h (ST_REGENTRY): New. (i386_st_collect_regmap): New. (i386_NUM_ST_COLLECT_GREGS): New. (supply_static_tracepoint_registers): New. * server.c (handle_query): Handle qXfer:statictrace:read. : Report support for StaticTracepoints, and qXfer:statictrace:read features. * server.h (traceframe_read_sdata) (supply_static_tracepoint_registers): Declare. * remote-utils.c (convert_int_to_ascii, hexchars, ishex, tohex) (unpack_varlen_hex): Include in IPA build. * Makefile.in (ustlibs, ustinc): New. (IPA_OBJS): Add remote-utils-ipa.o. ($(IPA_LIB)): Link -ldl and -lpthread. (UST_CFLAGS): New. (IPAGENT_CFLAGS): Add UST_CFLAGS. * config.in, configure: Regenerate. gdb/ * NEWS: Mention new support for static tracepoints. (New packets): Mention qTfSTM, qTsSTM, qTSTMat and qXfer:statictrace:read. (New features in the GDB remote stub, GDBserver): Mention static tracepoints support using an UST based backend. (New commands): Mention "info static-tracepoint-markers" and "strace". * breakpoint.c (is_marker_spec): New. (is_tracepoint): Handle static tracepoints. (validate_commands_for_breakpoint): Static tracepoints can't do while-stepping. (static_tracepoints_here): New. (bpstat_what): Handle static tracepoints. (print_one_breakpoint_location, allocate_bp_location, mention): Ditto. (create_breakpoint_sal): Ditto. (decode_static_tracepoint_spec): New. (create_breakpoint): Replace `hardwareflag', and `traceflag' with `type_wanted'. Adjust. Handle static tracepoint marker locations. (break_command_1): Adjust. (update_static_tracepoint): New. (update_breakpoint_locations): Handle static tracepoints. (breakpoint_re_set_one): Handle static tracepoint marker locations. (disable_command, enable_command): Handle static tracepoints. (trace_command, ftrace_command): Adjust. (strace_command): New. (create_tracepoint_from_upload): Adjust. (save_breakpoints): Handle static tracepoints. (_initialize_breakpoint): Install the "strace" command. * breakpoint.h (enum bptype): New bp_static_tracepoint type. (struct breakpoint): New fields static_trace_marker_id and static_trace_marker_id_idx. (breakpoints_here_p): Declare. (create_breakpoint): Adjust. (static_tracepoints_here): Declare. * remote.c (struct remote_state) : New field. (PACKET_qXfer_statictrace_read, PACKET_StaticTracepoints): New. (remote_static_tracepoint_marker_at): New. (remote_static_tracepoint_markers_by_strid): New. (remote_static_tracepoint_feature): New. (remote_disconnected_tracing_feature): Handle "StaticTracepoints". (remote_xfer_partial): Handle TARGET_OBJECT_STATIC_TRACE_DATA. (remote_supports_static_tracepoints): New. (remote_download_tracepoint): Download static tracepoints. (init_remote_ops): Install remote_static_tracepoint_marker_at and remote_static_tracepoint_markers_by_strid. (_initialize_remote): Install set|show remote static-tracepoints, and set|show remote read-sdata-object commands. * target.c (update_current_target): Inherit and default to_static_tracepoint_marker_at, and to_static_tracepoint_markers_by_strid. * target.h (static_tracepoint_marker): Forward declare. (enum target_object): New object TARGET_OBJECT_STATIC_TRACE_DATA. (static_tracepoint_marker_p): New typedef. (DEF_VEC_P(static_tracepoint_marker_p)): New VEC type. (struct target_ops): New fields to_static_tracepoint_marker_at and to_static_tracepoint_markers_by_strid. (target_static_tracepoint_marker_at) (target_static_tracepoint_markers_by_strid): New. * tracepoint.c: Include source.h. (validate_actionline): Handle $_sdata. (struct collection_list): New field strace_data. (add_static_trace_data): New. (clear_collection_list): Clear strace_data. (stringify_collection_list): Account for a possible static trace data collection. (encode_actions_1): Encode an $_sdata collection. (parse_tracepoint_definition): Handle static tracepoints. (parse_static_tracepoint_marker_definition): New. (release_static_tracepoint_marker): New. (print_one_static_tracepoint_marker): New. (info_static_tracepoint_markers_command): New. (sdata_make_value): New. (_initialize_tracepoint): Create the $_sdata convenience variable. Add the "info static-tracepoint-markers" command. Mention $_sdata in the "collect" command's help output. * tracepoint.h (struct static_tracepoint_marker): New. (parse_static_tracepoint_marker_definition) (release_static_tracepoint_marker): Declare. * mi/mi-cmd-break.c (mi_cmd_break_insert): Adjust. * python/py-breakpoint.c (bppy_new): Adjust. doc/ * gdb.texinfo (Convenience Variables): Document $_sdata. (Commands to Set Tracepoints): Describe static tracepoints. Add `Listing Static Tracepoint Markers' menu entry. Document "strace". (Tracepoint Action Lists): Document collecting $_sdata. (Listing Static Tracepoint Markers): New subsection. (Tracepoints support in gdbserver): Mention static tracepoints. (remote packets, enabling and disabling): Mention read-sdata-object. (General Query Packets) : Document qXfer:sdata:read and StaticTracepoint. Mention qTfSTM, qTsSTM and qTSTMat as tracepoint packets. Document qXfer:sdata:read. (Tracepoint packets): Document qTfSTM, qTsSTM and qTSTMat. --- gdb/doc/ChangeLog | 17 ++++ gdb/doc/gdb.texinfo | 265 +++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 270 insertions(+), 12 deletions(-) (limited to 'gdb/doc') diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 700ccfb..c51d005 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,20 @@ +2010-07-01 Pedro Alves + + * gdb.texinfo (Convenience Variables): Document $_sdata. + (Commands to Set Tracepoints): Describe static tracepoints. Add + `Listing Static Tracepoint Markers' menu entry. Document + "strace". + (Tracepoint Action Lists): Document collecting $_sdata. + (Listing Static Tracepoint Markers): New subsection. + (Tracepoints support in gdbserver): Mention static tracepoints. + (remote packets, enabling and disabling): Mention + read-sdata-object. + (General Query Packets) : Document qXfer:sdata:read + and StaticTracepoint. + Mention qTfSTM, qTsSTM and qTSTMat as tracepoint packets. + Document qXfer:sdata:read. + (Tracepoint packets): Document qTfSTM, qTsSTM and qTSTMat. + 2010-06-29 Joel Brobecker * gdb.texinfo (Threads In Python): Fix unmatched @end table. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 14b0092..7caad18 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -8279,6 +8279,13 @@ to match the format in which the data was printed. The variable @code{$_exitcode} is automatically set to the exit code when the program being debugged terminates. +@item $_sdata +@vindex $_sdata@r{, inspect, convenience variable} +The variable @code{$_sdata} contains extra collected static tracepoint +data. @xref{Tracepoint Actions,,Tracepoint Action Lists}. Note that +@code{$_sdata} could be empty, if not inspecting a trace buffer, or +if extra static tracepoint data has not been collected. + @item $_siginfo @vindex $_siginfo@r{, convenience variable} The variable @code{$_siginfo} contains extra signal information @@ -9590,6 +9597,27 @@ Some targets may support @dfn{fast tracepoints}, which are inserted in a different way (such as with a jump instead of a trap), that is faster but possibly restricted in where they may be installed. +@cindex static tracepoints +@cindex markers, static tracepoints +@cindex probing markers, static tracepoints +Regular and fast tracepoints are dynamic tracing facilities, meaning +that they can be used to insert tracepoints at (almost) any location +in the target. Some targets may also support controlling @dfn{static +tracepoints} from @value{GDBN}. With static tracing, a set of +instrumentation points, also known as @dfn{markers}, are embedded in +the target program, and can be activated or deactivated by name or +address. These are usually placed at locations which facilitate +investigating what the target is actually doing. @value{GDBN}'s +support for static tracing includes being able to list instrumentation +points, and attach them with @value{GDBN} defined high level +tracepoints that expose the whole range of convenience of +@value{GDBN}'s tracepoints support. Namelly, support for collecting +registers values and values of global or local (to the instrumentation +point) variables; tracepoint conditions and trace state variables. +The act of installing a @value{GDBN} static tracepoint on an +instrumentation point, or marker, is referred to as @dfn{probing} a +static tracepoint marker. + @code{gdbserver} supports tracepoints on some target systems. @xref{Server,,Tracepoints support in @code{gdbserver}}. @@ -9604,6 +9632,7 @@ conditions and actions. * Trace State Variables:: * Tracepoint Actions:: * Listing Tracepoints:: +* Listing Static Tracepoint Markers:: * Starting and Stopping Trace Experiments:: * Tracepoint Restrictions:: @end menu @@ -9663,6 +9692,65 @@ message. @value{GDBN} handles arguments to @code{ftrace} exactly as for @code{trace}. +@item strace @var{location} [ if @var{cond} ] +@cindex static tracepoint, setting +@kindex strace +The @code{strace} command sets a static tracepoint. For targets that +support it, setting a static tracepoint probes a static +instrumentation point, or marker, found at @var{location}. It may not +be possible to set a static tracepoint at the desired location, in +which case the command will exit with an explanatory message. + +@value{GDBN} handles arguments to @code{strace} exactly as for +@code{trace}, with the addition that the user can also specify +@code{-m @var{marker}} as @var{location}. This probes the marker +identified by the @var{marker} string identifier. This identifier +depends on the static tracepoint backend library your program is +using. You can find all the marker identifiers in the @samp{ID} field +of the @code{info static-tracepoint-markers} command output. +@xref{Listing Static Tracepoint Markers,,Listing Static Tracepoint +Markers}. For example, in the following small program using the UST +tracing engine: + +@smallexample +main () +@{ + trace_mark(ust, bar33, "str %s", "FOOBAZ"); +@} +@end smallexample + +@noindent +the marker id is composed of joining the first two arguments to the +@code{trace_mark} call with a slash, which translates to: + +@smallexample +(@value{GDBP}) info static-tracepoint-markers +Cnt Enb ID Address What +1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 + Data: "str %s" +[etc...] +@end smallexample + +@noindent +so you may probe the marker above with: + +@smallexample +(@value{GDBP}) strace -m ust/bar33 +@end smallexample + +Static tracepoints accept an extra collect action --- @code{collect +$_sdata}. This collects arbitrary user data passed in the probe point +call to the tracing library. In the UST example above, you'll see +that the third argument to @code{trace_mark} is a printf-like format +string. The user data is then the result of running that formating +string against the following arguments. Note that @code{info +static-tracepoint-markers} command output lists that format string in +the @samp{Data:} field. + +You can inspect this data when analyzing the trace buffer, by printing +the $_sdata variable like any other variable available to +@value{GDBN}. @xref{Tracepoint Actions,,Tracepoint Action Lists}. + @vindex $tpnum @cindex last tracepoint number @cindex recent tracepoint number @@ -9899,13 +9987,34 @@ special arguments are supported: @table @code @item $regs -collect all registers +Collect all registers. @item $args -collect all function arguments +Collect all function arguments. @item $locals -collect all local variables. +Collect all local variables. + +@item $_sdata +@vindex $_sdata@r{, collect} +Collect static tracepoint marker specific data. Only available for +static tracepoints. @xref{Tracepoint Actions,,Tracepoint Action +Lists}. On the UST static tracepoints library backend, an +instrumentation point resembles a @code{printf} function call. The +tracing library is able to collect user specified data formatted to a +character string using the format provided by the programmer that +instrumented the program. Other backends have similar mechanisms. +Here's an example of a UST marker call: + +@smallexample + const char master_name[] = "$your_name"; + trace_mark(channel1, marker1, "hello %s", master_name) +@end smallexample + +In this case, collecting @code{$_sdata} collects the string +@samp{hello $yourname}. When analyzing the trace buffer, you can +inspect @samp{$_sdata} like any other variable available to +@value{GDBN}. @end table You can give several consecutive @code{collect} commands, each one @@ -10000,6 +10109,60 @@ Num Type Disp Enb Address What This command can be abbreviated @code{info tp}. @end table +@node Listing Static Tracepoint Markers +@subsection Listing Static Tracepoint Markers + +@table @code +@kindex info static-tracepoint-markers +@cindex information about static tracepoint markers +@item info static-tracepoint-markers +Display information about all static tracepoint markers defined in the +program. + +For each marker, the following columns are printed: + +@table @emph +@item Count +An incrementing counter, output to help readability. This is not a +stable identifier. +@item ID +The marker ID, as reported by the target. +@item Enabled or Disabled +Probed markers are tagged with @samp{y}. @samp{n} identifies marks +that are not enabled. +@item Address +Where the marker is in your program, as a memory address. +@item What +Where the marker is in the source for your program, as a file and line +number. If the debug information included in the program does not +allow @value{GDBN} to locate the source of the marker, this column +will be left blank. +@end table + +@noindent +In addition, the following information may be printed for each marker: + +@table @emph +@item Data +User data passed to the tracing library by the marker call. In the +UST backend, this is the format string passed as argument to the +marker call. +@item Static tracepoints probing the marker +The list of static tracepoints attached to the marker. +@end table + +@smallexample +(@value{GDBP}) info static-tracepoint-markers +Cnt ID Enb Address What +1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25 + Data: number1 %d number2 %d + Probed by static tracepoints: #2 +2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24 + Data: str %s +(@value{GDBP}) +@end smallexample +@end table + @node Starting and Stopping Trace Experiments @subsection Starting and Stopping Trace Experiments @@ -15848,13 +16011,21 @@ of a multi-process mode debug session. @subsection Tracepoints support in @code{gdbserver} @cindex tracepoints support in @code{gdbserver} -On some targets, @code{gdbserver} supports tracepoints and fast -tracepoints. +On some targets, @code{gdbserver} supports tracepoints, fast +tracepoints and static tracepoints. -For fast tracepoints to work, a special library called the +For fast or static 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}. +@code{gdbserver}. In addition, support for static tracepoints +requires building the in-process agent library with static tracepoints +support. At present, the UST (LTTng Userspace Tracer, +@url{http://lttng.org/ust}) tracing engine is supported. This support +is automatically available if UST development headers are found in the +standard include path when @code{gdbserver} is built, or if +@code{gdbserver} was explicitly configured using @option{--with-ust} +to point at such headers. You can explicitly disable the support +using @option{--with-ust=no}. There are several ways to load the in-process agent in your program: @@ -15895,10 +16066,10 @@ 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 +case, before being able to use any of the fast or static tracepoints +features, you need to let the loader run and load the shared +libraries. The simplest 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 @@ -15918,7 +16089,8 @@ $ gdb myprogram 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 +process. You are now ready to install fast tracepoints, list static +tracepoint markers, probe static tracepoints markers, and start tracing. @node Remote Configuration @@ -16170,6 +16342,10 @@ are: @tab @code{qXfer:memory-map:read} @tab @code{info mem} +@item @code{read-sdata-object} +@tab @code{qXfer:sdata:read} +@tab @code{print $_sdata} + @item @code{read-spu-object} @tab @code{qXfer:spu:read} @tab @code{info spu} @@ -31958,6 +32134,11 @@ These are the currently defined stub features and their properties: @tab @samp{-} @tab Yes +@item @samp{qXfer:sdata:read} +@tab No +@tab @samp{-} +@tab Yes + @item @samp{qXfer:spu:read} @tab No @tab @samp{-} @@ -32061,6 +32242,10 @@ The remote stub understands the @samp{qXfer:libraries:read} packet The remote stub understands the @samp{qXfer:memory-map:read} packet (@pxref{qXfer memory map read}). +@item qXfer:sdata:read +The remote stub understands the @samp{qXfer:sdata:read} packet +(@pxref{qXfer sdata read}). + @item qXfer:spu:read The remote stub understands the @samp{qXfer:spu:read} packet (@pxref{qXfer spu read}). @@ -32129,6 +32314,10 @@ the source form of tracepoint definitions. @item QAllow The remote stub understands the @samp{QAllow} packet. +@item StaticTracepoint +@cindex static tracepoints, in remote protocol +The remote stub supports static tracepoints. + @end table @item qSymbol:: @@ -32213,6 +32402,9 @@ packets.) @itemx QTro @itemx qTStatus @itemx qTV +@itemx qTfSTM +@itemx qTsSTM +@itemx qTSTMat @xref{Tracepoint Packets}. @item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length} @@ -32269,6 +32461,18 @@ annex part of the generic @samp{qXfer} packet must be empty This packet is not probed by default; the remote stub must request it, by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). +@item qXfer:sdata:read::@var{offset},@var{length} +@anchor{qXfer sdata read} + +Read contents of the extra collected static tracepoint marker +information. The annex part of the generic @samp{qXfer} packet must +be empty (@pxref{qXfer read}). @xref{Tracepoint Actions,,Tracepoint +Action Lists}. + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response +(@pxref{qSupported}). + @item qXfer:siginfo:read::@var{offset},@var{length} @anchor{qXfer siginfo read} Read contents of the extra signal information on the target @@ -32808,6 +33012,43 @@ and multiple @code{qTsV} to get additional variables. Replies to these packets follow the syntax of the @code{QTDV} packets that define trace state variables. +@item qTfSTM +@itemx qTsSTM +These packets request data about static tracepoint markers that exist +in the target program. @value{GDBN} sends @code{qTfSTM} to get the +first piece of data, and multiple @code{qTsSTM} to get additional +pieces. Replies to these packets take the following form: + +Reply: +@table @samp +@item m @var{address}:@var{id}:@var{extra} +A single marker +@item m @var{address}:@var{id}:@var{extra},@var{address}:@var{id}:@var{extra}@dots{} +a comma-separated list of markers +@item l +(lower case letter @samp{L}) denotes end of list. +@item E @var{nn} +An error occurred. @var{nn} are hex digits. +@item +An empty reply indicates that the request is not supported by the +stub. +@end table + +@var{address} is encoded in hex. +@var{id} and @var{extra} are strings encoded in hex. + +In response to each query, the target will reply with a list of one or +more markers, separated by commas. @value{GDBN} will respond to each +reply with a request for more markers (using the @samp{qs} form of the +query), until the target responds with @samp{l} (lower-case ell, for +@dfn{last}). + +@item qTSTMat:@var{address} +This packets requests data about static tracepoint markers in the +target program at @var{address}. Replies to this packet follow the +syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static +tracepoint markers. + @item QTSave:@var{filename} This packet directs the target to save trace data to the file name @var{filename} in the target's filesystem. @var{filename} is encoded -- cgit v1.1