gdb/gdbserver/target.h

   1 /* Target operations for the remote server for GDB.
   2    Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009, 2010, 2011
   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 struct emit_ops;
  26
  27 /* Ways to "resume" a thread.  */
  28
  29 enum resume_kind
  30 {
  31   /* Thread should continue.  */
  32   resume_continue,
  33
  34   /* Thread should single-step.  */
  35   resume_step,
  36
  37   /* Thread should be stopped.  */
  38   resume_stop
  39 };
  40
  41 /* This structure describes how to resume a particular thread (or all
  42    threads) based on the client's request.  If thread is -1, then this
  43    entry applies to all threads.  These are passed around as an
  44    array.  */
  45
  46 struct thread_resume
  47 {
  48   ptid_t thread;
  49
  50   /* How to "resume".  */
  51   enum resume_kind kind;
  52
  53   /* If non-zero, send this signal when we resume, or to stop the
  54      thread.  If stopping a thread, and this is 0, the target should
  55      stop the thread however it best decides to (e.g., SIGSTOP on
  56      linux; SuspendThread on win32).  This is a host signal value (not
  57      enum target_signal).  */
  58   int sig;
  59 };
  60
  61 /* Generally, what has the program done?  */
  62 enum target_waitkind
  63   {
  64     /* The program has exited.  The exit status is in
  65        value.integer.  */
  66     TARGET_WAITKIND_EXITED,
  67
  68     /* The program has stopped with a signal.  Which signal is in
  69        value.sig.  */
  70     TARGET_WAITKIND_STOPPED,
  71
  72     /* The program has terminated with a signal.  Which signal is in
  73        value.sig.  */
  74     TARGET_WAITKIND_SIGNALLED,
  75
  76     /* The program is letting us know that it dynamically loaded
  77        something.  */
  78     TARGET_WAITKIND_LOADED,
  79
  80     /* The program has exec'ed a new executable file.  The new file's
  81        pathname is pointed to by value.execd_pathname.  */
  82     TARGET_WAITKIND_EXECD,
  83
  84     /* Nothing of interest to GDB happened, but we stopped anyway.  */
  85     TARGET_WAITKIND_SPURIOUS,
  86
  87     /* An event has occurred, but we should wait again.  In this case,
  88        we want to go back to the event loop and wait there for another
  89        event from the inferior.  */
  90     TARGET_WAITKIND_IGNORE
  91   };
  92
  93 struct target_waitstatus
  94   {
  95     enum target_waitkind kind;
  96
  97     /* Forked child pid, execd pathname, exit status or signal number.  */
  98     union
  99       {
 100         int integer;
 101         enum target_signal sig;
 102         ptid_t related_pid;
 103         char *execd_pathname;
 104       }
 105     value;
 106   };
 107
 108 /* Options that can be passed to target_ops->wait.  */
 109
 110 #define TARGET_WNOHANG 1
 111
 112 struct target_ops
 113 {
 114   /* Start a new process.
 115
 116      PROGRAM is a path to the program to execute.
 117      ARGS is a standard NULL-terminated array of arguments,
 118      to be passed to the inferior as ``argv''.
 119
 120      Returns the new PID on success, -1 on failure.  Registers the new
 121      process with the process list.  */
 122
 123   int (*create_inferior) (char *program, char **args);
 124
 125   /* Attach to a running process.
 126
 127      PID is the process ID to attach to, specified by the user
 128      or a higher layer.
 129
 130      Returns -1 if attaching is unsupported, 0 on success, and calls
 131      error() otherwise.  */
 132
 133   int (*attach) (unsigned long pid);
 134
 135   /* Kill inferior PID.  Return -1 on failure, and 0 on success.  */
 136
 137   int (*kill) (int pid);
 138
 139   /* Detach from inferior PID. Return -1 on failure, and 0 on
 140      success.  */
 141
 142   int (*detach) (int pid);
 143
 144   /* The inferior process has died.  Do what is right.  */
 145
 146   void (*mourn) (struct process_info *proc);
 147
 148   /* Wait for inferior PID to exit.  */
 149   void (*join) (int pid);
 150
 151   /* Return 1 iff the thread with process ID PID is alive.  */
 152
 153   int (*thread_alive) (ptid_t pid);
 154
 155   /* Resume the inferior process.  */
 156
 157   void (*resume) (struct thread_resume *resume_info, size_t n);
 158
 159   /* Wait for the inferior process or thread to change state.  Store
 160      status through argument pointer STATUS.
 161
 162      PTID = -1 to wait for any pid to do something, PTID(pid,0,0) to
 163      wait for any thread of process pid to do something.  Return ptid
 164      of child, or -1 in case of error; store status through argument
 165      pointer STATUS.  OPTIONS is a bit set of options defined as
 166      TARGET_W* above.  If options contains TARGET_WNOHANG and there's
 167      no child stop to report, return is
 168      null_ptid/TARGET_WAITKIND_IGNORE.  */
 169
 170   ptid_t (*wait) (ptid_t ptid, struct target_waitstatus *status, int options);
 171
 172   /* Fetch registers from the inferior process.
 173
 174      If REGNO is -1, fetch all registers; otherwise, fetch at least REGNO.  */
 175
 176   void (*fetch_registers) (struct regcache *regcache, int regno);
 177
 178   /* Store registers to the inferior process.
 179
 180      If REGNO is -1, store all registers; otherwise, store at least REGNO.  */
 181
 182   void (*store_registers) (struct regcache *regcache, int regno);
 183
 184   /* Prepare to read or write memory from the inferior process.
 185      Targets use this to do what is necessary to get the state of the
 186      inferior such that it is possible to access memory.
 187
 188      This should generally only be called from client facing routines,
 189      such as gdb_read_memory/gdb_write_memory, or the insert_point
 190      callbacks.
 191
 192      Like `read_memory' and `write_memory' below, returns 0 on success
 193      and errno on failure.  */
 194
 195   int (*prepare_to_access_memory) (void);
 196
 197   /* Undo the effects of prepare_to_access_memory.  */
 198
 199   void (*done_accessing_memory) (void);
 200
 201   /* Read memory from the inferior process.  This should generally be
 202      called through read_inferior_memory, which handles breakpoint shadowing.
 203
 204      Read LEN bytes at MEMADDR into a buffer at MYADDR.
 205
 206      Returns 0 on success and errno on failure.  */
 207
 208   int (*read_memory) (CORE_ADDR memaddr, unsigned char *myaddr, int len);
 209
 210   /* Write memory to the inferior process.  This should generally be
 211      called through write_inferior_memory, which handles breakpoint shadowing.
 212
 213      Write LEN bytes from the buffer at MYADDR to MEMADDR.
 214
 215      Returns 0 on success and errno on failure.  */
 216
 217   int (*write_memory) (CORE_ADDR memaddr, const unsigned char *myaddr,
 218                        int len);
 219
 220   /* Query GDB for the values of any symbols we're interested in.
 221      This function is called whenever we receive a "qSymbols::"
 222      query, which corresponds to every time more symbols (might)
 223      become available.  NULL if we aren't interested in any
 224      symbols.  */
 225
 226   void (*look_up_symbols) (void);
 227
 228   /* Send an interrupt request to the inferior process,
 229      however is appropriate.  */
 230
 231   void (*request_interrupt) (void);
 232
 233   /* Read auxiliary vector data from the inferior process.
 234
 235      Read LEN bytes at OFFSET into a buffer at MYADDR.  */
 236
 237   int (*read_auxv) (CORE_ADDR offset, unsigned char *myaddr,
 238                     unsigned int len);
 239
 240   /* Insert and remove a break or watchpoint.
 241      Returns 0 on success, -1 on failure and 1 on unsupported.
 242      The type is coded as follows:
 243        '0' - software-breakpoint
 244        '1' - hardware-breakpoint
 245        '2' - write watchpoint
 246        '3' - read watchpoint
 247        '4' - access watchpoint  */
 248
 249   int (*insert_point) (char type, CORE_ADDR addr, int len);
 250   int (*remove_point) (char type, CORE_ADDR addr, int len);
 251
 252   /* Returns 1 if target was stopped due to a watchpoint hit, 0 otherwise.  */
 253
 254   int (*stopped_by_watchpoint) (void);
 255
 256   /* Returns the address associated with the watchpoint that hit, if any;
 257      returns 0 otherwise.  */
 258
 259   CORE_ADDR (*stopped_data_address) (void);
 260
 261   /* Reports the text, data offsets of the executable.  This is
 262      needed for uclinux where the executable is relocated during load
 263      time.  */
 264
 265   int (*read_offsets) (CORE_ADDR *text, CORE_ADDR *data);
 266
 267   /* Fetch the address associated with a specific thread local storage
 268      area, determined by the specified THREAD, OFFSET, and LOAD_MODULE.
 269      Stores it in *ADDRESS and returns zero on success; otherwise returns
 270      an error code.  A return value of -1 means this system does not
 271      support the operation.  */
 272
 273   int (*get_tls_address) (struct thread_info *thread, CORE_ADDR offset,
 274                           CORE_ADDR load_module, CORE_ADDR *address);
 275
 276    /* Read/Write from/to spufs using qXfer packets.  */
 277   int (*qxfer_spu) (const char *annex, unsigned char *readbuf,
 278                     unsigned const char *writebuf, CORE_ADDR offset, int len);
 279
 280   /* Fill BUF with an hostio error packet representing the last hostio
 281      error.  */
 282   void (*hostio_last_error) (char *buf);
 283
 284   /* Read/Write OS data using qXfer packets.  */
 285   int (*qxfer_osdata) (const char *annex, unsigned char *readbuf,
 286                        unsigned const char *writebuf, CORE_ADDR offset,
 287                        int len);
 288
 289   /* Read/Write extra signal info.  */
 290   int (*qxfer_siginfo) (const char *annex, unsigned char *readbuf,
 291                         unsigned const char *writebuf,
 292                         CORE_ADDR offset, int len);
 293
 294   int (*supports_non_stop) (void);
 295
 296   /* Enables async target events.  Returns the previous enable
 297      state.  */
 298   int (*async) (int enable);
 299
 300   /* Switch to non-stop (1) or all-stop (0) mode.  Return 0 on
 301      success, -1 otherwise.  */
 302   int (*start_non_stop) (int);
 303
 304   /* Returns true if the target supports multi-process debugging.  */
 305   int (*supports_multi_process) (void);
 306
 307   /* If not NULL, target-specific routine to process monitor command.
 308      Returns 1 if handled, or 0 to perform default processing.  */
 309   int (*handle_monitor_command) (char *);
 310
 311   /* Returns the core given a thread, or -1 if not known.  */
 312   int (*core_of_thread) (ptid_t);
 313
 314   /* Read loadmaps.  Read LEN bytes at OFFSET into a buffer at MYADDR.  */
 315   int (*read_loadmap) (const char *annex, CORE_ADDR offset,
 316                        unsigned char *myaddr, unsigned int len);
 317
 318   /* Target specific qSupported support.  */
 319   void (*process_qsupported) (const char *);
 320
 321   /* Return 1 if the target supports tracepoints, 0 (or leave the
 322      callback NULL) otherwise.  */
 323   int (*supports_tracepoints) (void);
 324
 325   /* Read PC from REGCACHE.  */
 326   CORE_ADDR (*read_pc) (struct regcache *regcache);
 327
 328   /* Write PC to REGCACHE.  */
 329   void (*write_pc) (struct regcache *regcache, CORE_ADDR pc);
 330
 331   /* Return true if THREAD is known to be stopped now.  */
 332   int (*thread_stopped) (struct thread_info *thread);
 333
 334   /* Read Thread Information Block address.  */
 335   int (*get_tib_address) (ptid_t ptid, CORE_ADDR *address);
 336
 337   /* Pause all threads.  If FREEZE, arrange for any resume attempt be
 338      be ignored until an unpause_all call unfreezes threads again.
 339      There can be nested calls to pause_all, so a freeze counter
 340      should be maintained.  */
 341   void (*pause_all) (int freeze);
 342
 343   /* Unpause all threads.  Threads that hadn't been resumed by the
 344      client should be left stopped.  Basically a pause/unpause call
 345      pair should not end up resuming threads that were stopped before
 346      the pause call.  */
 347   void (*unpause_all) (int unfreeze);
 348
 349   /* Cancel all pending breakpoints hits in all threads.  */
 350   void (*cancel_breakpoints) (void);
 351
 352   /* Stabilize all threads.  That is, force them out of jump pads.  */
 353   void (*stabilize_threads) (void);
 354
 355   /* Install a fast tracepoint jump pad.  TPOINT is the address of the
 356      tracepoint internal object as used by the IPA agent.  TPADDR is
 357      the address of tracepoint.  COLLECTOR is address of the function
 358      the jump pad redirects to.  LOCKADDR is the address of the jump
 359      pad lock object.  ORIG_SIZE is the size in bytes of the
 360      instruction at TPADDR.  JUMP_ENTRY points to the address of the
 361      jump pad entry, and on return holds the address past the end of
 362      the created jump pad. JJUMP_PAD_INSN is a buffer containing a
 363      copy of the instruction at TPADDR.  ADJUST_INSN_ADDR and
 364      ADJUST_INSN_ADDR_END are output parameters that return the
 365      address range where the instruction at TPADDR was relocated
 366      to.  */
 367   int (*install_fast_tracepoint_jump_pad) (CORE_ADDR tpoint, CORE_ADDR tpaddr,
 368                                            CORE_ADDR collector,
 369                                            CORE_ADDR lockaddr,
 370                                            ULONGEST orig_size,
 371                                            CORE_ADDR *jump_entry,
 372                                            unsigned char *jjump_pad_insn,
 373                                            ULONGEST *jjump_pad_insn_size,
 374                                            CORE_ADDR *adjusted_insn_addr,
 375                                            CORE_ADDR *adjusted_insn_addr_end);
 376
 377   /* Return the bytecode operations vector for the current inferior.
 378      Returns NULL if bytecode compilation is not supported.  */
 379   struct emit_ops *(*emit_ops) (void);
 380 };
 381
 382 extern struct target_ops *the_target;
 383
 384 void set_target_ops (struct target_ops *);
 385
 386 #define create_inferior(program, args) \
 387   (*the_target->create_inferior) (program, args)
 388
 389 #define myattach(pid) \
 390   (*the_target->attach) (pid)
 391
 392 #define kill_inferior(pid) \
 393   (*the_target->kill) (pid)
 394
 395 #define detach_inferior(pid) \
 396   (*the_target->detach) (pid)
 397
 398 #define mourn_inferior(PROC) \
 399   (*the_target->mourn) (PROC)
 400
 401 #define mythread_alive(pid) \
 402   (*the_target->thread_alive) (pid)
 403
 404 #define fetch_inferior_registers(regcache, regno)       \
 405   (*the_target->fetch_registers) (regcache, regno)
 406
 407 #define store_inferior_registers(regcache, regno) \
 408   (*the_target->store_registers) (regcache, regno)
 409
 410 #define join_inferior(pid) \
 411   (*the_target->join) (pid)
 412
 413 #define target_supports_non_stop() \
 414   (the_target->supports_non_stop ? (*the_target->supports_non_stop ) () : 0)
 415
 416 #define target_async(enable) \
 417   (the_target->async ? (*the_target->async) (enable) : 0)
 418
 419 #define target_supports_multi_process() \
 420   (the_target->supports_multi_process ? \
 421    (*the_target->supports_multi_process) () : 0)
 422
 423 #define target_process_qsupported(query)                \
 424   do                                                    \
 425     {                                                   \
 426       if (the_target->process_qsupported)               \
 427         the_target->process_qsupported (query);         \
 428     } while (0)
 429
 430 #define target_supports_tracepoints()                   \
 431   (the_target->supports_tracepoints                     \
 432    ? (*the_target->supports_tracepoints) () : 0)
 433
 434 #define target_supports_fast_tracepoints()              \
 435   (the_target->install_fast_tracepoint_jump_pad != NULL)
 436
 437 #define thread_stopped(thread) \
 438   (*the_target->thread_stopped) (thread)
 439
 440 #define pause_all(freeze)                       \
 441   do                                            \
 442     {                                           \
 443       if (the_target->pause_all)                \
 444         (*the_target->pause_all) (freeze);      \
 445     } while (0)
 446
 447 #define unpause_all(unfreeze)                   \
 448   do                                            \
 449     {                                           \
 450       if (the_target->unpause_all)              \
 451         (*the_target->unpause_all) (unfreeze);  \
 452     } while (0)
 453
 454 #define cancel_breakpoints()                    \
 455   do                                            \
 456     {                                           \
 457       if (the_target->cancel_breakpoints)       \
 458         (*the_target->cancel_breakpoints) ();   \
 459     } while (0)
 460
 461 #define stabilize_threads()                     \
 462   do                                            \
 463     {                                           \
 464       if (the_target->stabilize_threads)        \
 465         (*the_target->stabilize_threads) ();    \
 466     } while (0)
 467
 468 #define install_fast_tracepoint_jump_pad(tpoint, tpaddr,                \
 469                                          collector, lockaddr,           \
 470                                          orig_size,                     \
 471                                          jump_entry, jjump_pad_insn,    \
 472                                          jjump_pad_insn_size,           \
 473                                          adjusted_insn_addr,            \
 474                                          adjusted_insn_addr_end)        \
 475   (*the_target->install_fast_tracepoint_jump_pad) (tpoint, tpaddr,      \
 476                                                    collector,lockaddr,  \
 477                                                    orig_size, jump_entry, \
 478                                                    jjump_pad_insn,      \
 479                                                    jjump_pad_insn_size, \
 480                                                    adjusted_insn_addr,  \
 481                                                    adjusted_insn_addr_end)
 482
 483 #define target_emit_ops() \
 484   (the_target->emit_ops ? (*the_target->emit_ops) () : NULL)
 485
 486 /* Start non-stop mode, returns 0 on success, -1 on failure.   */
 487
 488 int start_non_stop (int nonstop);
 489
 490 ptid_t mywait (ptid_t ptid, struct target_waitstatus *ourstatus, int options,
 491                int connected_wait);
 492
 493 #define prepare_to_access_memory()              \
 494   (the_target->prepare_to_access_memory         \
 495    ? (*the_target->prepare_to_access_memory) () \
 496    : 0)
 497
 498 #define done_accessing_memory()                         \
 499   do                                                    \
 500     {                                                   \
 501       if (the_target->done_accessing_memory)            \
 502         (*the_target->done_accessing_memory) ();        \
 503     } while (0)
 504
 505 int read_inferior_memory (CORE_ADDR memaddr, unsigned char *myaddr, int len);
 506
 507 int write_inferior_memory (CORE_ADDR memaddr, const unsigned char *myaddr,
 508                            int len);
 509
 510 void set_desired_inferior (int id);
 511
 512 const char *target_pid_to_str (ptid_t);
 513
 514 const char *target_waitstatus_to_string (const struct target_waitstatus *);
 515
 516 #endif /* TARGET_H */