gdb/target.h

   1 /* Interface between GDB and target environments, including files and processes
   2    Copyright 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
   3    2000, 2001, 2002 Free Software Foundation, Inc.
   4    Contributed by Cygnus Support.  Written by John Gilmore.
   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 2 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, write to the Free Software
  20    Foundation, Inc., 59 Temple Place - Suite 330,
  21    Boston, MA 02111-1307, USA.  */
  22
  23 #if !defined (TARGET_H)
  24 #define TARGET_H
  25
  26 struct objfile;
  27 struct ui_file;
  28 struct mem_attrib;
  29
  30 /* This include file defines the interface between the main part
  31    of the debugger, and the part which is target-specific, or
  32    specific to the communications interface between us and the
  33    target.
  34
  35    A TARGET is an interface between the debugger and a particular
  36    kind of file or process.  Targets can be STACKED in STRATA,
  37    so that more than one target can potentially respond to a request.
  38    In particular, memory accesses will walk down the stack of targets
  39    until they find a target that is interested in handling that particular
  40    address.  STRATA are artificial boundaries on the stack, within
  41    which particular kinds of targets live.  Strata exist so that
  42    people don't get confused by pushing e.g. a process target and then
  43    a file target, and wondering why they can't see the current values
  44    of variables any more (the file target is handling them and they
  45    never get to the process target).  So when you push a file target,
  46    it goes into the file stratum, which is always below the process
  47    stratum.  */
  48
  49 #include "bfd.h"
  50 #include "symtab.h"
  51 #include "dcache.h"
  52 #include "memattr.h"
  53
  54 enum strata
  55   {
  56     dummy_stratum,              /* The lowest of the low */
  57     file_stratum,               /* Executable files, etc */
  58     core_stratum,               /* Core dump files */
  59     download_stratum,           /* Downloading of remote targets */
  60     process_stratum,            /* Executing processes */
  61     thread_stratum              /* Executing threads */
  62   };
  63
  64 enum thread_control_capabilities
  65   {
  66     tc_none = 0,                /* Default: can't control thread execution.  */
  67     tc_schedlock = 1,           /* Can lock the thread scheduler.  */
  68     tc_switch = 2               /* Can switch the running thread on demand.  */
  69   };
  70
  71 /* Stuff for target_wait.  */
  72
  73 /* Generally, what has the program done?  */
  74 enum target_waitkind
  75   {
  76     /* The program has exited.  The exit status is in value.integer.  */
  77     TARGET_WAITKIND_EXITED,
  78
  79     /* The program has stopped with a signal.  Which signal is in
  80        value.sig.  */
  81     TARGET_WAITKIND_STOPPED,
  82
  83     /* The program has terminated with a signal.  Which signal is in
  84        value.sig.  */
  85     TARGET_WAITKIND_SIGNALLED,
  86
  87     /* The program is letting us know that it dynamically loaded something
  88        (e.g. it called load(2) on AIX).  */
  89     TARGET_WAITKIND_LOADED,
  90
  91     /* The program has forked.  A "related" process' ID is in
  92        value.related_pid.  I.e., if the child forks, value.related_pid
  93        is the parent's ID.  */
  94
  95     TARGET_WAITKIND_FORKED,
  96
  97     /* The program has vforked.  A "related" process's ID is in
  98        value.related_pid.  */
  99
 100     TARGET_WAITKIND_VFORKED,
 101
 102     /* The program has exec'ed a new executable file.  The new file's
 103        pathname is pointed to by value.execd_pathname.  */
 104
 105     TARGET_WAITKIND_EXECD,
 106
 107     /* The program has entered or returned from a system call.  On
 108        HP-UX, this is used in the hardware watchpoint implementation.
 109        The syscall's unique integer ID number is in value.syscall_id */
 110
 111     TARGET_WAITKIND_SYSCALL_ENTRY,
 112     TARGET_WAITKIND_SYSCALL_RETURN,
 113
 114     /* Nothing happened, but we stopped anyway.  This perhaps should be handled
 115        within target_wait, but I'm not sure target_wait should be resuming the
 116        inferior.  */
 117     TARGET_WAITKIND_SPURIOUS,
 118
 119     /* An event has occured, but we should wait again.
 120        Remote_async_wait() returns this when there is an event
 121        on the inferior, but the rest of the world is not interested in
 122        it. The inferior has not stopped, but has just sent some output
 123        to the console, for instance. In this case, we want to go back
 124        to the event loop and wait there for another event from the
 125        inferior, rather than being stuck in the remote_async_wait()
 126        function. This way the event loop is responsive to other events,
 127        like for instance the user typing.  */
 128     TARGET_WAITKIND_IGNORE
 129   };
 130
 131 struct target_waitstatus
 132   {
 133     enum target_waitkind kind;
 134
 135     /* Forked child pid, execd pathname, exit status or signal number.  */
 136     union
 137       {
 138         int integer;
 139         enum target_signal sig;
 140         int related_pid;
 141         char *execd_pathname;
 142         int syscall_id;
 143       }
 144     value;
 145   };
 146
 147 /* Possible types of events that the inferior handler will have to
 148    deal with.  */
 149 enum inferior_event_type
 150   {
 151     /* There is a request to quit the inferior, abandon it.  */
 152     INF_QUIT_REQ,
 153     /* Process a normal inferior event which will result in target_wait
 154        being called.  */
 155     INF_REG_EVENT,
 156     /* Deal with an error on the inferior.  */
 157     INF_ERROR,
 158     /* We are called because a timer went off.  */
 159     INF_TIMER,
 160     /* We are called to do stuff after the inferior stops.  */
 161     INF_EXEC_COMPLETE,
 162     /* We are called to do some stuff after the inferior stops, but we
 163        are expected to reenter the proceed() and
 164        handle_inferior_event() functions. This is used only in case of
 165        'step n' like commands.  */
 166     INF_EXEC_CONTINUE
 167   };
 168
 169 /* Return the string for a signal.  */
 170 extern char *target_signal_to_string (enum target_signal);
 171
 172 /* Return the name (SIGHUP, etc.) for a signal.  */
 173 extern char *target_signal_to_name (enum target_signal);
 174
 175 /* Given a name (SIGHUP, etc.), return its signal.  */
 176 enum target_signal target_signal_from_name (char *);
 177 \f
 178
 179 /* If certain kinds of activity happen, target_wait should perform
 180    callbacks.  */
 181 /* Right now we just call (*TARGET_ACTIVITY_FUNCTION) if I/O is possible
 182    on TARGET_ACTIVITY_FD.  */
 183 extern int target_activity_fd;
 184 /* Returns zero to leave the inferior alone, one to interrupt it.  */
 185 extern int (*target_activity_function) (void);
 186 \f
 187 struct thread_info;             /* fwd decl for parameter list below: */
 188
 189 struct target_ops
 190   {
 191     struct target_ops *beneath; /* To the target under this one.  */
 192     char *to_shortname;         /* Name this target type */
 193     char *to_longname;          /* Name for printing */
 194     char *to_doc;               /* Documentation.  Does not include trailing
 195                                    newline, and starts with a one-line descrip-
 196                                    tion (probably similar to to_longname).  */
 197     void (*to_open) (char *, int);
 198     void (*to_close) (int);
 199     void (*to_attach) (char *, int);
 200     void (*to_post_attach) (int);
 201     void (*to_detach) (char *, int);
 202     void (*to_disconnect) (char *, int);
 203     void (*to_resume) (ptid_t, int, enum target_signal);
 204     ptid_t (*to_wait) (ptid_t, struct target_waitstatus *);
 205     void (*to_post_wait) (ptid_t, int);
 206     void (*to_fetch_registers) (int);
 207     void (*to_store_registers) (int);
 208     void (*to_prepare_to_store) (void);
 209
 210     /* Transfer LEN bytes of memory between GDB address MYADDR and
 211        target address MEMADDR.  If WRITE, transfer them to the target, else
 212        transfer them from the target.  TARGET is the target from which we
 213        get this function.
 214
 215        Return value, N, is one of the following:
 216
 217        0 means that we can't handle this.  If errno has been set, it is the
 218        error which prevented us from doing it (FIXME: What about bfd_error?).
 219
 220        positive (call it N) means that we have transferred N bytes
 221        starting at MEMADDR.  We might be able to handle more bytes
 222        beyond this length, but no promises.
 223
 224        negative (call its absolute value N) means that we cannot
 225        transfer right at MEMADDR, but we could transfer at least
 226        something at MEMADDR + N.  */
 227
 228     int (*to_xfer_memory) (CORE_ADDR memaddr, char *myaddr,
 229                            int len, int write,
 230                            struct mem_attrib *attrib,
 231                            struct target_ops *target);
 232
 233     void (*to_files_info) (struct target_ops *);
 234     int (*to_insert_breakpoint) (CORE_ADDR, char *);
 235     int (*to_remove_breakpoint) (CORE_ADDR, char *);
 236     int (*to_can_use_hw_breakpoint) (int, int, int);
 237     int (*to_insert_hw_breakpoint) (CORE_ADDR, char *);
 238     int (*to_remove_hw_breakpoint) (CORE_ADDR, char *);
 239     int (*to_remove_watchpoint) (CORE_ADDR, int, int);
 240     int (*to_insert_watchpoint) (CORE_ADDR, int, int);
 241     int (*to_stopped_by_watchpoint) (void);
 242     int to_have_continuable_watchpoint;
 243     CORE_ADDR (*to_stopped_data_address) (void);
 244     int (*to_region_size_ok_for_hw_watchpoint) (int);
 245     void (*to_terminal_init) (void);
 246     void (*to_terminal_inferior) (void);
 247     void (*to_terminal_ours_for_output) (void);
 248     void (*to_terminal_ours) (void);
 249     void (*to_terminal_save_ours) (void);
 250     void (*to_terminal_info) (char *, int);
 251     void (*to_kill) (void);
 252     void (*to_load) (char *, int);
 253     int (*to_lookup_symbol) (char *, CORE_ADDR *);
 254     void (*to_create_inferior) (char *, char *, char **);
 255     void (*to_post_startup_inferior) (ptid_t);
 256     void (*to_acknowledge_created_inferior) (int);
 257     int (*to_insert_fork_catchpoint) (int);
 258     int (*to_remove_fork_catchpoint) (int);
 259     int (*to_insert_vfork_catchpoint) (int);
 260     int (*to_remove_vfork_catchpoint) (int);
 261     int (*to_follow_fork) (int);
 262     int (*to_insert_exec_catchpoint) (int);
 263     int (*to_remove_exec_catchpoint) (int);
 264     int (*to_reported_exec_events_per_exec_call) (void);
 265     int (*to_has_exited) (int, int, int *);
 266     void (*to_mourn_inferior) (void);
 267     int (*to_can_run) (void);
 268     void (*to_notice_signals) (ptid_t ptid);
 269     int (*to_thread_alive) (ptid_t ptid);
 270     void (*to_find_new_threads) (void);
 271     char *(*to_pid_to_str) (ptid_t);
 272     char *(*to_extra_thread_info) (struct thread_info *);
 273     void (*to_stop) (void);
 274     int (*to_query) (int /*char */ , char *, char *, int *);
 275     void (*to_rcmd) (char *command, struct ui_file *output);
 276     struct symtab_and_line *(*to_enable_exception_callback) (enum
 277                                                              exception_event_kind,
 278                                                              int);
 279     struct exception_event_record *(*to_get_current_exception_event) (void);
 280     char *(*to_pid_to_exec_file) (int pid);
 281     enum strata to_stratum;
 282     int to_has_all_memory;
 283     int to_has_memory;
 284     int to_has_stack;
 285     int to_has_registers;
 286     int to_has_execution;
 287     int to_has_thread_control;  /* control thread execution */
 288     struct section_table
 289      *to_sections;
 290     struct section_table
 291      *to_sections_end;
 292     /* ASYNC target controls */
 293     int (*to_can_async_p) (void);
 294     int (*to_is_async_p) (void);
 295     void (*to_async) (void (*cb) (enum inferior_event_type, void *context),
 296                       void *context);
 297     int to_async_mask_value;
 298     int (*to_find_memory_regions) (int (*) (CORE_ADDR,
 299                                             unsigned long,
 300                                             int, int, int,
 301                                             void *),
 302                                    void *);
 303     char * (*to_make_corefile_notes) (bfd *, int *);
 304
 305     /* Return the thread-local address at OFFSET in the
 306        thread-local storage for the thread PTID and the shared library
 307        or executable file given by OBJFILE.  If that block of
 308        thread-local storage hasn't been allocated yet, this function
 309        may return an error.  */
 310     CORE_ADDR (*to_get_thread_local_address) (ptid_t ptid,
 311                                               struct objfile *objfile,
 312                                               CORE_ADDR offset);
 313
 314     int to_magic;
 315     /* Need sub-structure for target machine related rather than comm related?
 316      */
 317   };
 318
 319 /* Magic number for checking ops size.  If a struct doesn't end with this
 320    number, somebody changed the declaration but didn't change all the
 321    places that initialize one.  */
 322
 323 #define OPS_MAGIC       3840
 324
 325 /* The ops structure for our "current" target process.  This should
 326    never be NULL.  If there is no target, it points to the dummy_target.  */
 327
 328 extern struct target_ops current_target;
 329
 330 /* Define easy words for doing these operations on our current target.  */
 331
 332 #define target_shortname        (current_target.to_shortname)
 333 #define target_longname         (current_target.to_longname)
 334
 335 /* The open routine takes the rest of the parameters from the command,
 336    and (if successful) pushes a new target onto the stack.
 337    Targets should supply this routine, if only to provide an error message.  */
 338
 339 #define target_open(name, from_tty)                                     \
 340   do {                                                                  \
 341     dcache_invalidate (target_dcache);                                  \
 342     (*current_target.to_open) (name, from_tty);                         \
 343   } while (0)
 344
 345 /* Does whatever cleanup is required for a target that we are no longer
 346    going to be calling.  Argument says whether we are quitting gdb and
 347    should not get hung in case of errors, or whether we want a clean
 348    termination even if it takes a while.  This routine is automatically
 349    always called just before a routine is popped off the target stack.
 350    Closing file descriptors and freeing memory are typical things it should
 351    do.  */
 352
 353 #define target_close(quitting)  \
 354      (*current_target.to_close) (quitting)
 355
 356 /* Attaches to a process on the target side.  Arguments are as passed
 357    to the `attach' command by the user.  This routine can be called
 358    when the target is not on the target-stack, if the target_can_run
 359    routine returns 1; in that case, it must push itself onto the stack.
 360    Upon exit, the target should be ready for normal operations, and
 361    should be ready to deliver the status of the process immediately
 362    (without waiting) to an upcoming target_wait call.  */
 363
 364 #define target_attach(args, from_tty)   \
 365      (*current_target.to_attach) (args, from_tty)
 366
 367 /* The target_attach operation places a process under debugger control,
 368    and stops the process.
 369
 370    This operation provides a target-specific hook that allows the
 371    necessary bookkeeping to be performed after an attach completes.  */
 372 #define target_post_attach(pid) \
 373      (*current_target.to_post_attach) (pid)
 374
 375 /* Takes a program previously attached to and detaches it.
 376    The program may resume execution (some targets do, some don't) and will
 377    no longer stop on signals, etc.  We better not have left any breakpoints
 378    in the program or it'll die when it hits one.  ARGS is arguments
 379    typed by the user (e.g. a signal to send the process).  FROM_TTY
 380    says whether to be verbose or not.  */
 381
 382 extern void target_detach (char *, int);
 383
 384 /* Disconnect from the current target without resuming it (leaving it
 385    waiting for a debugger).  */
 386
 387 extern void target_disconnect (char *, int);
 388
 389 /* Resume execution of the target process PTID.  STEP says whether to
 390    single-step or to run free; SIGGNAL is the signal to be given to
 391    the target, or TARGET_SIGNAL_0 for no signal.  The caller may not
 392    pass TARGET_SIGNAL_DEFAULT.  */
 393
 394 #define target_resume(ptid, step, siggnal)                              \
 395   do {                                                                  \
 396     dcache_invalidate(target_dcache);                                   \
 397     (*current_target.to_resume) (ptid, step, siggnal);                  \
 398   } while (0)
 399
 400 /* Wait for process pid to do something.  PTID = -1 to wait for any
 401    pid to do something.  Return pid of child, or -1 in case of error;
 402    store status through argument pointer STATUS.  Note that it is
 403    _NOT_ OK to throw_exception() out of target_wait() without popping
 404    the debugging target from the stack; GDB isn't prepared to get back
 405    to the prompt with a debugging target but without the frame cache,
 406    stop_pc, etc., set up.  */
 407
 408 #define target_wait(ptid, status)               \
 409      (*current_target.to_wait) (ptid, status)
 410
 411 /* The target_wait operation waits for a process event to occur, and
 412    thereby stop the process.
 413
 414    On some targets, certain events may happen in sequences.  gdb's
 415    correct response to any single event of such a sequence may require
 416    knowledge of what earlier events in the sequence have been seen.
 417
 418    This operation provides a target-specific hook that allows the
 419    necessary bookkeeping to be performed to track such sequences.  */
 420
 421 #define target_post_wait(ptid, status) \
 422      (*current_target.to_post_wait) (ptid, status)
 423
 424 /* Fetch at least register REGNO, or all regs if regno == -1.  No result.  */
 425
 426 #define target_fetch_registers(regno)   \
 427      (*current_target.to_fetch_registers) (regno)
 428
 429 /* Store at least register REGNO, or all regs if REGNO == -1.
 430    It can store as many registers as it wants to, so target_prepare_to_store
 431    must have been previously called.  Calls error() if there are problems.  */
 432
 433 #define target_store_registers(regs)    \
 434      (*current_target.to_store_registers) (regs)
 435
 436 /* Get ready to modify the registers array.  On machines which store
 437    individual registers, this doesn't need to do anything.  On machines
 438    which store all the registers in one fell swoop, this makes sure
 439    that REGISTERS contains all the registers from the program being
 440    debugged.  */
 441
 442 #define target_prepare_to_store()       \
 443      (*current_target.to_prepare_to_store) ()
 444
 445 extern DCACHE *target_dcache;
 446
 447 extern int do_xfer_memory (CORE_ADDR memaddr, char *myaddr, int len, int write,
 448                            struct mem_attrib *attrib);
 449
 450 extern int target_read_string (CORE_ADDR, char **, int, int *);
 451
 452 extern int target_read_memory (CORE_ADDR memaddr, char *myaddr, int len);
 453
 454 extern int target_write_memory (CORE_ADDR memaddr, char *myaddr, int len);
 455
 456 extern int xfer_memory (CORE_ADDR, char *, int, int,
 457                         struct mem_attrib *, struct target_ops *);
 458
 459 extern int child_xfer_memory (CORE_ADDR, char *, int, int,
 460                               struct mem_attrib *, struct target_ops *);
 461
 462 /* Make a single attempt at transfering LEN bytes.  On a successful
 463    transfer, the number of bytes actually transfered is returned and
 464    ERR is set to 0.  When a transfer fails, -1 is returned (the number
 465    of bytes actually transfered is not defined) and ERR is set to a
 466    non-zero error indication.  */
 467
 468 extern int target_read_memory_partial (CORE_ADDR addr, char *buf, int len,
 469                                        int *err);
 470
 471 extern int target_write_memory_partial (CORE_ADDR addr, char *buf, int len,
 472                                         int *err);
 473
 474 extern char *child_pid_to_exec_file (int);
 475
 476 extern char *child_core_file_to_sym_file (char *);
 477
 478 #if defined(CHILD_POST_ATTACH)
 479 extern void child_post_attach (int);
 480 #endif
 481
 482 extern void child_post_wait (ptid_t, int);
 483
 484 extern void child_post_startup_inferior (ptid_t);
 485
 486 extern void child_acknowledge_created_inferior (int);
 487
 488 extern int child_insert_fork_catchpoint (int);
 489
 490 extern int child_remove_fork_catchpoint (int);
 491
 492 extern int child_insert_vfork_catchpoint (int);
 493
 494 extern int child_remove_vfork_catchpoint (int);
 495
 496 extern void child_acknowledge_created_inferior (int);
 497
 498 extern int child_follow_fork (int);
 499
 500 extern int child_insert_exec_catchpoint (int);
 501
 502 extern int child_remove_exec_catchpoint (int);
 503
 504 extern int child_reported_exec_events_per_exec_call (void);
 505
 506 extern int child_has_exited (int, int, int *);
 507
 508 extern int child_thread_alive (ptid_t);
 509
 510 /* From infrun.c.  */
 511
 512 extern int inferior_has_forked (int pid, int *child_pid);
 513
 514 extern int inferior_has_vforked (int pid, int *child_pid);
 515
 516 extern int inferior_has_execd (int pid, char **execd_pathname);
 517
 518 /* From exec.c */
 519
 520 extern void print_section_info (struct target_ops *, bfd *);
 521
 522 /* Print a line about the current target.  */
 523
 524 #define target_files_info()     \
 525      (*current_target.to_files_info) (&current_target)
 526
 527 /* Insert a breakpoint at address ADDR in the target machine.  SAVE is
 528    a pointer to memory allocated for saving the target contents.  It
 529    is guaranteed by the caller to be long enough to save the number of
 530    breakpoint bytes indicated by BREAKPOINT_FROM_PC.  Result is 0 for
 531    success, or an errno value.  */
 532
 533 #define target_insert_breakpoint(addr, save)    \
 534      (*current_target.to_insert_breakpoint) (addr, save)
 535
 536 /* Remove a breakpoint at address ADDR in the target machine.
 537    SAVE is a pointer to the same save area
 538    that was previously passed to target_insert_breakpoint.
 539    Result is 0 for success, or an errno value.  */
 540
 541 #define target_remove_breakpoint(addr, save)    \
 542      (*current_target.to_remove_breakpoint) (addr, save)
 543
 544 /* Initialize the terminal settings we record for the inferior,
 545    before we actually run the inferior.  */
 546
 547 #define target_terminal_init() \
 548      (*current_target.to_terminal_init) ()
 549
 550 /* Put the inferior's terminal settings into effect.
 551    This is preparation for starting or resuming the inferior.  */
 552
 553 #define target_terminal_inferior() \
 554      (*current_target.to_terminal_inferior) ()
 555
 556 /* Put some of our terminal settings into effect,
 557    enough to get proper results from our output,
 558    but do not change into or out of RAW mode
 559    so that no input is discarded.
 560
 561    After doing this, either terminal_ours or terminal_inferior
 562    should be called to get back to a normal state of affairs.  */
 563
 564 #define target_terminal_ours_for_output() \
 565      (*current_target.to_terminal_ours_for_output) ()
 566
 567 /* Put our terminal settings into effect.
 568    First record the inferior's terminal settings
 569    so they can be restored properly later.  */
 570
 571 #define target_terminal_ours() \
 572      (*current_target.to_terminal_ours) ()
 573
 574 /* Save our terminal settings.
 575    This is called from TUI after entering or leaving the curses
 576    mode.  Since curses modifies our terminal this call is here
 577    to take this change into account.  */
 578
 579 #define target_terminal_save_ours() \
 580      (*current_target.to_terminal_save_ours) ()
 581
 582 /* Print useful information about our terminal status, if such a thing
 583    exists.  */
 584
 585 #define target_terminal_info(arg, from_tty) \
 586      (*current_target.to_terminal_info) (arg, from_tty)
 587
 588 /* Kill the inferior process.   Make it go away.  */
 589
 590 #define target_kill() \
 591      (*current_target.to_kill) ()
 592
 593 /* Load an executable file into the target process.  This is expected
 594    to not only bring new code into the target process, but also to
 595    update GDB's symbol tables to match.  */
 596
 597 extern void target_load (char *arg, int from_tty);
 598
 599 /* Look up a symbol in the target's symbol table.  NAME is the symbol
 600    name.  ADDRP is a CORE_ADDR * pointing to where the value of the
 601    symbol should be returned.  The result is 0 if successful, nonzero
 602    if the symbol does not exist in the target environment.  This
 603    function should not call error() if communication with the target
 604    is interrupted, since it is called from symbol reading, but should
 605    return nonzero, possibly doing a complain().  */
 606
 607 #define target_lookup_symbol(name, addrp) \
 608      (*current_target.to_lookup_symbol) (name, addrp)
 609
 610 /* Start an inferior process and set inferior_ptid to its pid.
 611    EXEC_FILE is the file to run.
 612    ALLARGS is a string containing the arguments to the program.
 613    ENV is the environment vector to pass.  Errors reported with error().
 614    On VxWorks and various standalone systems, we ignore exec_file.  */
 615
 616 #define target_create_inferior(exec_file, args, env)    \
 617      (*current_target.to_create_inferior) (exec_file, args, env)
 618
 619
 620 /* Some targets (such as ttrace-based HPUX) don't allow us to request
 621    notification of inferior events such as fork and vork immediately
 622    after the inferior is created.  (This because of how gdb gets an
 623    inferior created via invoking a shell to do it.  In such a scenario,
 624    if the shell init file has commands in it, the shell will fork and
 625    exec for each of those commands, and we will see each such fork
 626    event.  Very bad.)
 627
 628    Such targets will supply an appropriate definition for this function.  */
 629
 630 #define target_post_startup_inferior(ptid) \
 631      (*current_target.to_post_startup_inferior) (ptid)
 632
 633 /* On some targets, the sequence of starting up an inferior requires
 634    some synchronization between gdb and the new inferior process, PID.  */
 635
 636 #define target_acknowledge_created_inferior(pid) \
 637      (*current_target.to_acknowledge_created_inferior) (pid)
 638
 639 /* On some targets, we can catch an inferior fork or vfork event when
 640    it occurs.  These functions insert/remove an already-created
 641    catchpoint for such events.  */
 642
 643 #define target_insert_fork_catchpoint(pid) \
 644      (*current_target.to_insert_fork_catchpoint) (pid)
 645
 646 #define target_remove_fork_catchpoint(pid) \
 647      (*current_target.to_remove_fork_catchpoint) (pid)
 648
 649 #define target_insert_vfork_catchpoint(pid) \
 650      (*current_target.to_insert_vfork_catchpoint) (pid)
 651
 652 #define target_remove_vfork_catchpoint(pid) \
 653      (*current_target.to_remove_vfork_catchpoint) (pid)
 654
 655 /* If the inferior forks or vforks, this function will be called at
 656    the next resume in order to perform any bookkeeping and fiddling
 657    necessary to continue debugging either the parent or child, as
 658    requested, and releasing the other.  Information about the fork
 659    or vfork event is available via get_last_target_status ().
 660    This function returns 1 if the inferior should not be resumed
 661    (i.e. there is another event pending).  */
 662
 663 #define target_follow_fork(follow_child) \
 664      (*current_target.to_follow_fork) (follow_child)
 665
 666 /* On some targets, we can catch an inferior exec event when it
 667    occurs.  These functions insert/remove an already-created
 668    catchpoint for such events.  */
 669
 670 #define target_insert_exec_catchpoint(pid) \
 671      (*current_target.to_insert_exec_catchpoint) (pid)
 672
 673 #define target_remove_exec_catchpoint(pid) \
 674      (*current_target.to_remove_exec_catchpoint) (pid)
 675
 676 /* Returns the number of exec events that are reported when a process
 677    invokes a flavor of the exec() system call on this target, if exec
 678    events are being reported.  */
 679
 680 #define target_reported_exec_events_per_exec_call() \
 681      (*current_target.to_reported_exec_events_per_exec_call) ()
 682
 683 /* Returns TRUE if PID has exited.  And, also sets EXIT_STATUS to the
 684    exit code of PID, if any.  */
 685
 686 #define target_has_exited(pid,wait_status,exit_status) \
 687      (*current_target.to_has_exited) (pid,wait_status,exit_status)
 688
 689 /* The debugger has completed a blocking wait() call.  There is now
 690    some process event that must be processed.  This function should
 691    be defined by those targets that require the debugger to perform
 692    cleanup or internal state changes in response to the process event.  */
 693
 694 /* The inferior process has died.  Do what is right.  */
 695
 696 #define target_mourn_inferior() \
 697      (*current_target.to_mourn_inferior) ()
 698
 699 /* Does target have enough data to do a run or attach command? */
 700
 701 #define target_can_run(t) \
 702      ((t)->to_can_run) ()
 703
 704 /* post process changes to signal handling in the inferior.  */
 705
 706 #define target_notice_signals(ptid) \
 707      (*current_target.to_notice_signals) (ptid)
 708
 709 /* Check to see if a thread is still alive.  */
 710
 711 #define target_thread_alive(ptid) \
 712      (*current_target.to_thread_alive) (ptid)
 713
 714 /* Query for new threads and add them to the thread list.  */
 715
 716 #define target_find_new_threads() \
 717      (*current_target.to_find_new_threads) (); \
 718
 719 /* Make target stop in a continuable fashion.  (For instance, under
 720    Unix, this should act like SIGSTOP).  This function is normally
 721    used by GUIs to implement a stop button.  */
 722
 723 #define target_stop current_target.to_stop
 724
 725 /* Queries the target side for some information.  The first argument is a
 726    letter specifying the type of the query, which is used to determine who
 727    should process it.  The second argument is a string that specifies which
 728    information is desired and the third is a buffer that carries back the
 729    response from the target side. The fourth parameter is the size of the
 730    output buffer supplied.  */
 731
 732 #define target_query(query_type, query, resp_buffer, bufffer_size)      \
 733      (*current_target.to_query) (query_type, query, resp_buffer, bufffer_size)
 734
 735 /* Send the specified COMMAND to the target's monitor
 736    (shell,interpreter) for execution.  The result of the query is
 737    placed in OUTBUF.  */
 738
 739 #define target_rcmd(command, outbuf) \
 740      (*current_target.to_rcmd) (command, outbuf)
 741
 742
 743 /* Get the symbol information for a breakpointable routine called when
 744    an exception event occurs.
 745    Intended mainly for C++, and for those
 746    platforms/implementations where such a callback mechanism is available,
 747    e.g. HP-UX with ANSI C++ (aCC).  Some compilers (e.g. g++) support
 748    different mechanisms for debugging exceptions.  */
 749
 750 #define target_enable_exception_callback(kind, enable) \
 751      (*current_target.to_enable_exception_callback) (kind, enable)
 752
 753 /* Get the current exception event kind -- throw or catch, etc.  */
 754
 755 #define target_get_current_exception_event() \
 756      (*current_target.to_get_current_exception_event) ()
 757
 758 /* Does the target include all of memory, or only part of it?  This
 759    determines whether we look up the target chain for other parts of
 760    memory if this target can't satisfy a request.  */
 761
 762 #define target_has_all_memory   \
 763      (current_target.to_has_all_memory)
 764
 765 /* Does the target include memory?  (Dummy targets don't.)  */
 766
 767 #define target_has_memory       \
 768      (current_target.to_has_memory)
 769
 770 /* Does the target have a stack?  (Exec files don't, VxWorks doesn't, until
 771    we start a process.)  */
 772
 773 #define target_has_stack        \
 774      (current_target.to_has_stack)
 775
 776 /* Does the target have registers?  (Exec files don't.)  */
 777
 778 #define target_has_registers    \
 779      (current_target.to_has_registers)
 780
 781 /* Does the target have execution?  Can we make it jump (through
 782    hoops), or pop its stack a few times?  FIXME: If this is to work that
 783    way, it needs to check whether an inferior actually exists.
 784    remote-udi.c and probably other targets can be the current target
 785    when the inferior doesn't actually exist at the moment.  Right now
 786    this just tells us whether this target is *capable* of execution.  */
 787
 788 #define target_has_execution    \
 789      (current_target.to_has_execution)
 790
 791 /* Can the target support the debugger control of thread execution?
 792    a) Can it lock the thread scheduler?
 793    b) Can it switch the currently running thread?  */
 794
 795 #define target_can_lock_scheduler \
 796      (current_target.to_has_thread_control & tc_schedlock)
 797
 798 #define target_can_switch_threads \
 799      (current_target.to_has_thread_control & tc_switch)
 800
 801 /* Can the target support asynchronous execution? */
 802 #define target_can_async_p() (current_target.to_can_async_p ())
 803
 804 /* Is the target in asynchronous execution mode? */
 805 #define target_is_async_p() (current_target.to_is_async_p())
 806
 807 /* Put the target in async mode with the specified callback function. */
 808 #define target_async(CALLBACK,CONTEXT) \
 809      (current_target.to_async((CALLBACK), (CONTEXT)))
 810
 811 /* This is to be used ONLY within call_function_by_hand(). It provides
 812    a workaround, to have inferior function calls done in sychronous
 813    mode, even though the target is asynchronous. After
 814    target_async_mask(0) is called, calls to target_can_async_p() will
 815    return FALSE , so that target_resume() will not try to start the
 816    target asynchronously. After the inferior stops, we IMMEDIATELY
 817    restore the previous nature of the target, by calling
 818    target_async_mask(1). After that, target_can_async_p() will return
 819    TRUE. ANY OTHER USE OF THIS FEATURE IS DEPRECATED.
 820
 821    FIXME ezannoni 1999-12-13: we won't need this once we move
 822    the turning async on and off to the single execution commands,
 823    from where it is done currently, in remote_resume().  */
 824
 825 #define target_async_mask_value \
 826      (current_target.to_async_mask_value)
 827
 828 extern int target_async_mask (int mask);
 829
 830 extern void target_link (char *, CORE_ADDR *);
 831
 832 /* Converts a process id to a string.  Usually, the string just contains
 833    `process xyz', but on some systems it may contain
 834    `process xyz thread abc'.  */
 835
 836 #undef target_pid_to_str
 837 #define target_pid_to_str(PID) current_target.to_pid_to_str (PID)
 838
 839 #ifndef target_tid_to_str
 840 #define target_tid_to_str(PID) \
 841      target_pid_to_str (PID)
 842 extern char *normal_pid_to_str (ptid_t ptid);
 843 #endif
 844
 845 /* Return a short string describing extra information about PID,
 846    e.g. "sleeping", "runnable", "running on LWP 3".  Null return value
 847    is okay.  */
 848
 849 #define target_extra_thread_info(TP) \
 850      (current_target.to_extra_thread_info (TP))
 851
 852 /*
 853  * New Objfile Event Hook:
 854  *
 855  * Sometimes a GDB component wants to get notified whenever a new
 856  * objfile is loaded.  Mainly this is used by thread-debugging
 857  * implementations that need to know when symbols for the target
 858  * thread implemenation are available.
 859  *
 860  * The old way of doing this is to define a macro 'target_new_objfile'
 861  * that points to the function that you want to be called on every
 862  * objfile/shlib load.
 863  *
 864  * The new way is to grab the function pointer, 'target_new_objfile_hook',
 865  * and point it to the function that you want to be called on every
 866  * objfile/shlib load.
 867  *
 868  * If multiple clients are willing to be cooperative, they can each
 869  * save a pointer to the previous value of target_new_objfile_hook
 870  * before modifying it, and arrange for their function to call the
 871  * previous function in the chain.  In that way, multiple clients
 872  * can receive this notification (something like with signal handlers).
 873  */
 874
 875 extern void (*target_new_objfile_hook) (struct objfile *);
 876
 877 #ifndef target_pid_or_tid_to_str
 878 #define target_pid_or_tid_to_str(ID) \
 879      target_pid_to_str (ID)
 880 #endif
 881
 882 /* Attempts to find the pathname of the executable file
 883    that was run to create a specified process.
 884
 885    The process PID must be stopped when this operation is used.
 886
 887    If the executable file cannot be determined, NULL is returned.
 888
 889    Else, a pointer to a character string containing the pathname
 890    is returned.  This string should be copied into a buffer by
 891    the client if the string will not be immediately used, or if
 892    it must persist.  */
 893
 894 #define target_pid_to_exec_file(pid) \
 895      (current_target.to_pid_to_exec_file) (pid)
 896
 897 /*
 898  * Iterator function for target memory regions.
 899  * Calls a callback function once for each memory region 'mapped'
 900  * in the child process.  Defined as a simple macro rather than
 901  * as a function macro so that it can be tested for nullity.
 902  */
 903
 904 #define target_find_memory_regions(FUNC, DATA) \
 905      (current_target.to_find_memory_regions) (FUNC, DATA)
 906
 907 /*
 908  * Compose corefile .note section.
 909  */
 910
 911 #define target_make_corefile_notes(BFD, SIZE_P) \
 912      (current_target.to_make_corefile_notes) (BFD, SIZE_P)
 913
 914 /* Thread-local values.  */
 915 #define target_get_thread_local_address \
 916     (current_target.to_get_thread_local_address)
 917 #define target_get_thread_local_address_p() \
 918     (target_get_thread_local_address != NULL)
 919
 920 /* Hook to call target dependent code just after inferior target process has
 921    started.  */
 922
 923 #ifndef TARGET_CREATE_INFERIOR_HOOK
 924 #define TARGET_CREATE_INFERIOR_HOOK(PID)
 925 #endif
 926
 927 /* Hardware watchpoint interfaces.  */
 928
 929 /* Returns non-zero if we were stopped by a hardware watchpoint (memory read or
 930    write).  */
 931
 932 #ifndef STOPPED_BY_WATCHPOINT
 933 #define STOPPED_BY_WATCHPOINT(w) \
 934    (*current_target.to_stopped_by_watchpoint) ()
 935 #endif
 936
 937 /* Non-zero if we have continuable watchpoints  */
 938
 939 #ifndef HAVE_CONTINUABLE_WATCHPOINT
 940 #define HAVE_CONTINUABLE_WATCHPOINT \
 941    (current_target.to_have_continuable_watchpoint)
 942 #endif
 943
 944 /* HP-UX supplies these operations, which respectively disable and enable
 945    the memory page-protections that are used to implement hardware watchpoints
 946    on that platform.  See wait_for_inferior's use of these.  */
 947
 948 #if !defined(TARGET_DISABLE_HW_WATCHPOINTS)
 949 #define TARGET_DISABLE_HW_WATCHPOINTS(pid)
 950 #endif
 951
 952 #if !defined(TARGET_ENABLE_HW_WATCHPOINTS)
 953 #define TARGET_ENABLE_HW_WATCHPOINTS(pid)
 954 #endif
 955
 956 /* Provide defaults for hardware watchpoint functions.  */
 957
 958 /* If the *_hw_beakpoint functions have not been defined
 959    elsewhere use the definitions in the target vector.  */
 960
 961 /* Returns non-zero if we can set a hardware watchpoint of type TYPE.  TYPE is
 962    one of bp_hardware_watchpoint, bp_read_watchpoint, bp_write_watchpoint, or
 963    bp_hardware_breakpoint.  CNT is the number of such watchpoints used so far
 964    (including this one?).  OTHERTYPE is who knows what...  */
 965
 966 #ifndef TARGET_CAN_USE_HARDWARE_WATCHPOINT
 967 #define TARGET_CAN_USE_HARDWARE_WATCHPOINT(TYPE,CNT,OTHERTYPE) \
 968  (*current_target.to_can_use_hw_breakpoint) (TYPE, CNT, OTHERTYPE);
 969 #endif
 970
 971 #if !defined(TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT)
 972 #define TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT(byte_count) \
 973     (*current_target.to_region_size_ok_for_hw_watchpoint) (byte_count)
 974 #endif
 975
 976
 977 /* Set/clear a hardware watchpoint starting at ADDR, for LEN bytes.  TYPE is 0
 978    for write, 1 for read, and 2 for read/write accesses.  Returns 0 for
 979    success, non-zero for failure.  */
 980
 981 #ifndef target_insert_watchpoint
 982 #define target_insert_watchpoint(addr, len, type)       \
 983      (*current_target.to_insert_watchpoint) (addr, len, type)
 984
 985 #define target_remove_watchpoint(addr, len, type)       \
 986      (*current_target.to_remove_watchpoint) (addr, len, type)
 987 #endif
 988
 989 #ifndef target_insert_hw_breakpoint
 990 #define target_insert_hw_breakpoint(addr, save) \
 991      (*current_target.to_insert_hw_breakpoint) (addr, save)
 992
 993 #define target_remove_hw_breakpoint(addr, save) \
 994      (*current_target.to_remove_hw_breakpoint) (addr, save)
 995 #endif
 996
 997 #ifndef target_stopped_data_address
 998 #define target_stopped_data_address() \
 999     (*current_target.to_stopped_data_address) ()
1000 #endif
1001
1002 /* If defined, then we need to decr pc by this much after a hardware break-
1003    point.  Presumably this overrides DECR_PC_AFTER_BREAK...  */
1004
1005 #ifndef DECR_PC_AFTER_HW_BREAK
1006 #define DECR_PC_AFTER_HW_BREAK 0
1007 #endif
1008
1009 /* Sometimes gdb may pick up what appears to be a valid target address
1010    from a minimal symbol, but the value really means, essentially,
1011    "This is an index into a table which is populated when the inferior
1012    is run.  Therefore, do not attempt to use this as a PC."  */
1013
1014 #if !defined(PC_REQUIRES_RUN_BEFORE_USE)
1015 #define PC_REQUIRES_RUN_BEFORE_USE(pc) (0)
1016 #endif
1017
1018 /* This will only be defined by a target that supports catching vfork events,
1019    such as HP-UX.
1020
1021    On some targets (such as HP-UX 10.20 and earlier), resuming a newly vforked
1022    child process after it has exec'd, causes the parent process to resume as
1023    well.  To prevent the parent from running spontaneously, such targets should
1024    define this to a function that prevents that from happening.  */
1025 #if !defined(ENSURE_VFORKING_PARENT_REMAINS_STOPPED)
1026 #define ENSURE_VFORKING_PARENT_REMAINS_STOPPED(PID) (0)
1027 #endif
1028
1029 /* This will only be defined by a target that supports catching vfork events,
1030    such as HP-UX.
1031
1032    On some targets (such as HP-UX 10.20 and earlier), a newly vforked child
1033    process must be resumed when it delivers its exec event, before the parent
1034    vfork event will be delivered to us.  */
1035
1036 #if !defined(RESUME_EXECD_VFORKING_CHILD_TO_GET_PARENT_VFORK)
1037 #define RESUME_EXECD_VFORKING_CHILD_TO_GET_PARENT_VFORK() (0)
1038 #endif
1039
1040 /* Routines for maintenance of the target structures...
1041
1042    add_target:   Add a target to the list of all possible targets.
1043
1044    push_target:  Make this target the top of the stack of currently used
1045    targets, within its particular stratum of the stack.  Result
1046    is 0 if now atop the stack, nonzero if not on top (maybe
1047    should warn user).
1048
1049    unpush_target: Remove this from the stack of currently used targets,
1050    no matter where it is on the list.  Returns 0 if no
1051    change, 1 if removed from stack.
1052
1053    pop_target:   Remove the top thing on the stack of current targets.  */
1054
1055 extern void add_target (struct target_ops *);
1056
1057 extern int push_target (struct target_ops *);
1058
1059 extern int unpush_target (struct target_ops *);
1060
1061 extern void target_preopen (int);
1062
1063 extern void pop_target (void);
1064
1065 /* Struct section_table maps address ranges to file sections.  It is
1066    mostly used with BFD files, but can be used without (e.g. for handling
1067    raw disks, or files not in formats handled by BFD).  */
1068
1069 struct section_table
1070   {
1071     CORE_ADDR addr;             /* Lowest address in section */
1072     CORE_ADDR endaddr;          /* 1+highest address in section */
1073
1074     sec_ptr the_bfd_section;
1075
1076     bfd *bfd;                   /* BFD file pointer */
1077   };
1078
1079 /* Builds a section table, given args BFD, SECTABLE_PTR, SECEND_PTR.
1080    Returns 0 if OK, 1 on error.  */
1081
1082 extern int build_section_table (bfd *, struct section_table **,
1083                                 struct section_table **);
1084
1085 /* From mem-break.c */
1086
1087 extern int memory_remove_breakpoint (CORE_ADDR, char *);
1088
1089 extern int memory_insert_breakpoint (CORE_ADDR, char *);
1090
1091 extern int default_memory_remove_breakpoint (CORE_ADDR, char *);
1092
1093 extern int default_memory_insert_breakpoint (CORE_ADDR, char *);
1094
1095
1096 /* From target.c */
1097
1098 extern void initialize_targets (void);
1099
1100 extern void noprocess (void);
1101
1102 extern void find_default_attach (char *, int);
1103
1104 extern void find_default_create_inferior (char *, char *, char **);
1105
1106 extern struct target_ops *find_run_target (void);
1107
1108 extern struct target_ops *find_core_target (void);
1109
1110 extern struct target_ops *find_target_beneath (struct target_ops *);
1111
1112 extern int target_resize_to_sections (struct target_ops *target,
1113                                       int num_added);
1114
1115 extern void remove_target_sections (bfd *abfd);
1116
1117 \f
1118 /* Stuff that should be shared among the various remote targets.  */
1119
1120 /* Debugging level.  0 is off, and non-zero values mean to print some debug
1121    information (higher values, more information).  */
1122 extern int remote_debug;
1123
1124 /* Speed in bits per second, or -1 which means don't mess with the speed.  */
1125 extern int baud_rate;
1126 /* Timeout limit for response from target. */
1127 extern int remote_timeout;
1128
1129 \f
1130 /* Functions for helping to write a native target.  */
1131
1132 /* This is for native targets which use a unix/POSIX-style waitstatus.  */
1133 extern void store_waitstatus (struct target_waitstatus *, int);
1134
1135 /* Predicate to target_signal_to_host(). Return non-zero if the enum
1136    targ_signal SIGNO has an equivalent ``host'' representation.  */
1137 /* FIXME: cagney/1999-11-22: The name below was chosen in preference
1138    to the shorter target_signal_p() because it is far less ambigious.
1139    In this context ``target_signal'' refers to GDB's internal
1140    representation of the target's set of signals while ``host signal''
1141    refers to the target operating system's signal.  Confused?  */
1142
1143 extern int target_signal_to_host_p (enum target_signal signo);
1144
1145 /* Convert between host signal numbers and enum target_signal's.
1146    target_signal_to_host() returns 0 and prints a warning() on GDB's
1147    console if SIGNO has no equivalent host representation.  */
1148 /* FIXME: cagney/1999-11-22: Here ``host'' is used incorrectly, it is
1149    refering to the target operating system's signal numbering.
1150    Similarly, ``enum target_signal'' is named incorrectly, ``enum
1151    gdb_signal'' would probably be better as it is refering to GDB's
1152    internal representation of a target operating system's signal.  */
1153
1154 extern enum target_signal target_signal_from_host (int);
1155 extern int target_signal_to_host (enum target_signal);
1156
1157 /* Convert from a number used in a GDB command to an enum target_signal.  */
1158 extern enum target_signal target_signal_from_command (int);
1159
1160 /* Any target can call this to switch to remote protocol (in remote.c). */
1161 extern void push_remote_target (char *name, int from_tty);
1162 \f
1163 /* Imported from machine dependent code */
1164
1165 /* Blank target vector entries are initialized to target_ignore. */
1166 void target_ignore (void);
1167
1168 #endif /* !defined (TARGET_H) */