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