xref: /illumos-gate/usr/src/cmd/sgs/include/debug.h (revision 48125817)

/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */

/*
 * Copyright (c) 1991, 2010, Oracle and/or its affiliates. All rights reserved.
 */

#ifndef	_DEBUG_H
#define	_DEBUG_H

/*
 * Global include file for lddbg debugging.
 *
 * ld(1) and ld.so.1(1) carry out all diagnostic debugging calls via lazy
 * loading the library liblddbg.so.  Thus debugging is always enabled.  The
 * utility elfdump(1) is explicitly dependent upon this library.  There are two
 * categories of routines defined in this library:
 *
 *  o	Debugging routines that have specific linker knowledge, and test the
 *	class of debugging allowable before proceeding, start with the `Dbg_'
 *	prefix.
 *
 *  o	Lower level routines that provide generic ELF structure interpretation
 *	start with the `Elf_' prefix.  These latter routines are the only
 *	routines used by the elfdump(1) utility.
 */
#include <sys/times.h>
#include <sgs.h>
#include <libld.h>
#include <rtld.h>
#include <gelf.h>

#ifdef	__cplusplus
extern "C" {
#endif

/*
 * Define Dbg_*() interface values.  These values direct the debugging routine
 * to generate different diagnostics, thus the strings themselves are maintained
 * in the debugging library.
 */
#define	DBG_SUP_ENVIRON		1
#define	DBG_SUP_CMDLINE		2

#define	DBG_CONF_IGNORE		1	/* configuration processing errors */
#define	DBG_CONF_VERSION	2
#define	DBG_CONF_PRCFAIL	3
#define	DBG_CONF_CORRUPT	4
#define	DBG_CONF_ABIMISMATCH	5

#define	DBG_ORDER_INFO_RANGE	1	/* sh_link out of range */
#define	DBG_ORDER_INFO_ORDER	2	/* sh_info also ordered */
#define	DBG_ORDER_LINK_OUTRANGE	3	/* sh_link out of range */
#define	DBG_ORDER_FLAGS		4	/* sh_flags do not match */
#define	DBG_ORDER_CYCLIC	5	/* sh_link cyclic */
#define	DBG_ORDER_LINK_ERROR	6	/* sh_link (one) has an error */

#define	DBG_INIT_SORT		1	/* calling init from sorted order */
#define	DBG_INIT_PEND		2	/* calling pending init */
#define	DBG_INIT_DYN		3	/* dynamically triggered init */
#define	DBG_INIT_DONE		4	/* init completed */

#define	DBG_DLSYM_DEF		0
#define	DBG_DLSYM_NEXT		1
#define	DBG_DLSYM_DEFAULT	2
#define	DBG_DLSYM_SELF		3
#define	DBG_DLSYM_PROBE		4
#define	DBG_DLSYM_SINGLETON	5
#define	DBG_DLSYM_NUM		DBG_DLSYM_SINGLETON + 1

#define	DBG_DLCLOSE_NULL	0
#define	DBG_DLCLOSE_IGNORE	1
#define	DBG_DLCLOSE_RESCAN	2

#define	DBG_SYM_REDUCE_GLOBAL	1	/* reporting global symbols to local */
#define	DBG_SYM_REDUCE_RETAIN	2	/* reporting non reduced local syms */

#define	DBG_AUD_CALL		1	/* original call to auditor */
#define	DBG_AUD_RET		2	/* return from auditor diagnostic */

#define	DBG_AUD_LOCAL		0	/* auditor is local */
#define	DBG_AUD_GLOBAL		1	/* auditor is global */
#define	DBG_AUD_PRELOAD		2	/* auditor is preloaded */

/*
 * Group handle operations - passed to Dbg_file_hdl_title().  Indicate why
 * handle dependencies are being manipulated.
 */
#define	DBG_HDL_CREATE		0	/* handle creation */
#define	DBG_HDL_ADD		1	/* addition to existing handle */
#define	DBG_HDL_DELETE		2	/* deletion from a handle */
#define	DBG_HDL_ORPHAN		3	/* handle being moved to orphan list */
#define	DBG_HDL_REINST		4	/* handle reinstated from orphan list */

/*
 * Group handle dependency operations - passed to Dbg_file_hdl_action().
 * Identify the dependencies that are associated with a handle.
 */
#define	DBG_DEP_ADD		0	/* dependency added */
#define	DBG_DEP_UPDATE		1	/* dependency updated */
#define	DBG_DEP_DELETE		2	/* dependency deleted */
#define	DBG_DEP_REMOVE		3	/* dependency removed from handle */
#define	DBG_DEP_REMAIN		4	/* dependency must remain on handle */
#define	DBG_DEP_ORPHAN		5	/* dependency must remain an orphan */
#define	DBG_DEP_REINST		6	/* dependency reinstated from orphan */

/*
 * Binding information, indicating the result of a symbol binding.  Can also
 * indicate the reference as being EXTERN or PARENT.  Binding information is
 * used to augment diagnostic binding information (which in turn can be used by
 * lari(1)), and to enable ldd(1) -p processing.
 */
#define	DBG_BINFO_FOUND		0x0001	/* information regarding binding */
#define	DBG_BINFO_DIRECT	0x0002	/* bound directly */
#define	DBG_BINFO_COPYREF	0x0004	/* bound to copy relocated reference */
#define	DBG_BINFO_FILTEE	0x0008	/* bound to filtee */
#define	DBG_BINFO_INTERPOSE	0x0010	/* bound to an identified interposer */
#define	DBG_BINFO_PLTADDR	0x0020	/* bound to executables undefined plt */
#define	DBG_BINFO_MSK		0x0fff

#define	DBG_BINFO_REF_EXTERN	0x1000	/* reference to EXTERN */
#define	DBG_BINFO_REF_PARENT	0x2000	/* reference to PARENT */
#define	DBG_BINFO_REF_MSK	0xf000

/*
 * ld.so.1(1) symbol capabilities processing.
 */
#define	DBG_CAP_DEFAULT		0
#define	DBG_CAP_USED		1
#define	DBG_CAP_CANDIDATE	2
#define	DBG_CAP_REJECTED	3
#define	DBG_CAP_HW_1		4
#define	DBG_CAP_SF_1		5
#define	DBG_CAP_HW_2		6
#define	DBG_CAP_PLAT		7
#define	DBG_CAP_MACH		8

#define	DBG_REL_START		1
#define	DBG_REL_FINISH		2
#define	DBG_REL_NONE		3

#define	DBG_NL_STD		0	/* newline controllers - standard and */
#define	DBG_NL_FRC		2	/*    forced. */

#define	DBG_BNDREJ_DIRECT	0	/* bind rejected, direct to nodirect */
#define	DBG_BNDREJ_GROUP	1	/* bind rejected, group to nodirect */
#define	DBG_BNDREJ_SINGLE	2	/* bind rejected, singleton without */
					/*    default search model */
#define	DBG_BNDREJ_NUM		DBG_BNDREJ_SINGLE

/*
 * Dbg_state_str() is used to obtain commonly used "state transition"
 * strings used in various debugging output.
 */
#define	DBG_STATE_ADD		0	/* add */
#define	DBG_STATE_CURRENT	1	/* current */
#define	DBG_STATE_EXCLUDE	2	/* exclude */
#define	DBG_STATE_IGNORED	3	/* ignored */
#define	DBG_STATE_MOD_BEFORE	4	/* modify (before) */
#define	DBG_STATE_MOD_AFTER	5	/* modify (after) */
#define	DBG_STATE_NEW 		6	/* new */
#define	DBG_STATE_NEW_IMPLICIT	7	/* new (implicit) */
#define	DBG_STATE_RESET		8	/* reset */
#define	DBG_STATE_ORIGINAL	9	/* original */
#define	DBG_STATE_RESOLVED	10	/* resolved */

#define	DBG_STATE_NUM		11
typedef uint_t dbg_state_t;
extern	const char *Dbg_state_str(dbg_state_t);

/*
 * Define a debug descriptor, and a user macro that inspects the descriptor as
 * a means of triggering a class of diagnostic output.
 */
typedef struct {
	uint_t		d_class;	/* debugging classes */
	uint_t		d_extra;	/* extra public information */
	APlist		*d_list;	/* accepted link-map list names */
	struct timeval	d_totaltime;	/* total time since entry - */
					/*	gettimeofday(3c) */
	struct timeval	d_deltatime;	/* delta time since last diagnostic - */
					/*	gettimeofday(3c) */
} Dbg_desc;

extern	Dbg_desc	*dbg_desc;

/*
 * Macros used to avoid calls to liblddbg unless debugging is enabled.
 * liblddbg is lazy loaded --- this prevents it from happening unless
 * it will actually be used.
 */
#define	DBG_ENABLED	(dbg_desc->d_class)
#define	DBG_CALL(func)	if (DBG_ENABLED) func

/*
 * Most debugging tokens are interpreted within liblddbg, and thus any flags
 * within d_class are only meaningful to this library.  The following flags
 * extend the d_class diagnostic, and are maintained in d_extra.  These flags
 * may be interpreted by the debugging library itself or from the callers
 * dbg_print() routine.
 */
#define	DBG_E_DETAIL	0x00000001	/* add detail to a class */
#define	DBG_E_LONG	0x00000002	/* use long names (ie. no truncation) */
#define	DBG_E_DEMANGLE	0x00000004	/* demangle symbol names */
#define	DBG_E_STDNL	0x00000008	/* standard newline indicator */
#define	DBG_E_HELP	0x00000010	/* help requested */
#define	DBG_E_HELP_EXIT	0x00000020	/* hint: user should exit after help */
#define	DBG_E_TTIME	0x00000040	/* prepend total time */
#define	DBG_E_DTIME	0x00000080	/* prepend delta time */
#define	DBG_E_RESET	0x00000100	/* reset times */

/* ld only */
#define	DBG_E_SNAME	0x00001000	/* prepend simple name */
#define	DBG_E_FNAME	0x00002000	/* prepend full name */
#define	DBG_E_CLASS	0x00004000	/* prepend ELF class */

/* ld.so.1 only */
#define	DBG_E_LMID	0x00100000	/* prepend link-map id */
#define	DBG_E_LMID_LDSO	0x00200000	/* show ldso link-map list */
#define	DBG_E_LMID_ALL	0x00400000	/* show all non-ldso link-map lists */
#define	DBG_E_LMID_ALT	0x00800000	/* show all ALT link-map lists */
#define	DBG_E_LMID_BASE	0x01000000	/* show BASE link-map list */


#define	DBG_NOTDETAIL()	!(dbg_desc->d_extra & DBG_E_DETAIL)
#define	DBG_NOTLONG()	!(dbg_desc->d_extra & DBG_E_LONG)

#define	DBG_ISDEMANGLE() \
			(dbg_desc->d_extra & DBG_E_DEMANGLE)

#define	DBG_TOTALTIME	(dbg_desc->d_totaltime)
#define	DBG_DELTATIME	(dbg_desc->d_deltatime)

#define	DBG_ISTTIME()	(dbg_desc->d_extra & DBG_E_TTIME)
#define	DBG_ISDTIME()	(dbg_desc->d_extra & DBG_E_DTIME)
#define	DBG_ISTIME()	(dbg_desc->d_extra & (DBG_E_TTIME | DBG_E_DTIME))
#define	DBG_NOTTIME()	!(dbg_desc->d_extra & (DBG_E_TTIME | DBG_E_DTIME))

#define	DBG_ISRESET()	(dbg_desc->d_extra & DBG_E_RESET)
#define	DBG_ONRESET()	(dbg_desc->d_extra |= DBG_E_RESET)
#define	DBG_OFFRESET()	(dbg_desc->d_extra &= ~DBG_E_RESET)

#define	DBG_ISSNAME()	(dbg_desc->d_extra & DBG_E_SNAME)
#define	DBG_ISFNAME()	(dbg_desc->d_extra & DBG_E_FNAME)
#define	DBG_ISCLASS()	(dbg_desc->d_extra & DBG_E_CLASS)
#define	DBG_ISLMID()	(dbg_desc->d_extra & DBG_E_LMID)

/*
 * Print routine, this must be supplied by the application.  The initial
 * argument may provide a link-map list to associate with the format statement
 * that follows.
 */
/* PRINTFLIKE2 */
extern	void		dbg_print(Lm_list *, const char *, ...);

/*
 * Initialization routine, called before any other Dbg routines to
 * establish the necessary state.
 */
typedef enum { DBG_CALLER_LD, DBG_CALLER_RTLD } dbg_setup_caller_t;
extern	int		Dbg_setup(dbg_setup_caller_t, const char *,
			    Dbg_desc *, const char **);

/* Call dbg_print() to produce linker version output */
extern void		Dbg_version(void);

/* Call dbg_print() to produce help output */
extern	void		Dbg_help(void);

/*
 * Establish ELF32 and ELF64 class Dbg_*() interfaces.
 */
#if	defined(_ELF64)

#define	Dbg_demangle_name	Dbg64_demangle_name

#define	Dbg_bind_global		Dbg64_bind_global
#define	Dbg_bind_plt_summary	Dbg64_bind_plt_summary
#define	Dbg_bind_pltpad_from	Dbg64_bind_pltpad_from
#define	Dbg_bind_pltpad_to	Dbg64_bind_pltpad_to
#define	Dbg_bind_reject		Dbg64_bind_reject
#define	Dbg_bind_weak		Dbg64_bind_weak

#define	Dbg_cap_candidate	Dbg64_cap_candidate
#define	Dbg_cap_filter		Dbg64_cap_filter
#define	Dbg_cap_id		Dbg64_cap_id
#define	Dbg_cap_identical	Dbg64_cap_identical
#define	Dbg_cap_mapfile_title	Dbg64_cap_mapfile_title
#define	Dbg_cap_post_title	Dbg64_cap_post_title
#define	Dbg_cap_sec_title	Dbg64_cap_sec_title
#define	Dbg_cap_val		Dbg64_cap_val
#define	Dbg_cap_ptr_entry	Dbg64_cap_ptr_entry
#define	Dbg_cap_val_entry	Dbg64_cap_val_entry

#define	Dbg_dl_dladdr		Dbg64_dl_dladdr
#define	Dbg_dl_dlclose		Dbg64_dl_dlclose
#define	Dbg_dl_dldump		Dbg64_dl_dldump
#define	Dbg_dl_dlerror		Dbg64_dl_dlerror
#define	Dbg_dl_dlinfo		Dbg64_dl_dlinfo
#define	Dbg_dl_dlopen		Dbg64_dl_dlopen
#define	Dbg_dl_dlsym		Dbg64_dl_dlsym
#define	Dbg_dl_iphdr_enter	Dbg64_dl_iphdr_enter
#define	Dbg_dl_iphdr_callback	Dbg64_dl_iphdr_callback
#define	Dbg_dl_iphdr_mapchange	Dbg64_dl_iphdr_mapchange
#define	Dbg_dl_iphdr_unmap_ret	Dbg64_dl_iphdr_unmap_ret

#define	Dbg_ent_entry		Dbg64_ent_entry
#define	Dbg_ent_print		Dbg64_ent_print

#define	Dbg_file_analyze	Dbg64_file_analyze
#define	Dbg_file_aout		Dbg64_file_aout
#define	Dbg_file_ar		Dbg64_file_ar
#define	Dbg_file_ar_rescan	Dbg64_file_ar_rescan
#define	Dbg_file_bind_entry	Dbg64_file_bind_entry
#define	Dbg_file_bindings	Dbg64_file_bindings
#define	Dbg_file_bindings_done	Dbg64_file_bindings_done
#define	Dbg_file_cleanup	Dbg64_file_cleanup
#define	Dbg_file_cntl		Dbg64_file_cntl
#define	Dbg_file_config_dis	Dbg64_file_config_dis
#define	Dbg_file_config_obj	Dbg64_file_config_obj
#define	Dbg_file_del_rescan	Dbg64_file_del_rescan
#define	Dbg_file_delete		Dbg64_file_delete
#define	Dbg_file_deferred	Dbg64_file_deferred
#define	Dbg_file_elf		Dbg64_file_elf
#define	Dbg_file_filtee		Dbg64_file_filtee
#define	Dbg_file_filter		Dbg64_file_filter
#define	Dbg_file_fixname	Dbg64_file_fixname
#define	Dbg_file_generic	Dbg64_file_generic
#define	Dbg_file_hdl_action	Dbg64_file_hdl_action
#define	Dbg_file_hdl_collect	Dbg64_file_hdl_collect
#define	Dbg_file_hdl_title	Dbg64_file_hdl_title
#define	Dbg_file_lazyload	Dbg64_file_lazyload
#define	Dbg_file_ldso		Dbg64_file_ldso
#define	Dbg_file_mmapobj	Dbg64_file_mmapobj
#define	Dbg_file_mode_promote	Dbg64_file_mode_promote
#define	Dbg_file_modified	Dbg64_file_modified
#define	Dbg_file_needed		Dbg64_file_needed
#define	Dbg_file_output		Dbg64_file_output
#define	Dbg_file_preload	Dbg64_file_preload
#define	Dbg_file_prot		Dbg64_file_prot
#define	Dbg_file_rejected	Dbg64_file_rejected
#define	Dbg_file_reuse		Dbg64_file_reuse
#define	Dbg_file_skip		Dbg64_file_skip

#define	Dbg_got_display		Dbg64_got_display

#define	Dbg_libs_audit		Dbg64_libs_audit
#define	Dbg_libs_find		Dbg64_libs_find
#define	Dbg_libs_found		Dbg64_libs_found
#define	Dbg_libs_insecure	Dbg64_libs_insecure
#define	Dbg_libs_init		Dbg64_libs_init
#define	Dbg_libs_l		Dbg64_libs_l
#define	Dbg_libs_path		Dbg64_libs_path
#define	Dbg_libs_req		Dbg64_libs_req
#define	Dbg_libs_update		Dbg64_libs_update
#define	Dbg_libs_yp		Dbg64_libs_yp
#define	Dbg_libs_ylu		Dbg64_libs_ylu

#define	Dbg_map_cexp_id		Dbg64_map_cexp_id
#define	Dbg_map_dv		Dbg64_map_dv
#define	Dbg_map_dv_entry	Dbg64_map_dv_entry
#define	Dbg_map_ent		Dbg64_map_ent
#define	Dbg_map_ent_ord_title	Dbg64_map_ent_ord_title
#define	Dbg_map_hdr_noalloc	Dbg64_map_hdr_noalloc
#define	Dbg_map_parse		Dbg64_map_parse
#define	Dbg_map_pass		Dbg64_map_pass
#define	Dbg_map_post_title	Dbg64_map_post_title
#define	Dbg_map_seg		Dbg64_map_seg
#define	Dbg_map_seg_order	Dbg64_map_seg_order
#define	Dbg_map_seg_os_order	Dbg64_map_seg_os_order
#define	Dbg_map_size_new	Dbg64_map_size_new
#define	Dbg_map_size_old	Dbg64_map_size_old
#define	Dbg_map_sort_seg	Dbg64_map_sort_seg
#define	Dbg_map_sort_title	Dbg64_map_sort_title
#define	Dbg_map_symbol		Dbg64_map_symbol
#define	Dbg_map_version		Dbg64_map_version

#define	Dbg_move_adjexpandreloc	Dbg64_move_adjexpandreloc
#define	Dbg_move_adjmovereloc	Dbg64_move_adjmovereloc
#define	Dbg_move_bad		Dbg64_move_bad
#define	Dbg_move_data		Dbg64_move_data
#define	Dbg_move_entry1		Dbg64_move_entry1
#define	Dbg_move_entry2		Dbg64_move_entry2
#define	Dbg_move_expand		Dbg64_move_expand
#define	Dbg_move_input		Dbg64_move_input
#define	Dbg_move_outmove	Dbg64_move_outmove
#define	Dbg_move_outsctadj	Dbg64_move_outsctadj
#define	Dbg_move_parexpn	Dbg64_move_parexpn

#define	Dbg_reloc_apply_reg	Dbg64_reloc_apply_reg
#define	Dbg_reloc_apply_val	Dbg64_reloc_apply_val
#define	Dbg_reloc_ars_entry	Dbg64_reloc_ars_entry
#define	Dbg_reloc_copy		Dbg64_reloc_copy
#define	Dbg_reloc_discard	Dbg64_reloc_discard
#define	Dbg_reloc_doact		Dbg64_reloc_doact
#define	Dbg_reloc_doact_title	Dbg64_reloc_doact_title
#define	Dbg_reloc_dooutrel	Dbg64_reloc_dooutrel
#define	Dbg_reloc_entry		Dbg64_reloc_entry
#define	Dbg_reloc_error		Dbg64_reloc_error
#define	Dbg_reloc_generate	Dbg64_reloc_generate
#define	Dbg_reloc_in		Dbg64_reloc_in
#define	Dbg_reloc_ors_entry	Dbg64_reloc_ors_entry
#define	Dbg_reloc_out		Dbg64_reloc_out
#define	Dbg_reloc_proc		Dbg64_reloc_proc
#define	Dbg_reloc_run		Dbg64_reloc_run
#define	Dbg_reloc_transition	Dbg64_reloc_transition
#define	Dbg_reloc_sloppycomdat	Dbg64_reloc_sloppycomdat

#define	Dbg_sec_added		Dbg64_sec_added
#define	Dbg_sec_backing		Dbg64_sec_backing
#define	Dbg_sec_created		Dbg64_sec_created
#define	Dbg_sec_discarded	Dbg64_sec_discarded
#define	Dbg_sec_genstr_compress	Dbg64_sec_genstr_compress
#define	Dbg_sec_group		Dbg64_sec_group
#define	Dbg_sec_gnu_comdat	Dbg64_sec_gnu_comdat
#define	Dbg_sec_in		Dbg64_sec_in
#define	Dbg_sec_order_error	Dbg64_sec_order_error
#define	Dbg_sec_order_list	Dbg64_sec_order_list
#define	Dbg_sec_redirected	Dbg64_sec_redirected
#define	Dbg_sec_strtab		Dbg64_sec_strtab
#define	Dbg_sec_unsup_strmerge	Dbg64_sec_unsup_strmerge

#define	Dbg_seg_desc_entry	Dbg64_seg_desc_entry
#define	Dbg_seg_entry		Dbg64_seg_entry
#define	Dbg_seg_list		Dbg64_seg_list
#define	Dbg_seg_os		Dbg64_seg_os
#define	Dbg_seg_title		Dbg64_seg_title

#define	Dbg_shdr_modified	Dbg64_shdr_modified

#define	Dbg_statistics_ar	Dbg64_statistics_ar
#define	Dbg_statistics_ld	Dbg64_statistics_ld

#define	Dbg_support_action	Dbg64_support_action