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