gdb/gdbserver/target.h

   1 /* Target operations for the remote server for GDB.
   2    Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009
   3    Free Software Foundation, Inc.
   4
   5    Contributed by MontaVista Software.
   6
   7    This file is part of GDB.
   8
   9    This program is free software; you can redistribute it and/or modify
  10    it under the terms of the GNU General Public License as published by
  11    the Free Software Foundation; either version 3 of the License, or
  12    (at your option) any later version.
  13
  14    This program is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17    GNU General Public License for more details.
  18
  19    You should have received a copy of the GNU General Public License
  20    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  21
  22 #ifndef TARGET_H
  23 #define TARGET_H
  24
  25 /* Ways to "resume" a thread.  */
  26
  27 enum resume_kind
  28 {
  29   /* Thread should continue.  */
  30   resume_continue,
  31
  32   /* Thread should single-step.  */
  33   resume_step,
  34
  35   /* Thread should be stopped.  */
  36   resume_stop
  37 };
  38
  39 /* This structure describes how to resume a particular thread (or all
  40    threads) based on the client's request.  If thread is -1, then this
  41    entry applies to all threads.  These are passed around as an
  42    array.  */
  43
  44 struct thread_resume
  45 {
  46   ptid_t thread;
  47
  48   /* How to "resume".  */
  49   enum resume_kind kind;
  50
  51   /* If non-zero, send this signal when we resume, or to stop the
  52      thread.  If stopping a thread, and this is 0, the target should
  53      stop the thread however it best decides to (e.g., SIGSTOP on
  54      linux; SuspendThread on win32).  */
  55   int sig;
  56 };
  57
  58 /* Generally, what has the program done?  */
  59 enum target_waitkind
  60   {
  61     /* The program has exited.  The exit status is in
  62        value.integer.  */
  63     TARGET_WAITKIND_EXITED,
  64
  65     /* The program has stopped with a signal.  Which signal is in
  66        value.sig.  */
  67     TARGET_WAITKIND_STOPPED,
  68
  69     /* The program has terminated with a signal.  Which signal is in
  70        value.sig.  */
  71     TARGET_WAITKIND_SIGNALLED,
  72
  73     /* The program is letting us know that it dynamically loaded
  74        something.  */
  75     TARGET_WAITKIND_LOADED,
  76
  77     /* The program has exec'ed a new executable file.  The new file's
  78        pathname is pointed to by value.execd_pathname.  */
  79     TARGET_WAITKIND_EXECD,
  80
  81     /* Nothing of interest to GDB happened, but we stopped anyway.  */
  82     TARGET_WAITKIND_SPURIOUS,
  83
  84     /* An event has occurred, but we should wait again.  In this case,
  85        we want to go back to the event loop and wait there for another
  86        event from the inferior.  */
  87     TARGET_WAITKIND_IGNORE
  88   };
  89
  90 struct target_waitstatus
  91   {
  92     enum target_waitkind kind;
  93
  94     /* Forked child pid, execd pathname, exit status or signal number.  */
  95     union
  96       {
  97         int integer;
  98         enum target_signal sig;
  99         ptid_t related_pid;
 100         char *execd_pathname;
 101       }
 102     value;
 103   };
 104
 105 /* Options that can be passed to target_ops->wait.  */
 106
 107 #define TARGET_WNOHANG 1
 108
 109 struct target_ops
 110 {
 111   /* Start a new process.
 112
 113      PROGRAM is a path to the program to execute.
 114      ARGS is a standard NULL-terminated array of arguments,
 115      to be passed to the inferior as ``argv''.
 116
 117      Returns the new PID on success, -1 on failure.  Registers the new
 118      process with the process list.  */
 119
 120   int (*create_inferior) (char *program, char **args);
 121
 122   /* Attach to a running process.
 123
 124      PID is the process ID to attach to, specified by the user
 125      or a higher layer.
 126
 127      Returns -1 if attaching is unsupported, 0 on success, and calls
 128      error() otherwise.  */
 129
 130   int (*attach) (unsigned long pid);
 131
 132   /* Kill inferior PID.  Return -1 on failure, and 0 on success.  */
 133
 134   int (*kill) (int pid);
 135
 136   /* Detach from inferior PID. Return -1 on failure, and 0 on
 137      success.  */
 138
 139   int (*detach) (int pid);
 140
 141   /* Wait for inferior PID to exit.  */
 142   void (*join) (int pid);
 143
 144   /* Return 1 iff the thread with process ID PID is alive.  */
 145
 146   int (*thread_alive) (ptid_t pid);
 147
 148   /* Resume the inferior process.  */
 149
 150   void (*resume) (struct thread_resume *resume_info, size_t n);
 151
 152   /* Wait for the inferior process or thread to change state.  Store
 153      status through argument pointer STATUS.
 154
 155      PTID = -1 to wait for any pid to do something, PTID(pid,0,0) to
 156      wait for any thread of process pid to do something.  Return ptid
 157      of child, or -1 in case of error; store status through argument
 158      pointer STATUS.  OPTIONS is a bit set of options defined as
 159      TARGET_W* above.  If options contains TARGET_WNOHANG and there's
 160      no child stop to report, return is
 161      null_ptid/TARGET_WAITKIND_IGNORE.  */
 162
 163   ptid_t (*wait) (ptid_t ptid, struct target_waitstatus *status, int options);
 164
 165   /* Fetch registers from the inferior process.
 166
 167      If REGNO is -1, fetch all registers; otherwise, fetch at least REGNO.  */
 168
 169   void (*fetch_registers) (int regno);
 170
 171   /* Store registers to the inferior process.
 172
 173      If REGNO is -1, store all registers; otherwise, store at least REGNO.  */
 174
 175   void (*store_registers) (int regno);
 176
 177   /* Read memory from the inferior process.  This should generally be
 178      called through read_inferior_memory, which handles breakpoint shadowing.
 179
 180      Read LEN bytes at MEMADDR into a buffer at MYADDR.
 181
 182      Returns 0 on success and errno on failure.  */
 183
 184   int (*read_memory) (CORE_ADDR memaddr, unsigned char *myaddr, int len);
 185
 186   /* Write memory to the inferior process.  This should generally be
 187      called through write_inferior_memory, which handles breakpoint shadowing.
 188
 189      Write LEN bytes from the buffer at MYADDR to MEMADDR.
 190
 191      Returns 0 on success and errno on failure.  */
 192
 193   int (*write_memory) (CORE_ADDR memaddr, const unsigned char *myaddr,
 194                        int len);
 195
 196   /* Query GDB for the values of any symbols we're interested in.
 197      This function is called whenever we receive a "qSymbols::"
 198      query, which corresponds to every time more symbols (might)
 199      become available.  NULL if we aren't interested in any
 200      symbols.  */
 201
 202   void (*look_up_symbols) (void);
 203
 204   /* Send an interrupt request to the inferior process,
 205      however is appropriate.  */
 206
 207   void (*request_interrupt) (void);
 208
 209   /* Read auxiliary vector data from the inferior process.
 210
 211      Read LEN bytes at OFFSET into a buffer at MYADDR.  */
 212
 213   int (*read_auxv) (CORE_ADDR offset, unsigned char *myaddr,
 214                     unsigned int len);
 215
 216   /* Insert and remove a break or watchpoint.
 217      Returns 0 on success, -1 on failure and 1 on unsupported.
 218      The type is coded as follows:
 219        '0' - software-breakpoint
 220        '1' - hardware-breakpoint
 221        '2' - write watchpoint
 222        '3' - read watchpoint
 223        '4' - access watchpoint  */
 224
 225   int (*insert_point) (char type, CORE_ADDR addr, int len);
 226   int (*remove_point) (char type, CORE_ADDR addr, int len);
 227
 228   /* Returns 1 if target was stopped due to a watchpoint hit, 0 otherwise.  */
 229
 230   int (*stopped_by_watchpoint) (void);
 231
 232   /* Returns the address associated with the watchpoint that hit, if any;
 233      returns 0 otherwise.  */
 234
 235   CORE_ADDR (*stopped_data_address) (void);
 236
 237   /* Reports the text, data offsets of the executable.  This is
 238      needed for uclinux where the executable is relocated during load
 239      time.  */
 240
 241   int (*read_offsets) (CORE_ADDR *text, CORE_ADDR *data);
 242
 243   /* Fetch the address associated with a specific thread local storage
 244      area, determined by the specified THREAD, OFFSET, and LOAD_MODULE.
 245      Stores it in *ADDRESS and returns zero on success; otherwise returns
 246      an error code.  A return value of -1 means this system does not
 247      support the operation.  */
 248
 249   int (*get_tls_address) (struct thread_info *thread, CORE_ADDR offset,
 250                           CORE_ADDR load_module, CORE_ADDR *address);
 251
 252    /* Read/Write from/to spufs using qXfer packets.  */
 253   int (*qxfer_spu) (const char *annex, unsigned char *readbuf,
 254                     unsigned const char *writebuf, CORE_ADDR offset, int len);
 255
 256   /* Fill BUF with an hostio error packet representing the last hostio
 257      error.  */
 258   void (*hostio_last_error) (char *buf);
 259
 260   /* Read/Write OS data using qXfer packets.  */
 261   int (*qxfer_osdata) (const char *annex, unsigned char *readbuf,
 262                        unsigned const char *writebuf, CORE_ADDR offset,
 263                        int len);
 264
 265   /* Read/Write extra signal info.  */
 266   int (*qxfer_siginfo) (const char *annex, unsigned char *readbuf,
 267                         unsigned const char *writebuf,
 268                         CORE_ADDR offset, int len);
 269
 270   int (*supports_non_stop) (void);
 271
 272   /* Enables async target events.  Returns the previous enable
 273      state.  */
 274   int (*async) (int enable);
 275
 276   /* Switch to non-stop (1) or all-stop (0) mode.  Return 0 on
 277      success, -1 otherwise.  */
 278   int (*start_non_stop) (int);
 279
 280   /* Returns true if the target supports multi-process debugging.  */
 281   int (*supports_multi_process) (void);
 282 };
 283
 284 extern struct target_ops *the_target;
 285
 286 void set_target_ops (struct target_ops *);
 287
 288 #define create_inferior(program, args) \
 289   (*the_target->create_inferior) (program, args)
 290
 291 #define myattach(pid) \
 292   (*the_target->attach) (pid)
 293
 294 #define kill_inferior(pid) \
 295   (*the_target->kill) (pid)
 296
 297 #define detach_inferior(pid) \
 298   (*the_target->detach) (pid)
 299
 300 #define mythread_alive(pid) \
 301   (*the_target->thread_alive) (pid)
 302
 303 #define fetch_inferior_registers(regno) \
 304   (*the_target->fetch_registers) (regno)
 305
 306 #define store_inferior_registers(regno) \
 307   (*the_target->store_registers) (regno)
 308
 309 #define join_inferior(pid) \
 310   (*the_target->join) (pid)
 311
 312 #define target_supports_non_stop() \
 313   (the_target->supports_non_stop ? (*the_target->supports_non_stop ) () : 0)
 314
 315 #define target_async(enable) \
 316   (the_target->async ? (*the_target->async) (enable) : 0)
 317
 318 #define target_supports_multi_process() \
 319   (the_target->supports_multi_process ? \
 320    (*the_target->supports_multi_process) () : 0)
 321
 322 /* Start non-stop mode, returns 0 on success, -1 on failure.   */
 323
 324 int start_non_stop (int nonstop);
 325
 326 ptid_t mywait (ptid_t ptid, struct target_waitstatus *ourstatus, int options,
 327                int connected_wait);
 328
 329 int read_inferior_memory (CORE_ADDR memaddr, unsigned char *myaddr, int len);
 330
 331 int write_inferior_memory (CORE_ADDR memaddr, const unsigned char *myaddr,
 332                            int len);
 333
 334 void set_desired_inferior (int id);
 335
 336 const char *target_pid_to_str (ptid_t);
 337
 338 #endif /* TARGET_H */