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   /* Target specific qSupported support.  */
 315   void (*process_qsupported) (const char *);
 316
 317   /* Return 1 if the target supports tracepoints, 0 (or leave the
 318      callback NULL) otherwise.  */
 319   int (*supports_tracepoints) (void);
 320
 321   /* Read PC from REGCACHE.  */
 322   CORE_ADDR (*read_pc) (struct regcache *regcache);
 323
 324   /* Write PC to REGCACHE.  */
 325   void (*write_pc) (struct regcache *regcache, CORE_ADDR pc);
 326
 327   /* Return true if THREAD is known to be stopped now.  */
 328   int (*thread_stopped) (struct thread_info *thread);
 329
 330   /* Read Thread Information Block address.  */
 331   int (*get_tib_address) (ptid_t ptid, CORE_ADDR *address);
 332
 333   /* Pause all threads.  If FREEZE, arrange for any resume attempt be
 334      be ignored until an unpause_all call unfreezes threads again.
 335      There can be nested calls to pause_all, so a freeze counter
 336      should be maintained.  */
 337   void (*pause_all) (int freeze);
 338
 339   /* Unpause all threads.  Threads that hadn't been resumed by the
 340      client should be left stopped.  Basically a pause/unpause call
 341      pair should not end up resuming threads that were stopped before
 342      the pause call.  */
 343   void (*unpause_all) (int unfreeze);
 344
 345   /* Cancel all pending breakpoints hits in all threads.  */
 346   void (*cancel_breakpoints) (void);
 347
 348   /* Stabilize all threads.  That is, force them out of jump pads.  */
 349   void (*stabilize_threads) (void);
 350
 351   /* Install a fast tracepoint jump pad.  TPOINT is the address of the
 352      tracepoint internal object as used by the IPA agent.  TPADDR is
 353      the address of tracepoint.  COLLECTOR is address of the function
 354      the jump pad redirects to.  LOCKADDR is the address of the jump
 355      pad lock object.  ORIG_SIZE is the size in bytes of the
 356      instruction at TPADDR.  JUMP_ENTRY points to the address of the
 357      jump pad entry, and on return holds the address past the end of
 358      the created jump pad. JJUMP_PAD_INSN is a buffer containing a
 359      copy of the instruction at TPADDR.  ADJUST_INSN_ADDR and
 360      ADJUST_INSN_ADDR_END are output parameters that return the
 361      address range where the instruction at TPADDR was relocated
 362      to.  */
 363   int (*install_fast_tracepoint_jump_pad) (CORE_ADDR tpoint, CORE_ADDR tpaddr,
 364                                            CORE_ADDR collector,
 365                                            CORE_ADDR lockaddr,
 366                                            ULONGEST orig_size,
 367                                            CORE_ADDR *jump_entry,
 368                                            unsigned char *jjump_pad_insn,
 369                                            ULONGEST *jjump_pad_insn_size,
 370                                            CORE_ADDR *adjusted_insn_addr,
 371                                            CORE_ADDR *adjusted_insn_addr_end);
 372
 373   /* Return the bytecode operations vector for the current inferior.
 374      Returns NULL if bytecode compilation is not supported.  */
 375   struct emit_ops *(*emit_ops) (void);
 376 };
 377
 378 extern struct target_ops *the_target;
 379
 380 void set_target_ops (struct target_ops *);
 381
 382 #define create_inferior(program, args) \
 383   (*the_target->create_inferior) (program, args)
 384
 385 #define myattach(pid) \
 386   (*the_target->attach) (pid)
 387
 388 #define kill_inferior(pid) \
 389   (*the_target->kill) (pid)
 390
 391 #define detach_inferior(pid) \
 392   (*the_target->detach) (pid)
 393
 394 #define mourn_inferior(PROC) \
 395   (*the_target->mourn) (PROC)
 396
 397 #define mythread_alive(pid) \
 398   (*the_target->thread_alive) (pid)
 399
 400 #define fetch_inferior_registers(regcache, regno)       \
 401   (*the_target->fetch_registers) (regcache, regno)
 402
 403 #define store_inferior_registers(regcache, regno) \
 404   (*the_target->store_registers) (regcache, regno)
 405
 406 #define join_inferior(pid) \
 407   (*the_target->join) (pid)
 408
 409 #define target_supports_non_stop() \
 410   (the_target->supports_non_stop ? (*the_target->supports_non_stop ) () : 0)
 411
 412 #define target_async(enable) \
 413   (the_target->async ? (*the_target->async) (enable) : 0)
 414
 415 #define target_supports_multi_process() \
 416   (the_target->supports_multi_process ? \
 417    (*the_target->supports_multi_process) () : 0)
 418
 419 #define target_process_qsupported(query)                \
 420   do                                                    \
 421     {                                                   \
 422       if (the_target->process_qsupported)               \
 423         the_target->process_qsupported (query);         \
 424     } while (0)
 425
 426 #define target_supports_tracepoints()                   \
 427   (the_target->supports_tracepoints                     \
 428    ? (*the_target->supports_tracepoints) () : 0)
 429
 430 #define target_supports_fast_tracepoints()              \
 431   (the_target->install_fast_tracepoint_jump_pad != NULL)
 432
 433 #define thread_stopped(thread) \
 434   (*the_target->thread_stopped) (thread)
 435
 436 #define pause_all(freeze)                       \
 437   do                                            \
 438     {                                           \
 439       if (the_target->pause_all)                \
 440         (*the_target->pause_all) (freeze);      \
 441     } while (0)
 442
 443 #define unpause_all(unfreeze)                   \
 444   do                                            \
 445     {                                           \
 446       if (the_target->unpause_all)              \
 447         (*the_target->unpause_all) (unfreeze);  \
 448     } while (0)
 449
 450 #define cancel_breakpoints()                    \
 451   do                                            \
 452     {                                           \
 453       if (the_target->cancel_breakpoints)       \
 454         (*the_target->cancel_breakpoints) ();   \
 455     } while (0)
 456
 457 #define stabilize_threads()                     \
 458   do                                            \
 459     {                                           \
 460       if (the_target->stabilize_threads)        \
 461         (*the_target->stabilize_threads) ();    \
 462     } while (0)
 463
 464 #define install_fast_tracepoint_jump_pad(tpoint, tpaddr,                \
 465                                          collector, lockaddr,           \
 466                                          orig_size,                     \
 467                                          jump_entry, jjump_pad_insn,    \
 468                                          jjump_pad_insn_size,           \
 469                                          adjusted_insn_addr,            \
 470                                          adjusted_insn_addr_end)        \
 471   (*the_target->install_fast_tracepoint_jump_pad) (tpoint, tpaddr,      \
 472                                                    collector,lockaddr,  \
 473                                                    orig_size, jump_entry, \
 474                                                    jjump_pad_insn,      \
 475                                                    jjump_pad_insn_size, \
 476                                                    adjusted_insn_addr,  \
 477                                                    adjusted_insn_addr_end)
 478
 479 #define target_emit_ops() \
 480   (the_target->emit_ops ? (*the_target->emit_ops) () : NULL)
 481
 482 /* Start non-stop mode, returns 0 on success, -1 on failure.   */
 483
 484 int start_non_stop (int nonstop);
 485
 486 ptid_t mywait (ptid_t ptid, struct target_waitstatus *ourstatus, int options,
 487                int connected_wait);
 488
 489 #define prepare_to_access_memory()              \
 490   (the_target->prepare_to_access_memory         \
 491    ? (*the_target->prepare_to_access_memory) () \
 492    : 0)
 493
 494 #define done_accessing_memory()                         \
 495   do                                                    \
 496     {                                                   \
 497       if (the_target->done_accessing_memory)            \
 498         (*the_target->done_accessing_memory) ();        \
 499     } while (0)
 500
 501 int read_inferior_memory (CORE_ADDR memaddr, unsigned char *myaddr, int len);
 502
 503 int write_inferior_memory (CORE_ADDR memaddr, const unsigned char *myaddr,
 504                            int len);
 505
 506 void set_desired_inferior (int id);
 507
 508 const char *target_pid_to_str (ptid_t);
 509
 510 const char *target_waitstatus_to_string (const struct target_waitstatus *);
 511
 512 #endif /* TARGET_H */