Home | History | Annotate | Download | only in coregrind
      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-2012 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_CORE_GDBSERVER_H
     31 #define __PUB_CORE_GDBSERVER_H
     32 
     33 #include "pub_tool_gdbserver.h"
     34 
     35 /* Return the 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 there is some activity from vgdb
     47 // If it returns True, then extern void VG_(gdbserver) can be called
     48 // to handle this incoming vgdb request.
     49 extern Bool VG_(gdbserver_activity) (ThreadId tid);
     50 
     51 
     52 /* Called by low level to insert or remove a break or watch point.
     53    Break or watch point implementation is done using help from the tool.
     54    break point support implies some (small) specific instrumentation
     55    taken in charge for all tools by m_translate.c.
     56 
     57    Write/read/access watchpoint can only be provided by tools which are
     58    tracking addressability and/or accessibility of memory
     59    (so typically memcheck can provide it). Note that memcheck addressability
     60    bits do not differentiate between read and write accessibility.
     61    However, when accessing unaddressable byte, memcheck can differentiate
     62    reads from write, thereby providing read/write or access watchpoints.
     63 
     64    Note that gdbserver assumes that software breakpoint is supported
     65    (as this will be done by re-instrumenting the code).
     66    Note that len is ignored for sofware breakpoints. hardware_breakpoint
     67    are not supported.
     68 
     69    Returns True if the point has properly been inserted or removed
     70    Returns False otherwise. */
     71 Bool VG_(gdbserver_point) (PointKind kind, Bool insert,
     72                            Addr addr, int len);
     73 
     74 /* Entry point invoked by vgdb when it uses ptrace to cause a gdbserver
     75    invocation. A magic value is passed by vgdb in check as a verification
     76    that the call has been properly pushed by vgdb. */
     77 extern void VG_(invoke_gdbserver) ( int check );
     78 
     79 // To be called before delivering a signal.
     80 // Returns True if gdb user asks to pass the signal to the client.
     81 // Note that if the below returns True, the signal might
     82 // still be ignored if this is the action desired by the
     83 // guest program.
     84 extern Bool VG_(gdbserver_report_signal) (Int signo, ThreadId tid);
     85 
     86 /* software_breakpoint, single step and jump support ------------------------*/
     87 /* VG_(instrument_for_gdbserver_if_needed) allows to do "standard and easy"
     88    instrumentation for gdbserver.
     89    VG_(instrument_for_gdbserver_if_needed) does the following:
     90       * checks if gdbserver instrumentation is needed for vge.
     91       * if no gdbserver instrumentation needed,
     92            returns sb_in
     93       * otherwise
     94         It will instrument sb_in to allow gdbserver to properly
     95         handle breakpoints and single_stepping in sb_in.
     96         All the target jumps of sb_in will also be invalidated
     97         if these are not yet instrumented for gdbserver.
     98         This allows to have single_step working, using a lazily
     99         translation of the blocks which are being single stepped
    100         in.
    101 
    102    The typical usage of this function is to call it on the block
    103    instrumented by the tool instrument function i.e. :
    104      return VG_(instrument_for_gdbserver_if_needed) (sb_out,
    105                                                      layout,
    106                                                      vge,
    107                                                      gWordTy,
    108                                                      hWordTy);
    109    where sb_out is the block instrumented by the tool.
    110 
    111    If the block contains a call to a dirty helper that indirectly
    112    calls gdbserver, then this dirty helper can (indirectly) change
    113    the IP. This implies to jump to this IP after the call to
    114    gdbserver. */
    115 extern IRSB* VG_(instrument_for_gdbserver_if_needed)
    116      (IRSB* sb_in,                   /* block to be instrumented */
    117       VexGuestLayout* layout,
    118       VexGuestExtents* vge,
    119       IRType gWordTy, IRType hWordTy);
    120 
    121 /* reason for which gdbserver connection must be finished */
    122 typedef
    123    enum {
    124       orderly_finish,
    125       reset_after_error,
    126       reset_after_fork} FinishReason;
    127 
    128 /* output various gdbserver statistics and status. */
    129 extern void VG_(gdbserver_status_output)(void);
    130 
    131 /* Shared structure between vgdb and the process running
    132    under valgrind.
    133    We define two variants: a 32 bit and a 64 bit.
    134    The valgrind process will use the appropriate size,
    135    according to the architecture.
    136    vgdb will use what the valgrind process is using. */
    137 /* The below takes care that sizes will be 32 or 64 bits,
    138    whatever the architecture. A.o., vgdb.c cannot use directly
    139    the types from pub_core_threadstate.h as we want vgdb.c to
    140    be independent of the arch it is debugging in case of bi-arch
    141    Valgrind (e.g. x86 and amd64). So, the valgrind process must
    142    give all the needed info/offset to vgdb in the below structure. */
    143 
    144 typedef
    145    struct {
    146       // nr of bytes vgdb has written to valgrind
    147       volatile int written_by_vgdb;
    148       // nr of bytes seen by valgrind
    149       volatile int seen_by_valgrind;
    150 
    151       // address at which gdbserver can be invoked
    152       Addr32 invoke_gdbserver;
    153 
    154       // address of VG_(threads) and various sizes
    155       // and offset needed by vgdb.
    156       Addr32 threads;
    157       int sizeof_ThreadState;
    158       int offset_status;
    159       int offset_lwpid;
    160 
    161       // PID of the vgdb that last connected to the Valgrind gdbserver.
    162       // It will be set by vgdb after connecting.
    163       int vgdb_pid;
    164    } VgdbShared32;
    165 
    166 /* Same as VgdbShared32 but for 64 bits arch. */
    167 typedef
    168    struct {
    169       volatile int written_by_vgdb;
    170       volatile int seen_by_valgrind;
    171 
    172       Addr64 invoke_gdbserver;
    173 
    174       Addr64 threads;
    175       int sizeof_ThreadState;
    176       int offset_status;
    177       int offset_lwpid;
    178 
    179       int vgdb_pid;
    180    } VgdbShared64;
    181 
    182 // The below typedef makes the life of valgrind easier.
    183 // vgdb must however work explicitely with the specific 32 or 64 bits version.
    184 
    185 #if VEX_HOST_WORDSIZE == 8
    186 typedef VgdbShared64 VgdbShared;
    187 #elif VEX_HOST_WORDSIZE == 4
    188 typedef VgdbShared32 VgdbShared;
    189 #else
    190 # error "unexpected wordsize"
    191 #endif
    192 
    193 
    194 #endif   // __PUB_CORE_GDBSERVER_H
    195 /*--------------------------------------------------------------------*/
    196 /*--- end                                                          ---*/
    197 /*--------------------------------------------------------------------*/
    198