gdb/gdbserver/target.h

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