gdb/gdb_thread_db.h

   1 #ifdef HAVE_THREAD_DB_H
   2 #include <thread_db.h>
   3 #else
   4
   5 /* Copyright (C) 1999, 2000, 2007, 2008, 2009 Free Software Foundation, Inc.
   6    This file is part of the GNU C Library.
   7
   8    The GNU C Library is free software; you can redistribute it and/or
   9    modify it under the terms of the GNU Library General Public License as
  10    published by the Free Software Foundation; either version 3 of the
  11    License, or (at your option) any later version.
  12
  13    The GNU C Library 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 GNU
  16    Library General Public License for more details.
  17
  18    You should have received a copy of the GNU General Public License
  19    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  20
  21 #ifndef _THREAD_DB_H
  22 #define _THREAD_DB_H    1
  23
  24 /* This is the debugger interface for the LinuxThreads library.  It is
  25    modelled closely after the interface with same names in Solaris with
  26    the goal to share the same code in the debugger.  */
  27 #include <pthread.h>
  28 #include <sys/types.h>
  29 #include <sys/procfs.h>
  30
  31
  32 /* Error codes of the library.  */
  33 typedef enum
  34 {
  35   TD_OK,          /* No error.  */
  36   TD_ERR,         /* No further specified error.  */
  37   TD_NOTHR,       /* No matching thread found.  */
  38   TD_NOSV,        /* No matching synchronization handle found.  */
  39   TD_NOLWP,       /* No matching light-weighted process found.  */
  40   TD_BADPH,       /* Invalid process handle.  */
  41   TD_BADTH,       /* Invalid thread handle.  */
  42   TD_BADSH,       /* Invalid synchronization handle.  */
  43   TD_BADTA,       /* Invalid thread agent.  */
  44   TD_BADKEY,      /* Invalid key.  */
  45   TD_NOMSG,       /* No event available.  */
  46   TD_NOFPREGS,    /* No floating-point register content available.  */
  47   TD_NOLIBTHREAD, /* Application not linked with thread library.  */
  48   TD_NOEVENT,     /* Requested event is not supported.  */
  49   TD_NOCAPAB,     /* Capability not available.  */
  50   TD_DBERR,       /* Internal debug library error.  */
  51   TD_NOAPLIC,     /* Operation is not applicable.  */
  52   TD_NOTSD,       /* No thread-specific data available.  */
  53   TD_MALLOC,      /* Out of memory.  */
  54   TD_PARTIALREG,  /* Not entire register set was read or written.  */
  55   TD_NOXREGS,     /* X register set not available for given thread.  */
  56   TD_NOTALLOC     /* TLS memory not yet allocated.  */
  57 } td_err_e;
  58
  59
  60 /* Possible thread states.  TD_THR_ANY_STATE is a pseudo-state used to
  61    select threads regardless of state in td_ta_thr_iter().  */
  62 typedef enum
  63 {
  64   TD_THR_ANY_STATE,
  65   TD_THR_UNKNOWN,
  66   TD_THR_STOPPED,
  67   TD_THR_RUN,
  68   TD_THR_ACTIVE,
  69   TD_THR_ZOMBIE,
  70   TD_THR_SLEEP,
  71   TD_THR_STOPPED_ASLEEP
  72 } td_thr_state_e;
  73
  74 /* Thread type: user or system.  TD_THR_ANY_TYPE is a pseudo-type used
  75    to select threads regardless of type in td_ta_thr_iter().  */
  76 typedef enum
  77 {
  78   TD_THR_ANY_TYPE,
  79   TD_THR_USER,
  80   TD_THR_SYSTEM
  81 } td_thr_type_e;
  82
  83
  84 /* Types of the debugging library.  */
  85
  86 /* Handle for a process.  This type is opaque.  */
  87 typedef struct td_thragent td_thragent_t;
  88
  89 /* The actual thread handle type.  This is also opaque.  */
  90 typedef struct td_thrhandle
  91 {
  92   td_thragent_t *th_ta_p;
  93   psaddr_t th_unique;
  94 } td_thrhandle_t;
  95
  96
  97 /* Flags for `td_ta_thr_iter'.  */
  98 #define TD_THR_ANY_USER_FLAGS   0xffffffff
  99 #define TD_THR_LOWEST_PRIORITY  -20
 100 #define TD_SIGNO_MASK           NULL
 101
 102
 103 #define TD_EVENTSIZE    2
 104 #define BT_UISHIFT      5 /* log base 2 of BT_NBIPUI, to extract word index */
 105 #define BT_NBIPUI       (1 << BT_UISHIFT)       /* n bits per uint */
 106 #define BT_UIMASK       (BT_NBIPUI - 1)         /* to extract bit index */
 107
 108 /* Bitmask of enabled events. */
 109 typedef struct td_thr_events
 110 {
 111   uint32_t event_bits[TD_EVENTSIZE];
 112 } td_thr_events_t;
 113
 114 /* Event set manipulation macros. */
 115 #define __td_eventmask(n) \
 116   (UINT32_C (1) << (((n) - 1) & BT_UIMASK))
 117 #define __td_eventword(n) \
 118   ((UINT32_C ((n) - 1)) >> BT_UISHIFT)
 119
 120 #define td_event_emptyset(setp) \
 121   do {                                                                        \
 122     int __i;                                                                  \
 123     for (__i = TD_EVENTSIZE; __i > 0; --__i)                                  \
 124       (setp)->event_bits[__i - 1] = 0;                                        \
 125   } while (0)
 126
 127 #define td_event_fillset(setp) \
 128   do {                                                                        \
 129     int __i;                                                                  \
 130     for (__i = TD_EVENTSIZE; __i > 0; --__i)                                  \
 131       (setp)->event_bits[__i - 1] = UINT32_C (0xffffffff);                    \
 132   } while (0)
 133
 134 #define td_event_addset(setp, n) \
 135   (((setp)->event_bits[__td_eventword (n)]) |= __td_eventmask (n))
 136 #define td_event_delset(setp, n) \
 137   (((setp)->event_bits[__td_eventword (n)]) &= ~__td_eventmask (n))
 138 #define td_eventismember(setp, n) \
 139   (__td_eventmask (n) & ((setp)->event_bits[__td_eventword (n)]))
 140 #if TD_EVENTSIZE == 2
 141 # define td_eventisempty(setp) \
 142   (!((setp)->event_bits[0]) && !((setp)->event_bits[1]))
 143 #else
 144 # error "td_eventisempty must be changed to match TD_EVENTSIZE"
 145 #endif
 146
 147 /* Events reportable by the thread implementation.  */
 148 typedef enum
 149 {
 150   TD_ALL_EVENTS,                 /* Pseudo-event number.  */
 151   TD_EVENT_NONE = TD_ALL_EVENTS, /* Depends on context.  */
 152   TD_READY,                      /* Is executable now. */
 153   TD_SLEEP,                      /* Blocked in a synchronization obj.  */
 154   TD_SWITCHTO,                   /* Now assigned to a process.  */
 155   TD_SWITCHFROM,                 /* Not anymore assigned to a process.  */
 156   TD_LOCK_TRY,                   /* Trying to get an unavailable lock.  */
 157   TD_CATCHSIG,                   /* Signal posted to the thread.  */
 158   TD_IDLE,                       /* Process getting idle.  */
 159   TD_CREATE,                     /* New thread created.  */
 160   TD_DEATH,                      /* Thread terminated.  */
 161   TD_PREEMPT,                    /* Preempted.  */
 162   TD_PRI_INHERIT,                /* Inherited elevated priority.  */
 163   TD_REAP,                       /* Reaped.  */
 164   TD_CONCURRENCY,                /* Number of processes changing.  */
 165   TD_TIMEOUT,                    /* Conditional variable wait timed out.  */
 166   TD_MIN_EVENT_NUM = TD_READY,
 167   TD_MAX_EVENT_NUM = TD_TIMEOUT,
 168   TD_EVENTS_ENABLE = 31         /* Event reporting enabled.  */
 169 } td_event_e;
 170
 171 /* Values representing the different ways events are reported.  */
 172 typedef enum
 173 {
 174   NOTIFY_BPT,                   /* User must insert breakpoint at u.bptaddr. */
 175   NOTIFY_AUTOBPT,               /* Breakpoint at u.bptaddr is automatically
 176                                    inserted.  */
 177   NOTIFY_SYSCALL                /* System call u.syscallno will be invoked.  */
 178 } td_notify_e;
 179
 180 /* Description how event type is reported.  */
 181 typedef struct td_notify
 182 {
 183   td_notify_e type;             /* Way the event is reported.  */
 184   union
 185   {
 186     psaddr_t bptaddr;           /* Address of breakpoint.  */
 187     int syscallno;              /* Number of system call used.  */
 188   } u;
 189 } td_notify_t;
 190
 191 /* Some people still have libc5 or old glibc with no uintptr_t.
 192    They lose.  glibc 2.1.3 was released on 2000-02-25, and it has
 193    uintptr_t, so it's reasonable to force these people to upgrade.  */
 194
 195 #ifndef HAVE_UINTPTR_T
 196 #error No uintptr_t available; your C library is too old.
 197 /* Inhibit further compilation errors after this error.  */
 198 #define uintptr_t void *
 199 #endif
 200
 201 /* Structure used to report event.  */
 202 typedef struct td_event_msg
 203 {
 204   td_event_e event;             /* Event type being reported.  */
 205   const td_thrhandle_t *th_p;   /* Thread reporting the event.  */
 206   union
 207   {
 208 #if 0
 209     td_synchandle_t *sh;        /* Handle of synchronization object.  */
 210 #endif
 211     uintptr_t data;             /* Event specific data.  */
 212   } msg;
 213 } td_event_msg_t;
 214
 215 /* Structure containing event data available in each thread structure.  */
 216 typedef struct
 217 {
 218   td_thr_events_t eventmask;    /* Mask of enabled events.  */
 219   td_event_e eventnum;          /* Number of last event.  */
 220   void *eventdata;              /* Data associated with event.  */
 221 } td_eventbuf_t;
 222
 223
 224 /* Gathered statistics about the process.  */
 225 typedef struct td_ta_stats
 226 {
 227   int nthreads;                 /* Total number of threads in use.  */
 228   int r_concurrency;            /* Concurrency level requested by user.  */
 229   int nrunnable_num;            /* Average runnable threads, numerator.  */
 230   int nrunnable_den;            /* Average runnable threads, denominator.  */
 231   int a_concurrency_num;        /* Achieved concurrency level, numerator.  */
 232   int a_concurrency_den;        /* Achieved concurrency level, denominator.  */
 233   int nlwps_num;                /* Average number of processes in use,
 234                                    numerator.  */
 235   int nlwps_den;                /* Average number of processes in use,
 236                                    denominator.  */
 237   int nidle_num;                /* Average number of idling processes,
 238                                    numerator.  */
 239   int nidle_den;                /* Average number of idling processes,
 240                                    denominator.  */
 241 } td_ta_stats_t;
 242
 243
 244 /* Since Sun's library is based on Solaris threads we have to define a few
 245    types to map them to POSIX threads.  */
 246 typedef pthread_t thread_t;
 247 typedef pthread_key_t thread_key_t;
 248
 249
 250 /* Callback for iteration over threads.  */
 251 typedef int td_thr_iter_f (const td_thrhandle_t *, void *);
 252
 253 /* Callback for iteration over thread local data.  */
 254 typedef int td_key_iter_f (thread_key_t, void (*) (void *), void *);
 255
 256
 257
 258 /* Forward declaration.  This has to be defined by the user.  */
 259 struct ps_prochandle;
 260
 261
 262 /* Information about the thread.  */
 263 typedef struct td_thrinfo
 264 {
 265   td_thragent_t *ti_ta_p;               /* Process handle.  */
 266   unsigned int ti_user_flags;           /* Unused.  */
 267   thread_t ti_tid;                      /* Thread ID returned by
 268                                            pthread_create().  */
 269   char *ti_tls;                         /* Pointer to thread-local data.  */
 270   psaddr_t ti_startfunc;                /* Start function passed to
 271                                            pthread_create().  */
 272   psaddr_t ti_stkbase;                  /* Base of thread's stack.  */
 273   long int ti_stksize;                  /* Size of thread's stack.  */
 274   psaddr_t ti_ro_area;                  /* Unused.  */
 275   int ti_ro_size;                       /* Unused.  */
 276   td_thr_state_e ti_state;              /* Thread state.  */
 277   unsigned char ti_db_suspended;        /* Nonzero if suspended by debugger. */
 278   td_thr_type_e ti_type;                /* Type of the thread (system vs
 279                                            user thread).  */
 280   intptr_t ti_pc;                       /* Unused.  */
 281   intptr_t ti_sp;                       /* Unused.  */
 282   short int ti_flags;                   /* Unused.  */
 283   int ti_pri;                           /* Thread priority.  */
 284   lwpid_t ti_lid;                       /* Kernel pid for this thread.  */
 285   sigset_t ti_sigmask;                  /* Signal mask.  */
 286   unsigned char ti_traceme;             /* Nonzero if event reporting
 287                                            enabled.  */
 288   unsigned char ti_preemptflag;         /* Unused.  */
 289   unsigned char ti_pirecflag;           /* Unused.  */
 290   sigset_t ti_pending;                  /* Set of pending signals.  */
 291   td_thr_events_t ti_events;            /* Set of enabled events.  */
 292 } td_thrinfo_t;
 293
 294
 295
 296 /* Prototypes for exported library functions.  */
 297
 298 /* Initialize the thread debug support library.  */
 299 extern td_err_e td_init (void);
 300
 301 /* Historical relict.  Should not be used anymore.  */
 302 extern td_err_e td_log (void);
 303
 304 /* Generate new thread debug library handle for process PS.  */
 305 extern td_err_e td_ta_new (struct ps_prochandle *__ps, td_thragent_t **__ta);
 306
 307 /* Free resources allocated for TA.  */
 308 extern td_err_e td_ta_delete (td_thragent_t *__ta);
 309
 310 /* Get number of currently running threads in process associated with TA.  */
 311 extern td_err_e td_ta_get_nthreads (const td_thragent_t *__ta, int *__np);
 312
 313 /* Return process handle passed in `td_ta_new' for process associated with
 314    TA.  */
 315 extern td_err_e td_ta_get_ph (const td_thragent_t *__ta,
 316                               struct ps_prochandle **__ph);
 317
 318 /* Map thread library handle PT to thread debug library handle for process
 319    associated with TA and store result in *TH.  */
 320 extern td_err_e td_ta_map_id2thr (const td_thragent_t *__ta, pthread_t __pt,
 321                                   td_thrhandle_t *__th);
 322
 323 /* Map process ID LWPID to thread debug library handle for process
 324    associated with TA and store result in *TH.  */
 325 extern td_err_e td_ta_map_lwp2thr (const td_thragent_t *__ta, lwpid_t __lwpid,
 326                                    td_thrhandle_t *__th);
 327
 328
 329 /* Call for each thread in a process associated with TA the callback function
 330    CALLBACK.  */
 331 extern td_err_e td_ta_thr_iter (const td_thragent_t *__ta,
 332                                 td_thr_iter_f *__callback, void *__cbdata_p,
 333                                 td_thr_state_e __state, int __ti_pri,
 334                                 sigset_t *__ti_sigmask_p,
 335                                 unsigned int __ti_user_flags);
 336
 337 /* Call for each defined thread local data entry the callback function KI.  */
 338 extern td_err_e td_ta_tsd_iter (const td_thragent_t *__ta, td_key_iter_f *__ki,
 339                                 void *__p);
 340
 341
 342 /* Get event address for EVENT.  */
 343 extern td_err_e td_ta_event_addr (const td_thragent_t *__ta,
 344                                   td_event_e __event, td_notify_t *__ptr);
 345
 346 /* Enable EVENT in global mask.  */
 347 extern td_err_e td_ta_set_event (const td_thragent_t *__ta,
 348                                  td_thr_events_t *__event);
 349
 350 /* Disable EVENT in global mask.  */
 351 extern td_err_e td_ta_clear_event (const td_thragent_t *__ta,
 352                                    td_thr_events_t *__event);
 353
 354 /* Return information about last event.  */
 355 extern td_err_e td_ta_event_getmsg (const td_thragent_t *__ta,
 356                                     td_event_msg_t *msg);
 357
 358
 359 /* Set suggested concurrency level for process associated with TA.  */
 360 extern td_err_e td_ta_setconcurrency (const td_thragent_t *__ta, int __level);
 361
 362
 363 /* Enable collecting statistics for process associated with TA.  */
 364 extern td_err_e td_ta_enable_stats (const td_thragent_t *__ta, int __enable);
 365
 366 /* Reset statistics.  */
 367 extern td_err_e td_ta_reset_stats (const td_thragent_t *__ta);
 368
 369 /* Retrieve statistics from process associated with TA.  */
 370 extern td_err_e td_ta_get_stats (const td_thragent_t *__ta,
 371                                  td_ta_stats_t *__statsp);
 372
 373
 374 /* Validate that TH is a thread handle.  */
 375 extern td_err_e td_thr_validate (const td_thrhandle_t *__th);
 376
 377 /* Return information about thread TH.  */
 378 extern td_err_e td_thr_get_info (const td_thrhandle_t *__th,
 379                                  td_thrinfo_t *__infop);
 380
 381 /* Retrieve floating-point register contents of process running thread TH.  */
 382 extern td_err_e td_thr_getfpregs (const td_thrhandle_t *__th,
 383                                   prfpregset_t *__regset);
 384
 385 /* Retrieve general register contents of process running thread TH.  */
 386 extern td_err_e td_thr_getgregs (const td_thrhandle_t *__th,
 387                                  prgregset_t __gregs);
 388
 389 /* Retrieve extended register contents of process running thread TH.  */
 390 extern td_err_e td_thr_getxregs (const td_thrhandle_t *__th, void *__xregs);
 391
 392 /* Get size of extended register set of process running thread TH.  */
 393 extern td_err_e td_thr_getxregsize (const td_thrhandle_t *__th, int *__sizep);
 394
 395 /* Set floating-point register contents of process running thread TH.  */
 396 extern td_err_e td_thr_setfpregs (const td_thrhandle_t *__th,
 397                                   const prfpregset_t *__fpregs);
 398
 399 /* Set general register contents of process running thread TH.  */
 400 extern td_err_e td_thr_setgregs (const td_thrhandle_t *__th,
 401                                  prgregset_t __gregs);
 402
 403 /* Set extended register contents of process running thread TH.  */
 404 extern td_err_e td_thr_setxregs (const td_thrhandle_t *__th,
 405                                  const void *__addr);
 406
 407
 408 /* Enable reporting for EVENT for thread TH.  */
 409 extern td_err_e td_thr_event_enable (const td_thrhandle_t *__th, int __event);
 410
 411 /* Enable EVENT for thread TH.  */
 412 extern td_err_e td_thr_set_event (const td_thrhandle_t *__th,
 413                                   td_thr_events_t *__event);
 414
 415 /* Disable EVENT for thread TH.  */
 416 extern td_err_e td_thr_clear_event (const td_thrhandle_t *__th,
 417                                     td_thr_events_t *__event);
 418
 419 /* Get event message for thread TH.  */
 420 extern td_err_e td_thr_event_getmsg (const td_thrhandle_t *__th,
 421                                      td_event_msg_t *__msg);
 422
 423
 424 /* Set priority of thread TH.  */
 425 extern td_err_e td_thr_setprio (const td_thrhandle_t *__th, int __prio);
 426
 427
 428 /* Set pending signals for thread TH.  */
 429 extern td_err_e td_thr_setsigpending (const td_thrhandle_t *__th,
 430                                       unsigned char __n, const sigset_t *__ss);
 431
 432 /* Set signal mask for thread TH.  */
 433 extern td_err_e td_thr_sigsetmask (const td_thrhandle_t *__th,
 434                                    const sigset_t *__ss);
 435
 436
 437 /* Return thread local data associated with key TK in thread TH.  */
 438 extern td_err_e td_thr_tsd (const td_thrhandle_t *__th,
 439                             const thread_key_t __tk, void **__data);
 440
 441
 442 /* Suspend execution of thread TH.  */
 443 extern td_err_e td_thr_dbsuspend (const td_thrhandle_t *__th);
 444
 445 /* Resume execution of thread TH.  */
 446 extern td_err_e td_thr_dbresume (const td_thrhandle_t *__th);
 447
 448 #endif  /* thread_db.h */
 449
 450 #endif /* HAVE_THREAD_DB_H */