linuxthreads_db/thread_db.h

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