Merge commit '0b2e8253986c5c761129b58cfdac46d204903de1'
[unleashed.git] / include / thread_db.h
blobd3d5b51ffb0262407030ce1112101ab70e1480a0
1 /*
2 * CDDL HEADER START
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]
19 * CDDL HEADER END
23 * Copyright 2008 Sun Microsystems, Inc. All rights reserved.
24 * Use is subject to license terms.
27 #ifndef _THREAD_DB_H
28 #define _THREAD_DB_H
32 * Description:
33 * Types, global variables, and function definitions for users
34 * of libc_db (formerly libthread_db).
39 #include <sys/lwp.h>
40 #include <sys/procfs_isa.h>
41 #include <thread.h>
42 #include <proc_service.h>
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
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
54 * Opaque handle types.
57 /* Client's handle for a process */
58 struct ps_prochandle;
60 /* libthread's handle for a process */
61 typedef struct td_thragent td_thragent_t;
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;
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;
75 /* ------------------------------------------------------------------ */
78 * The libc_db event facility.
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 */
84 /* Bitmask of enabled events. */
85 typedef struct td_thr_events {
86 uint_t event_bits[TD_EVENTSIZE];
87 } td_thr_events_t;
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)
94 #define td_event_emptyset(setp) \
95 { \
96 int _i_; \
97 _i_ = TD_EVENTSIZE; \
98 while (_i_) (setp)->event_bits[--_i_] = 0; \
101 #define td_event_fillset(setp) \
103 int _i_; \
104 _i_ = TD_EVENTSIZE; \
105 while (_i_) (setp)->event_bits[--_i_] = \
106 0xffffffff; \
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]))
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;
141 * Ways that an event type can be reported.
143 typedef enum {
144 NOTIFY_BPT,
146 * bpt to be inserted at u.bptaddr by
147 * debugger
149 NOTIFY_AUTOBPT, /* bpt inserted at u.bptaddr by application */
150 NOTIFY_SYSCALL /* syscall u.syscallno will be invoked */
151 } td_notify_e;
154 * How an event type is reported.
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;
165 * An event message.
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;
176 /* --------------------------------------------------------------------- */
179 * Thread information structure as returned by td_thr_get_info(), and
180 * related types.
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().
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;
199 * Thread type: user or system.
200 * As of Solaris 9, all threads are type TD_THR_USER.
202 typedef enum {
203 TD_THR_ANY_TYPE, /* not used */
204 TD_THR_USER,
205 TD_THR_SYSTEM
206 } td_thr_type_e;
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;
234 #define ti_tls ti_exitval /* for source compatibility */
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;
250 * Iterator callback function declarations.
253 /* Callback function for td_ta_tsd_iter(). */
254 typedef int td_key_iter_f(thread_key_t, void (*destructor)(), void *);
256 /* Callback function for td_ta_thr_iter(). */
257 typedef int td_thr_iter_f(const td_thrhandle_t *, void *);
259 /* Callback function for td_ta_sync_iter(). */
260 typedef int td_sync_iter_f(const td_synchandle_t *, void *);
262 /* -------------------------------------------------------------------- */
265 * Synchronization Objects
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;
277 #define TD_SV_MAX_FLAGS 4
278 typedef uint8_t td_sync_flags_t;
281 * Synchronization object information structure filled in by td_sync_get_info()
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;
305 * Statistics structures for the various synchronization objects, contained
306 * within the td_syncstats structure returned by td_sync_get_stats().
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;
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;
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;
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;
355 * Synchronization object statistics structure filled in by td_sync_get_stats()
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;
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;
396 /* ----------------------------------------------------------------------- */
399 * Exported functions.
403 * Initialize the threads debug interface.
405 td_err_e
406 td_init(void);
409 * A no-op, left for historical reasons.
411 void
412 td_log(void);
415 * Allocate a new process handle ("thread agent").
417 td_err_e
418 td_ta_new(struct ps_prochandle *, td_thragent_t **);
421 * De-allocate a process handle, releasing all related resources.
423 td_err_e
424 td_ta_delete(td_thragent_t *);
427 * Map a process handle to a client process handle.
429 td_err_e
430 td_ta_get_ph(const td_thragent_t *, struct ps_prochandle **);
433 * Set the process's suggested concurrency level.
435 td_err_e
436 td_ta_setconcurrency(const td_thragent_t *, int);
439 * Get the number of threads in the process, including zombie threads.
441 td_err_e
442 td_ta_get_nthreads(const td_thragent_t *, int *);
445 * Map a tid, as returned by thr_create(), to a thread handle.
447 td_err_e
448 td_ta_map_id2thr(const td_thragent_t *, thread_t, td_thrhandle_t *);
451 * Map the address of a synchronization object to a sync. object handle.
453 td_err_e
454 td_ta_map_addr2sync(const td_thragent_t *, psaddr_t, td_synchandle_t *);
457 * Iterate over a process's thread-specific data (TSD) keys.
459 td_err_e
460 td_ta_tsd_iter(const td_thragent_t *, td_key_iter_f *, void *);
463 * Iterate over a process's threads, including zombie threads.
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);
470 * Iterate over a process's known synchronization objects.
472 td_err_e
473 td_ta_sync_iter(const td_thragent_t *, td_sync_iter_f *, void *);
476 * Enable/disable process statistics collection.
478 td_err_e
479 td_ta_enable_stats(const td_thragent_t *, int);
482 * Reset process statistics.
484 td_err_e
485 td_ta_reset_stats(const td_thragent_t *);
488 * Read process statistics.
490 td_err_e
491 td_ta_get_stats(const td_thragent_t *, td_ta_stats_t *);
494 * Get thread information.
496 td_err_e
497 td_thr_get_info(const td_thrhandle_t *, td_thrinfo_t *);
500 * Get the "event address" for an event type.
502 td_err_e
503 td_ta_event_addr(const td_thragent_t *, td_event_e, td_notify_t *);
506 * Enable/disable event reporting for a thread.
508 td_err_e
509 td_thr_event_enable(const td_thrhandle_t *, int);
512 * Enable a set of events for a thread.
514 td_err_e
515 td_thr_set_event(const td_thrhandle_t *, td_thr_events_t *);
518 * Disable a set of events for a thread.
520 td_err_e
521 td_thr_clear_event(const td_thrhandle_t *, td_thr_events_t *);
524 * Retrieve (and consume) an event message for a thread.
526 td_err_e
527 td_thr_event_getmsg(const td_thrhandle_t *, td_event_msg_t *);
530 * Enable a set of events in the process.
532 td_err_e
533 td_ta_set_event(const td_thragent_t *, td_thr_events_t *);
536 * Disable a set of events in the process.
538 td_err_e
539 td_ta_clear_event(const td_thragent_t *, td_thr_events_t *);
542 * Retrieve (and consume) an event message for some thread in the process.
544 td_err_e
545 td_ta_event_getmsg(const td_thragent_t *, td_event_msg_t *);
548 * Suspend a thread.
550 td_err_e
551 td_thr_dbsuspend(const td_thrhandle_t *);
554 * Resume a suspended thread.
556 td_err_e
557 td_thr_dbresume(const td_thrhandle_t *);
560 * Set a thread's signal mask.
562 td_err_e
563 td_thr_sigsetmask(const td_thrhandle_t *, const sigset_t);
566 * Set a thread's "signals-pending" set.
568 td_err_e
569 td_thr_setsigpending(const td_thrhandle_t *, uchar_t, const sigset_t);
572 * Get a thread's general register set.
574 td_err_e
575 td_thr_getgregs(const td_thrhandle_t *, prgregset_t);
578 * Set a thread's general register set.
580 td_err_e
581 td_thr_setgregs(const td_thrhandle_t *, const prgregset_t);
584 * Get a thread's floating-point register set.
586 td_err_e
587 td_thr_getfpregs(const td_thrhandle_t *, prfpregset_t *);
590 * Set a thread's floating-point register set.
592 td_err_e
593 td_thr_setfpregs(const td_thrhandle_t *, const prfpregset_t *);
596 * Get the size of the extra state register set for this architecture.
598 td_err_e
599 td_thr_getxregsize(const td_thrhandle_t *th_p, int *xregsize);
602 * Get a thread's extra state register set.
604 td_err_e
605 td_thr_getxregs(const td_thrhandle_t *th_p, void *xregs);
608 * Set a thread's extra state register set.
610 td_err_e
611 td_thr_setxregs(const td_thrhandle_t *th_p, const void *xregs);
614 * Validate a thread handle.
616 td_err_e
617 td_thr_validate(const td_thrhandle_t *);
620 * Get a thread-specific data pointer for a thread.
622 td_err_e
623 td_thr_tsd(const td_thrhandle_t *, thread_key_t, void **);
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'.
629 td_err_e
630 td_thr_tlsbase(const td_thrhandle_t *, ulong_t moduleid, psaddr_t *base);
633 * Set a thread's priority.
635 td_err_e
636 td_thr_setprio(const td_thrhandle_t *, int);
639 * Iterate over the set of locks owned by a thread.
641 td_err_e
642 td_thr_lockowner(const td_thrhandle_t *, td_sync_iter_f *, void *);
645 * Return the sync. handle of the object this thread is sleeping on.
647 td_err_e
648 td_thr_sleepinfo(const td_thrhandle_t *, td_synchandle_t *);
651 * Map an lwpid, as returned by _lwp_create(), to a thread handle.
653 td_err_e
654 td_ta_map_lwp2thr(const td_thragent_t *, lwpid_t, td_thrhandle_t *th_p);
657 * Enable/disable a process's synchronization object tracking.
659 td_err_e
660 td_ta_sync_tracking_enable(const td_thragent_t *, int);
663 * Get information about a synchronization object.
665 td_err_e
666 td_sync_get_info(const td_synchandle_t *, td_syncinfo_t *);
669 * Get statistics for a synchronization object.
671 td_err_e
672 td_sync_get_stats(const td_synchandle_t *, td_syncstats_t *);
675 * Set the state of a synchronization object.
677 td_err_e
678 td_sync_setstate(const td_synchandle_t *, int value);
681 * Iterate over all threads blocked on a synchronization object.
683 td_err_e
684 td_sync_waiters(const td_synchandle_t *, td_thr_iter_f *, void *);
686 #ifdef __cplusplus
688 #endif
690 #endif /* _THREAD_DB_H */