1 2 /*--------------------------------------------------------------------*/ 3 /*--- Handle remote gdb protocol. pub_tool_gdbserver.h ---*/ 4 /*--------------------------------------------------------------------*/ 5 6 /* 7 This file is part of Valgrind, a dynamic binary instrumentation 8 framework. 9 10 Copyright (C) 2011-2013 Philippe Waroquiers 11 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. 16 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. 21 22 You should have received a copy of the GNU General Public License 23 along with this program; if not, write to the Free Software 24 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 25 02111-1307, USA. 26 27 The GNU General Public License is contained in the file COPYING. 28 */ 29 30 #ifndef __PUB_TOOL_GDBSERVER_H 31 #define __PUB_TOOL_GDBSERVER_H 32 33 #include "pub_tool_basics.h" // VG_ macro 34 #include "libvex.h" 35 #include "libvex_ir.h" 36 37 //-------------------------------------------------------------------- 38 // PURPOSE: This module provides the support to have a gdb 39 // connecting to a valgrind process using remote gdb protocol. It provides 40 // * A function to allow a tool (or the valgrind core) to 41 // wait for a gdb to connect and then handle gdb commands. 42 // Typically, this can be used to let the user debug the process 43 // when valgrind reports an error. 44 // * A function allowing to instrument the code to support gdb breakpoints. 45 // * A function allowing the tool to support watchpoints. 46 // * A utility function to help implementing the processing of the 47 // gdb_monitor_command strings. 48 49 50 // Function to be used by tool or coregrind to allow a gdb to connect 51 // to this process. 52 // Calling VG_(gdbserver) with tid > 0 means to let a debugger attach 53 // to the valgrind process. gdbserver will report to gdb that the 54 // process stopped in thread tid. 55 // Calling VG_(gdbserver) with tid == 0 indicates to close 56 // the connection with GDB (if still open) and stop gdbserver. 57 //-------------------------------------------------------------------- 58 extern void VG_(gdbserver) ( ThreadId tid ); 59 60 /* VG_(dyn_vgdb_error) gets its initial value from 61 VG_(clo_vgdb_error). It can be changed after initial command 62 processing in order to enable/disable the call to VG_(gdbserver) in 63 m_errormgr.c. The main reasons to change the below is either 64 because the user updates it via a monitor command or to 65 (temporarily) avoid calling gdbserver for error reporting during 66 monitor command handling. 67 */ 68 extern Int VG_(dyn_vgdb_error); 69 70 /* defines the various kinds of breakpoints that gdbserver 71 might ask to insert/remove. Note that the below matches 72 the gdbserver protocol definition. The level of support 73 of the various breakpoint kinds depends on the tool. 74 75 For the moment, it is unclear how a tool would implement 76 hardware_breakpoint in valgrind :). 77 78 software_breakpoint implies some (small) specific 79 instrumentation to be done for gdbserver. This instrumentation 80 is implemented for all tools in m_translate.c. 81 82 write/read/access watchpoints can only be done by tools 83 which are maintaining some notion of address accessibility 84 as part of their instrumentation. watchpoints can then 85 be done by marking the watched address(es) as not accessible. 86 But instead of giving back an error (or whatever the tool 87 wants to do with unaccessible mechanism), the tool must then 88 just call gdbserver. See memcheck for an example of reusing 89 accessibility for watchpoint support. 90 */ 91 typedef 92 enum { 93 software_breakpoint, 94 hardware_breakpoint, 95 write_watchpoint, 96 read_watchpoint, 97 access_watchpoint } PointKind; 98 extern const HChar* VG_(ppPointKind) (PointKind kind); 99 100 101 /* watchpoint support --------------------------------------*/ 102 /* True if one or more bytes in [addr, addr+len[ are being watched by 103 gdbserver for write or read or access. 104 In addition, VG_(is_watched) will invoke gdbserver if 105 the access provided by the tool matches the watchpoint kind. 106 For this, the tool must pass the kind of access it has detected: 107 write_watchpoint indicates the tool has detected a write 108 read_watchpoint indicates the tool has detected a read 109 access_watchpoint indicates the tool has detected an access but does 110 not know if this is a read or a write 111 */ 112 extern Bool VG_(is_watched)(PointKind kind, Addr addr, Int szB); 113 114 extern void VG_(needs_watchpoint) ( 115 // indicates the given Addr/len is being watched (insert) 116 // or not watched anymore (! insert). 117 // gdbserver will maintain the list of watched addresses. 118 // The tool can use VG_(is_watched) to verify if an 119 // access to an Addr is in one of the watched intervals. 120 // Must return True if the watchpoint has been properly inserted or 121 // removed. False if not supported. 122 // Note that an address can only be watched for a single kind. 123 // The tool must be ready to be called successively with 124 // multiple kinds for the same addr and len and with 125 // different kinds. The last kind must replace the previous values. 126 // Behaviour with multiple watches having overlapping addr+len 127 // is undefined. 128 Bool (*watchpoint) (PointKind kind, Bool insert, Addr addr, SizeT len) 129 ); 130 131 132 // can be used during the processing of the VG_USERREQ__GDB_MONITOR_COMMAND 133 // tool client request to output information to gdb or vgdb. 134 // The output of VG_(gdb_printf) is not subject to 'output control' 135 // by the user: e.g. the monitor command 'v.set log_output' has no effect. 136 // The output of VG_(gdb_printf) is given to gdb/vgdb. The only case 137 // in which this output is not given to gdb/vgdb is when the connection 138 // with gdb/vgdb has been lost : in such a case, output is written 139 // to the valgrind log output. 140 // To produce some output which is subject to user output control via 141 // monitor command v.set gdb_output or mixed output, use VG_(printf) 142 // or VG_(umsg) or similar. 143 // Typically, VG_(gdb_printf) has to be used when there is no point 144 // having this output in the output log of Valgrind. Examples 145 // is the monitor help output, or if vgdb is used to implement 146 // 'tool control scripts' such as callgrind_control. 147 extern UInt VG_(gdb_printf) ( const HChar *format, ... ) PRINTF_CHECK(1, 2); 148 149 /* Utility functions to (e.g.) parse gdb monitor commands. 150 151 keywords is a set of keywords separated by a space 152 keyword_id will search for the keyword starting with the string input_word 153 and return its position. 154 It returns -1 if no keyword matches. 155 It returns -2 if two or more keywords are starting with input_word 156 and none of these matches exactly input_word 157 Example with keywords = "hello world here is hell" : 158 input_word result 159 ---------- ------ 160 paradise => -1 161 i => 3 162 hell => 4 163 hel => -2 164 ishtar => -1 165 166 report indicates when to output an error msg with VG_(gdb_printf). 167 kwd_report_none : no error is reported. 168 kwd_report_all : the error msg will show all possible keywords 169 kwd_report_duplicated_matches : the error msg will show only the 170 ambiguous matches. 171 */ 172 typedef 173 enum { 174 kwd_report_none, 175 kwd_report_all, 176 kwd_report_duplicated_matches } kwd_report_error; 177 extern Int VG_(keyword_id) (const HChar* keywords, const HChar* input_word, 178 kwd_report_error report); 179 180 /* Extract an address and (optionally) a size from the string 181 currently being parsed by strtok_r (see pub_tool_libcbase.h). 182 If no size in the string, keeps the current value of szB. 183 If parsing is ok, 184 returns True. 185 If parsing is not ok; 186 set *address and *szB to 0, 187 reports problem to the user using VG_(gdb_printf) 188 returns False. */ 189 extern Bool VG_(strtok_get_address_and_size) (Addr* address, 190 SizeT* szB, 191 HChar **ssaveptr); 192 193 /* Print various statistics about Valgrind core, 194 and optionally tool and memory statistics. */ 195 extern void VG_(print_all_stats) (Bool memory_stats, Bool tool_stats); 196 197 #endif // __PUB_TOOL_GDBSERVER_H 198 199 /*--------------------------------------------------------------------*/ 200 /*--- end ---*/ 201 /*--------------------------------------------------------------------*/ 202