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.
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.
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]
23 * Copyright 2008 Sun Microsystems, Inc. All rights reserved.
24 * Use is subject to license terms.
30 #pragma ident "%Z%%M% %I% %E% SMI"
35 * Types, global variables, and function definitions for users
36 * of libc_db (formerly libthread_db).
42 #include <sys/procfs_isa.h>
44 #include <proc_service.h>
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
56 * Opaque handle types.
59 /* Client's handle for a process */
62 /* libthread's handle for a process */
63 typedef struct td_thragent td_thragent_t
;
65 /* The thread handle. */
66 typedef struct td_thrhandle
{
67 td_thragent_t
*th_ta_p
;
71 /* The handle for a synchronization object. */
72 typedef struct td_synchandle
{
73 td_thragent_t
*sh_ta_p
;
77 /* ------------------------------------------------------------------ */
80 * The libc_db event facility.
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 */
86 /* Bitmask of enabled events. */
87 typedef struct td_thr_events
{
88 uint_t event_bits
[TD_EVENTSIZE
];
91 /* Event set manipulation macros. */
92 #define __td_eventmask(n) ((unsigned int)1 << (((n) - 1) \
94 #define __td_eventword(n) (((unsigned int)((n) - 1))>>5)
96 #define td_event_emptyset(setp) \
100 while (_i_) (setp)->event_bits[--_i_] = 0; \
103 #define td_event_fillset(setp) \
106 _i_ = TD_EVENTSIZE; \
107 while (_i_) (setp)->event_bits[--_i_] = \
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]))
121 TD_ALL_EVENTS
, /* pseudo-event number */
122 TD_EVENT_NONE
= TD_ALL_EVENTS
, /* depends on context */
137 TD_MIN_EVENT_NUM
= TD_READY
,
138 TD_MAX_EVENT_NUM
= TD_TIMEOUT
,
139 TD_EVENTS_ENABLE
= 31 /* Event reporting enabled */
143 * Ways that an event type can be reported.
148 * bpt to be inserted at u.bptaddr by
151 NOTIFY_AUTOBPT
, /* bpt inserted at u.bptaddr by application */
152 NOTIFY_SYSCALL
/* syscall u.syscallno will be invoked */
156 * How an event type is reported.
158 typedef struct td_notify
{
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 */
178 /* --------------------------------------------------------------------- */
181 * Thread information structure as returned by td_thr_get_info(), and
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().
197 TD_THR_STOPPED_ASLEEP
201 * Thread type: user or system.
202 * As of Solaris 9, all threads are type TD_THR_USER.
205 TD_THR_ANY_TYPE
, /* not used */
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 */
236 #define ti_tls ti_exitval /* for source compatibility */
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 */
252 * Iterator callback function declarations.
255 /* Callback function for td_ta_tsd_iter(). */
256 typedef int td_key_iter_f(thread_key_t
, void (*destructor
)(), void *);
258 /* Callback function for td_ta_thr_iter(). */
259 typedef int td_thr_iter_f(const td_thrhandle_t
*, void *);
261 /* Callback function for td_ta_sync_iter(). */
262 typedef int td_sync_iter_f(const td_synchandle_t
*, void *);
264 /* -------------------------------------------------------------------- */
267 * Synchronization Objects
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 */
279 #define TD_SV_MAX_FLAGS 4
280 typedef uint8_t td_sync_flags_t
;
283 * Synchronization object information structure filled in by td_sync_get_info()
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) */
293 int sem_count
; /* semaphore count */
294 int nreaders
; /* number of readers, -1 if writer */
295 int mutex_locked
; /* non-zero iff locked */
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 */
307 * Statistics structures for the various synchronization objects, contained
308 * within the td_syncstats structure returned by td_sync_get_stats().
313 hrtime_t mutex_sleep_time
;
314 hrtime_t mutex_hold_time
;
316 uint_t mutex_try_fail
;
317 uint_t mutex_internal
; /* internal to libthread */
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
;
327 uint_t cond_broadcast
;
328 uint_t cond_internal
; /* internal to libthread */
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
;
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
;
347 uint_t sema_wait_sleep
;
348 hrtime_t sema_wait_sleep_time
;
350 uint_t sema_trywait_fail
;
352 uint_t sema_max_count
;
353 uint_t sema_min_count
;
357 * Synchronization object statistics structure filled in by td_sync_get_stats()
359 typedef struct td_syncstats
{
360 td_syncinfo_t ss_info
; /* as returned by td_sync_get_info() */
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 */
370 /* The set of error codes. */
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 */
398 /* ----------------------------------------------------------------------- */
401 * Exported functions.
405 * Initialize the threads debug interface.
411 * A no-op, left for historical reasons.
417 * Allocate a new process handle ("thread agent").
420 td_ta_new(struct ps_prochandle
*, td_thragent_t
**);
423 * De-allocate a process handle, releasing all related resources.
426 td_ta_delete(td_thragent_t
*);
429 * Map a process handle to a client process handle.
432 td_ta_get_ph(const td_thragent_t
*, struct ps_prochandle
**);
435 * Set the process's suggested concurrency level.
438 td_ta_setconcurrency(const td_thragent_t
*, int);
441 * Get the number of threads in the process, including zombie threads.
444 td_ta_get_nthreads(const td_thragent_t
*, int *);
447 * Map a tid, as returned by thr_create(), to a thread handle.
450 td_ta_map_id2thr(const td_thragent_t
*, thread_t
, td_thrhandle_t
*);
453 * Map the address of a synchronization object to a sync. object handle.
456 td_ta_map_addr2sync(const td_thragent_t
*, psaddr_t
, td_synchandle_t
*);
459 * Iterate over a process's thread-specific data (TSD) keys.
462 td_ta_tsd_iter(const td_thragent_t
*, td_key_iter_f
*, void *);
465 * Iterate over a process's threads, including zombie threads.
468 td_ta_thr_iter(const td_thragent_t
*, td_thr_iter_f
*, void *,
469 td_thr_state_e
, int, sigset_t
*, unsigned);
472 * Iterate over a process's known synchronization objects.
475 td_ta_sync_iter(const td_thragent_t
*, td_sync_iter_f
*, void *);
478 * Enable/disable process statistics collection.
481 td_ta_enable_stats(const td_thragent_t
*, int);
484 * Reset process statistics.
487 td_ta_reset_stats(const td_thragent_t
*);
490 * Read process statistics.
493 td_ta_get_stats(const td_thragent_t
*, td_ta_stats_t
*);
496 * Get thread information.
499 td_thr_get_info(const td_thrhandle_t
*, td_thrinfo_t
*);
502 * Get the "event address" for an event type.
505 td_ta_event_addr(const td_thragent_t
*, td_event_e
, td_notify_t
*);
508 * Enable/disable event reporting for a thread.
511 td_thr_event_enable(const td_thrhandle_t
*, int);
514 * Enable a set of events for a thread.
517 td_thr_set_event(const td_thrhandle_t
*, td_thr_events_t
*);
520 * Disable a set of events for a thread.
523 td_thr_clear_event(const td_thrhandle_t
*, td_thr_events_t
*);
526 * Retrieve (and consume) an event message for a thread.
529 td_thr_event_getmsg(const td_thrhandle_t
*, td_event_msg_t
*);
532 * Enable a set of events in the process.
535 td_ta_set_event(const td_thragent_t
*, td_thr_events_t
*);
538 * Disable a set of events in the process.
541 td_ta_clear_event(const td_thragent_t
*, td_thr_events_t
*);
544 * Retrieve (and consume) an event message for some thread in the process.
547 td_ta_event_getmsg(const td_thragent_t
*, td_event_msg_t
*);
553 td_thr_dbsuspend(const td_thrhandle_t
*);
556 * Resume a suspended thread.
559 td_thr_dbresume(const td_thrhandle_t
*);
562 * Set a thread's signal mask.
565 td_thr_sigsetmask(const td_thrhandle_t
*, const sigset_t
);
568 * Set a thread's "signals-pending" set.
571 td_thr_setsigpending(const td_thrhandle_t
*, uchar_t
, const sigset_t
);
574 * Get a thread's general register set.
577 td_thr_getgregs(const td_thrhandle_t
*, prgregset_t
);
580 * Set a thread's general register set.
583 td_thr_setgregs(const td_thrhandle_t
*, const prgregset_t
);
586 * Get a thread's floating-point register set.
589 td_thr_getfpregs(const td_thrhandle_t
*, prfpregset_t
*);
592 * Set a thread's floating-point register set.
595 td_thr_setfpregs(const td_thrhandle_t
*, const prfpregset_t
*);
598 * Get the size of the extra state register set for this architecture.
601 td_thr_getxregsize(const td_thrhandle_t
*th_p
, int *xregsize
);
604 * Get a thread's extra state register set.
607 td_thr_getxregs(const td_thrhandle_t
*th_p
, void *xregs
);
610 * Set a thread's extra state register set.
613 td_thr_setxregs(const td_thrhandle_t
*th_p
, const void *xregs
);
616 * Validate a thread handle.
619 td_thr_validate(const td_thrhandle_t
*);
622 * Get a thread-specific data pointer for a thread.
625 td_thr_tsd(const td_thrhandle_t
*, thread_key_t
, void **);
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'.
632 td_thr_tlsbase(const td_thrhandle_t
*, ulong_t moduleid
, psaddr_t
*base
);
635 * Set a thread's priority.
638 td_thr_setprio(const td_thrhandle_t
*, int);
641 * Iterate over the set of locks owned by a thread.
644 td_thr_lockowner(const td_thrhandle_t
*, td_sync_iter_f
*, void *);
647 * Return the sync. handle of the object this thread is sleeping on.
650 td_thr_sleepinfo(const td_thrhandle_t
*, td_synchandle_t
*);
653 * Map an lwpid, as returned by _lwp_create(), to a thread handle.
656 td_ta_map_lwp2thr(const td_thragent_t
*, lwpid_t
, td_thrhandle_t
*th_p
);
659 * Enable/disable a process's synchronization object tracking.
662 td_ta_sync_tracking_enable(const td_thragent_t
*, int);
665 * Get information about a synchronization object.
668 td_sync_get_info(const td_synchandle_t
*, td_syncinfo_t
*);
671 * Get statistics for a synchronization object.
674 td_sync_get_stats(const td_synchandle_t
*, td_syncstats_t
*);
677 * Set the state of a synchronization object.
680 td_sync_setstate(const td_synchandle_t
*, int value
);
683 * Iterate over all threads blocked on a synchronization object.
686 td_sync_waiters(const td_synchandle_t
*, td_thr_iter_f
*, void *);
692 #endif /* _THREAD_DB_H */