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: 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 */