include/thread_db.h

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