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 to
 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.  If a trampoline is created by the function,
 363      then TRAMPOLINE and TRAMPOLINE_SIZE return the address and size of
 364      the trampoline, else they remain unchanged.  JJUMP_PAD_INSN is a
 365      buffer containing a copy of the instruction at TPADDR.
 366      ADJUST_INSN_ADDR and ADJUST_INSN_ADDR_END are output parameters that
 367      return the address range where the instruction at TPADDR was relocated
 368      to.  If an error occurs, the ERR may be used to pass on an error
 369      message.  */
 370   int (*install_fast_tracepoint_jump_pad) (CORE_ADDR tpoint, CORE_ADDR tpaddr,
 371                                            CORE_ADDR collector,
 372                                            CORE_ADDR lockaddr,
 373                                            ULONGEST orig_size,
 374                                            CORE_ADDR *jump_entry,
 375                                            CORE_ADDR *trampoline,
 376                                            ULONGEST *trampoline_size,
 377                                            unsigned char *jjump_pad_insn,
 378                                            ULONGEST *jjump_pad_insn_size,
 379                                            CORE_ADDR *adjusted_insn_addr,
 380                                            CORE_ADDR *adjusted_insn_addr_end,
 381                                            char *err);
 382
 383   /* Return the bytecode operations vector for the current inferior.
 384      Returns NULL if bytecode compilation is not supported.  */
 385   struct emit_ops *(*emit_ops) (void);
 386
 387   /* Returns true if the target supports disabling randomization.  */
 388   int (*supports_disable_randomization) (void);
 389
 390   /* Return the minimum length of an instruction that can be safely overwritten
 391      for use as a fast tracepoint.  */
 392   int (*get_min_fast_tracepoint_insn_len) (void);
 393 };
 394
 395 extern struct target_ops *the_target;
 396
 397 void set_target_ops (struct target_ops *);
 398
 399 #define create_inferior(program, args) \
 400   (*the_target->create_inferior) (program, args)
 401
 402 #define myattach(pid) \
 403   (*the_target->attach) (pid)
 404
 405 #define kill_inferior(pid) \
 406   (*the_target->kill) (pid)
 407
 408 #define detach_inferior(pid) \
 409   (*the_target->detach) (pid)
 410
 411 #define mourn_inferior(PROC) \
 412   (*the_target->mourn) (PROC)
 413
 414 #define mythread_alive(pid) \
 415   (*the_target->thread_alive) (pid)
 416
 417 #define fetch_inferior_registers(regcache, regno)       \
 418   (*the_target->fetch_registers) (regcache, regno)
 419
 420 #define store_inferior_registers(regcache, regno) \
 421   (*the_target->store_registers) (regcache, regno)
 422
 423 #define join_inferior(pid) \
 424   (*the_target->join) (pid)
 425
 426 #define target_supports_non_stop() \
 427   (the_target->supports_non_stop ? (*the_target->supports_non_stop ) () : 0)
 428
 429 #define target_async(enable) \
 430   (the_target->async ? (*the_target->async) (enable) : 0)
 431
 432 #define target_supports_multi_process() \
 433   (the_target->supports_multi_process ? \
 434    (*the_target->supports_multi_process) () : 0)
 435
 436 #define target_process_qsupported(query)                \
 437   do                                                    \
 438     {                                                   \
 439       if (the_target->process_qsupported)               \
 440         the_target->process_qsupported (query);         \
 441     } while (0)
 442
 443 #define target_supports_tracepoints()                   \
 444   (the_target->supports_tracepoints                     \
 445    ? (*the_target->supports_tracepoints) () : 0)
 446
 447 #define target_supports_fast_tracepoints()              \
 448   (the_target->install_fast_tracepoint_jump_pad != NULL)
 449
 450 #define target_get_min_fast_tracepoint_insn_len()       \
 451   (the_target->get_min_fast_tracepoint_insn_len         \
 452    ? (*the_target->get_min_fast_tracepoint_insn_len) () : 0)
 453
 454 #define thread_stopped(thread) \
 455   (*the_target->thread_stopped) (thread)
 456
 457 #define pause_all(freeze)                       \
 458   do                                            \
 459     {                                           \
 460       if (the_target->pause_all)                \
 461         (*the_target->pause_all) (freeze);      \
 462     } while (0)
 463
 464 #define unpause_all(unfreeze)                   \
 465   do                                            \
 466     {                                           \
 467       if (the_target->unpause_all)              \
 468         (*the_target->unpause_all) (unfreeze);  \
 469     } while (0)
 470
 471 #define cancel_breakpoints()                    \
 472   do                                            \
 473     {                                           \
 474       if (the_target->cancel_breakpoints)       \
 475         (*the_target->cancel_breakpoints) ();   \
 476     } while (0)
 477
 478 #define stabilize_threads()                     \
 479   do                                            \
 480     {                                           \
 481       if (the_target->stabilize_threads)        \
 482         (*the_target->stabilize_threads) ();    \
 483     } while (0)
 484
 485 #define install_fast_tracepoint_jump_pad(tpoint, tpaddr,                \
 486                                          collector, lockaddr,           \
 487                                          orig_size,                     \
 488                                          jump_entry,                    \
 489                                          trampoline, trampoline_size,   \
 490                                          jjump_pad_insn,                \
 491                                          jjump_pad_insn_size,           \
 492                                          adjusted_insn_addr,            \
 493                                          adjusted_insn_addr_end,        \
 494                                          err)                           \
 495   (*the_target->install_fast_tracepoint_jump_pad) (tpoint, tpaddr,      \
 496                                                    collector,lockaddr,  \
 497                                                    orig_size, jump_entry, \
 498                                                    trampoline,          \
 499                                                    trampoline_size,     \
 500                                                    jjump_pad_insn,      \
 501                                                    jjump_pad_insn_size, \
 502                                                    adjusted_insn_addr,  \
 503                                                    adjusted_insn_addr_end, \
 504                                                    err)
 505
 506 #define target_emit_ops() \
 507   (the_target->emit_ops ? (*the_target->emit_ops) () : NULL)
 508
 509 #define target_supports_disable_randomization() \
 510   (the_target->supports_disable_randomization ? \
 511    (*the_target->supports_disable_randomization) () : 0)
 512
 513 /* Start non-stop mode, returns 0 on success, -1 on failure.   */
 514
 515 int start_non_stop (int nonstop);
 516
 517 ptid_t mywait (ptid_t ptid, struct target_waitstatus *ourstatus, int options,
 518                int connected_wait);
 519
 520 #define prepare_to_access_memory()              \
 521   (the_target->prepare_to_access_memory         \
 522    ? (*the_target->prepare_to_access_memory) () \
 523    : 0)
 524
 525 #define done_accessing_memory()                         \
 526   do                                                    \
 527     {                                                   \
 528       if (the_target->done_accessing_memory)            \
 529         (*the_target->done_accessing_memory) ();        \
 530     } while (0)
 531
 532 int read_inferior_memory (CORE_ADDR memaddr, unsigned char *myaddr, int len);
 533
 534 int write_inferior_memory (CORE_ADDR memaddr, const unsigned char *myaddr,
 535                            int len);
 536
 537 void set_desired_inferior (int id);
 538
 539 const char *target_pid_to_str (ptid_t);
 540
 541 const char *target_waitstatus_to_string (const struct target_waitstatus *);
 542
 543 #endif /* TARGET_H */