1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 * or http://www.opensolaris.org/os/licensing. 10 * See the License for the specific language governing permissions 11 * and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL HEADER in each 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 * If applicable, add the following below this CDDL HEADER, with the 16 * fields enclosed by brackets "[]" replaced with your own identifying 17 * information: Portions Copyright [yyyy] [name of copyright owner] 18 * 19 * CDDL HEADER END 20 */ 21 22 /* 23 * Copyright 2008 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 27 #ifndef _THREAD_DB_H 28 #define _THREAD_DB_H 29 30 /* 31 * 32 * Description: 33 * Types, global variables, and function definitions for users 34 * of libc_db (formerly libthread_db). 35 * 36 */ 37 38 39 #include <sys/lwp.h> 40 #include <sys/procfs_isa.h> 41 #include <thread.h> 42 #include <proc_service.h> 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 #define TD_THR_ANY_USER_FLAGS 0xffffffff 49 #define TD_THR_LOWEST_PRIORITY -128 50 #define TD_SIGNO_MASK 0 51 #define TD_EVENTSIZE 2 52 53 /* 54 * Opaque handle types. 55 */ 56 57 /* Client's handle for a process */ 58 struct ps_prochandle; 59 60 /* libthread's handle for a process */ 61 typedef struct td_thragent td_thragent_t; 62 63 /* The thread handle. */ 64 typedef struct td_thrhandle { 65 td_thragent_t *th_ta_p; 66 psaddr_t th_unique; 67 } td_thrhandle_t; 68 69 /* The handle for a synchronization object. */ 70 typedef struct td_synchandle { 71 td_thragent_t *sh_ta_p; 72 psaddr_t sh_unique; 73 } td_synchandle_t; 74 75 /* ------------------------------------------------------------------ */ 76 77 /* 78 * The libc_db event facility. 79 */ 80 #define BT_UISHIFT 5 /* log base 2 of BT_NBIPUI, to extract word index */ 81 #define BT_NBIPUI (1 << BT_UISHIFT) /* n bits per uint */ 82 #define BT_UIMASK (BT_NBIPUI - 1) /* to extract bit index */ 83 84 /* Bitmask of enabled events. */ 85 typedef struct td_thr_events { 86 uint_t event_bits[TD_EVENTSIZE]; 87 } td_thr_events_t; 88 89 /* Event set manipulation macros. */ 90 #define __td_eventmask(n) ((unsigned int)1 << (((n) - 1) \ 91 & (BT_NBIPUI - 1))) 92 #define __td_eventword(n) (((unsigned int)((n) - 1))>>5) 93 94 #define td_event_emptyset(setp) \ 95 { \ 96 int _i_; \ 97 _i_ = TD_EVENTSIZE; \ 98 while (_i_) (setp)->event_bits[--_i_] = 0; \ 99 } 100 101 #define td_event_fillset(setp) \ 102 { \ 103 int _i_; \ 104 _i_ = TD_EVENTSIZE; \ 105 while (_i_) (setp)->event_bits[--_i_] = \ 106 0xffffffff; \ 107 } 108 109 #define td_event_addset(setp, n) \ 110 (((setp)->event_bits[__td_eventword(n)]) |= __td_eventmask(n)) 111 #define td_event_delset(setp, n) \ 112 (((setp)->event_bits[__td_eventword(n)]) &= ~__td_eventmask(n)) 113 #define td_eventismember(setp, n) \ 114 (__td_eventmask(n) & ((setp)->event_bits[__td_eventword(n)])) 115 #define td_eventisempty(setp) \ 116 (!((setp)->event_bits[0]) && !((setp)->event_bits[1])) 117 118 typedef enum { 119 TD_ALL_EVENTS, /* pseudo-event number */ 120 TD_EVENT_NONE = TD_ALL_EVENTS, /* depends on context */ 121 TD_READY, 122 TD_SLEEP, 123 TD_SWITCHTO, 124 TD_SWITCHFROM, 125 TD_LOCK_TRY, 126 TD_CATCHSIG, 127 TD_IDLE, 128 TD_CREATE, 129 TD_DEATH, 130 TD_PREEMPT, 131 TD_PRI_INHERIT, 132 TD_REAP, 133 TD_CONCURRENCY, 134 TD_TIMEOUT, 135 TD_MIN_EVENT_NUM = TD_READY, 136 TD_MAX_EVENT_NUM = TD_TIMEOUT, 137 TD_EVENTS_ENABLE = 31 /* Event reporting enabled */ 138 } td_event_e; 139 140 /* 141 * Ways that an event type can be reported. 142 */ 143 typedef enum { 144 NOTIFY_BPT, 145 /* 146 * bpt to be inserted at u.bptaddr by 147 * debugger 148 */ 149 NOTIFY_AUTOBPT, /* bpt inserted at u.bptaddr by application */ 150 NOTIFY_SYSCALL /* syscall u.syscallno will be invoked */ 151 } td_notify_e; 152 153 /* 154 * How an event type is reported. 155 */ 156 typedef struct td_notify { 157 td_notify_e type; 158 union { 159 psaddr_t bptaddr; 160 int syscallno; 161 } u; 162 } td_notify_t; 163 164 /* 165 * An event message. 166 */ 167 typedef struct td_event_msg { 168 td_event_e event; /* Event type being reported */ 169 const td_thrhandle_t *th_p; /* Thread reporting the event */ 170 union { /* Type-dependent event data */ 171 td_synchandle_t *sh; /* historical rubbish; ignore */ 172 uintptr_t data; /* valid, depending on event type */ 173 } msg; 174 } td_event_msg_t; 175 176 /* --------------------------------------------------------------------- */ 177 178 /* 179 * Thread information structure as returned by td_thr_get_info(), and 180 * related types. 181 */ 182 183 /* 184 * Possible thread states. TD_THR_ANY_STATE is a pseudo-state used 185 * to select threads regardless of state in td_ta_thr_iter(). 186 */ 187 typedef enum { 188 TD_THR_ANY_STATE, 189 TD_THR_UNKNOWN, 190 TD_THR_STOPPED, 191 TD_THR_RUN, 192 TD_THR_ACTIVE, 193 TD_THR_ZOMBIE, 194 TD_THR_SLEEP, 195 TD_THR_STOPPED_ASLEEP 196 } td_thr_state_e; 197 198 /* 199 * Thread type: user or system. 200 * As of Solaris 9, all threads are type TD_THR_USER. 201 */ 202 typedef enum { 203 TD_THR_ANY_TYPE, /* not used */ 204 TD_THR_USER, 205 TD_THR_SYSTEM 206 } td_thr_type_e; 207 208 typedef struct td_thrinfo { 209 td_thragent_t *ti_ta_p; /* process handle */ 210 unsigned ti_user_flags; /* flags passed to thr_create() */ 211 thread_t ti_tid; /* tid returned by thr_create() */ 212 void *ti_exitval; /* thread exit value (TD_THR_ZOMBIE) */ 213 psaddr_t ti_startfunc; /* startfunc passed to thr_create() */ 214 psaddr_t ti_stkbase; /* base of thread's stack */ 215 long ti_stksize; /* size of thread's stack */ 216 psaddr_t ti_ro_area; /* address of uthread_t struct */ 217 int ti_ro_size; /* size of uthread_t struct */ 218 td_thr_state_e ti_state; /* thread state */ 219 uchar_t ti_db_suspended; /* boolean: suspended by debugger? */ 220 td_thr_type_e ti_type; /* thread type */ 221 intptr_t ti_pc; /* resume PC when sleeping */ 222 intptr_t ti_sp; /* resume SP when sleeping */ 223 short ti_flags; /* flags used by libthread */ 224 int ti_pri; /* thread priority */ 225 lwpid_t ti_lid; /* last LWP assigned to this thread */ 226 sigset_t ti_sigmask; /* signal mask */ 227 uchar_t ti_traceme; /* event reporting enabled? */ 228 uchar_t ti_preemptflag; /* was thread preemppted? */ 229 uchar_t ti_pirecflag; /* priority inheritance happened */ 230 sigset_t ti_pending; /* set of pending signals */ 231 td_thr_events_t ti_events; /* set of enabled events */ 232 } td_thrinfo_t; 233 234 #define ti_tls ti_exitval /* for source compatibility */ 235 236 typedef struct td_ta_stats { 237 int nthreads; /* total number of threads in use */ 238 int r_concurrency; /* requested concurrency level */ 239 int nrunnable_num; /* numerator, avg. runnable threads */ 240 int nrunnable_den; /* denominator, avg. runnable threads */ 241 int a_concurrency_num; /* numerator, achieved concurrency level */ 242 int a_concurrency_den; /* denominator, concurrency level */ 243 int nlwps_num; /* numerator, average number of LWP's in use */ 244 int nlwps_den; /* denom., average number of LWP's in use */ 245 int nidle_num; /* numerator, avg. number of idling LWP's */ 246 int nidle_den; /* denom., avg. number of idling LWP's */ 247 } td_ta_stats_t; 248 249 /* 250 * Iterator callback function declarations. 251 */ 252 253 /* Callback function for td_ta_tsd_iter(). */ 254 typedef int td_key_iter_f(thread_key_t, void (*destructor)(), void *); 255 256 /* Callback function for td_ta_thr_iter(). */ 257 typedef int td_thr_iter_f(const td_thrhandle_t *, void *); 258 259 /* Callback function for td_ta_sync_iter(). */ 260 typedef int td_sync_iter_f(const td_synchandle_t *, void *); 261 262 /* -------------------------------------------------------------------- */ 263 264 /* 265 * Synchronization Objects 266 */ 267 268 /* Enumeration of synchronization object types. */ 269 typedef enum td_sync_type_e { 270 TD_SYNC_UNKNOWN, /* Sync. variable of unknown type */ 271 TD_SYNC_COND, /* Condition variable */ 272 TD_SYNC_MUTEX, /* Mutex lock */ 273 TD_SYNC_SEMA, /* Semaphore */ 274 TD_SYNC_RWLOCK /* Reader/Writer lock */ 275 } td_sync_type_e; 276 277 #define TD_SV_MAX_FLAGS 4 278 typedef uint8_t td_sync_flags_t; 279 280 /* 281 * Synchronization object information structure filled in by td_sync_get_info() 282 */ 283 typedef struct td_syncinfo { 284 td_thragent_t *si_ta_p; /* process handle */ 285 psaddr_t si_sv_addr; /* address of sync. object */ 286 td_sync_type_e si_type; /* object type */ 287 uint32_t si_shared_type; /* process-shared or process-private */ 288 td_sync_flags_t si_flags[TD_SV_MAX_FLAGS]; /* flags (?) */ 289 pid_t si_ownerpid; /* owner's process-id (USYNC_PROCESS) */ 290 union _si_un_state { 291 int sem_count; /* semaphore count */ 292 int nreaders; /* number of readers, -1 if writer */ 293 int mutex_locked; /* non-zero iff locked */ 294 } si_state; 295 int si_size; /* size in bytes of synch variable */ 296 uint8_t si_has_waiters; /* non-zero iff at least one waiter */ 297 uint8_t si_is_wlock; /* non-zero iff rwlock write-locked */ 298 uint8_t si_rcount; /* count for locked recursive mutex */ 299 uint8_t si_prioceiling; /* ceiling pri (PTHREAD_PRIO_PROTECT) */ 300 td_thrhandle_t si_owner; /* mutex holder or write-lock holder */ 301 psaddr_t si_data; /* optional data */ 302 } td_syncinfo_t; 303 304 /* 305 * Statistics structures for the various synchronization objects, contained 306 * within the td_syncstats structure returned by td_sync_get_stats(). 307 */ 308 typedef struct { 309 uint_t mutex_lock; 310 uint_t mutex_sleep; 311 hrtime_t mutex_sleep_time; 312 hrtime_t mutex_hold_time; 313 uint_t mutex_try; 314 uint_t mutex_try_fail; 315 uint_t mutex_internal; /* internal to libthread */ 316 } td_mutex_stats_t; 317 318 typedef struct { 319 uint_t cond_wait; 320 uint_t cond_timedwait; 321 hrtime_t cond_wait_sleep_time; 322 hrtime_t cond_timedwait_sleep_time; 323 uint_t cond_timedwait_timeout; 324 uint_t cond_signal; 325 uint_t cond_broadcast; 326 uint_t cond_internal; /* internal to libthread */ 327 } td_cond_stats_t; 328 329 typedef struct { 330 uint_t rw_rdlock; 331 uint_t rw_rdlock_sleep; 332 hrtime_t rw_rdlock_sleep_time; 333 uint_t rw_rdlock_try; 334 uint_t rw_rdlock_try_fail; 335 uint_t rw_wrlock; 336 uint_t rw_wrlock_sleep; 337 hrtime_t rw_wrlock_sleep_time; 338 hrtime_t rw_wrlock_hold_time; 339 uint_t rw_wrlock_try; 340 uint_t rw_wrlock_try_fail; 341 } td_rwlock_stats_t; 342 343 typedef struct { 344 uint_t sema_wait; 345 uint_t sema_wait_sleep; 346 hrtime_t sema_wait_sleep_time; 347 uint_t sema_trywait; 348 uint_t sema_trywait_fail; 349 uint_t sema_post; 350 uint_t sema_max_count; 351 uint_t sema_min_count; 352 } td_sema_stats_t; 353 354 /* 355 * Synchronization object statistics structure filled in by td_sync_get_stats() 356 */ 357 typedef struct td_syncstats { 358 td_syncinfo_t ss_info; /* as returned by td_sync_get_info() */ 359 union { 360 td_mutex_stats_t mutex; 361 td_cond_stats_t cond; 362 td_rwlock_stats_t rwlock; 363 td_sema_stats_t sema; 364 uint_t pad[32]; /* for future growth */ 365 } ss_un; 366 } td_syncstats_t; 367 368 /* The set of error codes. */ 369 typedef enum { 370 TD_OK, /* generic "call succeeded" */ 371 TD_ERR, /* generic error. */ 372 TD_NOTHR, /* no thread can be found to satisfy query */ 373 TD_NOSV, /* no synch. handle can be found to satisfy query */ 374 TD_NOLWP, /* no lwp can be found to satisfy query */ 375 TD_BADPH, /* invalid process handle */ 376 TD_BADTH, /* invalid thread handle */ 377 TD_BADSH, /* invalid synchronization handle */ 378 TD_BADTA, /* invalid thread agent */ 379 TD_BADKEY, /* invalid key */ 380 TD_NOMSG, /* no event message for td_thr_event_getmsg() */ 381 TD_NOFPREGS, /* FPU register set not available */ 382 TD_NOLIBTHREAD, /* application not linked with libthread */ 383 TD_NOEVENT, /* requested event is not supported */ 384 TD_NOCAPAB, /* capability not available */ 385 TD_DBERR, /* Debugger service failed */ 386 TD_NOAPLIC, /* Operation not applicable to */ 387 TD_NOTSD, /* No thread-specific data for this thread */ 388 TD_MALLOC, /* Malloc failed */ 389 TD_PARTIALREG, /* Only part of register set was writen/read */ 390 TD_NOXREGS, /* X register set not available for given thread */ 391 TD_NOTLS, /* There is no TLS in the specified module */ 392 TD_TLSDEFER /* module's TLS not yet allocated by the thread */ 393 } td_err_e; 394 395 396 /* ----------------------------------------------------------------------- */ 397 398 /* 399 * Exported functions. 400 */ 401 402 /* 403 * Initialize the threads debug interface. 404 */ 405 td_err_e 406 td_init(void); 407 408 /* 409 * A no-op, left for historical reasons. 410 */ 411 void 412 td_log(void); 413 414 /* 415 * Allocate a new process handle ("thread agent"). 416 */ 417 td_err_e 418 td_ta_new(struct ps_prochandle *, td_thragent_t **); 419 420 /* 421 * De-allocate a process handle, releasing all related resources. 422 */ 423 td_err_e 424 td_ta_delete(td_thragent_t *); 425 426 /* 427 * Map a process handle to a client process handle. 428 */ 429 td_err_e 430 td_ta_get_ph(const td_thragent_t *, struct ps_prochandle **); 431 432 /* 433 * Set the process's suggested concurrency level. 434 */ 435 td_err_e 436 td_ta_setconcurrency(const td_thragent_t *, int); 437 438 /* 439 * Get the number of threads in the process, including zombie threads. 440 */ 441 td_err_e 442 td_ta_get_nthreads(const td_thragent_t *, int *); 443 444 /* 445 * Map a tid, as returned by thr_create(), to a thread handle. 446 */ 447 td_err_e 448 td_ta_map_id2thr(const td_thragent_t *, thread_t, td_thrhandle_t *); 449 450 /* 451 * Map the address of a synchronization object to a sync. object handle. 452 */ 453 td_err_e 454 td_ta_map_addr2sync(const td_thragent_t *, psaddr_t, td_synchandle_t *); 455 456 /* 457 * Iterate over a process's thread-specific data (TSD) keys. 458 */ 459 td_err_e 460 td_ta_tsd_iter(const td_thragent_t *, td_key_iter_f *, void *); 461 462 /* 463 * Iterate over a process's threads, including zombie threads. 464 */ 465 td_err_e 466 td_ta_thr_iter(const td_thragent_t *, td_thr_iter_f *, void *, 467 td_thr_state_e, int, sigset_t *, unsigned); 468 469 /* 470 * Iterate over a process's known synchronization objects. 471 */ 472 td_err_e 473 td_ta_sync_iter(const td_thragent_t *, td_sync_iter_f *, void *); 474 475 /* 476 * Enable/disable process statistics collection. 477 */ 478 td_err_e 479 td_ta_enable_stats(const td_thragent_t *, int); 480 481 /* 482 * Reset process statistics. 483 */ 484 td_err_e 485 td_ta_reset_stats(const td_thragent_t *); 486 487 /* 488 * Read process statistics. 489 */ 490 td_err_e 491 td_ta_get_stats(const td_thragent_t *, td_ta_stats_t *); 492 493 /* 494 * Get thread information. 495 */ 496 td_err_e 497 td_thr_get_info(const td_thrhandle_t *, td_thrinfo_t *); 498 499 /* 500 * Get the "event address" for an event type. 501 */ 502 td_err_e 503 td_ta_event_addr(const td_thragent_t *, td_event_e, td_notify_t *); 504 505 /* 506 * Enable/disable event reporting for a thread. 507 */ 508 td_err_e 509 td_thr_event_enable(const td_thrhandle_t *, int); 510 511 /* 512 * Enable a set of events for a thread. 513 */ 514 td_err_e 515 td_thr_set_event(const td_thrhandle_t *, td_thr_events_t *); 516 517 /* 518 * Disable a set of events for a thread. 519 */ 520 td_err_e 521 td_thr_clear_event(const td_thrhandle_t *, td_thr_events_t *); 522 523 /* 524 * Retrieve (and consume) an event message for a thread. 525 */ 526 td_err_e 527 td_thr_event_getmsg(const td_thrhandle_t *, td_event_msg_t *); 528 529 /* 530 * Enable a set of events in the process. 531 */ 532 td_err_e 533 td_ta_set_event(const td_thragent_t *, td_thr_events_t *); 534 535 /* 536 * Disable a set of events in the process. 537 */ 538 td_err_e 539 td_ta_clear_event(const td_thragent_t *, td_thr_events_t *); 540 541 /* 542 * Retrieve (and consume) an event message for some thread in the process. 543 */ 544 td_err_e 545 td_ta_event_getmsg(const td_thragent_t *, td_event_msg_t *); 546 547 /* 548 * Suspend a thread. 549 */ 550 td_err_e 551 td_thr_dbsuspend(const td_thrhandle_t *); 552 553 /* 554 * Resume a suspended thread. 555 */ 556 td_err_e 557 td_thr_dbresume(const td_thrhandle_t *); 558 559 /* 560 * Set a thread's signal mask. 561 */ 562 td_err_e 563 td_thr_sigsetmask(const td_thrhandle_t *, const sigset_t); 564 565 /* 566 * Set a thread's "signals-pending" set. 567 */ 568 td_err_e 569 td_thr_setsigpending(const td_thrhandle_t *, uchar_t, const sigset_t); 570 571 /* 572 * Get a thread's general register set. 573 */ 574 td_err_e 575 td_thr_getgregs(const td_thrhandle_t *, prgregset_t); 576 577 /* 578 * Set a thread's general register set. 579 */ 580 td_err_e 581 td_thr_setgregs(const td_thrhandle_t *, const prgregset_t); 582 583 /* 584 * Get a thread's floating-point register set. 585 */ 586 td_err_e 587 td_thr_getfpregs(const td_thrhandle_t *, prfpregset_t *); 588 589 /* 590 * Set a thread's floating-point register set. 591 */ 592 td_err_e 593 td_thr_setfpregs(const td_thrhandle_t *, const prfpregset_t *); 594 595 /* 596 * Get the size of the extra state register set for this architecture. 597 */ 598 td_err_e 599 td_thr_getxregsize(const td_thrhandle_t *th_p, int *xregsize); 600 601 /* 602 * Get a thread's extra state register set. 603 */ 604 td_err_e 605 td_thr_getxregs(const td_thrhandle_t *th_p, void *xregs); 606 607 /* 608 * Set a thread's extra state register set. 609 */ 610 td_err_e 611 td_thr_setxregs(const td_thrhandle_t *th_p, const void *xregs); 612 613 /* 614 * Validate a thread handle. 615 */ 616 td_err_e 617 td_thr_validate(const td_thrhandle_t *); 618 619 /* 620 * Get a thread-specific data pointer for a thread. 621 */ 622 td_err_e 623 td_thr_tsd(const td_thrhandle_t *, thread_key_t, void **); 624 625 /* 626 * Get the base address of a thread's thread local storage (TLS) block 627 * for the module (executable or shared object) identified by 'moduleid'. 628 */ 629 td_err_e 630 td_thr_tlsbase(const td_thrhandle_t *, ulong_t moduleid, psaddr_t *base); 631 632 /* 633 * Set a thread's priority. 634 */ 635 td_err_e 636 td_thr_setprio(const td_thrhandle_t *, int); 637 638 /* 639 * Iterate over the set of locks owned by a thread. 640 */ 641 td_err_e 642 td_thr_lockowner(const td_thrhandle_t *, td_sync_iter_f *, void *); 643 644 /* 645 * Return the sync. handle of the object this thread is sleeping on. 646 */ 647 td_err_e 648 td_thr_sleepinfo(const td_thrhandle_t *, td_synchandle_t *); 649 650 /* 651 * Map an lwpid, as returned by _lwp_create(), to a thread handle. 652 */ 653 td_err_e 654 td_ta_map_lwp2thr(const td_thragent_t *, lwpid_t, td_thrhandle_t *th_p); 655 656 /* 657 * Enable/disable a process's synchronization object tracking. 658 */ 659 td_err_e 660 td_ta_sync_tracking_enable(const td_thragent_t *, int); 661 662 /* 663 * Get information about a synchronization object. 664 */ 665 td_err_e 666 td_sync_get_info(const td_synchandle_t *, td_syncinfo_t *); 667 668 /* 669 * Get statistics for a synchronization object. 670 */ 671 td_err_e 672 td_sync_get_stats(const td_synchandle_t *, td_syncstats_t *); 673 674 /* 675 * Set the state of a synchronization object. 676 */ 677 td_err_e 678 td_sync_setstate(const td_synchandle_t *, int value); 679 680 /* 681 * Iterate over all threads blocked on a synchronization object. 682 */ 683 td_err_e 684 td_sync_waiters(const td_synchandle_t *, td_thr_iter_f *, void *); 685 686 #ifdef __cplusplus 687 } 688 #endif 689 690 #endif /* _THREAD_DB_H */ 691