b7f33c1735c098f37d3e28afef87e25dca91a228
[kopensolaris-gnu/glibc.git] / nptl_db / thread_db.h
1 /* thread_db.h -- interface to libthread_db.so library for debugging -lpthread
2    Copyright (C) 1999,2001,2002,2003 Free Software Foundation, Inc.
3    This file is part of the GNU C Library.
4
5    The GNU C Library is free software; you can redistribute it and/or
6    modify it under the terms of the GNU Lesser General Public
7    License as published by the Free Software Foundation; either
8    version 2.1 of the License, or (at your option) any later version.
9
10    The GNU C Library is distributed in the hope that it will be useful,
11    but WITHOUT ANY WARRANTY; without even the implied warranty of
12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13    Lesser General Public License for more details.
14
15    You should have received a copy of the GNU Lesser General Public
16    License along with the GNU C Library; if not, write to the Free
17    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
18    02111-1307 USA.  */
19
20 #ifndef _THREAD_DB_H
21 #define _THREAD_DB_H    1
22
23 /* This is the debugger interface for the NPTL library.  It is
24    modelled closely after the interface with same names in Solaris
25    with the goal to share the same code in the debugger.  */
26 #include <pthread.h>
27 #include <stdint.h>
28 #include <sys/types.h>
29 #include <sys/procfs.h>
30
31
32 /* Error codes of the library.  */
33 typedef enum
34 {
35   TD_OK,          /* No error.  */
36   TD_ERR,         /* No further specified error.  */
37   TD_NOTHR,       /* No matching thread found.  */
38   TD_NOSV,        /* No matching synchronization handle found.  */
39   TD_NOLWP,       /* No matching light-weighted process found.  */
40   TD_BADPH,       /* Invalid process handle.  */
41   TD_BADTH,       /* Invalid thread handle.  */
42   TD_BADSH,       /* Invalid synchronization handle.  */
43   TD_BADTA,       /* Invalid thread agent.  */
44   TD_BADKEY,      /* Invalid key.  */
45   TD_NOMSG,       /* No event available.  */
46   TD_NOFPREGS,    /* No floating-point register content available.  */
47   TD_NOLIBTHREAD, /* Application not linked with thread library.  */
48   TD_NOEVENT,     /* Requested event is not supported.  */
49   TD_NOCAPAB,     /* Capability not available.  */
50   TD_DBERR,       /* Internal debug library error.  */
51   TD_NOAPLIC,     /* Operation is not applicable.  */
52   TD_NOTSD,       /* No thread-specific data available.  */
53   TD_MALLOC,      /* Out of memory.  */
54   TD_PARTIALREG,  /* Not entire register set was read or written.  */
55   TD_NOXREGS,     /* X register set not available for given thread.  */
56   TD_TLSDEFER,    /* Thread has not yet allocated TLS for given module.  */
57   TD_NOTALLOC = TD_TLSDEFER,
58   TD_VERSION,     /* Version if libpthread and libthread_db do not match.  */
59   TD_NOTLS        /* There is no TLS segment in the given module.  */
60 } td_err_e;
61
62
63 /* Possible thread states.  TD_THR_ANY_STATE is a pseudo-state used to
64    select threads regardless of state in td_ta_thr_iter().  */
65 typedef enum
66 {
67   TD_THR_ANY_STATE,
68   TD_THR_UNKNOWN,
69   TD_THR_STOPPED,
70   TD_THR_RUN,
71   TD_THR_ACTIVE,
72   TD_THR_ZOMBIE,
73   TD_THR_SLEEP,
74   TD_THR_STOPPED_ASLEEP
75 } td_thr_state_e;
76
77 /* Thread type: user or system.  TD_THR_ANY_TYPE is a pseudo-type used
78    to select threads regardless of type in td_ta_thr_iter().  */
79 typedef enum
80 {
81   TD_THR_ANY_TYPE,
82   TD_THR_USER,
83   TD_THR_SYSTEM
84 } td_thr_type_e;
85
86
87 /* Types of the debugging library.  */
88
89 /* Handle for a process.  This type is opaque.  */
90 typedef struct td_thragent td_thragent_t;
91
92 /* The actual thread handle type.  This is also opaque.  */
93 typedef struct td_thrhandle
94 {
95   td_thragent_t *th_ta_p;
96   psaddr_t th_unique;
97 } td_thrhandle_t;
98
99
100 /* Forward declaration of a type defined by and for the dynamic linker.  */
101 struct link_map;
102
103
104 /* Flags for `td_ta_thr_iter'.  */
105 #define TD_THR_ANY_USER_FLAGS   0xffffffff
106 #define TD_THR_LOWEST_PRIORITY  -20
107 #define TD_SIGNO_MASK           NULL
108
109
110 #define TD_EVENTSIZE    2
111 #define BT_UISHIFT      5 /* log base 2 of BT_NBIPUI, to extract word index */
112 #define BT_NBIPUI       (1 << BT_UISHIFT)       /* n bits per uint */
113 #define BT_UIMASK       (BT_NBIPUI - 1)         /* to extract bit index */
114
115 /* Bitmask of enabled events. */
116 typedef struct td_thr_events
117 {
118   uint32_t event_bits[TD_EVENTSIZE];
119 } td_thr_events_t;
120
121 /* Event set manipulation macros. */
122 #define __td_eventmask(n) \
123   (UINT32_C (1) << (((n) - 1) & BT_UIMASK))
124 #define __td_eventword(n) \
125   ((UINT32_C ((n) - 1)) >> BT_UISHIFT)
126
127 #define td_event_emptyset(setp) \
128   do {                                                                        \
129     int __i;                                                                  \
130     for (__i = TD_EVENTSIZE; __i > 0; --__i)                                  \
131       (setp)->event_bits[__i - 1] = 0;                                        \
132   } while (0)
133
134 #define td_event_fillset(setp) \
135   do {                                                                        \
136     int __i;                                                                  \
137     for (__i = TD_EVENTSIZE; __i > 0; --__i)                                  \
138       (setp)->event_bits[__i - 1] = UINT32_C (0xffffffff);                    \
139   } while (0)
140
141 #define td_event_addset(setp, n) \
142   (((setp)->event_bits[__td_eventword (n)]) |= __td_eventmask (n))
143 #define td_event_delset(setp, n) \
144   (((setp)->event_bits[__td_eventword (n)]) &= ~__td_eventmask (n))
145 #define td_eventismember(setp, n) \
146   (__td_eventmask (n) & ((setp)->event_bits[__td_eventword (n)]))
147 #if TD_EVENTSIZE == 2
148 # define td_eventisempty(setp) \
149   (!((setp)->event_bits[0]) && !((setp)->event_bits[1]))
150 #else
151 # error "td_eventisempty must be changed to match TD_EVENTSIZE"
152 #endif
153
154 /* Events reportable by the thread implementation.  */
155 typedef enum
156 {
157   TD_ALL_EVENTS,                 /* Pseudo-event number.  */
158   TD_EVENT_NONE = TD_ALL_EVENTS, /* Depends on context.  */
159   TD_READY,                      /* Is executable now. */
160   TD_SLEEP,                      /* Blocked in a synchronization obj.  */
161   TD_SWITCHTO,                   /* Now assigned to a process.  */
162   TD_SWITCHFROM,                 /* Not anymore assigned to a process.  */
163   TD_LOCK_TRY,                   /* Trying to get an unavailable lock.  */
164   TD_CATCHSIG,                   /* Signal posted to the thread.  */
165   TD_IDLE,                       /* Process getting idle.  */
166   TD_CREATE,                     /* New thread created.  */
167   TD_DEATH,                      /* Thread terminated.  */
168   TD_PREEMPT,                    /* Preempted.  */
169   TD_PRI_INHERIT,                /* Inherited elevated priority.  */
170   TD_REAP,                       /* Reaped.  */
171   TD_CONCURRENCY,                /* Number of processes changing.  */
172   TD_TIMEOUT,                    /* Conditional variable wait timed out.  */
173   TD_MIN_EVENT_NUM = TD_READY,
174   TD_MAX_EVENT_NUM = TD_TIMEOUT,
175   TD_EVENTS_ENABLE = 31         /* Event reporting enabled.  */
176 } td_event_e;
177
178 /* Values representing the different ways events are reported.  */
179 typedef enum
180 {
181   NOTIFY_BPT,                   /* User must insert breakpoint at u.bptaddr. */
182   NOTIFY_AUTOBPT,               /* Breakpoint at u.bptaddr is automatically
183                                    inserted.  */
184   NOTIFY_SYSCALL                /* System call u.syscallno will be invoked.  */
185 } td_notify_e;
186
187 /* Description how event type is reported.  */
188 typedef struct td_notify
189 {
190   td_notify_e type;             /* Way the event is reported.  */
191   union
192   {
193     psaddr_t bptaddr;           /* Address of breakpoint.  */
194     int syscallno;              /* Number of system call used.  */
195   } u;
196 } td_notify_t;
197
198 /* Structure used to report event.  */
199 typedef struct td_event_msg
200 {
201   td_event_e event;             /* Event type being reported.  */
202   const td_thrhandle_t *th_p;   /* Thread reporting the event.  */
203   union
204   {
205 # if 0
206     td_synchandle_t *sh;        /* Handle of synchronization object.  */
207 #endif
208     uintptr_t data;             /* Event specific data.  */
209   } msg;
210 } td_event_msg_t;
211
212 /* Structure containing event data available in each thread structure.  */
213 typedef struct
214 {
215   td_thr_events_t eventmask;    /* Mask of enabled events.  */
216   td_event_e eventnum;          /* Number of last event.  */
217   void *eventdata;              /* Data associated with event.  */
218 } td_eventbuf_t;
219
220
221 /* Gathered statistics about the process.  */
222 typedef struct td_ta_stats
223 {
224   int nthreads;                 /* Total number of threads in use.  */
225   int r_concurrency;            /* Concurrency level requested by user.  */
226   int nrunnable_num;            /* Average runnable threads, numerator.  */
227   int nrunnable_den;            /* Average runnable threads, denominator.  */
228   int a_concurrency_num;        /* Achieved concurrency level, numerator.  */
229   int a_concurrency_den;        /* Achieved concurrency level, denominator.  */
230   int nlwps_num;                /* Average number of processes in use,
231                                    numerator.  */
232   int nlwps_den;                /* Average number of processes in use,
233                                    denominator.  */
234   int nidle_num;                /* Average number of idling processes,
235                                    numerator.  */
236   int nidle_den;                /* Average number of idling processes,
237                                    denominator.  */
238 } td_ta_stats_t;
239
240
241 /* Since Sun's library is based on Solaris threads we have to define a few
242    types to map them to POSIX threads.  */
243 #if 0
244 typedef pthread_t thread_t;
245 typedef pthread_key_t thread_key_t;
246 #endif
247 #include <thread.h>
248
249
250 /* Callback for iteration over threads.  */
251 typedef int td_thr_iter_f (const td_thrhandle_t *, void *);
252
253 /* Callback for iteration over thread local data.  */
254 typedef int td_key_iter_f (thread_key_t, void (*) (void *), void *);
255
256
257
258 /* Forward declaration.  This has to be defined by the user.  */
259 struct ps_prochandle;
260
261
262 /* Information about the thread.  */
263 typedef struct td_thrinfo
264 {
265   td_thragent_t *ti_ta_p;               /* Process handle.  */
266   unsigned int ti_user_flags;           /* Unused.  */
267   thread_t ti_tid;                      /* Thread ID returned by
268                                            pthread_create().  */
269   char *ti_tls;                         /* Pointer to thread-local data.  */
270   psaddr_t ti_startfunc;                /* Start function passed to
271                                            pthread_create().  */
272   psaddr_t ti_stkbase;                  /* Base of thread's stack.  */
273   long int ti_stksize;                  /* Size of thread's stack.  */
274   psaddr_t ti_ro_area;                  /* Unused.  */
275   int ti_ro_size;                       /* Unused.  */
276   td_thr_state_e ti_state;              /* Thread state.  */
277   unsigned char ti_db_suspended;        /* Nonzero if suspended by debugger. */
278   td_thr_type_e ti_type;                /* Type of the thread (system vs
279                                            user thread).  */
280   intptr_t ti_pc;                       /* Unused.  */
281   intptr_t ti_sp;                       /* Unused.  */
282   short int ti_flags;                   /* Unused.  */
283   int ti_pri;                           /* Thread priority.  */
284   lwpid_t ti_lid;                       /* Kernel PID for this thread.  */
285   sigset_t ti_sigmask;                  /* Signal mask.  */
286   unsigned char ti_traceme;             /* Nonzero if event reporting
287                                            enabled.  */
288   unsigned char ti_preemptflag;         /* Unused.  */
289   unsigned char ti_pirecflag;           /* Unused.  */
290   sigset_t ti_pending;                  /* Set of pending signals.  */
291   td_thr_events_t ti_events;            /* Set of enabled events.  */
292 } td_thrinfo_t;
293
294
295
296 /* Prototypes for exported library functions.  */
297
298 /* Initialize the thread debug support library.  */
299 extern td_err_e td_init (void);
300
301 /* Historical relict.  Should not be used anymore.  */
302 extern td_err_e td_log (void);
303
304 /* Return list of symbols the library can request.  */
305 extern const char **td_symbol_list (void);
306
307 /* Generate new thread debug library handle for process PS.  */
308 extern td_err_e td_ta_new (struct ps_prochandle *__ps, td_thragent_t **__ta);
309
310 /* Free resources allocated for TA.  */
311 extern td_err_e td_ta_delete (td_thragent_t *__ta);
312
313 /* Get number of currently running threads in process associated with TA.  */
314 extern td_err_e td_ta_get_nthreads (const td_thragent_t *__ta, int *__np);
315
316 /* Return process handle passed in `td_ta_new' for process associated with
317    TA.  */
318 extern td_err_e td_ta_get_ph (const td_thragent_t *__ta,
319                               struct ps_prochandle **__ph);
320
321 /* Map thread library handle PT to thread debug library handle for process
322    associated with TA and store result in *TH.  */
323 extern td_err_e td_ta_map_id2thr (const td_thragent_t *__ta, pthread_t __pt,
324                                   td_thrhandle_t *__th);
325
326 /* Map process ID LWPID to thread debug library handle for process
327    associated with TA and store result in *TH.  */
328 extern td_err_e td_ta_map_lwp2thr (const td_thragent_t *__ta, lwpid_t __lwpid,
329                                    td_thrhandle_t *__th);
330
331
332 /* Call for each thread in a process associated with TA the callback function
333    CALLBACK.  */
334 extern td_err_e td_ta_thr_iter (const td_thragent_t *__ta,
335                                 td_thr_iter_f *__callback, void *__cbdata_p,
336                                 td_thr_state_e __state, int __ti_pri,
337                                 sigset_t *__ti_sigmask_p,
338                                 unsigned int __ti_user_flags);
339
340 /* Call for each defined thread local data entry the callback function KI.  */
341 extern td_err_e td_ta_tsd_iter (const td_thragent_t *__ta, td_key_iter_f *__ki,
342                                 void *__p);
343
344
345 /* Get event address for EVENT.  */
346 extern td_err_e td_ta_event_addr (const td_thragent_t *__ta,
347                                   td_event_e __event, td_notify_t *__ptr);
348
349 /* Enable EVENT in global mask.  */
350 extern td_err_e td_ta_set_event (const td_thragent_t *__ta,
351                                  td_thr_events_t *__event);
352
353 /* Disable EVENT in global mask.  */
354 extern td_err_e td_ta_clear_event (const td_thragent_t *__ta,
355                                    td_thr_events_t *__event);
356
357 /* Return information about last event.  */
358 extern td_err_e td_ta_event_getmsg (const td_thragent_t *__ta,
359                                     td_event_msg_t *__msg);
360
361
362 /* Set suggested concurrency level for process associated with TA.  */
363 extern td_err_e td_ta_setconcurrency (const td_thragent_t *__ta, int __level);
364
365
366 /* Enable collecting statistics for process associated with TA.  */
367 extern td_err_e td_ta_enable_stats (const td_thragent_t *__ta, int __enable);
368
369 /* Reset statistics.  */
370 extern td_err_e td_ta_reset_stats (const td_thragent_t *__ta);
371
372 /* Retrieve statistics from process associated with TA.  */
373 extern td_err_e td_ta_get_stats (const td_thragent_t *__ta,
374                                  td_ta_stats_t *__statsp);
375
376
377 /* Validate that TH is a thread handle.  */
378 extern td_err_e td_thr_validate (const td_thrhandle_t *__th);
379
380 /* Return information about thread TH.  */
381 extern td_err_e td_thr_get_info (const td_thrhandle_t *__th,
382                                  td_thrinfo_t *__infop);
383
384 /* Retrieve floating-point register contents of process running thread TH.  */
385 extern td_err_e td_thr_getfpregs (const td_thrhandle_t *__th,
386                                   prfpregset_t *__regset);
387
388 /* Retrieve general register contents of process running thread TH.  */
389 extern td_err_e td_thr_getgregs (const td_thrhandle_t *__th,
390                                  prgregset_t __gregs);
391
392 /* Retrieve extended register contents of process running thread TH.  */
393 extern td_err_e td_thr_getxregs (const td_thrhandle_t *__th, void *__xregs);
394
395 /* Get size of extended register set of process running thread TH.  */
396 extern td_err_e td_thr_getxregsize (const td_thrhandle_t *__th, int *__sizep);
397
398 /* Set floating-point register contents of process running thread TH.  */
399 extern td_err_e td_thr_setfpregs (const td_thrhandle_t *__th,
400                                   const prfpregset_t *__fpregs);
401
402 /* Set general register contents of process running thread TH.  */
403 extern td_err_e td_thr_setgregs (const td_thrhandle_t *__th,
404                                  prgregset_t __gregs);
405
406 /* Set extended register contents of process running thread TH.  */
407 extern td_err_e td_thr_setxregs (const td_thrhandle_t *__th,
408                                  const void *__addr);
409
410
411 /* Get address of the given module's TLS storage area for the given thread.  */
412 extern td_err_e td_thr_tlsbase (const td_thrhandle_t *__th,
413                                 unsigned long int __modid,
414                                 psaddr_t *__base);
415
416 /* Get address of thread local variable.  */
417 extern td_err_e td_thr_tls_get_addr (const td_thrhandle_t *__th,
418                                      psaddr_t __map_address, size_t __offset,
419                                      psaddr_t *__address);
420
421
422 /* Enable reporting for EVENT for thread TH.  */
423 extern td_err_e td_thr_event_enable (const td_thrhandle_t *__th, int __event);
424
425 /* Enable EVENT for thread TH.  */
426 extern td_err_e td_thr_set_event (const td_thrhandle_t *__th,
427                                   td_thr_events_t *__event);
428
429 /* Disable EVENT for thread TH.  */
430 extern td_err_e td_thr_clear_event (const td_thrhandle_t *__th,
431                                     td_thr_events_t *__event);
432
433 /* Get event message for thread TH.  */
434 extern td_err_e td_thr_event_getmsg (const td_thrhandle_t *__th,
435                                      td_event_msg_t *__msg);
436
437
438 /* Set priority of thread TH.  */
439 extern td_err_e td_thr_setprio (const td_thrhandle_t *__th, int __prio);
440
441
442 /* Set pending signals for thread TH.  */
443 extern td_err_e td_thr_setsigpending (const td_thrhandle_t *__th,
444                                       unsigned char __n, const sigset_t *__ss);
445
446 /* Set signal mask for thread TH.  */
447 extern td_err_e td_thr_sigsetmask (const td_thrhandle_t *__th,
448                                    const sigset_t *__ss);
449
450
451 /* Return thread local data associated with key TK in thread TH.  */
452 extern td_err_e td_thr_tsd (const td_thrhandle_t *__th,
453                             const thread_key_t __tk, void **__data);
454
455
456 /* Suspend execution of thread TH.  */
457 extern td_err_e td_thr_dbsuspend (const td_thrhandle_t *__th);
458
459 /* Resume execution of thread TH.  */
460 extern td_err_e td_thr_dbresume (const td_thrhandle_t *__th);
461
462 #endif  /* thread_db.h */