Banner file for linuxthread_db library.
[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/procfs.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_NOLIBTHREAD, /* 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 /* Handle for a process.  This type is opaque.  */
85 typedef struct td_thragent td_thragent_t;
86
87 /* The actual thread handle type.  This is also opaque.  */
88 typedef struct td_thrhandle
89 {
90   td_thragent_t *th_ta_p;
91   psaddr_t th_unique;
92 } td_thrhandle_t;
93
94
95 /* Flags for `td_ta_thr_iter'.  */
96 #define TD_THR_ANY_USER_FLAGS   0xffffffff
97 #define TD_THR_LOWEST_PRIORITY  -20
98 #define TD_SIGNO_MASK           NULL
99
100
101 #define TD_EVENTSIZE    2
102 #define BT_UISHIFT      5 /* log base 2 of BT_NBIPUI, to extract word index */
103 #define BT_NBIPUI       (1 << BT_UISHIFT)       /* n bits per uint */
104 #define BT_UIMASK       (BT_NBIPUI - 1)         /* to extract bit index */
105
106 /* Bitmask of enabled events. */
107 typedef struct td_thr_events
108 {
109   uint32_t event_bits[TD_EVENTSIZE];
110 } td_thr_events_t;
111
112 /* Event set manipulation macros. */
113 #define __td_eventmask(n) \
114   (UINT32_C (1) << (((n) - 1) & BT_UIMASK))
115 #define __td_eventword(n) \
116   ((UINT32_C ((n) - 1)) >> BT_UISHIFT)
117
118 #define td_event_emptyset(setp) \
119   do {                                                                        \
120     int __i;                                                                  \
121     for (__i = TD_EVENTSIZE; __i > 0; --__i)                                  \
122       (setp)->event_bits[__i - 1] = 0;                                        \
123   } while (0)
124
125 #define td_event_fillset(setp) \
126   do {                                                                        \
127     int __i;                                                                  \
128     for (__i = TD_EVENTSIZE; __i > 0; --__i)                                  \
129       (setp)->event_bits[__i - 1] = UINT32_C (0xffffffff);                    \
130   } while (0)
131
132 #define td_event_addset(setp, n) \
133   (((setp)->event_bits[__td_eventword (n)]) |= __td_eventmask (n))
134 #define td_event_delset(setp, n) \
135   (((setp)->event_bits[__td_eventword (n)]) &= ~__td_eventmask (n))
136 #define td_eventismember(setp, n) \
137   (__td_eventmask (n) & ((setp)->event_bits[__td_eventword (n)]))
138 #if TD_EVENTSIZE == 2
139 # define td_eventisempty(setp) \
140   (!((setp)->event_bits[0]) && !((setp)->event_bits[1]))
141 #else
142 # error "td_eventisempty must be changed to match TD_EVENTSIZE"
143 #endif
144
145 /* Events reportable by the thread implementation.  */
146 typedef enum
147 {
148   TD_ALL_EVENTS,                 /* Pseudo-event number.  */
149   TD_EVENT_NONE = TD_ALL_EVENTS, /* Depends on context.  */
150   TD_READY,                      /* Is executable now. */
151   TD_SLEEP,                      /* Blocked in a synchronization obj.  */
152   TD_SWITCHTO,                   /* Now assigned to a process.  */
153   TD_SWITCHFROM,                 /* Not anymore assigned to a process.  */
154   TD_LOCK_TRY,                   /* Trying to get an unavailable lock.  */
155   TD_CATCHSIG,                   /* Signal posted to the thread.  */
156   TD_IDLE,                       /* Process getting idle.  */
157   TD_CREATE,                     /* New thread created.  */
158   TD_DEATH,                      /* Thread terminated.  */
159   TD_PREEMPT,                    /* Preempted.  */
160   TD_PRI_INHERIT,                /* Inherited elevated priority.  */
161   TD_REAP,                       /* Reaped.  */
162   TD_CONCURRENCY,                /* Number of processes changing.  */
163   TD_TIMEOUT,                    /* Conditional variable wait timed out.  */
164   TD_MIN_EVENT_NUM = TD_READY,
165   TD_MAX_EVENT_NUM = TD_TIMEOUT,
166   TD_EVENTS_ENABLE = 31         /* Event reporting enabled.  */
167 } td_event_e;
168
169 /* Values representing the different ways events are reported.  */
170 typedef enum
171 {
172   NOTIFY_BPT,                   /* User must insert breakpoint at u.bptaddr. */
173   NOTIFY_AUTOBPT,               /* Breakpoint at u.bptaddr is automatically
174                                    inserted.  */
175   NOTIFY_SYSCALL                /* System call u.syscallno will be invoked.  */
176 } td_notify_e;
177
178 /* Description how event type is reported.  */
179 typedef struct td_notify
180 {
181   td_notify_e type;             /* Way the event is reported.  */
182   union
183   {
184     psaddr_t bptaddr;           /* Address of breakpoint.  */
185     int syscallno;              /* Number of system call used.  */
186   } u;
187 } td_notify_t;
188
189 /* Structure used to report event.  */
190 typedef struct td_event_msg
191 {
192   td_event_e event;             /* Event type being reported.  */
193   const td_thrhandle_t *th_p;   /* Thread reporting the event.  */
194   union
195   {
196 # if 0
197     td_synchandle_t *sh;        /* Handle of synchronization object.  */
198 #endif
199     uintptr_t data;             /* Event specific data.  */
200   } msg;
201 } td_event_msg_t;
202
203 /* Structure containing event data available in each thread structure.  */
204 typedef struct
205 {
206   td_thr_events_t eventmask;    /* Mask of enabled events.  */
207   td_event_e eventnum;          /* Number of last event.  */
208   void *eventdata;              /* Data associated with event.  */
209 } td_eventbuf_t;
210
211
212 /* Gathered statistics about the process.  */
213 typedef struct td_ta_stats
214 {
215   int nthreads;                 /* Total number of threads in use.  */
216   int r_concurrency;            /* Concurrency level requested by user.  */
217   int nrunnable_num;            /* Average runnable threads, numerator.  */
218   int nrunnable_den;            /* Average runnable threads, denominator.  */
219   int a_concurrency_num;        /* Achieved concurrency level, numerator.  */
220   int a_concurrency_den;        /* Achieved concurrency level, denominator.  */
221   int nlwps_num;                /* Average number of processes in use,
222                                    numerator.  */
223   int nlwps_den;                /* Average number of processes in use,
224                                    denominator.  */
225   int nidle_num;                /* Average number of idling processes,
226                                    numerator.  */
227   int nidle_den;                /* Average number of idling processes,
228                                    denominator.  */
229 } td_ta_stats_t;
230
231
232 /* Since Sun's library is based on Solaris threads we have to define a few
233    types to map them to POSIX threads.  */
234 typedef pthread_t thread_t;
235 typedef pthread_key_t thread_key_t;
236
237
238 /* Callback for iteration over threads.  */
239 typedef int td_thr_iter_f (const td_thrhandle_t *, void *);
240
241 /* Callback for iteration over thread local data.  */
242 typedef int td_key_iter_f (thread_key_t, void (*) (void *), void *);
243
244
245
246 /* Forward declaration.  This has to be defined by the user.  */
247 struct ps_prochandle;
248
249
250 /* Information about the thread.  */
251 typedef struct td_thrinfo
252 {
253   td_thragent_t *ti_ta_p;               /* Process handle.  */
254   unsigned int ti_user_flags;           /* Unused.  */
255   thread_t ti_tid;                      /* Thread ID returned by
256                                            pthread_create().  */
257   char *ti_tls;                         /* Pointer to thread-local data.  */
258   psaddr_t ti_startfunc;                /* Start function passed to
259                                            pthread_create().  */
260   psaddr_t ti_stkbase;                  /* Base of thread's stack.  */
261   long int ti_stksize;                  /* Size of thread's stack.  */
262   psaddr_t ti_ro_area;                  /* Unused.  */
263   int ti_ro_size;                       /* Unused.  */
264   td_thr_state_e ti_state;              /* Thread state.  */
265   unsigned char ti_db_suspended;        /* Nonzero if suspended by debugger. */
266   td_thr_type_e ti_type;                /* Type of the thread (system vs
267                                            user thread).  */
268   intptr_t ti_pc;                       /* Unused.  */
269   intptr_t ti_sp;                       /* Unused.  */
270   short int ti_flags;                   /* Unused.  */
271   int ti_pri;                           /* Thread priority.  */
272   lwpid_t ti_lid;                       /* Unused.  */
273   sigset_t ti_sigmask;                  /* Signal mask.  */
274   unsigned char ti_traceme;             /* Nonzero if event reporting
275                                            enabled.  */
276   unsigned char ti_preemptflag;         /* Unused.  */
277   unsigned char ti_pirecflag;           /* Unused.  */
278   sigset_t ti_pending;                  /* Set of pending signals.  */
279   td_thr_events_t ti_events;            /* Set of enabled events.  */
280 } td_thrinfo_t;
281
282
283
284 /* Prototypes for exported library functions.  */
285
286 /* Initialize the thread debug support library.  */
287 extern td_err_e td_init (void);
288
289 /* Historical relict.  Should not be used anymore.  */
290 extern td_err_e td_log (void);
291
292 /* Generate new thread debug library handle for process PS.  */
293 extern td_err_e td_ta_new (struct ps_prochandle *__ps, td_thragent_t **__ta);
294
295 /* Free resources allocated for TA.  */
296 extern td_err_e td_ta_delete (td_thragent_t *__ta);
297
298 /* Get number of currently running threads in process associated with TA.  */
299 extern td_err_e td_ta_get_nthreads (const td_thragent_t *__ta, int *__np);
300
301 /* Return process handle passed in `td_ta_new' for process associated with
302    TA.  */
303 extern td_err_e td_ta_get_ph (const td_thragent_t *__ta,
304                               struct ps_prochandle **__ph);
305
306 /* Map thread library handle PT to thread debug library handle for process
307    associated with TA and store result in *TH.  */
308 extern td_err_e td_ta_map_id2thr (const td_thragent_t *__ta, pthread_t __pt,
309                                   td_thrhandle_t *__th);
310
311 /* Map process ID LWPID to thread debug library handle for process
312    associated with TA and store result in *TH.  */
313 extern td_err_e td_ta_map_lwp2thr (const td_thragent_t *__ta, lwpid_t __lwpid,
314                                    td_thrhandle_t *__th);
315
316
317 /* Call for each thread in a process associated with TA the callback function
318    CALLBACK.  */
319 extern td_err_e td_ta_thr_iter (const td_thragent_t *__ta,
320                                 td_thr_iter_f *__callback, void *__cbdata_p,
321                                 td_thr_state_e __state, int __ti_pri,
322                                 sigset_t *__ti_sigmask_p,
323                                 unsigned int __ti_user_flags);
324
325 /* Call for each defined thread local data entry the callback function KI.  */
326 extern td_err_e td_ta_tsd_iter (const td_thragent_t *__ta, td_key_iter_f *__ki,
327                                 void *__p);
328
329
330 /* Get event address for EVENT.  */
331 extern td_err_e td_ta_event_addr (const td_thragent_t *__ta,
332                                   td_event_e __event, td_notify_t *__ptr);
333
334 /* Enable EVENT in global mask.  */
335 extern td_err_e td_ta_set_event (const td_thragent_t *__ta,
336                                  td_thr_events_t *__event);
337
338 /* Disable EVENT in global mask.  */
339 extern td_err_e td_ta_clear_event (const td_thragent_t *__ta,
340                                    td_thr_events_t *__event);
341
342 /* Return information about last event.  */
343 extern td_err_e td_ta_event_getmsg (const td_thragent_t *__ta,
344                                     td_event_msg_t *msg);
345
346
347 /* Set suggested concurrency level for process associated with TA.  */
348 extern td_err_e td_ta_setconcurrency (const td_thragent_t *__ta, int __level);
349
350
351 /* Enable collecting statistics for process associated with TA.  */
352 extern td_err_e td_ta_enable_stats (const td_thragent_t *__ta, int __enable);
353
354 /* Reset statistics.  */
355 extern td_err_e td_ta_reset_stats (const td_thragent_t *__ta);
356
357 /* Retrieve statistics from process associated with TA.  */
358 extern td_err_e td_ta_get_stats (const td_thragent_t *__ta,
359                                  td_ta_stats_t *__statsp);
360
361
362 /* Validate that TH is a thread handle.  */
363 extern td_err_e td_thr_validate (const td_thrhandle_t *__th);
364
365 /* Return information about thread TH.  */
366 extern td_err_e td_thr_get_info (const td_thrhandle_t *__th,
367                                  td_thrinfo_t *__infop);
368
369 /* Retrieve floating-point register contents of process running thread TH.  */
370 extern td_err_e td_thr_getfpregs (const td_thrhandle_t *__th,
371                                   prfpregset_t *__regset);
372
373 /* Retrieve general register contents of process running thread TH.  */
374 extern td_err_e td_thr_getgregs (const td_thrhandle_t *__th,
375                                  prgregset_t __gregs);
376
377 /* Retrieve extended register contents of process running thread TH.  */
378 extern td_err_e td_thr_getxregs (const td_thrhandle_t *__th, void *__xregs);
379
380 /* Get size of extended register set of process running thread TH.  */
381 extern td_err_e td_thr_getxregsize (const td_thrhandle_t *__th, int *__sizep);
382
383 /* Set floating-point register contents of process running thread TH.  */
384 extern td_err_e td_thr_setfpregs (const td_thrhandle_t *__th,
385                                   const prfpregset_t *__fpregs);
386
387 /* Set general register contents of process running thread TH.  */
388 extern td_err_e td_thr_setgregs (const td_thrhandle_t *__th,
389                                  prgregset_t __gregs);
390
391 /* Set extended register contents of process running thread TH.  */
392 extern td_err_e td_thr_setxregs (const td_thrhandle_t *__th,
393                                  const void *__addr);
394
395
396 /* Enable reporting for EVENT for thread TH.  */
397 extern td_err_e td_thr_event_enable (const td_thrhandle_t *__th, int __event);
398
399 /* Enable EVENT for thread TH.  */
400 extern td_err_e td_thr_set_event (const td_thrhandle_t *__th,
401                                   td_thr_events_t *__event);
402
403 /* Disable EVENT for thread TH.  */
404 extern td_err_e td_thr_clear_event (const td_thrhandle_t *__th,
405                                     td_thr_events_t *__event);
406
407 /* Get event message for thread TH.  */
408 extern td_err_e td_thr_event_getmsg (const td_thrhandle_t *__th,
409                                      td_event_msg_t *__msg);
410
411
412 /* Set priority of thread TH.  */
413 extern td_err_e td_thr_setprio (const td_thrhandle_t *__th, int __prio);
414
415
416 /* Set pending signals for thread TH.  */
417 extern td_err_e td_thr_setsigpending (const td_thrhandle_t *__th,
418                                       unsigned char __n, const sigset_t *__ss);
419
420 /* Set signal mask for thread TH.  */
421 extern td_err_e td_thr_sigsetmask (const td_thrhandle_t *__th,
422                                    const sigset_t *__ss);
423
424
425 /* Return thread local data associated with key TK in thread TH.  */
426 extern td_err_e td_thr_tsd (const td_thrhandle_t *__th,
427                             const thread_key_t __tk, void **__data);
428
429
430 /* Suspend execution of thread TH.  */
431 extern td_err_e td_thr_dbsuspend (const td_thrhandle_t *__th);
432
433 /* Resume execution of thread TH.  */
434 extern td_err_e td_thr_dbresume (const td_thrhandle_t *__th);
435
436 #endif  /* thread_db.h */