glibc/sysdeps/nptl/thread_db.h

/* thread_db.h -- interface to libthread_db.so library for debugging -lpthread
   Copyright (C) 1999-2022 Free Software Foundation, Inc.
   This file is part of the GNU C Library.

   The GNU C Library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.

   The GNU C Library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with the GNU C Library; if not, see
   <https://www.gnu.org/licenses/>.  */

#ifndef _THREAD_DB_H
#define _THREAD_DB_H	1

/* This is the debugger interface for the NPTL library.  It is
   modelled closely after the interface with same names in Solaris
   with the goal to share the same code in the debugger.  */
#include <pthread.h>
#include <stdint.h>
#include <sys/types.h>
#include <sys/procfs.h>


/* Error codes of the library.  */
typedef enum
{
  TD_OK,	  /* No error.  */
  TD_ERR,	  /* No further specified error.  */
  TD_NOTHR,	  /* No matching thread found.  */
  TD_NOSV,	  /* No matching synchronization handle found.  */
  TD_NOLWP,	  /* No matching light-weighted process found.  */
  TD_BADPH,	  /* Invalid process handle.  */
  TD_BADTH,	  /* Invalid thread handle.  */
  TD_BADSH,	  /* Invalid synchronization handle.  */
  TD_BADTA,	  /* Invalid thread agent.  */
  TD_BADKEY,	  /* Invalid key.  */
  TD_NOMSG,	  /* No event available.  */
  TD_NOFPREGS,	  /* No floating-point register content available.  */
  TD_NOLIBTHREAD, /* Application not linked with thread library.  */
  TD_NOEVENT,	  /* Requested event is not supported.  */
  TD_NOCAPAB,	  /* Capability not available.  */
  TD_DBERR,	  /* Internal debug library error.  */
  TD_NOAPLIC,	  /* Operation is not applicable.  */
  TD_NOTSD,	  /* No thread-specific data available.  */
  TD_MALLOC,	  /* Out of memory.  */
  TD_PARTIALREG,  /* Not entire register set was read or written.  */
  TD_NOXREGS,	  /* X register set not available for given thread.  */
  TD_TLSDEFER,	  /* Thread has not yet allocated TLS for given module.  */
  TD_NOTALLOC = TD_TLSDEFER,
  TD_VERSION,	  /* Version if libpthread and libthread_db do not match.  */
  TD_NOTLS	  /* There is no TLS segment in the given module.  */
} td_err_e;


/* Possible thread states.  TD_THR_ANY_STATE is a pseudo-state used to
   select threads regardless of state in td_ta_thr_iter().  */
typedef enum
{
  TD_THR_ANY_STATE,
  TD_THR_UNKNOWN,
  TD_THR_STOPPED,
  TD_THR_RUN,
  TD_THR_ACTIVE,
  TD_THR_ZOMBIE,
  TD_THR_SLEEP,
  TD_THR_STOPPED_ASLEEP
} td_thr_state_e;

/* Thread type: user or system.  TD_THR_ANY_TYPE is a pseudo-type used
   to select threads regardless of type in td_ta_thr_iter().  */
typedef enum
{
  TD_THR_ANY_TYPE,
  TD_THR_USER,
  TD_THR_SYSTEM
} td_thr_type_e;


/* Types of the debugging library.  */

/* Handle for a process.  This type is opaque.  */
typedef struct td_thragent td_thragent_t;

/* The actual thread handle type.  This is also opaque.  */
typedef struct td_thrhandle
{
  td_thragent_t *th_ta_p;
  psaddr_t th_unique;
} td_thrhandle_t;


/* Forward declaration of a type defined by and for the dynamic linker.  */
struct link_map;


/* Flags for `td_ta_thr_iter'.  */
#define TD_THR_ANY_USER_FLAGS	0xffffffff
#define TD_THR_LOWEST_PRIORITY	-20
#define TD_SIGNO_MASK		NULL


#define TD_EVENTSIZE	2
#define BT_UISHIFT	5 /* log base 2 of BT_NBIPUI, to extract word index */
#define BT_NBIPUI	(1 << BT_UISHIFT)       /* n bits per unsigned int */
#define BT_UIMASK	(BT_NBIPUI - 1)         /* to extract bit index */

/* Bitmask of enabled events. */
typedef struct td_thr_events
{
  uint32_t event_bits[TD_EVENTSIZE];
} td_thr_events_t;

/* Event set manipulation macros. */
#define __td_eventmask(n) \
  (UINT32_C (1) << (((n) - 1) & BT_UIMASK))
#define __td_eventword(n) \
  ((UINT32_C ((n) - 1)) >> BT_UISHIFT)

#define td_event_emptyset(setp) \
  do {									      \
    int __i;								      \
    for (__i = TD_EVENTSIZE; __i > 0; --__i)				      \
      (setp)->event_bits[__i - 1] = 0;					      \
  } while (0)

#define td_event_fillset(setp) \
  do {									      \
    int __i;								      \
    for (__i = TD_EVENTSIZE; __i > 0; --__i)				      \
      (setp)->event_bits[__i - 1] = UINT32_C (0xffffffff);		      \
  } while (0)

#define td_event_addset(setp, n) \
  (((setp)->event_bits[__td_eventword (n)]) |= __td_eventmask (n))
#define td_event_delset(setp, n) \
  (((setp)->event_bits[__td_eventword (n)]) &= ~__td_eventmask (n))
#define td_eventismember(setp, n) \
  (__td_eventmask (n) & ((setp)->event_bits[__td_eventword (n)]))
#if TD_EVENTSIZE == 2
# define td_eventisempty(setp) \
  (!((setp)->event_bits[0]) && !((setp)->event_bits[1]))
#else
# error "td_eventisempty must be changed to match TD_EVENTSIZE"
#endif

/* Events reportable by the thread implementation.  */
typedef enum
{
  TD_ALL_EVENTS,		 /* Pseudo-event number.  */
  TD_EVENT_NONE = TD_ALL_EVENTS, /* Depends on context.  */
  TD_READY,			 /* Is executable now. */
  TD_SLEEP,			 /* Blocked in a synchronization obj.  */
  TD_SWITCHTO,			 /* Now assigned to a process.  */
  TD_SWITCHFROM,		 /* Not anymore assigned to a process.  */
  TD_LOCK_TRY,			 /* Trying to get an unavailable lock.  */
  TD_CATCHSIG,			 /* Signal posted to the thread.  */
  TD_IDLE,			 /* Process getting idle.  */
  TD_CREATE,			 /* New thread created.  */
  TD_DEATH,			 /* Thread terminated.  */
  TD_PREEMPT,			 /* Preempted.  */
  TD_PRI_INHERIT,		 /* Inherited elevated priority.  */
  TD_REAP,			 /* Reaped.  */
  TD_CONCURRENCY,		 /* Number of processes changing.  */
  TD_TIMEOUT,			 /* Conditional variable wait timed out.  */
  TD_MIN_EVENT_NUM = TD_READY,
  TD_MAX_EVENT_NUM = TD_TIMEOUT,
  TD_EVENTS_ENABLE = 31		/* Event reporting enabled.  */
} td_event_e;

/* Values representing the different ways events are reported.  */
typedef enum
{
  NOTIFY_BPT,			/* User must insert breakpoint at u.bptaddr. */
  NOTIFY_AUTOBPT,		/* Breakpoint at u.bptaddr is automatically
				   inserted.  */
  NOTIFY_SYSCALL		/* System call u.syscallno will be invoked.  */
} td_notify_e;

/* Description how event type is reported.  */
typedef struct td_notify
{
  td_notify_e type;		/* Way the event is reported.  */
  union
  {
    psaddr_t bptaddr;		/* Address of breakpoint.  */
    int syscallno;		/* Number of system call used.  */
  } u;
} td_notify_t;

/* Structure used to report event.  */
typedef struct td_event_msg
{
  td_event_e event;		/* Event type being reported.  */
  const td_thrhandle_t *th_p;	/* Thread reporting the event.  */
  union
  {
# if 0
    td_synchandle_t *sh;	/* Handle of synchronization object.  */
#endif
    uintptr_t data;		/* Event specific data.  */
  } msg;
} td_event_msg_t;

/* Structure containing event data available in each thread structure.  */
typedef struct
{
  td_thr_events_t eventmask;	/* Mask of enabled events.  */
  td_event_e eventnum;		/* Number of last event.  */
  void *eventdata;		/* Data associated with event.  */
} td_eventbuf_t;


/* Gathered statistics about the process.  */
typedef struct td_ta_stats
{
  int nthreads;       		/* Total number of threads in use.  */
  int r_concurrency;		/* Concurrency level requested by user.  */
  int nrunnable_num;		/* Average runnable threads, numerator.  */
  int nrunnable_den;		/* Average runnable threads, denominator.  */
  int a_concurrency_num;	/* Achieved concurrency level, numerator.  */
  int a_concurrency_den;	/* Achieved concurrency level, denominator.  */
  int nlwps_num;		/* Average number of processes in use,
				   numerator.  */
  int nlwps_den;		/* Average number of processes in use,
				   denominator.  */
  int nidle_num;		/* Average number of idling processes,
				   numerator.  */
  int nidle_den;		/* Average number of idling processes,
				   denominator.  */
} td_ta_stats_t;


/* Since Sun's library is based on Solaris threads we have to define a few
   types to map them to POSIX threads.  */
typedef pthread_t thread_t;
typedef pthread_key_t thread_key_t;


/* Callback for iteration over threads.  */
typedef int td_thr_iter_f (const td_thrhandle_t *, void *);

/* Callback for iteration over thread local data.  */
typedef int td_key_iter_f (thread_key_t, void (*) (void *), void *);



/* Forward declaration.  This has to be defined by the user.  */
struct ps_prochandle;


/* Information about the thread.  */
typedef struct td_thrinfo
{
  td_thragent_t *ti_ta_p;		/* Process handle.  */
  unsigned int ti_user_flags;		/* Unused.  */
  thread_t ti_tid;			/* Thread ID returned by
					   pthread_create().  */
  char *ti_tls;				/* Pointer to thread-local data.  */
  psaddr_t ti_startfunc;		/* Start function passed to
					   pthread_create().  */
  psaddr_t ti_stkbase;			/* Base of thread's stack.  */
  long int ti_stksize;			/* Size of thread's stack.  */
  psaddr_t ti_ro_area;			/* Unused.  */
  int ti_ro_size;			/* Unused.  */
  td_thr_state_e ti_state;		/* Thread state.  */
  unsigned char ti_db_suspended;	/* Nonzero if suspended by debugger. */
  td_thr_type_e ti_type;		/* Type of the thread (system vs
					   user thread).  */
  intptr_t ti_pc;			/* Unused.  */
  intptr_t ti_sp;			/* Unused.  */
  short int ti_flags;			/* Unused.  */
  int ti_pri;				/* Thread priority.  */
  lwpid_t ti_lid;			/* Kernel PID for this thread.  */
  sigset_t ti_sigmask;			/* Signal mask.  */
  unsigned char ti_traceme;		/* Nonzero if event reporting
					   enabled.  */
  unsigned char ti_preemptflag;		/* Unused.  */
  unsigned char ti_pirecflag;		/* Unused.  */
  sigset_t ti_pending;			/* Set of pending signals.  */
  td_thr_events_t ti_events;		/* Set of enabled events.  */
} td_thrinfo_t;



/* Prototypes for exported library functions.  */

/* Initialize the thread debug support library.  */
extern td_err_e td_init (void);

/* Historical relict.  Should not be used anymore.  */
extern td_err_e td_log (void);

/* Return list of symbols the library can request.  */
extern const char **td_symbol_list (void);

/* Generate new thread debug library handle for process PS.  */
extern td_err_e td_ta_new (struct ps_prochandle *__ps, td_thragent_t **__ta);

/* Free resources allocated for TA.  */
extern td_err_e td_ta_delete (td_thragent_t *__ta);

/* Get number of currently running threads in process associated with TA.  */
extern td_err_e td_ta_get_nthreads (const td_thragent_t *__ta, int *__np);

/* Return process handle passed in `td_ta_new' for process associated with
   TA.  */
extern td_err_e td_ta_get_ph (const td_thragent_t *__ta,
			      struct ps_prochandle **__ph);

/* Map thread library handle PT to thread debug library handle for process
   associated with TA and store result in *TH.  */
extern td_err_e td_ta_map_id2thr (const td_thragent_t *__ta, pthread_t __pt,
				  td_thrhandle_t *__th);

/* Map process ID LWPID to thread debug library handle for process
   associated with TA and store result in *TH.  */
extern td_err_e td_ta_map_lwp2thr (const td_thragent_t *__ta, lwpid_t __lwpid,
				   td_thrhandle_t *__th);


/* Call for each thread in a process associated with TA the callback function
   CALLBACK.  */
extern td_err_e td_ta_thr_iter (const td_thragent_t *__ta,
				td_thr_iter_f *__callback, void *__cbdata_p,
				td_thr_state_e __state, int __ti_pri,
				sigset_t *__ti_sigmask_p,
				unsigned int __ti_user_flags);

/* Call for each defined thread local data entry the callback function KI.  */
extern td_err_e td_ta_tsd_iter (const td_thragent_t *__ta, td_key_iter_f *__ki,
				void *__p);


/* Get event address for EVENT.  */
extern td_err_e td_ta_event_addr (const td_thragent_t *__ta,
				  td_event_e __event, td_notify_t *__ptr);

/* Enable EVENT in global mask.  */
extern td_err_e td_ta_set_event (const td_thragent_t *__ta,
				 td_thr_events_t *__event);

/* Disable EVENT in global mask.  */
extern td_err_e td_ta_clear_event (const td_thragent_t *__ta,
				   td_thr_events_t *__event);

/* Return information about last event.  */
extern td_err_e td_ta_event_getmsg (const td_thragent_t *__ta,
				    td_event_msg_t *__msg);


/* Set suggested concurrency level for process associated with TA.  */
extern td_err_e td_ta_setconcurrency (const td_thragent_t *__ta, int __level);


/* Enable collecting statistics for process associated with TA.  */
extern td_err_e td_ta_enable_stats (const td_thragent_t *__ta, int __enable);

/* Reset statistics.  */
extern td_err_e td_ta_reset_stats (const td_thragent_t *__ta);

/* Retrieve statistics from process associated with TA.  */
extern td_err_e td_ta_get_stats (const td_thragent_t *__ta,
				 td_ta_stats_t *__statsp);


/* Validate that TH is a thread handle.  */
extern td_err_e td_thr_validate (const td_thrhandle_t *__th);

/* Return information about thread TH.  */
extern td_err_e td_thr_get_info (const td_thrhandle_t *__th,
				 td_thrinfo_t *__infop);

/* Retrieve floating-point register contents of process running thread TH.  */
extern td_err_e td_thr_getfpregs (const td_thrhandle_t *__th,
				  prfpregset_t *__regset);

/* Retrieve general register contents of process running thread TH.  */
extern td_err_e td_thr_getgregs (const td_thrhandle_t *__th,
				 prgregset_t __gregs);

/* Retrieve extended register contents of process running thread TH.  */
extern td_err_e td_thr_getxregs (const td_thrhandle_t *__th, void *__xregs);

/* Get size of extended register set of process running thread TH.  */
extern td_err_e td_thr_getxregsize (const td_thrhandle_t *__th, int *__sizep);

/* Set floating-point register contents of process running thread TH.  */
extern td_err_e td_thr_setfpregs (const td_thrhandle_t *__th,
				  const prfpregset_t *__fpregs);

/* Set general register contents of process running thread TH.  */
extern td_err_e td_thr_setgregs (const td_thrhandle_t *__th,
				 prgregset_t __gregs);

/* Set extended register contents of process running thread TH.  */
extern td_err_e td_thr_setxregs (const td_thrhandle_t *__th,
				 const void *__addr);


/* Get address of the given module's TLS storage area for the given thread.  */
extern td_err_e td_thr_tlsbase (const td_thrhandle_t *__th,
				unsigned long int __modid,
				psaddr_t *__base);

/* Get address of thread local variable.  */
extern td_err_e td_thr_tls_get_addr (const td_thrhandle_t *__th,
				     psaddr_t __map_address, size_t __offset,
				     psaddr_t *__address);


/* Enable reporting for EVENT for thread TH.  */
extern td_err_e td_thr_event_enable (const td_thrhandle_t *__th, int __event);

/* Enable EVENT for thread TH.  */
extern td_err_e td_thr_set_event (const td_thrhandle_t *__th,
				  td_thr_events_t *__event);

/* Disable EVENT for thread TH.  */
extern td_err_e td_thr_clear_event (const td_thrhandle_t *__th,
				    td_thr_events_t *__event);

/* Get event message for thread TH.  */
extern td_err_e td_thr_event_getmsg (const td_thrhandle_t *__th,
				     td_event_msg_t *__msg);


/* Set priority of thread TH.  */
extern td_err_e td_thr_setprio (const td_thrhandle_t *__th, int __prio);


/* Set pending signals for thread TH.  */
extern td_err_e td_thr_setsigpending (const td_thrhandle_t *__th,
				      unsigned char __n, const sigset_t *__ss);

/* Set signal mask for thread TH.  */
extern td_err_e td_thr_sigsetmask (const td_thrhandle_t *__th,
				   const sigset_t *__ss);


/* Return thread local data associated with key TK in thread TH.  */
extern td_err_e td_thr_tsd (const td_thrhandle_t *__th,
			    const thread_key_t __tk, void **__data);


/* Suspend execution of thread TH.  */
extern td_err_e td_thr_dbsuspend (const td_thrhandle_t *__th);

/* Resume execution of thread TH.  */
extern td_err_e td_thr_dbresume (const td_thrhandle_t *__th);

#endif	/* thread_db.h */