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