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