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