include/pub_tool_gdbserver.h

   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-2017 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
  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.
  53 // Calling VG_(gdbserver) with tid == 0 indicates to close
  54 // the connection with GDB (if still open) and stop gdbserver.
  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;
  96 extern const HChar* VG_(ppPointKind) (PointKind kind);
  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.
 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.
 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;
 175 extern Int VG_(keyword_id) (const HChar* keywords, const HChar* input_word,
 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.
 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,
 188                                               SizeT* szB,
 189                                               HChar **ssaveptr);
 190
 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
 195 #endif   // __PUB_TOOL_GDBSERVER_H
 196
 197 /*--------------------------------------------------------------------*/
 198 /*--- end                                                          ---*/
 199 /*--------------------------------------------------------------------*/