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