gdb/common/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 /* Structure used to report event.  */
 207 typedef struct td_event_msg
 208 {
 209   td_event_e event;             /* Event type being reported.  */
 210   const td_thrhandle_t *th_p;   /* Thread reporting the event.  */
 211   union
 212   {
 213 #if 0
 214     td_synchandle_t *sh;        /* Handle of synchronization object.  */
 215 #endif
 216     uintptr_t data;             /* Event specific data.  */
 217   } msg;
 218 } td_event_msg_t;
 219
 220 /* Structure containing event data available in each thread structure.  */
 221 typedef struct
 222 {
 223   td_thr_events_t eventmask;    /* Mask of enabled events.  */
 224   td_event_e eventnum;          /* Number of last event.  */
 225   void *eventdata;              /* Data associated with event.  */
 226 } td_eventbuf_t;
 227
 228
 229 /* Gathered statistics about the process.  */
 230 typedef struct td_ta_stats
 231 {
 232   int nthreads;                 /* Total number of threads in use.  */
 233   int r_concurrency;            /* Concurrency level requested by user.  */
 234   int nrunnable_num;            /* Average runnable threads, numerator.  */
 235   int nrunnable_den;            /* Average runnable threads, denominator.  */
 236   int a_concurrency_num;        /* Achieved concurrency level, numerator.  */
 237   int a_concurrency_den;        /* Achieved concurrency level, denominator.  */
 238   int nlwps_num;                /* Average number of processes in use,
 239                                    numerator.  */
 240   int nlwps_den;                /* Average number of processes in use,
 241                                    denominator.  */
 242   int nidle_num;                /* Average number of idling processes,
 243                                    numerator.  */
 244   int nidle_den;                /* Average number of idling processes,
 245                                    denominator.  */
 246 } td_ta_stats_t;
 247
 248
 249 /* Since Sun's library is based on Solaris threads we have to define a few
 250    types to map them to POSIX threads.  */
 251 typedef pthread_t thread_t;
 252 typedef pthread_key_t thread_key_t;
 253
 254
 255 /* Callback for iteration over threads.  */
 256 typedef int td_thr_iter_f (const td_thrhandle_t *, void *);
 257
 258 /* Callback for iteration over thread local data.  */
 259 typedef int td_key_iter_f (thread_key_t, void (*) (void *), void *);
 260
 261
 262
 263 /* Forward declaration.  This has to be defined by the user.  */
 264 struct ps_prochandle;
 265
 266
 267 /* Information about the thread.  */
 268 typedef struct td_thrinfo
 269 {
 270   td_thragent_t *ti_ta_p;               /* Process handle.  */
 271   unsigned int ti_user_flags;           /* Unused.  */
 272   thread_t ti_tid;                      /* Thread ID returned by
 273                                            pthread_create().  */
 274   char *ti_tls;                         /* Pointer to thread-local data.  */
 275   psaddr_t ti_startfunc;                /* Start function passed to
 276                                            pthread_create().  */
 277   psaddr_t ti_stkbase;                  /* Base of thread's stack.  */
 278   long int ti_stksize;                  /* Size of thread's stack.  */
 279   psaddr_t ti_ro_area;                  /* Unused.  */
 280   int ti_ro_size;                       /* Unused.  */
 281   td_thr_state_e ti_state;              /* Thread state.  */
 282   unsigned char ti_db_suspended;        /* Nonzero if suspended by
 283                                            debugger.  */
 284   td_thr_type_e ti_type;                /* Type of the thread (system vs
 285                                            user thread).  */
 286   intptr_t ti_pc;                       /* Unused.  */
 287   intptr_t ti_sp;                       /* Unused.  */
 288   short int ti_flags;                   /* Unused.  */
 289   int ti_pri;                           /* Thread priority.  */
 290   lwpid_t ti_lid;                       /* Kernel pid for this thread.  */
 291   sigset_t ti_sigmask;                  /* Signal mask.  */
 292   unsigned char ti_traceme;             /* Nonzero if event reporting
 293                                            enabled.  */
 294   unsigned char ti_preemptflag;         /* Unused.  */
 295   unsigned char ti_pirecflag;           /* Unused.  */
 296   sigset_t ti_pending;                  /* Set of pending signals.  */
 297   td_thr_events_t ti_events;            /* Set of enabled events.  */
 298 } td_thrinfo_t;
 299
 300
 301
 302 /* Prototypes for exported library functions.  */
 303
 304 /* Initialize the thread debug support library.  */
 305 extern td_err_e td_init (void);
 306
 307 /* Historical relict.  Should not be used anymore.  */
 308 extern td_err_e td_log (void);
 309
 310 /* Generate new thread debug library handle for process PS.  */
 311 extern td_err_e td_ta_new (struct ps_prochandle *__ps, td_thragent_t **__ta);
 312
 313 /* Free resources allocated for TA.  */
 314 extern td_err_e td_ta_delete (td_thragent_t *__ta);
 315
 316 /* Get number of currently running threads in process associated with TA.  */
 317 extern td_err_e td_ta_get_nthreads (const td_thragent_t *__ta, int *__np);
 318
 319 /* Return process handle passed in `td_ta_new' for process associated with
 320    TA.  */
 321 extern td_err_e td_ta_get_ph (const td_thragent_t *__ta,
 322                               struct ps_prochandle **__ph);
 323
 324 /* Map thread library handle PT to thread debug library handle for process
 325    associated with TA and store result in *TH.  */
 326 extern td_err_e td_ta_map_id2thr (const td_thragent_t *__ta, pthread_t __pt,
 327                                   td_thrhandle_t *__th);
 328
 329 /* Map process ID LWPID to thread debug library handle for process
 330    associated with TA and store result in *TH.  */
 331 extern td_err_e td_ta_map_lwp2thr (const td_thragent_t *__ta, lwpid_t __lwpid,
 332                                    td_thrhandle_t *__th);
 333
 334
 335 /* Call for each thread in a process associated with TA the callback function
 336    CALLBACK.  */
 337 extern td_err_e td_ta_thr_iter (const td_thragent_t *__ta,
 338                                 td_thr_iter_f *__callback, void *__cbdata_p,
 339                                 td_thr_state_e __state, int __ti_pri,
 340                                 sigset_t *__ti_sigmask_p,
 341                                 unsigned int __ti_user_flags);
 342
 343 /* Call for each defined thread local data entry the callback function KI.  */
 344 extern td_err_e td_ta_tsd_iter (const td_thragent_t *__ta, td_key_iter_f *__ki,
 345                                 void *__p);
 346
 347
 348 /* Get event address for EVENT.  */
 349 extern td_err_e td_ta_event_addr (const td_thragent_t *__ta,
 350                                   td_event_e __event, td_notify_t *__ptr);
 351
 352 /* Enable EVENT in global mask.  */
 353 extern td_err_e td_ta_set_event (const td_thragent_t *__ta,
 354                                  td_thr_events_t *__event);
 355
 356 /* Disable EVENT in global mask.  */
 357 extern td_err_e td_ta_clear_event (const td_thragent_t *__ta,
 358                                    td_thr_events_t *__event);
 359
 360 /* Return information about last event.  */
 361 extern td_err_e td_ta_event_getmsg (const td_thragent_t *__ta,
 362                                     td_event_msg_t *msg);
 363
 364
 365 /* Set suggested concurrency level for process associated with TA.  */
 366 extern td_err_e td_ta_setconcurrency (const td_thragent_t *__ta, int __level);
 367
 368
 369 /* Enable collecting statistics for process associated with TA.  */
 370 extern td_err_e td_ta_enable_stats (const td_thragent_t *__ta, int __enable);
 371
 372 /* Reset statistics.  */
 373 extern td_err_e td_ta_reset_stats (const td_thragent_t *__ta);
 374
 375 /* Retrieve statistics from process associated with TA.  */
 376 extern td_err_e td_ta_get_stats (const td_thragent_t *__ta,
 377                                  td_ta_stats_t *__statsp);
 378
 379
 380 /* Validate that TH is a thread handle.  */
 381 extern td_err_e td_thr_validate (const td_thrhandle_t *__th);
 382
 383 /* Return information about thread TH.  */
 384 extern td_err_e td_thr_get_info (const td_thrhandle_t *__th,
 385                                  td_thrinfo_t *__infop);
 386
 387 /* Retrieve floating-point register contents of process running thread TH.  */
 388 extern td_err_e td_thr_getfpregs (const td_thrhandle_t *__th,
 389                                   prfpregset_t *__regset);
 390
 391 /* Retrieve general register contents of process running thread TH.  */
 392 extern td_err_e td_thr_getgregs (const td_thrhandle_t *__th,
 393                                  prgregset_t __gregs);
 394
 395 /* Retrieve extended register contents of process running thread TH.  */
 396 extern td_err_e td_thr_getxregs (const td_thrhandle_t *__th, void *__xregs);
 397
 398 /* Get size of extended register set of process running thread TH.  */
 399 extern td_err_e td_thr_getxregsize (const td_thrhandle_t *__th, int *__sizep);
 400
 401 /* Set floating-point register contents of process running thread TH.  */
 402 extern td_err_e td_thr_setfpregs (const td_thrhandle_t *__th,
 403                                   const prfpregset_t *__fpregs);
 404
 405 /* Set general register contents of process running thread TH.  */
 406 extern td_err_e td_thr_setgregs (const td_thrhandle_t *__th,
 407                                  prgregset_t __gregs);
 408
 409 /* Set extended register contents of process running thread TH.  */
 410 extern td_err_e td_thr_setxregs (const td_thrhandle_t *__th,
 411                                  const void *__addr);
 412
 413
 414 /* Enable reporting for EVENT for thread TH.  */
 415 extern td_err_e td_thr_event_enable (const td_thrhandle_t *__th, int __event);
 416
 417 /* Enable EVENT for thread TH.  */
 418 extern td_err_e td_thr_set_event (const td_thrhandle_t *__th,
 419                                   td_thr_events_t *__event);
 420
 421 /* Disable EVENT for thread TH.  */
 422 extern td_err_e td_thr_clear_event (const td_thrhandle_t *__th,
 423                                     td_thr_events_t *__event);
 424
 425 /* Get event message for thread TH.  */
 426 extern td_err_e td_thr_event_getmsg (const td_thrhandle_t *__th,
 427                                      td_event_msg_t *__msg);
 428
 429
 430 /* Set priority of thread TH.  */
 431 extern td_err_e td_thr_setprio (const td_thrhandle_t *__th, int __prio);
 432
 433
 434 /* Set pending signals for thread TH.  */
 435 extern td_err_e td_thr_setsigpending (const td_thrhandle_t *__th,
 436                                       unsigned char __n, const sigset_t *__ss);
 437
 438 /* Set signal mask for thread TH.  */
 439 extern td_err_e td_thr_sigsetmask (const td_thrhandle_t *__th,
 440                                    const sigset_t *__ss);
 441
 442
 443 /* Return thread local data associated with key TK in thread TH.  */
 444 extern td_err_e td_thr_tsd (const td_thrhandle_t *__th,
 445                             const thread_key_t __tk, void **__data);
 446
 447
 448 /* Suspend execution of thread TH.  */
 449 extern td_err_e td_thr_dbsuspend (const td_thrhandle_t *__th);
 450
 451 /* Resume execution of thread TH.  */
 452 extern td_err_e td_thr_dbresume (const td_thrhandle_t *__th);
 453
 454 #endif  /* thread_db.h */
 455
 456 #endif /* HAVE_THREAD_DB_H */