1 /* thread_db.h -- interface to libthread_db.so library for debugging -lpthread 2 Copyright (C) 1999,2001,2002,2003 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 <http://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 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 #ifdef __cplusplus 31 extern "C" { 32 #endif 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_TLSDEFER, /* Thread has not yet allocated TLS for given module. */ 59 TD_NOTALLOC = TD_TLSDEFER, 60 TD_VERSION, /* Version if libpthread and libthread_db do not match. */ 61 TD_NOTLS /* There is TLS segment in the given module. */ 62 } td_err_e; 63 64 65 /* Possible thread states. TD_THR_ANY_STATE is a pseudo-state used to 66 select threads regardless of state in td_ta_thr_iter(). */ 67 typedef enum 68 { 69 TD_THR_ANY_STATE, 70 TD_THR_UNKNOWN, 71 TD_THR_STOPPED, 72 TD_THR_RUN, 73 TD_THR_ACTIVE, 74 TD_THR_ZOMBIE, 75 TD_THR_SLEEP, 76 TD_THR_STOPPED_ASLEEP 77 } td_thr_state_e; 78 79 /* Thread type: user or system. TD_THR_ANY_TYPE is a pseudo-type used 80 to select threads regardless of type in td_ta_thr_iter(). */ 81 typedef enum 82 { 83 TD_THR_ANY_TYPE, 84 TD_THR_USER, 85 TD_THR_SYSTEM 86 } td_thr_type_e; 87 88 89 /* Types of the debugging library. */ 90 91 /* Handle for a process. This type is opaque. */ 92 typedef struct td_thragent td_thragent_t; 93 94 /* The actual thread handle type. This is also opaque. */ 95 typedef struct td_thrhandle 96 { 97 td_thragent_t *th_ta_p; 98 psaddr_t th_unique; 99 } td_thrhandle_t; 100 101 102 /* Forward declaration of a type defined by and for the dynamic linker. */ 103 struct link_map; 104 105 106 /* Flags for `td_ta_thr_iter'. */ 107 #define TD_THR_ANY_USER_FLAGS 0xffffffff 108 #define TD_THR_LOWEST_PRIORITY -20 109 #define TD_SIGNO_MASK NULL 110 111 112 #define TD_EVENTSIZE 2 113 #define BT_UISHIFT 5 /* log base 2 of BT_NBIPUI, to extract word index */ 114 #define BT_NBIPUI (1 << BT_UISHIFT) /* n bits per uint */ 115 #define BT_UIMASK (BT_NBIPUI - 1) /* to extract bit index */ 116 117 /* Bitmask of enabled events. */ 118 typedef struct td_thr_events 119 { 120 uint32_t event_bits[TD_EVENTSIZE]; 121 } td_thr_events_t; 122 123 /* Event set manipulation macros. */ 124 #define __td_eventmask(n) \ 125 (UINT32_C (1) << (((n) - 1) & BT_UIMASK)) 126 #define __td_eventword(n) \ 127 ((UINT32_C ((n) - 1)) >> BT_UISHIFT) 128 129 #define td_event_emptyset(setp) \ 130 do { \ 131 int __i; \ 132 for (__i = TD_EVENTSIZE; __i > 0; --__i) \ 133 (setp)->event_bits[__i - 1] = 0; \ 134 } while (0) 135 136 #define td_event_fillset(setp) \ 137 do { \ 138 int __i; \ 139 for (__i = TD_EVENTSIZE; __i > 0; --__i) \ 140 (setp)->event_bits[__i - 1] = UINT32_C (0xffffffff); \ 141 } while (0) 142 143 #define td_event_addset(setp, n) \ 144 (((setp)->event_bits[__td_eventword (n)]) |= __td_eventmask (n)) 145 #define td_event_delset(setp, n) \ 146 (((setp)->event_bits[__td_eventword (n)]) &= ~__td_eventmask (n)) 147 #define td_eventismember(setp, n) \ 148 (__td_eventmask (n) & ((setp)->event_bits[__td_eventword (n)])) 149 #if TD_EVENTSIZE == 2 150 # define td_eventisempty(setp) \ 151 (!((setp)->event_bits[0]) && !((setp)->event_bits[1])) 152 #else 153 # error "td_eventisempty must be changed to match TD_EVENTSIZE" 154 #endif 155 156 /* Events reportable by the thread implementation. */ 157 typedef enum 158 { 159 TD_ALL_EVENTS, /* Pseudo-event number. */ 160 TD_EVENT_NONE = TD_ALL_EVENTS, /* Depends on context. */ 161 TD_READY, /* Is executable now. */ 162 TD_SLEEP, /* Blocked in a synchronization obj. */ 163 TD_SWITCHTO, /* Now assigned to a process. */ 164 TD_SWITCHFROM, /* Not anymore assigned to a process. */ 165 TD_LOCK_TRY, /* Trying to get an unavailable lock. */ 166 TD_CATCHSIG, /* Signal posted to the thread. */ 167 TD_IDLE, /* Process getting idle. */ 168 TD_CREATE, /* New thread created. */ 169 TD_DEATH, /* Thread terminated. */ 170 TD_PREEMPT, /* Preempted. */ 171 TD_PRI_INHERIT, /* Inherited elevated priority. */ 172 TD_REAP, /* Reaped. */ 173 TD_CONCURRENCY, /* Number of processes changing. */ 174 TD_TIMEOUT, /* Conditional variable wait timed out. */ 175 TD_MIN_EVENT_NUM = TD_READY, 176 TD_MAX_EVENT_NUM = TD_TIMEOUT, 177 TD_EVENTS_ENABLE = 31 /* Event reporting enabled. */ 178 } td_event_e; 179 180 /* Values representing the different ways events are reported. */ 181 typedef enum 182 { 183 NOTIFY_BPT, /* User must insert breakpoint at u.bptaddr. */ 184 NOTIFY_AUTOBPT, /* Breakpoint at u.bptaddr is automatically 185 inserted. */ 186 NOTIFY_SYSCALL /* System call u.syscallno will be invoked. */ 187 } td_notify_e; 188 189 /* Description how event type is reported. */ 190 typedef struct td_notify 191 { 192 td_notify_e type; /* Way the event is reported. */ 193 union 194 { 195 psaddr_t bptaddr; /* Address of breakpoint. */ 196 int syscallno; /* Number of system call used. */ 197 } u; 198 } td_notify_t; 199 200 /* Structure used to report event. */ 201 typedef struct td_event_msg 202 { 203 td_event_e event; /* Event type being reported. */ 204 const td_thrhandle_t *th_p; /* Thread reporting the event. */ 205 union 206 { 207 # if 0 208 td_synchandle_t *sh; /* Handle of synchronization object. */ 209 #endif 210 uintptr_t data; /* Event specific data. */ 211 } msg; 212 } td_event_msg_t; 213 214 /* Structure containing event data available in each thread structure. */ 215 typedef struct 216 { 217 td_thr_events_t eventmask; /* Mask of enabled events. */ 218 td_event_e eventnum; /* Number of last event. */ 219 void *eventdata; /* Data associated with event. */ 220 } td_eventbuf_t; 221 222 223 /* Gathered statistics about the process. */ 224 typedef struct td_ta_stats 225 { 226 int nthreads; /* Total number of threads in use. */ 227 int r_concurrency; /* Concurrency level requested by user. */ 228 int nrunnable_num; /* Average runnable threads, numerator. */ 229 int nrunnable_den; /* Average runnable threads, denominator. */ 230 int a_concurrency_num; /* Achieved concurrency level, numerator. */ 231 int a_concurrency_den; /* Achieved concurrency level, denominator. */ 232 int nlwps_num; /* Average number of processes in use, 233 numerator. */ 234 int nlwps_den; /* Average number of processes in use, 235 denominator. */ 236 int nidle_num; /* Average number of idling processes, 237 numerator. */ 238 int nidle_den; /* Average number of idling processes, 239 denominator. */ 240 } td_ta_stats_t; 241 242 243 /* Since Sun's library is based on Solaris threads we have to define a few 244 types to map them to POSIX threads. */ 245 typedef pthread_t thread_t; 246 typedef pthread_key_t thread_key_t; 247 248 249 /* Callback for iteration over threads. */ 250 typedef int td_thr_iter_f (const td_thrhandle_t *, void *); 251 252 /* Callback for iteration over thread local data. */ 253 typedef int td_key_iter_f (thread_key_t, void (*) (void *), void *); 254 255 256 257 /* Forward declaration. This has to be defined by the user. */ 258 struct ps_prochandle; 259 260 261 /* Information about the thread. */ 262 typedef struct td_thrinfo 263 { 264 td_thragent_t *ti_ta_p; /* Process handle. */ 265 unsigned int ti_user_flags; /* Unused. */ 266 thread_t ti_tid; /* Thread ID returned by 267 pthread_create(). */ 268 char *ti_tls; /* Pointer to thread-local data. */ 269 psaddr_t ti_startfunc; /* Start function passed to 270 pthread_create(). */ 271 psaddr_t ti_stkbase; /* Base of thread's stack. */ 272 long int ti_stksize; /* Size of thread's stack. */ 273 psaddr_t ti_ro_area; /* Unused. */ 274 int ti_ro_size; /* Unused. */ 275 td_thr_state_e ti_state; /* Thread state. */ 276 unsigned char ti_db_suspended; /* Nonzero if suspended by debugger. */ 277 td_thr_type_e ti_type; /* Type of the thread (system vs 278 user thread). */ 279 intptr_t ti_pc; /* Unused. */ 280 intptr_t ti_sp; /* Unused. */ 281 short int ti_flags; /* Unused. */ 282 int ti_pri; /* Thread priority. */ 283 lwpid_t ti_lid; /* Unused. */ 284 sigset_t ti_sigmask; /* Signal mask. */ 285 unsigned char ti_traceme; /* Nonzero if event reporting 286 enabled. */ 287 unsigned char ti_preemptflag; /* Unused. */ 288 unsigned char ti_pirecflag; /* Unused. */ 289 sigset_t ti_pending; /* Set of pending signals. */ 290 td_thr_events_t ti_events; /* Set of enabled events. */ 291 } td_thrinfo_t; 292 293 294 295 /* Prototypes for exported library functions. */ 296 297 /* Initialize the thread debug support library. */ 298 extern td_err_e td_init (void); 299 300 /* Historical relict. Should not be used anymore. */ 301 extern td_err_e td_log (void); 302 303 /* Return list of symbols the library can request. */ 304 extern const char **td_symbol_list (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 /* Get address of the given module's TLS storage area for the given thread. */ 411 extern td_err_e td_thr_tlsbase (const td_thrhandle_t *__th, 412 unsigned long int __modid, 413 psaddr_t *__base); 414 415 /* Get address of thread local variable. */ 416 extern td_err_e td_thr_tls_get_addr (const td_thrhandle_t *__th, 417 void *__map_address, size_t __offset, 418 void **__address); 419 420 421 /* Enable reporting for EVENT for thread TH. */ 422 extern td_err_e td_thr_event_enable (const td_thrhandle_t *__th, int __event); 423 424 /* Enable EVENT for thread TH. */ 425 extern td_err_e td_thr_set_event (const td_thrhandle_t *__th, 426 td_thr_events_t *__event); 427 428 /* Disable EVENT for thread TH. */ 429 extern td_err_e td_thr_clear_event (const td_thrhandle_t *__th, 430 td_thr_events_t *__event); 431 432 /* Get event message for thread TH. */ 433 extern td_err_e td_thr_event_getmsg (const td_thrhandle_t *__th, 434 td_event_msg_t *__msg); 435 436 437 /* Set priority of thread TH. */ 438 extern td_err_e td_thr_setprio (const td_thrhandle_t *__th, int __prio); 439 440 441 /* Set pending signals for thread TH. */ 442 extern td_err_e td_thr_setsigpending (const td_thrhandle_t *__th, 443 unsigned char __n, const sigset_t *__ss); 444 445 /* Set signal mask for thread TH. */ 446 extern td_err_e td_thr_sigsetmask (const td_thrhandle_t *__th, 447 const sigset_t *__ss); 448 449 450 /* Return thread local data associated with key TK in thread TH. */ 451 extern td_err_e td_thr_tsd (const td_thrhandle_t *__th, 452 const thread_key_t __tk, void **__data); 453 454 455 /* Suspend execution of thread TH. */ 456 extern td_err_e td_thr_dbsuspend (const td_thrhandle_t *__th); 457 458 /* Resume execution of thread TH. */ 459 extern td_err_e td_thr_dbresume (const td_thrhandle_t *__th); 460 461 #ifdef __cplusplus 462 } 463 #endif 464 465 #endif /* thread_db.h */ 466