|
GDB (API)
|
|
GDB (API)
|
00001 /* thread_db.h -- interface to libthread_db.so library for debugging -lpthread 00002 Copyright (C) 1999-2013 Free Software Foundation, Inc. 00003 This file is part of the GNU C Library. 00004 00005 The GNU C Library is free software; you can redistribute it and/or 00006 modify it under the terms of the GNU Lesser General Public 00007 License as published by the Free Software Foundation; either 00008 version 2.1 of the License, or (at your option) any later version. 00009 00010 The GNU C Library is distributed in the hope that it will be useful, 00011 but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00013 Lesser General Public License for more details. 00014 00015 You should have received a copy of the GNU Lesser General Public 00016 License along with the GNU C Library; if not, see 00017 <http://www.gnu.org/licenses/>. */ 00018 00019 #ifndef _THREAD_DB_H 00020 #define _THREAD_DB_H 1 00021 00022 /* This is the debugger interface for the NPTL library. It is 00023 modelled closely after the interface with same names in Solaris 00024 with the goal to share the same code in the debugger. */ 00025 #include <pthread.h> 00026 #include <stdint.h> 00027 #include <sys/types.h> 00028 #include <sys/procfs.h> 00029 00030 00031 /* Error codes of the library. */ 00032 typedef enum 00033 { 00034 TD_OK, /* No error. */ 00035 TD_ERR, /* No further specified error. */ 00036 TD_NOTHR, /* No matching thread found. */ 00037 TD_NOSV, /* No matching synchronization handle found. */ 00038 TD_NOLWP, /* No matching light-weighted process found. */ 00039 TD_BADPH, /* Invalid process handle. */ 00040 TD_BADTH, /* Invalid thread handle. */ 00041 TD_BADSH, /* Invalid synchronization handle. */ 00042 TD_BADTA, /* Invalid thread agent. */ 00043 TD_BADKEY, /* Invalid key. */ 00044 TD_NOMSG, /* No event available. */ 00045 TD_NOFPREGS, /* No floating-point register content available. */ 00046 TD_NOLIBTHREAD, /* Application not linked with thread library. */ 00047 TD_NOEVENT, /* Requested event is not supported. */ 00048 TD_NOCAPAB, /* Capability not available. */ 00049 TD_DBERR, /* Internal debug library error. */ 00050 TD_NOAPLIC, /* Operation is not applicable. */ 00051 TD_NOTSD, /* No thread-specific data available. */ 00052 TD_MALLOC, /* Out of memory. */ 00053 TD_PARTIALREG, /* Not entire register set was read or written. */ 00054 TD_NOXREGS, /* X register set not available for given thread. */ 00055 TD_TLSDEFER, /* Thread has not yet allocated TLS for given module. */ 00056 TD_NOTALLOC = TD_TLSDEFER, 00057 TD_VERSION, /* Version if libpthread and libthread_db do not match. */ 00058 TD_NOTLS /* There is no TLS segment in the given module. */ 00059 } td_err_e; 00060 00061 00062 /* Possible thread states. TD_THR_ANY_STATE is a pseudo-state used to 00063 select threads regardless of state in td_ta_thr_iter(). */ 00064 typedef enum 00065 { 00066 TD_THR_ANY_STATE, 00067 TD_THR_UNKNOWN, 00068 TD_THR_STOPPED, 00069 TD_THR_RUN, 00070 TD_THR_ACTIVE, 00071 TD_THR_ZOMBIE, 00072 TD_THR_SLEEP, 00073 TD_THR_STOPPED_ASLEEP 00074 } td_thr_state_e; 00075 00076 /* Thread type: user or system. TD_THR_ANY_TYPE is a pseudo-type used 00077 to select threads regardless of type in td_ta_thr_iter(). */ 00078 typedef enum 00079 { 00080 TD_THR_ANY_TYPE, 00081 TD_THR_USER, 00082 TD_THR_SYSTEM 00083 } td_thr_type_e; 00084 00085 00086 /* Types of the debugging library. */ 00087 00088 /* Handle for a process. This type is opaque. */ 00089 typedef struct td_thragent td_thragent_t; 00090 00091 /* The actual thread handle type. This is also opaque. */ 00092 typedef struct td_thrhandle 00093 { 00094 td_thragent_t *th_ta_p; 00095 psaddr_t th_unique; 00096 } td_thrhandle_t; 00097 00098 00099 /* Forward declaration of a type defined by and for the dynamic linker. */ 00100 struct link_map; 00101 00102 00103 /* Flags for `td_ta_thr_iter'. */ 00104 #define TD_THR_ANY_USER_FLAGS 0xffffffff 00105 #define TD_THR_LOWEST_PRIORITY -20 00106 #define TD_SIGNO_MASK NULL 00107 00108 00109 #define TD_EVENTSIZE 2 00110 #define BT_UISHIFT 5 /* log base 2 of BT_NBIPUI, to extract word index */ 00111 #define BT_NBIPUI (1 << BT_UISHIFT) /* n bits per uint */ 00112 #define BT_UIMASK (BT_NBIPUI - 1) /* to extract bit index */ 00113 00114 /* Bitmask of enabled events. */ 00115 typedef struct td_thr_events 00116 { 00117 uint32_t event_bits[TD_EVENTSIZE]; 00118 } td_thr_events_t; 00119 00120 /* Event set manipulation macros. */ 00121 #define __td_eventmask(n) \ 00122 (UINT32_C (1) << (((n) - 1) & BT_UIMASK)) 00123 #define __td_eventword(n) \ 00124 ((UINT32_C ((n) - 1)) >> BT_UISHIFT) 00125 00126 #define td_event_emptyset(setp) \ 00127 do { \ 00128 int __i; \ 00129 for (__i = TD_EVENTSIZE; __i > 0; --__i) \ 00130 (setp)->event_bits[__i - 1] = 0; \ 00131 } while (0) 00132 00133 #define td_event_fillset(setp) \ 00134 do { \ 00135 int __i; \ 00136 for (__i = TD_EVENTSIZE; __i > 0; --__i) \ 00137 (setp)->event_bits[__i - 1] = UINT32_C (0xffffffff); \ 00138 } while (0) 00139 00140 #define td_event_addset(setp, n) \ 00141 (((setp)->event_bits[__td_eventword (n)]) |= __td_eventmask (n)) 00142 #define td_event_delset(setp, n) \ 00143 (((setp)->event_bits[__td_eventword (n)]) &= ~__td_eventmask (n)) 00144 #define td_eventismember(setp, n) \ 00145 (__td_eventmask (n) & ((setp)->event_bits[__td_eventword (n)])) 00146 #if TD_EVENTSIZE == 2 00147 # define td_eventisempty(setp) \ 00148 (!((setp)->event_bits[0]) && !((setp)->event_bits[1])) 00149 #else 00150 # error "td_eventisempty must be changed to match TD_EVENTSIZE" 00151 #endif 00152 00153 /* Events reportable by the thread implementation. */ 00154 typedef enum 00155 { 00156 TD_ALL_EVENTS, /* Pseudo-event number. */ 00157 TD_EVENT_NONE = TD_ALL_EVENTS, /* Depends on context. */ 00158 TD_READY, /* Is executable now. */ 00159 TD_SLEEP, /* Blocked in a synchronization obj. */ 00160 TD_SWITCHTO, /* Now assigned to a process. */ 00161 TD_SWITCHFROM, /* Not anymore assigned to a process. */ 00162 TD_LOCK_TRY, /* Trying to get an unavailable lock. */ 00163 TD_CATCHSIG, /* Signal posted to the thread. */ 00164 TD_IDLE, /* Process getting idle. */ 00165 TD_CREATE, /* New thread created. */ 00166 TD_DEATH, /* Thread terminated. */ 00167 TD_PREEMPT, /* Preempted. */ 00168 TD_PRI_INHERIT, /* Inherited elevated priority. */ 00169 TD_REAP, /* Reaped. */ 00170 TD_CONCURRENCY, /* Number of processes changing. */ 00171 TD_TIMEOUT, /* Conditional variable wait timed out. */ 00172 TD_MIN_EVENT_NUM = TD_READY, 00173 TD_MAX_EVENT_NUM = TD_TIMEOUT, 00174 TD_EVENTS_ENABLE = 31 /* Event reporting enabled. */ 00175 } td_event_e; 00176 00177 /* Values representing the different ways events are reported. */ 00178 typedef enum 00179 { 00180 NOTIFY_BPT, /* User must insert breakpoint at u.bptaddr. */ 00181 NOTIFY_AUTOBPT, /* Breakpoint at u.bptaddr is automatically 00182 inserted. */ 00183 NOTIFY_SYSCALL /* System call u.syscallno will be invoked. */ 00184 } td_notify_e; 00185 00186 /* Description how event type is reported. */ 00187 typedef struct td_notify 00188 { 00189 td_notify_e type; /* Way the event is reported. */ 00190 union 00191 { 00192 psaddr_t bptaddr; /* Address of breakpoint. */ 00193 int syscallno; /* Number of system call used. */ 00194 } u; 00195 } td_notify_t; 00196 00197 /* Structure used to report event. */ 00198 typedef struct td_event_msg 00199 { 00200 td_event_e event; /* Event type being reported. */ 00201 const td_thrhandle_t *th_p; /* Thread reporting the event. */ 00202 union 00203 { 00204 # if 0 00205 td_synchandle_t *sh; /* Handle of synchronization object. */ 00206 #endif 00207 uintptr_t data; /* Event specific data. */ 00208 } msg; 00209 } td_event_msg_t; 00210 00211 /* Structure containing event data available in each thread structure. */ 00212 typedef struct 00213 { 00214 td_thr_events_t eventmask; /* Mask of enabled events. */ 00215 td_event_e eventnum; /* Number of last event. */ 00216 void *eventdata; /* Data associated with event. */ 00217 } td_eventbuf_t; 00218 00219 00220 /* Gathered statistics about the process. */ 00221 typedef struct td_ta_stats 00222 { 00223 int nthreads; /* Total number of threads in use. */ 00224 int r_concurrency; /* Concurrency level requested by user. */ 00225 int nrunnable_num; /* Average runnable threads, numerator. */ 00226 int nrunnable_den; /* Average runnable threads, denominator. */ 00227 int a_concurrency_num; /* Achieved concurrency level, numerator. */ 00228 int a_concurrency_den; /* Achieved concurrency level, denominator. */ 00229 int nlwps_num; /* Average number of processes in use, 00230 numerator. */ 00231 int nlwps_den; /* Average number of processes in use, 00232 denominator. */ 00233 int nidle_num; /* Average number of idling processes, 00234 numerator. */ 00235 int nidle_den; /* Average number of idling processes, 00236 denominator. */ 00237 } td_ta_stats_t; 00238 00239 00240 /* Since Sun's library is based on Solaris threads we have to define a few 00241 types to map them to POSIX threads. */ 00242 typedef pthread_t thread_t; 00243 typedef pthread_key_t thread_key_t; 00244 00245 00246 /* Callback for iteration over threads. */ 00247 typedef int td_thr_iter_f (const td_thrhandle_t *, void *); 00248 00249 /* Callback for iteration over thread local data. */ 00250 typedef int td_key_iter_f (thread_key_t, void (*) (void *), void *); 00251 00252 00253 00254 /* Forward declaration. This has to be defined by the user. */ 00255 struct ps_prochandle; 00256 00257 00258 /* Information about the thread. */ 00259 typedef struct td_thrinfo 00260 { 00261 td_thragent_t *ti_ta_p; /* Process handle. */ 00262 unsigned int ti_user_flags; /* Unused. */ 00263 thread_t ti_tid; /* Thread ID returned by 00264 pthread_create(). */ 00265 char *ti_tls; /* Pointer to thread-local data. */ 00266 psaddr_t ti_startfunc; /* Start function passed to 00267 pthread_create(). */ 00268 psaddr_t ti_stkbase; /* Base of thread's stack. */ 00269 long int ti_stksize; /* Size of thread's stack. */ 00270 psaddr_t ti_ro_area; /* Unused. */ 00271 int ti_ro_size; /* Unused. */ 00272 td_thr_state_e ti_state; /* Thread state. */ 00273 unsigned char ti_db_suspended; /* Nonzero if suspended by debugger. */ 00274 td_thr_type_e ti_type; /* Type of the thread (system vs 00275 user thread). */ 00276 intptr_t ti_pc; /* Unused. */ 00277 intptr_t ti_sp; /* Unused. */ 00278 short int ti_flags; /* Unused. */ 00279 int ti_pri; /* Thread priority. */ 00280 lwpid_t ti_lid; /* Kernel PID for this thread. */ 00281 sigset_t ti_sigmask; /* Signal mask. */ 00282 unsigned char ti_traceme; /* Nonzero if event reporting 00283 enabled. */ 00284 unsigned char ti_preemptflag; /* Unused. */ 00285 unsigned char ti_pirecflag; /* Unused. */ 00286 sigset_t ti_pending; /* Set of pending signals. */ 00287 td_thr_events_t ti_events; /* Set of enabled events. */ 00288 } td_thrinfo_t; 00289 00290 00291 00292 /* Prototypes for exported library functions. */ 00293 00294 /* Initialize the thread debug support library. */ 00295 extern td_err_e td_init (void); 00296 00297 /* Historical relict. Should not be used anymore. */ 00298 extern td_err_e td_log (void); 00299 00300 /* Return list of symbols the library can request. */ 00301 extern const char **td_symbol_list (void); 00302 00303 /* Generate new thread debug library handle for process PS. */ 00304 extern td_err_e td_ta_new (struct ps_prochandle *__ps, td_thragent_t **__ta); 00305 00306 /* Free resources allocated for TA. */ 00307 extern td_err_e td_ta_delete (td_thragent_t *__ta); 00308 00309 /* Get number of currently running threads in process associated with TA. */ 00310 extern td_err_e td_ta_get_nthreads (const td_thragent_t *__ta, int *__np); 00311 00312 /* Return process handle passed in `td_ta_new' for process associated with 00313 TA. */ 00314 extern td_err_e td_ta_get_ph (const td_thragent_t *__ta, 00315 struct ps_prochandle **__ph); 00316 00317 /* Map thread library handle PT to thread debug library handle for process 00318 associated with TA and store result in *TH. */ 00319 extern td_err_e td_ta_map_id2thr (const td_thragent_t *__ta, pthread_t __pt, 00320 td_thrhandle_t *__th); 00321 00322 /* Map process ID LWPID to thread debug library handle for process 00323 associated with TA and store result in *TH. */ 00324 extern td_err_e td_ta_map_lwp2thr (const td_thragent_t *__ta, lwpid_t __lwpid, 00325 td_thrhandle_t *__th); 00326 00327 00328 /* Call for each thread in a process associated with TA the callback function 00329 CALLBACK. */ 00330 extern td_err_e td_ta_thr_iter (const td_thragent_t *__ta, 00331 td_thr_iter_f *__callback, void *__cbdata_p, 00332 td_thr_state_e __state, int __ti_pri, 00333 sigset_t *__ti_sigmask_p, 00334 unsigned int __ti_user_flags); 00335 00336 /* Call for each defined thread local data entry the callback function KI. */ 00337 extern td_err_e td_ta_tsd_iter (const td_thragent_t *__ta, td_key_iter_f *__ki, 00338 void *__p); 00339 00340 00341 /* Get event address for EVENT. */ 00342 extern td_err_e td_ta_event_addr (const td_thragent_t *__ta, 00343 td_event_e __event, td_notify_t *__ptr); 00344 00345 /* Enable EVENT in global mask. */ 00346 extern td_err_e td_ta_set_event (const td_thragent_t *__ta, 00347 td_thr_events_t *__event); 00348 00349 /* Disable EVENT in global mask. */ 00350 extern td_err_e td_ta_clear_event (const td_thragent_t *__ta, 00351 td_thr_events_t *__event); 00352 00353 /* Return information about last event. */ 00354 extern td_err_e td_ta_event_getmsg (const td_thragent_t *__ta, 00355 td_event_msg_t *__msg); 00356 00357 00358 /* Set suggested concurrency level for process associated with TA. */ 00359 extern td_err_e td_ta_setconcurrency (const td_thragent_t *__ta, int __level); 00360 00361 00362 /* Enable collecting statistics for process associated with TA. */ 00363 extern td_err_e td_ta_enable_stats (const td_thragent_t *__ta, int __enable); 00364 00365 /* Reset statistics. */ 00366 extern td_err_e td_ta_reset_stats (const td_thragent_t *__ta); 00367 00368 /* Retrieve statistics from process associated with TA. */ 00369 extern td_err_e td_ta_get_stats (const td_thragent_t *__ta, 00370 td_ta_stats_t *__statsp); 00371 00372 00373 /* Validate that TH is a thread handle. */ 00374 extern td_err_e td_thr_validate (const td_thrhandle_t *__th); 00375 00376 /* Return information about thread TH. */ 00377 extern td_err_e td_thr_get_info (const td_thrhandle_t *__th, 00378 td_thrinfo_t *__infop); 00379 00380 /* Retrieve floating-point register contents of process running thread TH. */ 00381 extern td_err_e td_thr_getfpregs (const td_thrhandle_t *__th, 00382 prfpregset_t *__regset); 00383 00384 /* Retrieve general register contents of process running thread TH. */ 00385 extern td_err_e td_thr_getgregs (const td_thrhandle_t *__th, 00386 prgregset_t __gregs); 00387 00388 /* Retrieve extended register contents of process running thread TH. */ 00389 extern td_err_e td_thr_getxregs (const td_thrhandle_t *__th, void *__xregs); 00390 00391 /* Get size of extended register set of process running thread TH. */ 00392 extern td_err_e td_thr_getxregsize (const td_thrhandle_t *__th, int *__sizep); 00393 00394 /* Set floating-point register contents of process running thread TH. */ 00395 extern td_err_e td_thr_setfpregs (const td_thrhandle_t *__th, 00396 const prfpregset_t *__fpregs); 00397 00398 /* Set general register contents of process running thread TH. */ 00399 extern td_err_e td_thr_setgregs (const td_thrhandle_t *__th, 00400 prgregset_t __gregs); 00401 00402 /* Set extended register contents of process running thread TH. */ 00403 extern td_err_e td_thr_setxregs (const td_thrhandle_t *__th, 00404 const void *__addr); 00405 00406 00407 /* Get address of the given module's TLS storage area for the given thread. */ 00408 extern td_err_e td_thr_tlsbase (const td_thrhandle_t *__th, 00409 unsigned long int __modid, 00410 psaddr_t *__base); 00411 00412 /* Get address of thread local variable. */ 00413 extern td_err_e td_thr_tls_get_addr (const td_thrhandle_t *__th, 00414 psaddr_t __map_address, size_t __offset, 00415 psaddr_t *__address); 00416 00417 00418 /* Enable reporting for EVENT for thread TH. */ 00419 extern td_err_e td_thr_event_enable (const td_thrhandle_t *__th, int __event); 00420 00421 /* Enable EVENT for thread TH. */ 00422 extern td_err_e td_thr_set_event (const td_thrhandle_t *__th, 00423 td_thr_events_t *__event); 00424 00425 /* Disable EVENT for thread TH. */ 00426 extern td_err_e td_thr_clear_event (const td_thrhandle_t *__th, 00427 td_thr_events_t *__event); 00428 00429 /* Get event message for thread TH. */ 00430 extern td_err_e td_thr_event_getmsg (const td_thrhandle_t *__th, 00431 td_event_msg_t *__msg); 00432 00433 00434 /* Set priority of thread TH. */ 00435 extern td_err_e td_thr_setprio (const td_thrhandle_t *__th, int __prio); 00436 00437 00438 /* Set pending signals for thread TH. */ 00439 extern td_err_e td_thr_setsigpending (const td_thrhandle_t *__th, 00440 unsigned char __n, const sigset_t *__ss); 00441 00442 /* Set signal mask for thread TH. */ 00443 extern td_err_e td_thr_sigsetmask (const td_thrhandle_t *__th, 00444 const sigset_t *__ss); 00445 00446 00447 /* Return thread local data associated with key TK in thread TH. */ 00448 extern td_err_e td_thr_tsd (const td_thrhandle_t *__th, 00449 const thread_key_t __tk, void **__data); 00450 00451 00452 /* Suspend execution of thread TH. */ 00453 extern td_err_e td_thr_dbsuspend (const td_thrhandle_t *__th); 00454 00455 /* Resume execution of thread TH. */ 00456 extern td_err_e td_thr_dbresume (const td_thrhandle_t *__th); 00457 00458 #endif /* thread_db.h */
1.7.6.1
