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