gdb/gdbthread.h

   1 /* Multi-process/thread control defs for GDB, the GNU debugger.
   2    Copyright (C) 1987, 1988, 1989, 1990, 1991, 1992, 1993, 1997, 1998, 1999,
   3    2000, 2007, 2008, 2009 Free Software Foundation, Inc.
   4    Contributed by Lynx Real-Time Systems, Inc.  Los Gatos, CA.
   5
   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 GDBTHREAD_H
  23 #define GDBTHREAD_H
  24
  25 struct symtab;
  26
  27 #include "breakpoint.h"
  28 #include "frame.h"
  29 #include "ui-out.h"
  30 #include "inferior.h"
  31
  32 struct thread_info
  33 {
  34   struct thread_info *next;
  35   ptid_t ptid;                  /* "Actual process id";
  36                                     In fact, this may be overloaded with
  37                                     kernel thread id, etc.  */
  38   int num;                      /* Convenient handle (GDB thread id) */
  39
  40   /* Non-zero means the thread is executing.  Note: this is different
  41      from saying that there is an active target and we are stopped at
  42      a breakpoint, for instance.  This is a real indicator whether the
  43      thread is off and running.  */
  44   /* This field is internal to thread.c.  Never access it directly,
  45      use is_executing instead.  */
  46   int executing_;
  47
  48   /* Frontend view of the thread state.  Note that the RUNNING/STOPPED
  49      states are different from EXECUTING.  When the thread is stopped
  50      internally while handling an internal event, like a software
  51      single-step breakpoint, EXECUTING will be false, but running will
  52      still be true.  As a possible future extension, this could turn
  53      into enum { stopped, exited, stepping, finishing, until(ling),
  54      running ... }  */
  55   /* This field is internal to thread.c.  Never access it directly,
  56      use is_running instead.  */
  57   int state_;
  58
  59   /* If this is > 0, then it means there's code out there that relies
  60      on this thread being listed.  Don't delete it from the lists even
  61      if we detect it exiting.  */
  62   int refcount;
  63
  64   /* User/external stepping state.  */
  65
  66   /* Step-resume or longjmp-resume breakpoint.  */
  67   struct breakpoint *step_resume_breakpoint;
  68
  69   /* Range to single step within.
  70
  71      If this is nonzero, respond to a single-step signal by continuing
  72      to step if the pc is in this range.
  73
  74      If step_range_start and step_range_end are both 1, it means to
  75      step for a single instruction (FIXME: it might clean up
  76      wait_for_inferior in a minor way if this were changed to the
  77      address of the instruction and that address plus one.  But maybe
  78      not.).  */
  79   CORE_ADDR step_range_start;   /* Inclusive */
  80   CORE_ADDR step_range_end;     /* Exclusive */
  81
  82   /* Stack frame address as of when stepping command was issued.
  83      This is how we know when we step into a subroutine call, and how
  84      to set the frame for the breakpoint used to step out.  */
  85   struct frame_id step_frame_id;
  86   int current_line;
  87   struct symtab *current_symtab;
  88
  89   /* Internal stepping state.  */
  90
  91   /* Record the pc of the thread the last time it stopped.  This is
  92      maintained by proceed and keep_going, and used in
  93      adjust_pc_after_break to distinguish a hardware single-step
  94      SIGTRAP from a breakpoint SIGTRAP.  */
  95   CORE_ADDR prev_pc;
  96
  97   /* Nonzero if we are presently stepping over a breakpoint.
  98
  99      If we hit a breakpoint or watchpoint, and then continue, we need
 100      to single step the current thread with breakpoints disabled, to
 101      avoid hitting the same breakpoint or watchpoint again.  And we
 102      should step just a single thread and keep other threads stopped,
 103      so that other threads don't miss breakpoints while they are
 104      removed.
 105
 106      So, this variable simultaneously means that we need to single
 107      step the current thread, keep other threads stopped, and that
 108      breakpoints should be removed while we step.
 109
 110      This variable is set either:
 111      - in proceed, when we resume inferior on user's explicit request
 112      - in keep_going, if handle_inferior_event decides we need to
 113      step over breakpoint.
 114
 115      The variable is cleared in normal_stop.  The proceed calls
 116      wait_for_inferior, which calls handle_inferior_event in a loop,
 117      and until wait_for_inferior exits, this variable is changed only
 118      by keep_going.  */
 119   int trap_expected;
 120
 121   /* Should we step over breakpoint next time keep_going is called?  */
 122   int stepping_over_breakpoint;
 123
 124   /* Set to TRUE if we should finish single-stepping over a breakpoint
 125      after hitting the current step-resume breakpoint.  */
 126   int step_after_step_resume_breakpoint;
 127
 128   /* This is set TRUE when a catchpoint of a shared library event
 129      triggers.  Since we don't wish to leave the inferior in the
 130      solib hook when we report the event, we step the inferior
 131      back to user code before stopping and reporting the event.  */
 132   int stepping_through_solib_after_catch;
 133
 134   /* When stepping_through_solib_after_catch is TRUE, this is a
 135      list of the catchpoints that should be reported as triggering
 136      when we finally do stop stepping.  */
 137   bpstat stepping_through_solib_catchpoints;
 138
 139   /* Per-thread command support.  */
 140
 141   /* Pointer to what is left to do for an execution command after the
 142      target stops.  Used only in asynchronous mode, by targets that
 143      support async execution.  Several execution commands use it.  */
 144   struct continuation *continuations;
 145
 146   /* Similar to the above, but used when a single execution command
 147      requires several resume/stop iterations.  Used by the step
 148      command.  */
 149   struct continuation *intermediate_continuations;
 150
 151   /* Nonzero if the thread is being proceeded for a "finish" command
 152      or a similar situation when stop_registers should be saved.  */
 153   int proceed_to_finish;
 154
 155   /* Nonzero if the thread is being proceeded for an inferior function
 156      call.  */
 157   int in_infcall;
 158
 159   enum step_over_calls_kind step_over_calls;
 160
 161   /* Nonzero if stopped due to a step command.  */
 162   int stop_step;
 163
 164   /* If stepping, nonzero means step count is > 1 so don't print frame
 165      next time inferior stops if it stops due to stepping.  */
 166   int step_multi;
 167
 168   /* Last signal that the inferior received (why it stopped).  */
 169   enum target_signal stop_signal;
 170
 171   /* Chain containing status of breakpoint(s) the thread stopped
 172      at.  */
 173   bpstat stop_bpstat;
 174
 175   /* True if this thread has been explicitly requested to stop.  */
 176   int stop_requested;
 177
 178   /* Private data used by the target vector implementation.  */
 179   struct private_thread_info *private;
 180 };
 181
 182 /* Create an empty thread list, or empty the existing one.  */
 183 extern void init_thread_list (void);
 184
 185 /* Add a thread to the thread list, print a message
 186    that a new thread is found, and return the pointer to
 187    the new thread.  Caller my use this pointer to
 188    initialize the private thread data.  */
 189 extern struct thread_info *add_thread (ptid_t ptid);
 190
 191 /* Same as add_thread, but does not print a message
 192    about new thread.  */
 193 extern struct thread_info *add_thread_silent (ptid_t ptid);
 194
 195 /* Same as add_thread, and sets the private info.  */
 196 extern struct thread_info *add_thread_with_info (ptid_t ptid,
 197                                                  struct private_thread_info *);
 198
 199 /* Delete an existing thread list entry.  */
 200 extern void delete_thread (ptid_t);
 201
 202 /* Delete an existing thread list entry, and be quiet about it.  Used
 203    after the process this thread having belonged to having already
 204    exited, for example.  */
 205 extern void delete_thread_silent (ptid_t);
 206
 207 /* Delete a step_resume_breakpoint from the thread database. */
 208 extern void delete_step_resume_breakpoint (struct thread_info *);
 209
 210 /* Translate the integer thread id (GDB's homegrown id, not the system's)
 211    into a "pid" (which may be overloaded with extra thread information).  */
 212 extern ptid_t thread_id_to_pid (int);
 213
 214 /* Translate a 'pid' (which may be overloaded with extra thread information)
 215    into the integer thread id (GDB's homegrown id, not the system's).  */
 216 extern int pid_to_thread_id (ptid_t ptid);
 217
 218 /* Boolean test for an already-known pid (which may be overloaded with
 219    extra thread information).  */
 220 extern int in_thread_list (ptid_t ptid);
 221
 222 /* Boolean test for an already-known thread id (GDB's homegrown id,
 223    not the system's).  */
 224 extern int valid_thread_id (int thread);
 225
 226 /* Search function to lookup a thread by 'pid'.  */
 227 extern struct thread_info *find_thread_pid (ptid_t ptid);
 228
 229 /* Find thread by GDB user-visible thread number.  */
 230 struct thread_info *find_thread_id (int num);
 231
 232 /* Finds the first thread of the inferior given by PID.  If PID is -1,
 233    returns the first thread in the list.  */
 234 struct thread_info *first_thread_of_process (int pid);
 235
 236 /* Change the ptid of thread OLD_PTID to NEW_PTID.  */
 237 void thread_change_ptid (ptid_t old_ptid, ptid_t new_ptid);
 238
 239 /* Iterator function to call a user-provided callback function
 240    once for each known thread.  */
 241 typedef int (*thread_callback_func) (struct thread_info *, void *);
 242 extern struct thread_info *iterate_over_threads (thread_callback_func, void *);
 243
 244 extern int thread_count (void);
 245
 246 /* Switch from one thread to another.  */
 247 extern void switch_to_thread (ptid_t ptid);
 248
 249 /* Marks thread PTID is running, or stopped.
 250    If PIDGET (PTID) is -1, marks all threads.  */
 251 extern void set_running (ptid_t ptid, int running);
 252
 253 /* Marks or clears thread(s) PTID as having been requested to stop.
 254    If PTID is MINUS_ONE_PTID, applies to all threads.  If
 255    ptid_is_pid(PTID) is true, applies to all threads of the process
 256    pointed at by PTID.  If STOP, then the THREAD_STOP_REQUESTED
 257    observer is called with PTID as argument.  */
 258 extern void set_stop_requested (ptid_t ptid, int stop);
 259
 260 /* NOTE: Since the thread state is not a boolean, most times, you do
 261    not want to check it with negation.  If you really want to check if
 262    the thread is stopped,
 263
 264     use (good):
 265
 266      if (is_stopped (ptid))
 267
 268     instead of (bad):
 269
 270      if (!is_running (ptid))
 271
 272    The latter also returns true on exited threads, most likelly not
 273    what you want.  */
 274
 275 /* Reports if in the frontend's perpective, thread PTID is running.  */
 276 extern int is_running (ptid_t ptid);
 277
 278 /* Is this thread listed, but known to have exited?  We keep it listed
 279    (but not visible) until it's safe to delete.  */
 280 extern int is_exited (ptid_t ptid);
 281
 282 /* In the frontend's perpective, is this thread stopped?  */
 283 extern int is_stopped (ptid_t ptid);
 284
 285 /* In the frontend's perpective is there any thread running?  */
 286 extern int any_running (void);
 287
 288 /* Marks thread PTID as executing, or not.  If PIDGET (PTID) is -1,
 289    marks all threads.
 290
 291    Note that this is different from the running state.  See the
 292    description of state_ and executing_ fields of struct
 293    thread_info.  */
 294 extern void set_executing (ptid_t ptid, int executing);
 295
 296 /* Reports if thread PTID is executing.  */
 297 extern int is_executing (ptid_t ptid);
 298
 299 /* Merge the executing property of thread PTID over to its thread
 300    state property (frontend running/stopped view).
 301
 302    "not executing" -> "stopped"
 303    "executing"     -> "running"
 304    "exited"        -> "exited"
 305
 306    If PIDGET (PTID) is -1, go over all threads.
 307
 308    Notifications are only emitted if the thread state did change.  */
 309 extern void finish_thread_state (ptid_t ptid);
 310
 311 /* Same as FINISH_THREAD_STATE, but with an interface suitable to be
 312    registered as a cleanup.  PTID_P points to the ptid_t that is
 313    passed to FINISH_THREAD_STATE.  */
 314 extern void finish_thread_state_cleanup (void *ptid_p);
 315
 316 /* Commands with a prefix of `thread'.  */
 317 extern struct cmd_list_element *thread_cmd_list;
 318
 319 /* Print notices on thread events (attach, detach, etc.), set with
 320    `set print thread-events'.  */
 321 extern int print_thread_events;
 322
 323 extern void print_thread_info (struct ui_out *uiout, int thread,
 324                                int pid);
 325
 326 extern struct cleanup *make_cleanup_restore_current_thread (void);
 327
 328 /* Returns a pointer into the thread_info corresponding to
 329    INFERIOR_PTID.  INFERIOR_PTID *must* be in the thread list.  */
 330 extern struct thread_info* inferior_thread (void);
 331
 332 #endif /* GDBTHREAD_H */