gdb/gdbserver/target.h

   1 /* Target operations for the remote server for GDB.
   2    Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009, 2010
   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   /* The inferior process has died.  Do what is right.  */
 142
 143   void (*mourn) (struct process_info *proc);
 144
 145   /* Wait for inferior PID to exit.  */
 146   void (*join) (int pid);
 147
 148   /* Return 1 iff the thread with process ID PID is alive.  */
 149
 150   int (*thread_alive) (ptid_t pid);
 151
 152   /* Resume the inferior process.  */
 153
 154   void (*resume) (struct thread_resume *resume_info, size_t n);
 155
 156   /* Wait for the inferior process or thread to change state.  Store
 157      status through argument pointer STATUS.
 158
 159      PTID = -1 to wait for any pid to do something, PTID(pid,0,0) to
 160      wait for any thread of process pid to do something.  Return ptid
 161      of child, or -1 in case of error; store status through argument
 162      pointer STATUS.  OPTIONS is a bit set of options defined as
 163      TARGET_W* above.  If options contains TARGET_WNOHANG and there's
 164      no child stop to report, return is
 165      null_ptid/TARGET_WAITKIND_IGNORE.  */
 166
 167   ptid_t (*wait) (ptid_t ptid, struct target_waitstatus *status, int options);
 168
 169   /* Fetch registers from the inferior process.
 170
 171      If REGNO is -1, fetch all registers; otherwise, fetch at least REGNO.  */
 172
 173   void (*fetch_registers) (struct regcache *regcache, int regno);
 174
 175   /* Store registers to the inferior process.
 176
 177      If REGNO is -1, store all registers; otherwise, store at least REGNO.  */
 178
 179   void (*store_registers) (struct regcache *regcache, int regno);
 180
 181   /* Read memory from the inferior process.  This should generally be
 182      called through read_inferior_memory, which handles breakpoint shadowing.
 183
 184      Read LEN bytes at MEMADDR into a buffer at MYADDR.
 185
 186      Returns 0 on success and errno on failure.  */
 187
 188   int (*read_memory) (CORE_ADDR memaddr, unsigned char *myaddr, int len);
 189
 190   /* Write memory to the inferior process.  This should generally be
 191      called through write_inferior_memory, which handles breakpoint shadowing.
 192
 193      Write LEN bytes from the buffer at MYADDR to MEMADDR.
 194
 195      Returns 0 on success and errno on failure.  */
 196
 197   int (*write_memory) (CORE_ADDR memaddr, const unsigned char *myaddr,
 198                        int len);
 199
 200   /* Query GDB for the values of any symbols we're interested in.
 201      This function is called whenever we receive a "qSymbols::"
 202      query, which corresponds to every time more symbols (might)
 203      become available.  NULL if we aren't interested in any
 204      symbols.  */
 205
 206   void (*look_up_symbols) (void);
 207
 208   /* Send an interrupt request to the inferior process,
 209      however is appropriate.  */
 210
 211   void (*request_interrupt) (void);
 212
 213   /* Read auxiliary vector data from the inferior process.
 214
 215      Read LEN bytes at OFFSET into a buffer at MYADDR.  */
 216
 217   int (*read_auxv) (CORE_ADDR offset, unsigned char *myaddr,
 218                     unsigned int len);
 219
 220   /* Insert and remove a break or watchpoint.
 221      Returns 0 on success, -1 on failure and 1 on unsupported.
 222      The type is coded as follows:
 223        '0' - software-breakpoint
 224        '1' - hardware-breakpoint
 225        '2' - write watchpoint
 226        '3' - read watchpoint
 227        '4' - access watchpoint  */
 228
 229   int (*insert_point) (char type, CORE_ADDR addr, int len);
 230   int (*remove_point) (char type, CORE_ADDR addr, int len);
 231
 232   /* Returns 1 if target was stopped due to a watchpoint hit, 0 otherwise.  */
 233
 234   int (*stopped_by_watchpoint) (void);
 235
 236   /* Returns the address associated with the watchpoint that hit, if any;
 237      returns 0 otherwise.  */
 238
 239   CORE_ADDR (*stopped_data_address) (void);
 240
 241   /* Reports the text, data offsets of the executable.  This is
 242      needed for uclinux where the executable is relocated during load
 243      time.  */
 244
 245   int (*read_offsets) (CORE_ADDR *text, CORE_ADDR *data);
 246
 247   /* Fetch the address associated with a specific thread local storage
 248      area, determined by the specified THREAD, OFFSET, and LOAD_MODULE.
 249      Stores it in *ADDRESS and returns zero on success; otherwise returns
 250      an error code.  A return value of -1 means this system does not
 251      support the operation.  */
 252
 253   int (*get_tls_address) (struct thread_info *thread, CORE_ADDR offset,
 254                           CORE_ADDR load_module, CORE_ADDR *address);
 255
 256    /* Read/Write from/to spufs using qXfer packets.  */
 257   int (*qxfer_spu) (const char *annex, unsigned char *readbuf,
 258                     unsigned const char *writebuf, CORE_ADDR offset, int len);
 259
 260   /* Fill BUF with an hostio error packet representing the last hostio
 261      error.  */
 262   void (*hostio_last_error) (char *buf);
 263
 264   /* Read/Write OS data using qXfer packets.  */
 265   int (*qxfer_osdata) (const char *annex, unsigned char *readbuf,
 266                        unsigned const char *writebuf, CORE_ADDR offset,
 267                        int len);
 268
 269   /* Read/Write extra signal info.  */
 270   int (*qxfer_siginfo) (const char *annex, unsigned char *readbuf,
 271                         unsigned const char *writebuf,
 272                         CORE_ADDR offset, int len);
 273
 274   int (*supports_non_stop) (void);
 275
 276   /* Enables async target events.  Returns the previous enable
 277      state.  */
 278   int (*async) (int enable);
 279
 280   /* Switch to non-stop (1) or all-stop (0) mode.  Return 0 on
 281      success, -1 otherwise.  */
 282   int (*start_non_stop) (int);
 283
 284   /* Returns true if the target supports multi-process debugging.  */
 285   int (*supports_multi_process) (void);
 286
 287   /* If not NULL, target-specific routine to process monitor command.
 288      Returns 1 if handled, or 0 to perform default processing.  */
 289   int (*handle_monitor_command) (char *);
 290
 291   /* Returns the core given a thread, or -1 if not known.  */
 292   int (*core_of_thread) (ptid_t);
 293
 294   /* Target specific qSupported support.  */
 295   void (*process_qsupported) (const char *);
 296
 297   /* Return 1 if the target supports tracepoints, 0 (or leave the
 298      callback NULL) otherwise.  */
 299   int (*supports_tracepoints) (void);
 300
 301   /* Read PC from REGCACHE.  */
 302   CORE_ADDR (*read_pc) (struct regcache *regcache);
 303
 304   /* Write PC to REGCACHE.  */
 305   void (*write_pc) (struct regcache *regcache, CORE_ADDR pc);
 306
 307   /* Return true if THREAD is known to be stopped now.  */
 308   int (*thread_stopped) (struct thread_info *thread);
 309
 310   /* Read Thread Information Block address.  */
 311   int (*get_tib_address) (ptid_t ptid, CORE_ADDR *address);
 312
 313   /* Pause all threads.  If FREEZE, arrange for any resume attempt be
 314      be ignored until an unpause_all call unfreezes threads again.
 315      There can be nested calls to pause_all, so a freeze counter
 316      should be maintained.  */
 317   void (*pause_all) (int freeze);
 318
 319   /* Unpause all threads.  Threads that hadn't been resumed by the
 320      client should be left stopped.  Basically a pause/unpause call
 321      pair should not end up resuming threads that were stopped before
 322      the pause call.  */
 323   void (*unpause_all) (int unfreeze);
 324
 325   /* Cancel all pending breakpoints hits in all threads.  */
 326   void (*cancel_breakpoints) (void);
 327
 328   /* Stabilize all threads.  That is, force them out of jump pads.  */
 329   void (*stabilize_threads) (void);
 330
 331   /* Install a fast tracepoint jump pad.  TPOINT is the address of the
 332      tracepoint internal object as used by the IPA agent.  TPADDR is
 333      the address of tracepoint.  COLLECTOR is address of the function
 334      the jump pad redirects to.  LOCKADDR is the address of the jump
 335      pad lock object.  ORIG_SIZE is the size in bytes of the
 336      instruction at TPADDR.  JUMP_ENTRY points to the address of the
 337      jump pad entry, and on return holds the address past the end of
 338      the created jump pad. JJUMP_PAD_INSN is a buffer containing a
 339      copy of the instruction at TPADDR.  ADJUST_INSN_ADDR and
 340      ADJUST_INSN_ADDR_END are output parameters that return the
 341      address range where the instruction at TPADDR was relocated
 342      to.  */
 343   int (*install_fast_tracepoint_jump_pad) (CORE_ADDR tpoint, CORE_ADDR tpaddr,
 344                                            CORE_ADDR collector,
 345                                            CORE_ADDR lockaddr,
 346                                            ULONGEST orig_size,
 347                                            CORE_ADDR *jump_entry,
 348                                            unsigned char *jjump_pad_insn,
 349                                            ULONGEST *jjump_pad_insn_size,
 350                                            CORE_ADDR *adjusted_insn_addr,
 351                                            CORE_ADDR *adjusted_insn_addr_end);
 352 };
 353
 354 extern struct target_ops *the_target;
 355
 356 void set_target_ops (struct target_ops *);
 357
 358 #define create_inferior(program, args) \
 359   (*the_target->create_inferior) (program, args)
 360
 361 #define myattach(pid) \
 362   (*the_target->attach) (pid)
 363
 364 #define kill_inferior(pid) \
 365   (*the_target->kill) (pid)
 366
 367 #define detach_inferior(pid) \
 368   (*the_target->detach) (pid)
 369
 370 #define mourn_inferior(PROC) \
 371   (*the_target->mourn) (PROC)
 372
 373 #define mythread_alive(pid) \
 374   (*the_target->thread_alive) (pid)
 375
 376 #define fetch_inferior_registers(regcache, regno)       \
 377   (*the_target->fetch_registers) (regcache, regno)
 378
 379 #define store_inferior_registers(regcache, regno) \
 380   (*the_target->store_registers) (regcache, regno)
 381
 382 #define join_inferior(pid) \
 383   (*the_target->join) (pid)
 384
 385 #define target_supports_non_stop() \
 386   (the_target->supports_non_stop ? (*the_target->supports_non_stop ) () : 0)
 387
 388 #define target_async(enable) \
 389   (the_target->async ? (*the_target->async) (enable) : 0)
 390
 391 #define target_supports_multi_process() \
 392   (the_target->supports_multi_process ? \
 393    (*the_target->supports_multi_process) () : 0)
 394
 395 #define target_process_qsupported(query)                \
 396   do                                                    \
 397     {                                                   \
 398       if (the_target->process_qsupported)               \
 399         the_target->process_qsupported (query);         \
 400     } while (0)
 401
 402 #define target_supports_tracepoints()                   \
 403   (the_target->supports_tracepoints                     \
 404    ? (*the_target->supports_tracepoints) () : 0)
 405
 406 #define target_supports_fast_tracepoints()              \
 407   (the_target->install_fast_tracepoint_jump_pad != NULL)
 408
 409 #define thread_stopped(thread) \
 410   (*the_target->thread_stopped) (thread)
 411
 412 #define pause_all(freeze)                       \
 413   do                                            \
 414     {                                           \
 415       if (the_target->pause_all)                \
 416         (*the_target->pause_all) (freeze);      \
 417     } while (0)
 418
 419 #define unpause_all(unfreeze)                   \
 420   do                                            \
 421     {                                           \
 422       if (the_target->unpause_all)              \
 423         (*the_target->unpause_all) (unfreeze);  \
 424     } while (0)
 425
 426 #define cancel_breakpoints()                    \
 427   do                                            \
 428     {                                           \
 429       if (the_target->cancel_breakpoints)       \
 430         (*the_target->cancel_breakpoints) ();   \
 431     } while (0)
 432
 433 #define stabilize_threads()                     \
 434   do                                            \
 435     {                                           \
 436       if (the_target->stabilize_threads)        \
 437         (*the_target->stabilize_threads) ();    \
 438     } while (0)
 439
 440 #define install_fast_tracepoint_jump_pad(tpoint, tpaddr,                \
 441                                          collector, lockaddr,           \
 442                                          orig_size,                     \
 443                                          jump_entry, jjump_pad_insn,    \
 444                                          jjump_pad_insn_size,           \
 445                                          adjusted_insn_addr,            \
 446                                          adjusted_insn_addr_end)        \
 447   (*the_target->install_fast_tracepoint_jump_pad) (tpoint, tpaddr,      \
 448                                                    collector,lockaddr,  \
 449                                                    orig_size, jump_entry, \
 450                                                    jjump_pad_insn,      \
 451                                                    jjump_pad_insn_size, \
 452                                                    adjusted_insn_addr,  \
 453                                                    adjusted_insn_addr_end)
 454
 455 /* Start non-stop mode, returns 0 on success, -1 on failure.   */
 456
 457 int start_non_stop (int nonstop);
 458
 459 ptid_t mywait (ptid_t ptid, struct target_waitstatus *ourstatus, int options,
 460                int connected_wait);
 461
 462 int read_inferior_memory (CORE_ADDR memaddr, unsigned char *myaddr, int len);
 463
 464 int write_inferior_memory (CORE_ADDR memaddr, const unsigned char *myaddr,
 465                            int len);
 466
 467 void set_desired_inferior (int id);
 468
 469 const char *target_pid_to_str (ptid_t);
 470
 471 const char *target_waitstatus_to_string (const struct target_waitstatus *);
 472
 473 #endif /* TARGET_H */