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