coregrind/pub_core_gdbserver.h

   1
   2 /*--------------------------------------------------------------------*/
   3 /*--- Handle remote gdb protocol.             pub_core_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, see <http://www.gnu.org/licenses/>.
  24
  25    The GNU General Public License is contained in the file COPYING.
  26 */
  27
  28 #ifndef __PUB_CORE_GDBSERVER_H
  29 #define __PUB_CORE_GDBSERVER_H
  30
  31 #include "pub_tool_gdbserver.h"
  32 #include "pub_core_options.h"
  33 #include "pub_core_threadstate.h"   // VgSchedReturnCode
  34
  35 /* Return the default path prefix for the named pipes (FIFOs) used by vgdb/gdb
  36    to communicate with valgrind */
  37 HChar* VG_(vgdb_prefix_default)(void);
  38
  39 // After a fork or after an exec, call the below to (possibly) terminate
  40 // the previous gdbserver and then activate a new gdbserver
  41 // before any guest code execution, to e.g. allow the user to set
  42 // breakpoints before execution.
  43 // If VG_(clo_vgdb) == No, the below has no effect.
  44 void VG_(gdbserver_prerun_action) (ThreadId tid);
  45
  46 // True if the initialisation of gdbserver was done,
  47 // i.e. VG_(gdbserver_prerun_action) was called.
  48 Bool VG_(gdbserver_init_done) (void);
  49
  50 // True if gdbserver should stop execution for the specified stop at reason
  51 Bool VG_(gdbserver_stop_at) (VgdbStopAt stopat);
  52
  53 // True if there is some activity from vgdb
  54 // If it returns True, then extern void VG_(gdbserver) can be called
  55 // to handle this incoming vgdb request.
  56 extern Bool VG_(gdbserver_activity) (ThreadId tid);
  57
  58 // If connected to GDB, VG_(gdbserver_exit) reports to GDB that the process
  59 // is about to exit.
  60 // gdbserver is then stopped (using VG_(gdbserver) (0))
  61 void VG_(gdbserver_exit) (ThreadId tid, VgSchedReturnCode tids_schedretcode);
  62
  63 /* On systems that defines PR_SET_PTRACER, verify if ptrace_scope is
  64    is permissive enough for vgdb.
  65    Otherwise, call set_ptracer.
  66    This is especially aimed at Ubuntu >= 10.10 which has added
  67    the ptrace_scope context. */
  68 void VG_(set_ptracer)(void);
  69
  70 /* Called by low level to insert or remove a break or watch point.
  71    Break or watch point implementation is done using help from the tool.
  72    break point support implies some (small) specific instrumentation
  73    taken in charge for all tools by m_translate.c.
  74
  75    Write/read/access watchpoint can only be provided by tools which are
  76    tracking addressability and/or accessibility of memory
  77    (so typically memcheck can provide it). Note that memcheck addressability
  78    bits do not differentiate between read and write accessibility.
  79    However, when accessing unaddressable byte, memcheck can differentiate
  80    reads from write, thereby providing read/write or access watchpoints.
  81
  82    Note that gdbserver assumes that software breakpoint is supported
  83    (as this will be done by re-instrumenting the code).
  84    Note that len is ignored for software breakpoints. hardware_breakpoint
  85    are not supported.
  86
  87    Returns True if the point has properly been inserted or removed
  88    Returns False otherwise. */
  89 Bool VG_(gdbserver_point) (PointKind kind, Bool insert,
  90                            Addr addr, int len);
  91
  92 /* True if there is a breakpoint at addr. */
  93 Bool VG_(has_gdbserver_breakpoint) (Addr addr);
  94
  95 /* Entry point invoked by vgdb when it uses ptrace to cause a gdbserver
  96    invocation. A magic value is passed by vgdb in check as a verification
  97    that the call has been properly pushed by vgdb. */
  98 extern void VG_(invoke_gdbserver) ( int check );
  99
 100 // To be called by core (m_signals.c) before delivering a signal.
 101 // Returns False if gdb user asks to not pass the signal to the client.
 102 // Returns True if signal must be passed to the client, either because
 103 // no gdb is connected, or gdb instructs to pass the signal.
 104 // Note that if the below returns True, the signal might
 105 // still be ignored if this is the action desired by the
 106 // guest program. Using GDB, the user can also modify the signal to be
 107 // reported (e.g. changing the signo to pass to the guest).
 108 // If this function returns True, m_signals.c should deliver the signal
 109 // info as modified by VG_(gdbserver_report_signal).
 110 // If this function returns False, no signal should be reported.
 111 extern Bool VG_(gdbserver_report_signal) (vki_siginfo_t *info, ThreadId tid);
 112
 113 // If no gdb is connected yet, wait for a gdb to connect and report
 114 // this (supposedly) fatal signal.
 115 // If a gdb is already connected, this does nothing (as normally
 116 // the signal was already reported to the already connected gdb).
 117 extern void VG_(gdbserver_report_fatal_signal) (const vki_siginfo_t *info,
 118                                                 ThreadId tid);
 119
 120 // To be called by core before and after a client syscall.
 121 // If GDB has asked to observe the syscall, control will be given to GDB.
 122 // When Before is True, it is a report before the syscall,
 123 // False means a report after the syscall.
 124 extern void VG_(gdbserver_report_syscall) (Bool before, UWord sysno,
 125                                            ThreadId tid);
 126
 127 /* Entry point invoked by scheduler.c to execute the request
 128    VALGRIND_CLIENT_MONITOR_COMMAND.
 129    Returns True if command was not recognised. */
 130 extern Bool VG_(client_monitor_command) (HChar* cmd);
 131
 132 /* software_breakpoint, single step and jump support ------------------------*/
 133 /* VG_(instrument_for_gdbserver_if_needed) allows to do "standard and easy"
 134    instrumentation for gdbserver.
 135    VG_(instrument_for_gdbserver_if_needed) does the following:
 136       * checks if gdbserver instrumentation is needed for vge.
 137       * if no gdbserver instrumentation needed,
 138            returns sb_in
 139       * otherwise
 140         It will instrument sb_in to allow gdbserver to properly
 141         handle breakpoints and single_stepping in sb_in.
 142         All the target jumps of sb_in will also be invalidated
 143         if these are not yet instrumented for gdbserver.
 144         This allows to have single_step working, using a lazily
 145         translation of the blocks which are being single stepped
 146         in.
 147
 148    The typical usage of this function is to call it on the block
 149    instrumented by the tool instrument function i.e. :
 150      return VG_(instrument_for_gdbserver_if_needed) (sb_out,
 151                                                      layout,
 152                                                      vge,
 153                                                      gWordTy,
 154                                                      hWordTy);
 155    where sb_out is the block instrumented by the tool.
 156
 157    If the block contains a call to a dirty helper that indirectly
 158    calls gdbserver, then this dirty helper can (indirectly) change
 159    the IP. This implies to jump to this IP after the call to
 160    gdbserver. */
 161 extern IRSB* VG_(instrument_for_gdbserver_if_needed)
 162      (IRSB* sb_in,                   /* block to be instrumented */
 163       const VexGuestLayout* layout,
 164       const VexGuestExtents* vge,
 165       IRType gWordTy, IRType hWordTy);
 166
 167 /* reason for which gdbserver connection must be finished */
 168 typedef
 169    enum {
 170       orderly_finish,
 171       reset_after_error,
 172       reset_after_fork} FinishReason;
 173
 174 /* output various gdbserver statistics and status. */
 175 extern void VG_(gdbserver_status_output)(void);
 176
 177 /* Shared structure between vgdb and the process running
 178    under valgrind.
 179    We define two variants: a 32 bit and a 64 bit.
 180    The valgrind process will use the appropriate size,
 181    according to the architecture.
 182    vgdb will use what the valgrind process is using. */
 183 /* The below takes care that sizes will be 32 or 64 bits,
 184    whatever the architecture. A.o., vgdb.c cannot use directly
 185    the types from pub_core_threadstate.h as we want vgdb.c to
 186    be independent of the arch it is debugging in case of bi-arch
 187    Valgrind (e.g. x86 and amd64). So, the valgrind process must
 188    give all the needed info/offset to vgdb in the below structure. */
 189
 190 typedef
 191    struct {
 192       // nr of bytes vgdb has written to valgrind
 193       volatile int written_by_vgdb;
 194       // nr of bytes seen by valgrind
 195       volatile int seen_by_valgrind;
 196
 197       // address at which gdbserver can be invoked
 198       Addr32 invoke_gdbserver;
 199
 200       // address of VG_(threads) and various sizes
 201       // and offset needed by vgdb.
 202       Addr32 threads;
 203       int vg_n_threads;
 204       int sizeof_ThreadState;
 205       int offset_status;
 206       int offset_lwpid;
 207
 208       // PID of the vgdb that last connected to the Valgrind gdbserver.
 209       // It will be set by vgdb after connecting.
 210       int vgdb_pid;
 211    } VgdbShared32;
 212
 213 /* Same as VgdbShared32 but for 64 bits arch. */
 214 typedef
 215    struct {
 216       volatile int written_by_vgdb;
 217       volatile int seen_by_valgrind;
 218
 219       Addr64 invoke_gdbserver;
 220
 221       Addr64 threads;
 222       int vg_n_threads;
 223       int sizeof_ThreadState;
 224       int offset_status;
 225       int offset_lwpid;
 226
 227       int vgdb_pid;
 228    } VgdbShared64;
 229
 230 // The below typedef makes the life of valgrind easier.
 231 // vgdb must however work explicitly with the specific 32 or 64 bits version.
 232
 233 #if VEX_HOST_WORDSIZE == 8
 234 typedef VgdbShared64 VgdbShared;
 235 #elif VEX_HOST_WORDSIZE == 4
 236 typedef VgdbShared32 VgdbShared;
 237 #else
 238 # error "unexpected wordsize"
 239 #endif
 240
 241
 242 #endif   // __PUB_CORE_GDBSERVER_H
 243 /*--------------------------------------------------------------------*/
 244 /*--- end                                                          ---*/
 245 /*--------------------------------------------------------------------*/