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