gdb/gdbserver/target.h

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