gdb/gdb_thread_db.h

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