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