---

---

---

001: /* thread_db.h -- interface to libthread_db.so library for debugging -lpthread
002:    Copyright (C) 1999,2001,2002,2003 Free Software Foundation, Inc.
003:    This file is part of the GNU C Library.
004: 
005:    The GNU C Library is free software; you can redistribute it and/or
006:    modify it under the terms of the GNU Lesser General Public
007:    License as published by the Free Software Foundation; either
008:    version 2.1 of the License, or (at your option) any later version.
009: 
010:    The GNU C Library is distributed in the hope that it will be useful,
011:    but WITHOUT ANY WARRANTY; without even the implied warranty of
012:    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013:    Lesser General Public License for more details.
014: 
015:    You should have received a copy of the GNU Lesser General Public
016:    License along with the GNU C Library; if not, write to the Free
017:    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
018:    02111-1307 USA.  */
019: 
020: #ifndef _THREAD_DB_H
021: #define _THREAD_DB_H    1
022: 
023: /* This is the debugger interface for the NPTL library.  It is
024:    modelled closely after the interface with same names in Solaris
025:    with the goal to share the same code in the debugger.  */
026: #include <pthread.h>
027: #include <stdint.h>
028: #include <sys/types.h>
029: #include <sys/procfs.h>
030: 
031: 
032: /* Error codes of the library.  */
033: typedef enum
034: {
035:   TD_OK,          /* No error.  */
036:   TD_ERR,         /* No further specified error.  */
037:   TD_NOTHR,       /* No matching thread found.  */
038:   TD_NOSV,        /* No matching synchronization handle found.  */
039:   TD_NOLWP,       /* No matching light-weighted process found.  */
040:   TD_BADPH,       /* Invalid process handle.  */
041:   TD_BADTH,       /* Invalid thread handle.  */
042:   TD_BADSH,       /* Invalid synchronization handle.  */
043:   TD_BADTA,       /* Invalid thread agent.  */
044:   TD_BADKEY,      /* Invalid key.  */
045:   TD_NOMSG,       /* No event available.  */
046:   TD_NOFPREGS,    /* No floating-point register content available.  */
047:   TD_NOLIBTHREAD, /* Application not linked with thread library.  */
048:   TD_NOEVENT,     /* Requested event is not supported.  */
049:   TD_NOCAPAB,     /* Capability not available.  */
050:   TD_DBERR,       /* Internal debug library error.  */
051:   TD_NOAPLIC,     /* Operation is not applicable.  */
052:   TD_NOTSD,       /* No thread-specific data available.  */
053:   TD_MALLOC,      /* Out of memory.  */
054:   TD_PARTIALREG,  /* Not entire register set was read or written.  */
055:   TD_NOXREGS,     /* X register set not available for given thread.  */
056:   TD_TLSDEFER,    /* Thread has not yet allocated TLS for given module.  */
057:   TD_NOTALLOC = TD_TLSDEFER,
058:   TD_VERSION,     /* Version if libpthread and libthread_db do not match.  */
059:   TD_NOTLS        /* There is no TLS segment in the given module.  */
060: } td_err_e;
061: 
062: 
063: /* Possible thread states.  TD_THR_ANY_STATE is a pseudo-state used to
064:    select threads regardless of state in td_ta_thr_iter().  */
065: typedef enum
066: {
067:   TD_THR_ANY_STATE,
068:   TD_THR_UNKNOWN,
069:   TD_THR_STOPPED,
070:   TD_THR_RUN,
071:   TD_THR_ACTIVE,
072:   TD_THR_ZOMBIE,
073:   TD_THR_SLEEP,
074:   TD_THR_STOPPED_ASLEEP
075: } td_thr_state_e;
076: 
077: /* Thread type: user or system.  TD_THR_ANY_TYPE is a pseudo-type used
078:    to select threads regardless of type in td_ta_thr_iter().  */
079: typedef enum
080: {
081:   TD_THR_ANY_TYPE,
082:   TD_THR_USER,
083:   TD_THR_SYSTEM
084: } td_thr_type_e;
085: 
086: 
087: /* Types of the debugging library.  */
088: 
089: /* Handle for a process.  This type is opaque.  */
090: typedef struct td_thragent td_thragent_t;
091: 
092: /* The actual thread handle type.  This is also opaque.  */
093: typedef struct td_thrhandle
094: {
095:   td_thragent_t *th_ta_p;
096:   psaddr_t th_unique;
097: } td_thrhandle_t;
098: 
099: 
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: typedef pthread_t thread_t;
244: typedef pthread_key_t thread_key_t;
245: 
246: 
247: /* Callback for iteration over threads.  */
248: typedef int td_thr_iter_f (const td_thrhandle_t *, void *);
249: 
250: /* Callback for iteration over thread local data.  */
251: typedef int td_key_iter_f (thread_key_t, void (*) (void *), void *);
252: 
253: 
254: 
255: /* Forward declaration.  This has to be defined by the user.  */
256: struct ps_prochandle;
257: 
258: 
259: /* Information about the thread.  */
260: typedef struct td_thrinfo
261: {
262:   td_thragent_t *ti_ta_p;               /* Process handle.  */
263:   unsigned int ti_user_flags;           /* Unused.  */
264:   thread_t ti_tid;                      /* Thread ID returned by
265:                                            pthread_create().  */
266:   char *ti_tls;                         /* Pointer to thread-local data.  */
267:   psaddr_t ti_startfunc;                /* Start function passed to
268:                                            pthread_create().  */
269:   psaddr_t ti_stkbase;                  /* Base of thread's stack.  */
270:   long int ti_stksize;                  /* Size of thread's stack.  */
271:   psaddr_t ti_ro_area;                  /* Unused.  */
272:   int ti_ro_size;                       /* Unused.  */
273:   td_thr_state_e ti_state;              /* Thread state.  */
274:   unsigned char ti_db_suspended;        /* Nonzero if suspended by debugger. */
275:   td_thr_type_e ti_type;                /* Type of the thread (system vs
276:                                            user thread).  */
277:   intptr_t ti_pc;                       /* Unused.  */
278:   intptr_t ti_sp;                       /* Unused.  */
279:   short int ti_flags;                   /* Unused.  */
280:   int ti_pri;                           /* Thread priority.  */
281:   lwpid_t ti_lid;                       /* Kernel PID for this thread.  */
282:   sigset_t ti_sigmask;                  /* Signal mask.  */
283:   unsigned char ti_traceme;             /* Nonzero if event reporting
284:                                            enabled.  */
285:   unsigned char ti_preemptflag;         /* Unused.  */
286:   unsigned char ti_pirecflag;           /* Unused.  */
287:   sigset_t ti_pending;                  /* Set of pending signals.  */
288:   td_thr_events_t ti_events;            /* Set of enabled events.  */
289: } td_thrinfo_t;
290: 
291: 
292: 
293: /* Prototypes for exported library functions.  */
294: 
295: /* Initialize the thread debug support library.  */
296: extern td_err_e td_init (void);
297: 
298: /* Historical relict.  Should not be used anymore.  */
299: extern td_err_e td_log (void);
300: 
301: /* Return list of symbols the library can request.  */
302: extern const char **td_symbol_list (void);
303: 
304: /* Generate new thread debug library handle for process PS.  */
305: extern td_err_e td_ta_new (struct ps_prochandle *__ps, td_thragent_t **__ta);
306: 
307: /* Free resources allocated for TA.  */
308: extern td_err_e td_ta_delete (td_thragent_t *__ta);
309: 
310: /* Get number of currently running threads in process associated with TA.  */
311: extern td_err_e td_ta_get_nthreads (const td_thragent_t *__ta, int *__np);
312: 
313: /* Return process handle passed in `td_ta_new' for process associated with
314:    TA.  */
315: extern td_err_e td_ta_get_ph (const td_thragent_t *__ta,
316:                               struct ps_prochandle **__ph);
317: 
318: /* Map thread library handle PT to thread debug library handle for process
319:    associated with TA and store result in *TH.  */
320: extern td_err_e td_ta_map_id2thr (const td_thragent_t *__ta, pthread_t __pt,
321:                                   td_thrhandle_t *__th);
322: 
323: /* Map process ID LWPID to thread debug library handle for process
324:    associated with TA and store result in *TH.  */
325: extern td_err_e td_ta_map_lwp2thr (const td_thragent_t *__ta, lwpid_t __lwpid,
326:                                    td_thrhandle_t *__th);
327: 
328: 
329: /* Call for each thread in a process associated with TA the callback function
330:    CALLBACK.  */
331: extern td_err_e td_ta_thr_iter (const td_thragent_t *__ta,
332:                                 td_thr_iter_f *__callback, void *__cbdata_p,
333:                                 td_thr_state_e __state, int __ti_pri,
334:                                 sigset_t *__ti_sigmask_p,
335:                                 unsigned int __ti_user_flags);
336: 
337: /* Call for each defined thread local data entry the callback function KI.  */
338: extern td_err_e td_ta_tsd_iter (const td_thragent_t *__ta, td_key_iter_f *__ki,
339:                                 void *__p);
340: 
341: 
342: /* Get event address for EVENT.  */
343: extern td_err_e td_ta_event_addr (const td_thragent_t *__ta,
344:                                   td_event_e __event, td_notify_t *__ptr);
345: 
346: /* Enable EVENT in global mask.  */
347: extern td_err_e td_ta_set_event (const td_thragent_t *__ta,
348:                                  td_thr_events_t *__event);
349: 
350: /* Disable EVENT in global mask.  */
351: extern td_err_e td_ta_clear_event (const td_thragent_t *__ta,
352:                                    td_thr_events_t *__event);
353: 
354: /* Return information about last event.  */
355: extern td_err_e td_ta_event_getmsg (const td_thragent_t *__ta,
356:                                     td_event_msg_t *__msg);
357: 
358: 
359: /* Set suggested concurrency level for process associated with TA.  */
360: extern td_err_e td_ta_setconcurrency (const td_thragent_t *__ta, int __level);
361: 
362: 
363: /* Enable collecting statistics for process associated with TA.  */
364: extern td_err_e td_ta_enable_stats (const td_thragent_t *__ta, int __enable);
365: 
366: /* Reset statistics.  */
367: extern td_err_e td_ta_reset_stats (const td_thragent_t *__ta);
368: 
369: /* Retrieve statistics from process associated with TA.  */
370: extern td_err_e td_ta_get_stats (const td_thragent_t *__ta,
371:                                  td_ta_stats_t *__statsp);
372: 
373: 
374: /* Validate that TH is a thread handle.  */
375: extern td_err_e td_thr_validate (const td_thrhandle_t *__th);
376: 
377: /* Return information about thread TH.  */
378: extern td_err_e td_thr_get_info (const td_thrhandle_t *__th,
379:                                  td_thrinfo_t *__infop);
380: 
381: /* Retrieve floating-point register contents of process running thread TH.  */
382: extern td_err_e td_thr_getfpregs (const td_thrhandle_t *__th,
383:                                   prfpregset_t *__regset);
384: 
385: /* Retrieve general register contents of process running thread TH.  */
386: extern td_err_e td_thr_getgregs (const td_thrhandle_t *__th,
387:                                  prgregset_t __gregs);
388: 
389: /* Retrieve extended register contents of process running thread TH.  */
390: extern td_err_e td_thr_getxregs (const td_thrhandle_t *__th, void *__xregs);
391: 
392: /* Get size of extended register set of process running thread TH.  */
393: extern td_err_e td_thr_getxregsize (const td_thrhandle_t *__th, int *__sizep);
394: 
395: /* Set floating-point register contents of process running thread TH.  */
396: extern td_err_e td_thr_setfpregs (const td_thrhandle_t *__th,
397:                                   const prfpregset_t *__fpregs);
398: 
399: /* Set general register contents of process running thread TH.  */
400: extern td_err_e td_thr_setgregs (const td_thrhandle_t *__th,
401:                                  prgregset_t __gregs);
402: 
403: /* Set extended register contents of process running thread TH.  */
404: extern td_err_e td_thr_setxregs (const td_thrhandle_t *__th,
405:                                  const void *__addr);
406: 
407: 
408: /* Get address of the given module's TLS storage area for the given thread.  */
409: extern td_err_e td_thr_tlsbase (const td_thrhandle_t *__th,
410:                                 unsigned long int __modid,
411:                                 psaddr_t *__base);
412: 
413: /* Get address of thread local variable.  */
414: extern td_err_e td_thr_tls_get_addr (const td_thrhandle_t *__th,
415:                                      psaddr_t __map_address, size_t __offset,
416:                                      psaddr_t *__address);
417: 
418: 
419: /* Enable reporting for EVENT for thread TH.  */
420: extern td_err_e td_thr_event_enable (const td_thrhandle_t *__th, int __event);
421: 
422: /* Enable EVENT for thread TH.  */
423: extern td_err_e td_thr_set_event (const td_thrhandle_t *__th,
424:                                   td_thr_events_t *__event);
425: 
426: /* Disable EVENT for thread TH.  */
427: extern td_err_e td_thr_clear_event (const td_thrhandle_t *__th,
428:                                     td_thr_events_t *__event);
429: 
430: /* Get event message for thread TH.  */
431: extern td_err_e td_thr_event_getmsg (const td_thrhandle_t *__th,
432:                                      td_event_msg_t *__msg);
433: 
434: 
435: /* Set priority of thread TH.  */
436: extern td_err_e td_thr_setprio (const td_thrhandle_t *__th, int __prio);
437: 
438: 
439: /* Set pending signals for thread TH.  */
440: extern td_err_e td_thr_setsigpending (const td_thrhandle_t *__th,
441:                                       unsigned char __n, const sigset_t *__ss);
442: 
443: /* Set signal mask for thread TH.  */
444: extern td_err_e td_thr_sigsetmask (const td_thrhandle_t *__th,
445:                                    const sigset_t *__ss);
446: 
447: 
448: /* Return thread local data associated with key TK in thread TH.  */
449: extern td_err_e td_thr_tsd (const td_thrhandle_t *__th,
450:                             const thread_key_t __tk, void **__data);
451: 
452: 
453: /* Suspend execution of thread TH.  */
454: extern td_err_e td_thr_dbsuspend (const td_thrhandle_t *__th);
455: 
456: /* Resume execution of thread TH.  */
457: extern td_err_e td_thr_dbresume (const td_thrhandle_t *__th);
458: 
459: #endif  /* thread_db.h */
460: 

---

---

---