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