2 /*--------------------------------------------------------------------*/
3 /*--- Handle remote gdb protocol. pub_tool_gdbserver.h ---*/
4 /*--------------------------------------------------------------------*/
7 This file is part of Valgrind, a dynamic binary instrumentation
10 Copyright (C) 2011-2017 Philippe Waroquiers
12 This program is free software; you can redistribute it and/or
13 modify it under the terms of the GNU General Public License as
14 published by the Free Software Foundation; either version 2 of the
15 License, or (at your option) any later version.
17 This program is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 General Public License for more details.
22 You should have received a copy of the GNU General Public License
23 along with this program; if not, see <http://www.gnu.org/licenses/>.
25 The GNU General Public License is contained in the file COPYING.
28 #ifndef __PUB_TOOL_GDBSERVER_H
29 #define __PUB_TOOL_GDBSERVER_H
31 #include "pub_tool_basics.h" // VG_ macro
33 //--------------------------------------------------------------------
34 // PURPOSE: This module provides the support to have a gdb
35 // connecting to a valgrind process using remote gdb protocol. It provides
36 // * A function to allow a tool (or the valgrind core) to
37 // wait for a gdb to connect and then handle gdb commands.
38 // Typically, this can be used to let the user debug the process
39 // when valgrind reports an error.
40 // * A function allowing to instrument the code to support gdb breakpoints.
41 // * A function allowing the tool to support watchpoints.
42 // * A utility function to help implementing the processing of the
43 // gdb_monitor_command strings.
46 // Function to be used by tool or coregrind to allow a gdb to connect
48 // Calling VG_(gdbserver) with tid > 0 means to let a debugger attach
49 // to the valgrind process. gdbserver will report to gdb that the
50 // process stopped in thread tid.
51 // Calling VG_(gdbserver) with tid == 0 indicates to close
52 // the connection with GDB (if still open) and stop gdbserver.
53 //--------------------------------------------------------------------
54 extern void VG_(gdbserver
) ( ThreadId tid
);
56 /* defines the various kinds of breakpoints that gdbserver
57 might ask to insert/remove. Note that the below matches
58 the gdbserver protocol definition. The level of support
59 of the various breakpoint kinds depends on the tool.
61 For the moment, it is unclear how a tool would implement
62 hardware_breakpoint in valgrind :).
64 software_breakpoint implies some (small) specific
65 instrumentation to be done for gdbserver. This instrumentation
66 is implemented for all tools in m_translate.c.
68 write/read/access watchpoints can only be done by tools
69 which are maintaining some notion of address accessibility
70 as part of their instrumentation. watchpoints can then
71 be done by marking the watched address(es) as not accessible.
72 But instead of giving back an error (or whatever the tool
73 wants to do with unaccessible mechanism), the tool must then
74 just call gdbserver. See memcheck for an example of reusing
75 accessibility for watchpoint support.
83 access_watchpoint
} PointKind
;
84 extern const HChar
* VG_(ppPointKind
) (PointKind kind
);
87 /* watchpoint support --------------------------------------*/
88 /* True if one or more bytes in [addr, addr+len[ are being watched by
89 gdbserver for write or read or access.
90 In addition, VG_(is_watched) will invoke gdbserver if
91 the access provided by the tool matches the watchpoint kind.
92 For this, the tool must pass the kind of access it has detected:
93 write_watchpoint indicates the tool has detected a write
94 read_watchpoint indicates the tool has detected a read
95 access_watchpoint indicates the tool has detected an access but does
96 not know if this is a read or a write
98 extern Bool
VG_(is_watched
)(PointKind kind
, Addr addr
, Int szB
);
100 extern void VG_(needs_watchpoint
) (
101 // indicates the given Addr/len is being watched (insert)
102 // or not watched anymore (! insert).
103 // gdbserver will maintain the list of watched addresses.
104 // The tool can use VG_(is_watched) to verify if an
105 // access to an Addr is in one of the watched intervals.
106 // Must return True if the watchpoint has been properly inserted or
107 // removed. False if not supported.
108 // Note that an address can only be watched for a single kind.
109 // The tool must be ready to be called successively with
110 // multiple kinds for the same addr and len and with
111 // different kinds. The last kind must replace the previous values.
112 // Behaviour with multiple watches having overlapping addr+len
114 Bool (*watchpoint
) (PointKind kind
, Bool insert
, Addr addr
, SizeT len
)
118 // can be used during the processing of the VG_USERREQ__GDB_MONITOR_COMMAND
119 // tool client request to output information to gdb or vgdb.
120 // The output of VG_(gdb_printf) is not subject to 'output control'
121 // by the user: e.g. the monitor command 'v.set log_output' has no effect.
122 // The output of VG_(gdb_printf) is given to gdb/vgdb. The only case
123 // in which this output is not given to gdb/vgdb is when the connection
124 // with gdb/vgdb has been lost : in such a case, output is written
125 // to the valgrind log output.
126 // To produce some output which is subject to user output control via
127 // monitor command v.set gdb_output or mixed output, use VG_(printf)
128 // or VG_(umsg) or similar.
129 // Typically, VG_(gdb_printf) has to be used when there is no point
130 // having this output in the output log of Valgrind. Examples
131 // is the monitor help output, or if vgdb is used to implement
132 // 'tool control scripts' such as callgrind_control.
133 extern UInt
VG_(gdb_printf
) ( const HChar
*format
, ... ) PRINTF_CHECK(1, 2);
135 /* Utility functions to (e.g.) parse gdb monitor commands.
137 keywords is a set of keywords separated by a space
138 keyword_id will search for the keyword starting with the string input_word
139 and return its position.
140 It returns -1 if no keyword matches.
141 It returns -2 if two or more keywords are starting with input_word
142 and none of these matches exactly input_word
143 Example with keywords = "hello world here is hell" :
152 report indicates when to output an error msg with VG_(gdb_printf).
153 kwd_report_none : no error is reported.
154 kwd_report_all : the error msg will show all possible keywords
155 kwd_report_duplicated_matches : the error msg will show only the
162 kwd_report_duplicated_matches
} kwd_report_error
;
163 extern Int
VG_(keyword_id
) (const HChar
* keywords
, const HChar
* input_word
,
164 kwd_report_error report
);
166 /* Extract an address and (optionally) a size from the string
167 currently being parsed by strtok_r (see pub_tool_libcbase.h).
168 If no size in the string, keeps the current value of szB.
171 If parsing is not ok;
172 set *address and *szB to 0,
173 reports problem to the user using VG_(gdb_printf)
175 extern Bool
VG_(strtok_get_address_and_size
) (Addr
* address
,
179 /* Print various statistics about Valgrind core,
180 and optionally tool and memory statistics. */
181 extern void VG_(print_all_stats
) (Bool memory_stats
, Bool tool_stats
);
183 #endif // __PUB_TOOL_GDBSERVER_H
185 /*--------------------------------------------------------------------*/
187 /*--------------------------------------------------------------------*/