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