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