27c478bdstevel@tonic-gate * CDDL HEADER START
37c478bdstevel@tonic-gate *
47c478bdstevel@tonic-gate * The contents of this file are subject to the terms of the
57c478bdstevel@tonic-gate * Common Development and Distribution License, Version 1.0 only
67c478bdstevel@tonic-gate * (the "License").  You may not use this file except in compliance
77c478bdstevel@tonic-gate * with the License.
87c478bdstevel@tonic-gate *
97c478bdstevel@tonic-gate * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
107c478bdstevel@tonic-gate * or http://www.opensolaris.org/os/licensing.
117c478bdstevel@tonic-gate * See the License for the specific language governing permissions
127c478bdstevel@tonic-gate * and limitations under the License.
137c478bdstevel@tonic-gate *
147c478bdstevel@tonic-gate * When distributing Covered Code, include this CDDL HEADER in each
157c478bdstevel@tonic-gate * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
167c478bdstevel@tonic-gate * If applicable, add the following below this CDDL HEADER, with the
177c478bdstevel@tonic-gate * fields enclosed by brackets "[]" replaced with your own identifying
187c478bdstevel@tonic-gate * information: Portions Copyright [yyyy] [name of copyright owner]
197c478bdstevel@tonic-gate *
207c478bdstevel@tonic-gate * CDDL HEADER END
217c478bdstevel@tonic-gate */
237c478bdstevel@tonic-gate * Copyright 2005 Sun Microsystems, Inc.  All rights reserved.
247c478bdstevel@tonic-gate * Use is subject to license terms.
25399ca3aJohn Levon *
26399ca3aJohn Levon * Copyright 2018 Joyent, Inc.
277c478bdstevel@tonic-gate */
297c478bdstevel@tonic-gate#ifndef	_MDB_TARGET_H
307c478bdstevel@tonic-gate#define	_MDB_TARGET_H
327c478bdstevel@tonic-gate#include <sys/utsname.h>
337c478bdstevel@tonic-gate#include <sys/types.h>
347c478bdstevel@tonic-gate#include <gelf.h>
367c478bdstevel@tonic-gate#ifdef	__cplusplus
377c478bdstevel@tonic-gateextern "C" {
417c478bdstevel@tonic-gate * Forward declaration of the target structure: the target itself is defined in
427c478bdstevel@tonic-gate * mdb_tgt_impl.h and is opaque with respect to callers of this interface.
437c478bdstevel@tonic-gate */
457c478bdstevel@tonic-gatestruct mdb_tgt;
467c478bdstevel@tonic-gatestruct mdb_arg;
477c478bdstevel@tonic-gatestruct ctf_file;
497c478bdstevel@tonic-gatetypedef struct mdb_tgt mdb_tgt_t;
517c478bdstevel@tonic-gateextern void mdb_create_builtin_tgts(void);
527c478bdstevel@tonic-gateextern void mdb_create_loadable_disasms(void);
557c478bdstevel@tonic-gate * Target Constructors
567c478bdstevel@tonic-gate *
577c478bdstevel@tonic-gate * These functions are used to create a complete debugger target.  The
587c478bdstevel@tonic-gate * constructor is passed as an argument to mdb_tgt_create().
597c478bdstevel@tonic-gate */
617c478bdstevel@tonic-gateextern int mdb_value_tgt_create(mdb_tgt_t *, int, const char *[]);
627c478bdstevel@tonic-gate#ifndef _KMDB
637c478bdstevel@tonic-gateextern int mdb_kvm_tgt_create(mdb_tgt_t *, int, const char *[]);
647c478bdstevel@tonic-gateextern int mdb_proc_tgt_create(mdb_tgt_t *, int, const char *[]);
657c478bdstevel@tonic-gateextern int mdb_kproc_tgt_create(mdb_tgt_t *, int, const char *[]);
667c478bdstevel@tonic-gateextern int mdb_rawfile_tgt_create(mdb_tgt_t *, int, const char *[]);
679c3024aHans Rosenfeld#ifdef __amd64
689c3024aHans Rosenfeldextern int mdb_bhyve_tgt_create(mdb_tgt_t *, int, const char *[]);
699c3024aHans Rosenfeld#endif
717c478bdstevel@tonic-gateextern int kmdb_kvm_create(mdb_tgt_t *, int, const char *[]);
757c478bdstevel@tonic-gate * Targets are created by calling mdb_tgt_create() with an optional set of
767c478bdstevel@tonic-gate * target flags, an argument list, and a target constructor (see above):
777c478bdstevel@tonic-gate */
797c478bdstevel@tonic-gate#define	MDB_TGT_F_RDWR		0x0001	/* Open for writing (else read-only) */
807c478bdstevel@tonic-gate#define	MDB_TGT_F_ALLOWIO	0x0002	/* Allow I/O mem access (live only) */
817c478bdstevel@tonic-gate#define	MDB_TGT_F_FORCE		0x0004	/* Force open (even if non-exclusive) */
827c478bdstevel@tonic-gate#define	MDB_TGT_F_PRELOAD	0x0008	/* Preload all symbol tables */
837c478bdstevel@tonic-gate#define	MDB_TGT_F_NOLOAD	0x0010	/* Do not do load-object processing */
847c478bdstevel@tonic-gate#define	MDB_TGT_F_NOSTOP	0x0020	/* Do not stop target on attach */
857c478bdstevel@tonic-gate#define	MDB_TGT_F_STEP		0x0040	/* Single-step is pending */
867c478bdstevel@tonic-gate#define	MDB_TGT_F_STEP_OUT	0x0080	/* Step-out is pending */
87399ca3aJohn Levon#define	MDB_TGT_F_NEXT		0x0100	/* Step-over is pending */
88399ca3aJohn Levon#define	MDB_TGT_F_CONT		0x0200	/* Continue is pending */
89399ca3aJohn Levon#define	MDB_TGT_F_BUSY		0x0400	/* Target is busy executing */
90399ca3aJohn Levon#define	MDB_TGT_F_ASIO		0x0800	/* Use t_aread and t_awrite for i/o */
91399ca3aJohn Levon#define	MDB_TGT_F_UNLOAD	0x1000	/* Unload has been requested */
92399ca3aJohn Levon#define	MDB_TGT_F_ALL		0x1fff	/* Mask of all valid flags */
947c478bdstevel@tonic-gatetypedef int mdb_tgt_ctor_f(mdb_tgt_t *, int, const char *[]);
967c478bdstevel@tonic-gateextern mdb_tgt_t *mdb_tgt_create(mdb_tgt_ctor_f *, int, int, const char *[]);
977c478bdstevel@tonic-gateextern void mdb_tgt_destroy(mdb_tgt_t *);
997c478bdstevel@tonic-gateextern int mdb_tgt_getflags(mdb_tgt_t *);
1007c478bdstevel@tonic-gateextern int mdb_tgt_setflags(mdb_tgt_t *, int);
1017c478bdstevel@tonic-gateextern int mdb_tgt_setcontext(mdb_tgt_t *, void *);
1047c478bdstevel@tonic-gate * Targets are activated and de-activated by the debugger framework.  An
1057c478bdstevel@tonic-gate * activation occurs after construction when the target becomes the current
1067c478bdstevel@tonic-gate * target in the debugger.  A target is de-activated prior to its destructor
1077c478bdstevel@tonic-gate * being called by mdb_tgt_destroy, or when another target is activated.
1087c478bdstevel@tonic-gate * These callbacks are suitable for loading support modules and other tasks.
1097c478bdstevel@tonic-gate */
1107c478bdstevel@tonic-gateextern void mdb_tgt_activate(mdb_tgt_t *);
1137c478bdstevel@tonic-gate * Prior to issuing a new command prompt, the debugger framework calls the
1147c478bdstevel@tonic-gate * target's periodic callback to allow it to load new modules or perform
1157c478bdstevel@tonic-gate * other background tasks.
1167c478bdstevel@tonic-gate */
1177c478bdstevel@tonic-gateextern void mdb_tgt_periodic(mdb_tgt_t *);
1207c478bdstevel@tonic-gate * Convenience functions for accessing miscellaneous target information.
1217c478bdstevel@tonic-gate */
1227c478bdstevel@tonic-gateextern const char *mdb_tgt_name(mdb_tgt_t *);
1237c478bdstevel@tonic-gateextern const char *mdb_tgt_isa(mdb_tgt_t *);
1247c478bdstevel@tonic-gateextern const char *mdb_tgt_platform(mdb_tgt_t *);
1257c478bdstevel@tonic-gateextern int mdb_tgt_uname(mdb_tgt_t *, struct utsname *);
1267c478bdstevel@tonic-gateextern int mdb_tgt_dmodel(mdb_tgt_t *);
1297c478bdstevel@tonic-gate * Address Space Interface
1307c478bdstevel@tonic-gate *
1317c478bdstevel@tonic-gate * Each target can provide access to a set of address spaces, which may include
1327c478bdstevel@tonic-gate * a primary virtual address space, a physical address space, an object file
1337c478bdstevel@tonic-gate * address space (where virtual addresses are converted to file offsets in an
1347c478bdstevel@tonic-gate * object file), and an I/O port address space.  Additionally, the target can
1357c478bdstevel@tonic-gate * provide access to alternate address spaces, which are identified by the
1367c478bdstevel@tonic-gate * opaque mdb_tgt_as_t type.  If the 'as' parameter to mdb_tgt_aread or
1377c478bdstevel@tonic-gate * mdb_tgt_awrite is one of the listed constants, these calls are equivalent
1387c478bdstevel@tonic-gate * to mdb_tgt_{v|p|f|io}read or write.
1397c478bdstevel@tonic-gate */
1417c478bdstevel@tonic-gatetypedef void *		mdb_tgt_as_t;		/* Opaque address space id */
1427c478bdstevel@tonic-gatetypedef uint64_t	mdb_tgt_addr_t;		/* Generic unsigned address */
1437c478bdstevel@tonic-gatetypedef uint64_t	physaddr_t;		/* Physical memory address */
1459c3024aHans Rosenfeld#define	MDB_TGT_AS_VIRT	((mdb_tgt_as_t)-1L)	/* Virtual address space: */
1469c3024aHans Rosenfeld#define	MDB_TGT_AS_VIRT_I ((mdb_tgt_as_t)-2L)	/*   special case for code */
1479c3024aHans Rosenfeld#define	MDB_TGT_AS_VIRT_S ((mdb_tgt_as_t)-3L)	/*   special case for stack */
1489c3024aHans Rosenfeld#define	MDB_TGT_AS_PHYS	((mdb_tgt_as_t)-4L)	/* Physical address space */
1499c3024aHans Rosenfeld#define	MDB_TGT_AS_FILE	((mdb_tgt_as_t)-5L)	/* Object file address space */
1509c3024aHans Rosenfeld#define	MDB_TGT_AS_IO	((mdb_tgt_as_t)-6L)	/* I/o address space */
1527c478bdstevel@tonic-gateextern ssize_t mdb_tgt_aread(mdb_tgt_t *, mdb_tgt_as_t,
1537c478bdstevel@tonic-gate	void *, size_t, mdb_tgt_addr_t);
1557c478bdstevel@tonic-gateextern ssize_t mdb_tgt_awrite(mdb_tgt_t *, mdb_tgt_as_t,
1567c478bdstevel@tonic-gate	const void *, size_t, mdb_tgt_addr_t);
1587c478bdstevel@tonic-gateextern ssize_t mdb_tgt_vread(mdb_tgt_t *, void *, size_t, uintptr_t);
1597c478bdstevel@tonic-gateextern ssize_t mdb_tgt_vwrite(mdb_tgt_t *, const void *, size_t, uintptr_t);
1607c478bdstevel@tonic-gateextern ssize_t mdb_tgt_pread(mdb_tgt_t *, void *, size_t, physaddr_t);
1617c478bdstevel@tonic-gateextern ssize_t mdb_tgt_pwrite(mdb_tgt_t *, const void *, size_t, physaddr_t);
1627c478bdstevel@tonic-gateextern ssize_t mdb_tgt_fread(mdb_tgt_t *, void *, size_t, uintptr_t);
1637c478bdstevel@tonic-gateextern ssize_t mdb_tgt_fwrite(mdb_tgt_t *, const void *, size_t, uintptr_t);
1647c478bdstevel@tonic-gateextern ssize_t mdb_tgt_ioread(mdb_tgt_t *, void *, size_t, uintptr_t);
1657c478bdstevel@tonic-gateextern ssize_t mdb_tgt_iowrite(mdb_tgt_t *, const void *, size_t, uintptr_t);
1687c478bdstevel@tonic-gate * Convert an address-space's virtual address to the corresponding
1697c478bdstevel@tonic-gate * physical address (only useful for kernel targets):
1707c478bdstevel@tonic-gate */
1717c478bdstevel@tonic-gateextern int mdb_tgt_vtop(mdb_tgt_t *, mdb_tgt_as_t, uintptr_t, physaddr_t *);
1747c478bdstevel@tonic-gate * Convenience functions for reading and writing null-terminated
1757c478bdstevel@tonic-gate * strings from any of the target address spaces:
1767c478bdstevel@tonic-gate */
1777c478bdstevel@tonic-gateextern ssize_t mdb_tgt_readstr(mdb_tgt_t *, mdb_tgt_as_t,
1787c478bdstevel@tonic-gate	char *, size_t, mdb_tgt_addr_t);
1807c478bdstevel@tonic-gateextern ssize_t mdb_tgt_writestr(mdb_tgt_t *, mdb_tgt_as_t,
1817c478bdstevel@tonic-gate	const char *, mdb_tgt_addr_t);
1847c478bdstevel@tonic-gate * Symbol Table Interface
1857c478bdstevel@tonic-gate *
1867c478bdstevel@tonic-gate * Each target can provide access to one or more symbol tables, which can be
1877c478bdstevel@tonic-gate * iterated over, or used to lookup symbols by either name or address.  The
1887c478bdstevel@tonic-gate * target can support a primary executable and primary dynamic symbol table,
1897c478bdstevel@tonic-gate * a symbol table for its run-time link-editor, and symbol tables for one or
1907c478bdstevel@tonic-gate * more loaded objects.  A symbol is uniquely identified by an object name,
1917c478bdstevel@tonic-gate * a symbol table id, and a symbol id.  Symbols can be discovered by iterating
1927c478bdstevel@tonic-gate * over them, looking them up by name, or looking them up by address.
1937c478bdstevel@tonic-gate */
1957c478bdstevel@tonic-gatetypedef struct mdb_syminfo {
1967c478bdstevel@tonic-gate	uint_t sym_table;	/* Symbol table id (see symbol_iter, below) */
1977c478bdstevel@tonic-gate	uint_t sym_id;		/* Symbol identifier */
1987c478bdstevel@tonic-gate} mdb_syminfo_t;
2017c478bdstevel@tonic-gate * Reserved object names for mdb_tgt_lookup_by_name():
2027c478bdstevel@tonic-gate */
2037c478bdstevel@tonic-gate#define	MDB_TGT_OBJ_EXEC	((const char *)0L)	/* Executable symbols */
2047c478bdstevel@tonic-gate#define	MDB_TGT_OBJ_RTLD	((const char *)1L)	/* Ldso/krtld symbols */
2057c478bdstevel@tonic-gate#define	MDB_TGT_OBJ_EVERY	((const char *)-1L)	/* All known symbols */
2077c478bdstevel@tonic-gateextern int mdb_tgt_lookup_by_scope(mdb_tgt_t *, const char *,
2087c478bdstevel@tonic-gate	GElf_Sym *, mdb_syminfo_t *);
2107c478bdstevel@tonic-gateextern int mdb_tgt_lookup_by_name(mdb_tgt_t *, const char *,
2117c478bdstevel@tonic-gate	const char *, GElf_Sym *, mdb_syminfo_t *);
2147c478bdstevel@tonic-gate * Flag bit passed to mdb_tgt_lookup_by_addr():
2157c478bdstevel@tonic-gate */
2167c478bdstevel@tonic-gate#define	MDB_TGT_SYM_FUZZY	0	/* Match closest address */
2177c478bdstevel@tonic-gate#define	MDB_TGT_SYM_EXACT	1	/* Match exact address only */
2197c478bdstevel@tonic-gate#define	MDB_TGT_SYM_NAMLEN	1024	/* Recommended max symbol name length */
2217c478bdstevel@tonic-gateextern int mdb_tgt_lookup_by_addr(mdb_tgt_t *, uintptr_t, uint_t,
2227c478bdstevel@tonic-gate	char *, size_t, GElf_Sym *, mdb_syminfo_t *);
2257c478bdstevel@tonic-gate * Callback function prototype for mdb_tgt_symbol_iter():
2267c478bdstevel@tonic-gate */
2277c478bdstevel@tonic-gatetypedef int mdb_tgt_sym_f(void *, const GElf_Sym *, const char *,
2287c478bdstevel@tonic-gate	const mdb_syminfo_t *sip, const char *);
2317c478bdstevel@tonic-gate * Values for selecting symbol tables with mdb_tgt_symbol_iter():
2327c478bdstevel@tonic-gate */
2337c478bdstevel@tonic-gate#define	MDB_TGT_PRVSYM		0	/* User's private symbol table */
2347c478bdstevel@tonic-gate#define	MDB_TGT_SYMTAB		1	/* Normal symbol table (.symtab) */
2357c478bdstevel@tonic-gate#define	MDB_TGT_DYNSYM		2	/* Dynamic symbol table (.dynsym) */
2387c478bdstevel@tonic-gate * Values for selecting symbols of interest by binding and type.  These flags
239ac58c5dDave Pacheco * can be used to construct a bitmask to pass to mdb_tgt_symbol_iter().  The
240ac58c5dDave Pacheco * module API has its own slightly different names for these values.  If you are
241ac58c5dDave Pacheco * adding a new flag here, you should consider exposing it in the module API.
242ac58c5dDave Pacheco * If you are changing these flags and their meanings, you will need to update
243ac58c5dDave Pacheco * the module API implementation to account for those changes.
2447c478bdstevel@tonic-gate */
2457c478bdstevel@tonic-gate#define	MDB_TGT_BIND_LOCAL	0x0001	/* Local (static-scope) symbols */
2467c478bdstevel@tonic-gate#define	MDB_TGT_BIND_GLOBAL	0x0002	/* Global symbols */
2477c478bdstevel@tonic-gate#define	MDB_TGT_BIND_WEAK	0x0004	/* Weak binding symbols */
2497c478bdstevel@tonic-gate#define	MDB_TGT_BIND_ANY	0x0007	/* Any of the above */
2517c478bdstevel@tonic-gate#define	MDB_TGT_TYPE_NOTYPE	0x0100	/* Symbol has no type */
2527c478bdstevel@tonic-gate#define	MDB_TGT_TYPE_OBJECT	0x0200	/* Symbol refers to data */
2537c478bdstevel@tonic-gate#define	MDB_TGT_TYPE_FUNC	0x0400	/* Symbol refers to text */
2547c478bdstevel@tonic-gate#define	MDB_TGT_TYPE_SECT	0x0800	/* Symbol refers to a section */
2557c478bdstevel@tonic-gate#define	MDB_TGT_TYPE_FILE	0x1000	/* Symbol refers to a source file */
2567c478bdstevel@tonic-gate#define	MDB_TGT_TYPE_COMMON	0x2000	/* Symbol refers to a common block */
2577c478bdstevel@tonic-gate#define	MDB_TGT_TYPE_TLS	0x4000	/* Symbol refers to TLS */
2597c478bdstevel@tonic-gate#define	MDB_TGT_TYPE_ANY	0x7f00	/* Any of the above */
2617c478bdstevel@tonic-gateextern int mdb_tgt_symbol_iter(mdb_tgt_t *, const char *, uint_t, uint_t,
2627c478bdstevel@tonic-gate	mdb_tgt_sym_f *, void *);
2657c478bdstevel@tonic-gate * Convenience functions for reading and writing at the address specified
2667c478bdstevel@tonic-gate * by a given object file and symbol name:
2677c478bdstevel@tonic-gate */
2687c478bdstevel@tonic-gateextern ssize_t mdb_tgt_readsym(mdb_tgt_t *, mdb_tgt_as_t, void *, size_t,
2697c478bdstevel@tonic-gate	const char *, const char *);
2717c478bdstevel@tonic-gateextern ssize_t mdb_tgt_writesym(mdb_tgt_t *, mdb_tgt_as_t, const void *, size_t,
2727c478bdstevel@tonic-gate	const char *, const char *);
2757c478bdstevel@tonic-gate * Virtual Address Mapping and Load Object interface
2767c478bdstevel@tonic-gate *
2777c478bdstevel@tonic-gate * These interfaces allow the caller to iterate over the various virtual
2787c478bdstevel@tonic-gate * address space mappings, or only those mappings corresponding to load objects.
2797c478bdstevel@tonic-gate * The mapping name (MDB_TGT_MAPSZ) is defined to be large enough for a string
2807c478bdstevel@tonic-gate * of length MAXPATHLEN, plus space for "LM`<lmid>" where lmid is a hex number.
2817c478bdstevel@tonic-gate */
2837c478bdstevel@tonic-gate#define	MDB_TGT_MAPSZ		1048	/* Maximum length of mapping name */
2857c478bdstevel@tonic-gate#define	MDB_TGT_MAP_R		0x01	/* Mapping is readable */
2867c478bdstevel@tonic-gate#define	MDB_TGT_MAP_W		0x02	/* Mapping is writeable */
2877c478bdstevel@tonic-gate#define	MDB_TGT_MAP_X		0x04	/* Mapping is executable */
2887c478bdstevel@tonic-gate#define	MDB_TGT_MAP_SHMEM	0x08	/* Mapping is shared memory */
2897c478bdstevel@tonic-gate#define	MDB_TGT_MAP_STACK	0x10	/* Mapping is a stack of some kind */
2907c478bdstevel@tonic-gate#define	MDB_TGT_MAP_HEAP	0x20	/* Mapping is a heap of some kind */
2917c478bdstevel@tonic-gate#define	MDB_TGT_MAP_ANON	0x40	/* Mapping is anonymous memory */
2937c478bdstevel@tonic-gatetypedef struct mdb_map {
2947c478bdstevel@tonic-gate	char map_name[MDB_TGT_MAPSZ];	/* Name of mapped object */
2957c478bdstevel@tonic-gate	uintptr_t map_base;		/* Virtual address of base of mapping */
2967c478bdstevel@tonic-gate	size_t map_size;		/* Size of mapping in bytes */
2977c478bdstevel@tonic-gate	uint_t map_flags;		/* Flags (see above) */
2987c478bdstevel@tonic-gate} mdb_map_t;
3007c478bdstevel@tonic-gatetypedef int mdb_tgt_map_f(void *, const mdb_map_t *, const char *);
3027c478bdstevel@tonic-gateextern int mdb_tgt_mapping_iter(mdb_tgt_t *, mdb_tgt_map_f *, void *);
3037c478bdstevel@tonic-gateextern int mdb_tgt_object_iter(mdb_tgt_t *, mdb_tgt_map_f *, void *);
3057c478bdstevel@tonic-gateextern const mdb_map_t *mdb_tgt_addr_to_map(mdb_tgt_t *, uintptr_t);
3067c478bdstevel@tonic-gateextern const mdb_map_t *mdb_tgt_name_to_map(mdb_tgt_t *, const char *);
3087c478bdstevel@tonic-gateextern struct ctf_file *mdb_tgt_addr_to_ctf(mdb_tgt_t *, uintptr_t);
3097c478bdstevel@tonic-gateextern struct ctf_file *mdb_tgt_name_to_ctf(mdb_tgt_t *, const char *);
3127c478bdstevel@tonic-gate * Execution Control Interface
3137c478bdstevel@tonic-gate *
3147c478bdstevel@tonic-gate * For in-situ debugging, we provide a relatively simple interface for target
3157c478bdstevel@tonic-gate * execution control.  The target can be continued, or the representative
3167c478bdstevel@tonic-gate * thread of control can be single-stepped.  Once the target has stopped, the
3177c478bdstevel@tonic-gate * status of the representative thread is returned (this status can also be
3187c478bdstevel@tonic-gate * obtained using mdb_tgt_status()).  Upon continue, the target's internal list
3197c478bdstevel@tonic-gate * of software event specifiers determines what types of events will cause the
3207c478bdstevel@tonic-gate * target to stop and transfer control back to the debugger.  The target
3217c478bdstevel@tonic-gate * allows any number of virtual event specifiers to be registered, along with
3227c478bdstevel@tonic-gate * an associated callback.  These virtual specifiers are layered on top of
3237c478bdstevel@tonic-gate * underlying software event specifiers that are private to the target.  The
3247c478bdstevel@tonic-gate * virtual event specifier list can be manipulated by the functions described
3257c478bdstevel@tonic-gate * below.  We currently support the following types of traced events:
3267c478bdstevel@tonic-gate * breakpoints, watchpoints, system call entry, system call exit, signals,
3277c478bdstevel@tonic-gate * and machine faults.
3287c478bdstevel@tonic-gate */
3307c478bdstevel@tonic-gatetypedef uintptr_t mdb_tgt_tid_t;	/* Opaque thread identifier */
3327c478bdstevel@tonic-gatetypedef struct mdb_tgt_status {
3337c478bdstevel@tonic-gate	mdb_tgt_tid_t st_tid;		/* Id of thread in question */
3347c478bdstevel@tonic-gate	uintptr_t st_pc;		/* Program counter, if stopped */
3357c478bdstevel@tonic-gate	uint_t st_state;		/* Program state (see below) */
3367c478bdstevel@tonic-gate	uint_t st_flags;		/* Status flags (see below) */
3377c478bdstevel@tonic-gate} mdb_tgt_status_t;
3407c478bdstevel@tonic-gate * Program state (st_state):
3417c478bdstevel@tonic-gate * (MDB_STATE_* definitions in the module API need to be in sync with these)
3427c478bdstevel@tonic-gate */
3437c478bdstevel@tonic-gate#define	MDB_TGT_IDLE		0	/* Target is idle (not running yet) */
3447c478bdstevel@tonic-gate#define	MDB_TGT_RUNNING		1	/* Target is currently executing */
3457c478bdstevel@tonic-gate#define	MDB_TGT_STOPPED		2	/* Target is stopped */
3467c478bdstevel@tonic-gate#define	MDB_TGT_UNDEAD		3	/* Target is undead (zombie) */
3477c478bdstevel@tonic-gate#define	MDB_TGT_DEAD		4	/* Target is dead (core dump) */
3487c478bdstevel@tonic-gate#define	MDB_TGT_LOST		5	/* Target lost by debugger */
3517c478bdstevel@tonic-gate * Status flags (st_flags):
3527c478bdstevel@tonic-gate */
3537c478bdstevel@tonic-gate#define	MDB_TGT_ISTOP		0x1	/* Stop on event of interest */
3547c478bdstevel@tonic-gate#define	MDB_TGT_DSTOP		0x2	/* Stop directive is pending */
3557c478bdstevel@tonic-gate#define	MDB_TGT_BUSY		0x4	/* Busy in debugger */
3577c478bdstevel@tonic-gateextern int mdb_tgt_status(mdb_tgt_t *, mdb_tgt_status_t *);
3587c478bdstevel@tonic-gateextern int mdb_tgt_run(mdb_tgt_t *, int, const struct mdb_arg *);
3597c478bdstevel@tonic-gateextern int mdb_tgt_step(mdb_tgt_t *, mdb_tgt_status_t *);
3607c478bdstevel@tonic-gateextern int mdb_tgt_step_out(mdb_tgt_t *, mdb_tgt_status_t *);
3617c478bdstevel@tonic-gateextern int mdb_tgt_next(mdb_tgt_t *, mdb_tgt_status_t *);
3627c478bdstevel@tonic-gateextern int mdb_tgt_continue(mdb_tgt_t *, mdb_tgt_status_t *);
3637c478bdstevel@tonic-gateextern int mdb_tgt_signal(mdb_tgt_t *, int);
3667c478bdstevel@tonic-gate * Iterating through the specifier list yields the integer id (VID) and private
3677c478bdstevel@tonic-gate * data pointer for each specifier.
3687c478bdstevel@tonic-gate */
3697c478bdstevel@tonic-gatetypedef int mdb_tgt_vespec_f(mdb_tgt_t *, void *, int, void *);
3727c478bdstevel@tonic-gate * Each event specifier is defined to be in one of the following states.  The
3737c478bdstevel@tonic-gate * state transitions are discussed in detail in the comments in mdb_target.c.
3747c478bdstevel@tonic-gate */
3757c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_IDLE	1	/* Inactive (e.g. object not loaded) */
3767c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_ACTIVE	2	/* Active but not armed in target */
3777c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_ARMED	3	/* Active and armed (e.g. bkpt set) */
3787c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_ERROR	4	/* Failed to arm event */
3817c478bdstevel@tonic-gate * Event specifiers may also have one or more of the following additional
3827c478bdstevel@tonic-gate * properties (spec_flags bits):
3837c478bdstevel@tonic-gate */
3847c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_INTERNAL	0x0001	/* Internal to target implementation */
3857c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_SILENT	0x0002	/* Do not describe when matched */
3867c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_TEMPORARY	0x0004	/* Delete next time target stops */
3877c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_MATCHED	0x0008	/* Specifier matched at last stop */
3887c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_DISABLED	0x0010	/* Specifier cannot be armed */
3897c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_DELETED	0x0020	/* Specifier has been deleted */
3907c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_AUTODEL	0x0040	/* Delete when match limit reached */
3917c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_AUTODIS	0x0080	/* Disable when match limit reached */
3927c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_AUTOSTOP	0x0100	/* Stop when match limit reached */
3937c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_STICKY	0x0200	/* Do not delete as part of :z */
3957c478bdstevel@tonic-gate#define	MDB_TGT_SPEC_HIDDEN	(MDB_TGT_SPEC_INTERNAL | MDB_TGT_SPEC_SILENT)
3977c478bdstevel@tonic-gatetypedef struct mdb_tgt_spec_desc {
3987c478bdstevel@tonic-gate	int spec_id;			/* Event specifier id (VID) */
3997c478bdstevel@tonic-gate	uint_t spec_flags;		/* Flags (see above) */
4007c478bdstevel@tonic-gate	uint_t spec_hits;		/* Count of number of times matched */
4017c478bdstevel@tonic-gate	uint_t spec_limit;		/* Limit on number of times matched */
4027c478bdstevel@tonic-gate	int spec_state;			/* State (see above) */
4037c478bdstevel@tonic-gate	int spec_errno;			/* Last error code (if IDLE or ERROR) */
4047c478bdstevel@tonic-gate	uintptr_t spec_base;		/* Start of affected memory region */
4057c478bdstevel@tonic-gate	size_t spec_size;		/* Size of affected memory region */
4067c478bdstevel@tonic-gate	void *spec_data;		/* Callback private data */
4077c478bdstevel@tonic-gate} mdb_tgt_spec_desc_t;
4107c478bdstevel@tonic-gate * The target provides functions to convert a VID into the private data pointer,
4117c478bdstevel@tonic-gate * or a complete description of the event specifier and its state.
4127c478bdstevel@tonic-gate */
4137c478bdstevel@tonic-gateextern void *mdb_tgt_vespec_data(mdb_tgt_t *, int);
4147c478bdstevel@tonic-gateextern char *mdb_tgt_vespec_info(mdb_tgt_t *, int,
4157c478bdstevel@tonic-gate    mdb_tgt_spec_desc_t *, char *, size_t);
4187c478bdstevel@tonic-gate * The common target layer provides functions to iterate over the list of
4197c478bdstevel@tonic-gate * registered event specifiers, modify or disable them, and delete them.
4207c478bdstevel@tonic-gate */
4217c478bdstevel@tonic-gateextern int mdb_tgt_vespec_iter(mdb_tgt_t *, mdb_tgt_vespec_f *, void *);
4227c478bdstevel@tonic-gateextern int mdb_tgt_vespec_modify(mdb_tgt_t *, int, uint_t, uint_t, void *);
4237c478bdstevel@tonic-gateextern int mdb_tgt_vespec_enable(mdb_tgt_t *, int);
4247c478bdstevel@tonic-gateextern int mdb_tgt_vespec_disable(mdb_tgt_t *, int);
4257c478bdstevel@tonic-gateextern int mdb_tgt_vespec_delete(mdb_tgt_t *, int);
4287c478bdstevel@tonic-gate * The mdb_tgt_add_* functions are used to add software event specifiers to the
4297c478bdstevel@tonic-gate * target.  The caller provides a bitmask of flags (spec_flags above), callback
4307c478bdstevel@tonic-gate * function pointer, and callback data as arguments.  Whenever a matching event
4317c478bdstevel@tonic-gate * is detected, a software event callback function is invoked.  The callback
4327c478bdstevel@tonic-gate * receives a pointer to the target, the VID of the corresponding event
4337c478bdstevel@tonic-gate * specifier, and a private data pointer as arguments.  If no callback is
4347c478bdstevel@tonic-gate * desired, the caller can specify a pointer to the no_se_f default callback.
4357c478bdstevel@tonic-gate * Unlike other target layer functions, the mdb_tgt_add_* interfaces return the
4367c478bdstevel@tonic-gate * VID of the new event (which may be positive or negative), or 0 if the new
4377c478bdstevel@tonic-gate * event could not be created.
4387c478bdstevel@tonic-gate */
4397c478bdstevel@tonic-gatetypedef void mdb_tgt_se_f(mdb_tgt_t *, int, void *);
4407c478bdstevel@tonic-gateextern void no_se_f(mdb_tgt_t *, int, void *);
4437c478bdstevel@tonic-gate * Breakpoints can be set at a specified virtual address or using MDB's
4447c478bdstevel@tonic-gate * symbol notation:
4457c478bdstevel@tonic-gate */
4467c478bdstevel@tonic-gateextern int mdb_tgt_add_vbrkpt(mdb_tgt_t *, uintptr_t,
4477c478bdstevel@tonic-gate    int, mdb_tgt_se_f *, void *);
4497c478bdstevel@tonic-gateextern int mdb_tgt_add_sbrkpt(mdb_tgt_t *, const char *,
4507c478bdstevel@tonic-gate    int, mdb_tgt_se_f *, void *);
4537c478bdstevel@tonic-gate * Watchpoints can be set at physical, virtual, or I/O port addresses for any
4547c478bdstevel@tonic-gate * combination of read, write, or execute operations.
4557c478bdstevel@tonic-gate */
4567c478bdstevel@tonic-gate#define	MDB_TGT_WA_R		0x1	/* Read watchpoint */
4577c478bdstevel@tonic-gate#define	MDB_TGT_WA_W		0x2	/* Write watchpoint */
4587c478bdstevel@tonic-gate#define	MDB_TGT_WA_X		0x4	/* Execute watchpoint */
4607c478bdstevel@tonic-gate#define	MDB_TGT_WA_RWX	(MDB_TGT_WA_R | MDB_TGT_WA_W | MDB_TGT_WA_X)
4627c478bdstevel@tonic-gateextern int mdb_tgt_add_pwapt(mdb_tgt_t *, physaddr_t, size_t, uint_t,
4637c478bdstevel@tonic-gate    int, mdb_tgt_se_f *, void *);
4657c478bdstevel@tonic-gateextern int mdb_tgt_add_vwapt(mdb_tgt_t *, uintptr_t, size_t, uint_t,
4667c478bdstevel@tonic-gate    int, mdb_tgt_se_f *, void *);
4687c478bdstevel@tonic-gateextern int mdb_tgt_add_iowapt(mdb_tgt_t *, uintptr_t, size_t, uint_t,
4697c478bdstevel@tonic-gate    int, mdb_tgt_se_f *, void *);
4727c478bdstevel@tonic-gate * For user process debugging, tracepoints can be set on entry or exit from
4737c478bdstevel@tonic-gate * a system call, or on receipt of a software signal or fault.
4747c478bdstevel@tonic-gate */
4757c478bdstevel@tonic-gateextern int mdb_tgt_add_sysenter(mdb_tgt_t *, int, int, mdb_tgt_se_f *, void *);
4767c478bdstevel@tonic-gateextern int mdb_tgt_add_sysexit(mdb_tgt_t *, int, int, mdb_tgt_se_f *, void *);
4777c478bdstevel@tonic-gateextern int mdb_tgt_add_signal(mdb_tgt_t *, int, int, mdb_tgt_se_f *, void *);
4787c478bdstevel@tonic-gateextern int mdb_tgt_add_fault(mdb_tgt_t *, int, int, mdb_tgt_se_f *, void *);
4817c478bdstevel@tonic-gate * Machine Register Interface
4827c478bdstevel@tonic-gate *
4837c478bdstevel@tonic-gate * The machine registers for a given thread can be manipulated using the
4847c478bdstevel@tonic-gate * getareg and putareg interface; the caller must know the naming convention
4857c478bdstevel@tonic-gate * for registers for the given target architecture.  For the purposes of
4867c478bdstevel@tonic-gate * this interface, we declare the register container to be the largest
4877c478bdstevel@tonic-gate * current integer container.
4887c478bdstevel@tonic-gate */
4907c478bdstevel@tonic-gatetypedef uint64_t mdb_tgt_reg_t;
4927c478bdstevel@tonic-gateextern int mdb_tgt_getareg(mdb_tgt_t *, mdb_tgt_tid_t,
4937c478bdstevel@tonic-gate	const char *, mdb_tgt_reg_t *);
4957c478bdstevel@tonic-gateextern int mdb_tgt_putareg(mdb_tgt_t *, mdb_tgt_tid_t,
4967c478bdstevel@tonic-gate	const char *, mdb_tgt_reg_t);
4997c478bdstevel@tonic-gate * Stack Interface
5007c478bdstevel@tonic-gate *
5017c478bdstevel@tonic-gate * The target stack interface provides the ability to iterate backward through
5027c478bdstevel@tonic-gate * the frames of an execution stack.  For the purposes of this interface, the
5037c478bdstevel@tonic-gate * mdb_tgt_gregset (general purpose register set) is an opaque type: there must
5047c478bdstevel@tonic-gate * be an implicit contract between the target implementation and any debugger
5057c478bdstevel@tonic-gate * modules that must interpret the contents of this structure.  The callback
5067c478bdstevel@tonic-gate * function is provided with the only elements of a stack frame which we can
5077c478bdstevel@tonic-gate * reasonably abstract: the virtual address corresponding to a program counter
5087c478bdstevel@tonic-gate * value, and an array of arguments passed to the function call represented by
5097c478bdstevel@tonic-gate * this frame.  The rest of the frame is presumed to be contained within the
5107c478bdstevel@tonic-gate * mdb_tgt_gregset_t, and is architecture-specific.
5117c478bdstevel@tonic-gate */
5137c478bdstevel@tonic-gatetypedef struct mdb_tgt_gregset mdb_tgt_gregset_t;
5157c478bdstevel@tonic-gatetypedef int mdb_tgt_stack_f(void *, uintptr_t, uint_t, const long *,
5167c478bdstevel@tonic-gate	const mdb_tgt_gregset_t *);
5177c478bdstevel@tonic-gatetypedef int mdb_tgt_stack_iter_f(mdb_tgt_t *, const mdb_tgt_gregset_t *,
5187c478bdstevel@tonic-gate	mdb_tgt_stack_f *, void *);
5207c478bdstevel@tonic-gateextern mdb_tgt_stack_iter_f mdb_tgt_stack_iter;
5237c478bdstevel@tonic-gate * External Data Interface
5247c478bdstevel@tonic-gate *
5257c478bdstevel@tonic-gate * The external data interface provides each target with the ability to export
5267c478bdstevel@tonic-gate * a set of named buffers that contain data which is associated with the
5277c478bdstevel@tonic-gate * target, but is somehow not accessible through one of its address spaces and
5287c478bdstevel@tonic-gate * does not correspond to a machine register.  A process credential is an
5297c478bdstevel@tonic-gate * example of such a buffer: the credential is associated with the given
5307c478bdstevel@tonic-gate * process, but is stored in the kernel (not the process's address space) and
5317c478bdstevel@tonic-gate * thus is not accessible through any other target interface.  Since it is
5327c478bdstevel@tonic-gate * exported via /proc, the user process target can export this information as a
5337c478bdstevel@tonic-gate * named buffer for target-specific dcmds to consume.
5347c478bdstevel@tonic-gate */
5367c478bdstevel@tonic-gatetypedef int mdb_tgt_xdata_f(void *, const char *, const char *, size_t);
5387c478bdstevel@tonic-gateextern int mdb_tgt_xdata_iter(mdb_tgt_t *, mdb_tgt_xdata_f *, void *);
5397c478bdstevel@tonic-gateextern ssize_t mdb_tgt_getxdata(mdb_tgt_t *, const char *, void *, size_t);
5417c478bdstevel@tonic-gate#ifdef	__cplusplus
5457c478bdstevel@tonic-gate#endif	/* _MDB_TARGET_H */