xref: /illumos-gate/usr/src/cmd/mdb/common/mdb/mdb_target_impl.h (revision a48fdbef3a00fbebe91cb7211c789eff0e39c957)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 /*
22  * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
23  * Use is subject to license terms.
24  */
25 /*
26  * Copyright (c) 2018, Joyent, Inc.  All rights reserved.
27  * Copyright 2024 Oxide Computer Company
28  */
29 
30 #ifndef	_MDB_TARGET_IMPL_H
31 #define	_MDB_TARGET_IMPL_H
32 
33 #include <mdb/mdb_target.h>
34 #include <mdb/mdb_module.h>
35 #include <mdb/mdb_list.h>
36 #include <mdb/mdb_gelf.h>
37 #include <sys/auxv.h>
38 
39 #ifdef	__cplusplus
40 extern "C" {
41 #endif
42 
43 #ifdef _MDB
44 
45 /*
46  * Target Operations
47  *
48  * This ops vector implements the set of primitives which can be used by the
49  * debugger to interact with the target, and encompasses most of the calls
50  * found in <mdb/mdb_target.h>.  The remainder of the target interface is
51  * implemented by common code that invokes these primitives or manipulates
52  * the common target structures directly.
53  */
54 
55 typedef struct mdb_tgt_ops {
56 	int (*t_setflags)(mdb_tgt_t *, int);
57 	int (*t_setcontext)(mdb_tgt_t *, void *);
58 
59 	void (*t_activate)(mdb_tgt_t *);
60 	void (*t_deactivate)(mdb_tgt_t *);
61 	void (*t_periodic)(mdb_tgt_t *);
62 	void (*t_destroy)(mdb_tgt_t *);
63 
64 	const char *(*t_name)(mdb_tgt_t *);
65 	const char *(*t_isa)(mdb_tgt_t *);
66 	const char *(*t_platform)(mdb_tgt_t *);
67 	int (*t_uname)(mdb_tgt_t *, struct utsname *);
68 	int (*t_dmodel)(mdb_tgt_t *);
69 
70 	ssize_t (*t_aread)(mdb_tgt_t *,
71 	    mdb_tgt_as_t, void *, size_t, mdb_tgt_addr_t);
72 
73 	ssize_t (*t_awrite)(mdb_tgt_t *,
74 	    mdb_tgt_as_t, const void *, size_t, mdb_tgt_addr_t);
75 
76 	ssize_t (*t_vread)(mdb_tgt_t *, void *, size_t, uintptr_t);
77 	ssize_t (*t_vwrite)(mdb_tgt_t *, const void *, size_t, uintptr_t);
78 	ssize_t (*t_pread)(mdb_tgt_t *, void *, size_t, physaddr_t);
79 	ssize_t (*t_pwrite)(mdb_tgt_t *, const void *, size_t, physaddr_t);
80 	ssize_t (*t_fread)(mdb_tgt_t *, void *, size_t, uintptr_t);
81 	ssize_t (*t_fwrite)(mdb_tgt_t *, const void *, size_t, uintptr_t);
82 	ssize_t (*t_ioread)(mdb_tgt_t *, void *, size_t, uintptr_t);
83 	ssize_t (*t_iowrite)(mdb_tgt_t *, const void *, size_t, uintptr_t);
84 
85 	int (*t_vtop)(mdb_tgt_t *, mdb_tgt_as_t, uintptr_t, physaddr_t *);
86 
87 	int (*t_lookup_by_name)(mdb_tgt_t *,
88 	    const char *, const char *, GElf_Sym *, mdb_syminfo_t *);
89 
90 	int (*t_lookup_by_addr)(mdb_tgt_t *,
91 	    uintptr_t, uint_t, char *, size_t, GElf_Sym *, mdb_syminfo_t *);
92 
93 	int (*t_symbol_iter)(mdb_tgt_t *,
94 	    const char *, uint_t, uint_t, mdb_tgt_sym_f *, void *);
95 
96 	int (*t_mapping_iter)(mdb_tgt_t *, mdb_tgt_map_f *, void *);
97 	int (*t_object_iter)(mdb_tgt_t *, mdb_tgt_map_f *, void *);
98 
99 	const mdb_map_t *(*t_addr_to_map)(mdb_tgt_t *, uintptr_t);
100 	const mdb_map_t *(*t_name_to_map)(mdb_tgt_t *, const char *);
101 	struct ctf_file *(*t_addr_to_ctf)(mdb_tgt_t *, uintptr_t);
102 	struct ctf_file *(*t_name_to_ctf)(mdb_tgt_t *, const char *);
103 
104 	int (*t_status)(mdb_tgt_t *, mdb_tgt_status_t *);
105 	int (*t_run)(mdb_tgt_t *, int, const struct mdb_arg *);
106 	int (*t_step)(mdb_tgt_t *, mdb_tgt_status_t *);
107 	int (*t_step_out)(mdb_tgt_t *, uintptr_t *);
108 	int (*t_next)(mdb_tgt_t *, uintptr_t *);
109 	int (*t_cont)(mdb_tgt_t *, mdb_tgt_status_t *);
110 	int (*t_signal)(mdb_tgt_t *, int);
111 
112 	int (*t_add_vbrkpt)(mdb_tgt_t *, uintptr_t,
113 	    int, mdb_tgt_se_f *, void *);
114 	int (*t_add_sbrkpt)(mdb_tgt_t *, const char *,
115 	    int, mdb_tgt_se_f *, void *);
116 
117 	int (*t_add_pwapt)(mdb_tgt_t *, physaddr_t, size_t, uint_t,
118 	    int, mdb_tgt_se_f *, void *);
119 	int (*t_add_vwapt)(mdb_tgt_t *, uintptr_t, size_t, uint_t,
120 	    int, mdb_tgt_se_f *, void *);
121 	int (*t_add_iowapt)(mdb_tgt_t *, uintptr_t, size_t, uint_t,
122 	    int, mdb_tgt_se_f *, void *);
123 
124 	int (*t_add_sysenter)(mdb_tgt_t *, int, int, mdb_tgt_se_f *, void *);
125 	int (*t_add_sysexit)(mdb_tgt_t *, int, int, mdb_tgt_se_f *, void *);
126 	int (*t_add_signal)(mdb_tgt_t *, int, int, mdb_tgt_se_f *, void *);
127 	int (*t_add_fault)(mdb_tgt_t *, int, int, mdb_tgt_se_f *, void *);
128 
129 	int (*t_getareg)(mdb_tgt_t *, mdb_tgt_tid_t, const char *,
130 	    mdb_tgt_reg_t *);
131 	int (*t_putareg)(mdb_tgt_t *, mdb_tgt_tid_t, const char *,
132 	    mdb_tgt_reg_t);
133 
134 	int (*t_stack_iter)(mdb_tgt_t *, const mdb_tgt_gregset_t *,
135 	    mdb_tgt_stack_f *, void *);
136 
137 	int (*t_auxv)(mdb_tgt_t *, const auxv_t **auxvp);
138 
139 	int (*t_thread_name)(mdb_tgt_t *, mdb_tgt_tid_t, char *, size_t);
140 } mdb_tgt_ops_t;
141 
142 /*
143  * Software Event Specifiers
144  *
145  * The common target layer provides support for the management of software
146  * event specifiers, used to describe conditions under which a live executing
147  * target program instance will stop and transfer control back to the debugger.
148  * Software event management design is discussed in more detail in mdb_target.c.
149  */
150 
151 struct mdb_sespec;			/* Software event specifier */
152 struct mdb_vespec;			/* Virtual event specifier */
153 
154 typedef struct mdb_se_ops {
155 	int (*se_ctor)(mdb_tgt_t *, struct mdb_sespec *, void *);
156 	void (*se_dtor)(mdb_tgt_t *, struct mdb_sespec *);
157 	char *(*se_info)(mdb_tgt_t *, struct mdb_sespec *,
158 	    struct mdb_vespec *, mdb_tgt_spec_desc_t *, char *, size_t);
159 	int (*se_secmp)(mdb_tgt_t *, struct mdb_sespec *, void *);
160 	int (*se_vecmp)(mdb_tgt_t *, struct mdb_vespec *, void *);
161 	int (*se_arm)(mdb_tgt_t *, struct mdb_sespec *);
162 	int (*se_disarm)(mdb_tgt_t *, struct mdb_sespec *);
163 	int (*se_cont)(mdb_tgt_t *, struct mdb_sespec *, mdb_tgt_status_t *);
164 	int (*se_match)(mdb_tgt_t *, struct mdb_sespec *, mdb_tgt_status_t *);
165 } mdb_se_ops_t;
166 
167 #define	T_SE_END	((void *)-1L)	/* Sentinel for end of t_matched list */
168 
169 typedef struct mdb_sespec {
170 	mdb_list_t se_selist;		/* Sespec list forward/back pointers */
171 	mdb_list_t se_velist;		/* List of layered virtual specifiers */
172 	struct mdb_sespec *se_matched;	/* Pointer to next se on matched list */
173 	const mdb_se_ops_t *se_ops;	/* Pointer to ops vector */
174 	void *se_data;			/* Private storage for ops vector */
175 	uint_t se_refs;			/* Reference count */
176 	int se_state;			/* Event specifier state */
177 	int se_errno;			/* Last error code (if error state) */
178 } mdb_sespec_t;
179 
180 typedef struct mdb_vespec {
181 	mdb_list_t ve_list;		/* Vespec list forward/back pointers */
182 	int ve_id;			/* Virtual event specifier ID (VID) */
183 	int ve_flags;			/* Flags (see mdb_target.h) */
184 	uint_t ve_refs;			/* Reference count */
185 	uint_t ve_hits;			/* Count of number of times matched */
186 	uint_t ve_limit;		/* Limit on number of times matched */
187 	mdb_sespec_t *ve_se;		/* Backpointer to sespec */
188 	mdb_tgt_se_f *ve_callback;	/* Callback for event owner */
189 	void *ve_data;			/* Private storage for callback */
190 	void *ve_args;			/* Arguments for sespec constructor */
191 	void (*ve_dtor)(struct mdb_vespec *); /* Destructor for ve_args */
192 } mdb_vespec_t;
193 
194 /*
195  * Xdata Descriptors
196  *
197  * Each external data item (xdata) exported by the target has a corresponding
198  * descriptor associated with the target.  The descriptor provides the name
199  * and description of the data, as well as the routine which is used to
200  * retrieve the actual data or its size.
201  */
202 
203 typedef struct mdb_xdata {
204 	mdb_list_t xd_list;		/* Xdata list forward/back pointers */
205 	const char *xd_name;		/* Buffer name */
206 	const char *xd_desc;		/* Buffer description */
207 	ssize_t (*xd_copy)(mdb_tgt_t *, void *, size_t); /* Copy routine */
208 } mdb_xdata_t;
209 
210 /*
211  * Target Structure
212  *
213  * The target itself contains a few common data members, and then a pointer to
214  * the underlying ops vector and its private storage pointer.  MDB can manage
215  * multiple targets simultaneously, and the list of all constructed targets is
216  * pointed to by the mdb_t structure.
217  */
218 
219 struct mdb_tgt {
220 	mdb_list_t t_tgtlist;		/* Target list forward/back pointers */
221 	mdb_list_t t_active;		/* List of active event specifiers */
222 	mdb_list_t t_idle;		/* List of inactive event specifiers */
223 	mdb_list_t t_xdlist;		/* List of xdata descriptors */
224 	mdb_module_t *t_module;		/* Backpointer to containing module */
225 	void *t_pshandle;		/* Proc service handle (if not tgt) */
226 	const mdb_tgt_ops_t *t_ops;	/* Pointer to target ops vector */
227 	void *t_data;			/* Private storage for implementation */
228 	mdb_tgt_status_t t_status;	/* Cached target status */
229 	mdb_sespec_t *t_matched;	/* List of matched event specifiers */
230 	uint_t t_flags;			/* Mode flags (see <mdb_target.h>) */
231 	uint_t t_vecnt;			/* Total number of vespecs */
232 	int t_vepos;			/* Sequence # for next vespec id > 0 */
233 	int t_veneg;			/* Sequence # for next vespec id < 0 */
234 };
235 
236 /*
237  * Special functions which targets can use to fill ops vector slots:
238  */
239 extern long mdb_tgt_notsup();		/* Return -1, errno EMDB_TGTNOTSUP */
240 extern long mdb_tgt_hwnotsup();		/* return -1, errno EMDB_TGTHWNOTSUP */
241 extern void *mdb_tgt_null();		/* Return NULL, errno EMDB_TGTNOTSUP */
242 extern long mdb_tgt_nop();		/* Return 0 for success */
243 
244 /*
245  * Utility structures for target implementations:
246  */
247 #define	MDB_TGT_R_PRIV		0x001	/* Privileged register */
248 #define	MDB_TGT_R_EXPORT	0x002	/* Export register as a variable */
249 #define	MDB_TGT_R_ALIAS		0x004	/* Alias for another register name */
250 #define	MDB_TGT_R_XREG		0x008	/* Extended register */
251 #define	MDB_TGT_R_FPS		0x010	/* Single-precision floating-point */
252 #define	MDB_TGT_R_FPD		0x020	/* Double-precision floating-point */
253 #define	MDB_TGT_R_FPQ		0x040	/* Quad-precision floating-point */
254 #define	MDB_TGT_R_FPU		0x080	/* FPU control/status register */
255 #define	MDB_TGT_R_RDONLY	0x100	/* Register is read-only */
256 #define	MDB_TGT_R_32		0x200	/* 32-bit version of register */
257 #define	MDB_TGT_R_16		0x400	/* 16-bit version of register */
258 #define	MDB_TGT_R_8H		0x800	/* upper half of a 16-bit reg */
259 #define	MDB_TGT_R_8L		0x1000	/* lower half of a 16-bit reg */
260 
261 #define	MDB_TGT_R_IS_FP(f)	((f) & 0xf0) /* Test MDB_TGT_R_FP* bits */
262 
263 #define	MDB_TGT_R_NVAL(n, f)	((((ulong_t)(n)) << 16UL) | (f))
264 #define	MDB_TGT_R_NUM(v)	(((v) >> 16) & 0xffff)
265 #define	MDB_TGT_R_FLAGS(v)	((v) & 0xffff)
266 
267 typedef struct mdb_tgt_regdesc {
268 	const char *rd_name;		/* Register string name */
269 	ushort_t rd_num;		/* Register index number */
270 	ushort_t rd_flags;		/* Register flags (see above) */
271 } mdb_tgt_regdesc_t;
272 
273 /*
274  * Utility functions for target implementations to use in order to simplify
275  * the implementation of various routines and to insert and delete xdata
276  * specifiers and software event specifiers.  Refer to the associated comments
277  * in mdb_target.c for more information about each function.
278  */
279 
280 extern int mdb_tgt_xdata_insert(mdb_tgt_t *, const char *, const char *,
281 	ssize_t (*)(mdb_tgt_t *, void *, size_t));
282 
283 extern int mdb_tgt_xdata_delete(mdb_tgt_t *, const char *);
284 
285 extern int mdb_tgt_sym_match(const GElf_Sym *, uint_t);
286 extern void mdb_tgt_elf_export(mdb_gelf_file_t *);
287 
288 extern int mdb_tgt_sespec_activate_one(mdb_tgt_t *t, mdb_sespec_t *);
289 extern int mdb_tgt_sespec_activate_all(mdb_tgt_t *t);
290 
291 extern void mdb_tgt_sespec_idle_one(mdb_tgt_t *t, mdb_sespec_t *, int);
292 extern void mdb_tgt_sespec_idle_all(mdb_tgt_t *t, int, int);
293 
294 extern void mdb_tgt_sespec_arm_one(mdb_tgt_t *t, mdb_sespec_t *);
295 extern void mdb_tgt_sespec_arm_all(mdb_tgt_t *t);
296 
297 extern void mdb_tgt_sespec_idle_one(mdb_tgt_t *t, mdb_sespec_t *, int);
298 extern void mdb_tgt_sespec_idle_all(mdb_tgt_t *t, int, int);
299 
300 extern void mdb_tgt_sespec_prune_one(mdb_tgt_t *t, mdb_sespec_t *);
301 extern void mdb_tgt_sespec_prune_all(mdb_tgt_t *t);
302 
303 extern mdb_sespec_t *mdb_tgt_sespec_insert(mdb_tgt_t *,
304     const mdb_se_ops_t *, mdb_list_t *);
305 
306 extern mdb_sespec_t *mdb_tgt_sespec_lookup_active(mdb_tgt_t *,
307     const mdb_se_ops_t *, void *);
308 
309 extern mdb_sespec_t *mdb_tgt_sespec_lookup_idle(mdb_tgt_t *,
310     const mdb_se_ops_t *, void *);
311 
312 extern void mdb_tgt_sespec_hold(mdb_tgt_t *, mdb_sespec_t *);
313 extern void mdb_tgt_sespec_rele(mdb_tgt_t *, mdb_sespec_t *);
314 
315 extern void mdb_tgt_sespec_prune_one(mdb_tgt_t *t, mdb_sespec_t *);
316 extern void mdb_tgt_sespec_prune_all(mdb_tgt_t *t);
317 
318 extern mdb_sespec_t *mdb_tgt_sespec_insert(mdb_tgt_t *,
319     const mdb_se_ops_t *, mdb_list_t *);
320 
321 extern mdb_sespec_t *mdb_tgt_sespec_lookup_active(mdb_tgt_t *,
322     const mdb_se_ops_t *, void *);
323 
324 extern mdb_sespec_t *mdb_tgt_sespec_lookup_idle(mdb_tgt_t *,
325     const mdb_se_ops_t *, void *);
326 
327 extern void mdb_tgt_sespec_hold(mdb_tgt_t *, mdb_sespec_t *);
328 extern void mdb_tgt_sespec_rele(mdb_tgt_t *, mdb_sespec_t *);
329 
330 extern int mdb_tgt_vespec_insert(mdb_tgt_t *, const mdb_se_ops_t *,
331     int, mdb_tgt_se_f *, void *, void *, void (*)(mdb_vespec_t *));
332 
333 extern mdb_vespec_t *mdb_tgt_vespec_lookup(mdb_tgt_t *, int);
334 
335 extern int mdb_tgt_auxv(mdb_tgt_t *, const auxv_t **);
336 
337 extern void mdb_tgt_vespec_hold(mdb_tgt_t *, mdb_vespec_t *);
338 extern void mdb_tgt_vespec_rele(mdb_tgt_t *, mdb_vespec_t *);
339 
340 /*
341  * Utility function that target implementations can use to register dcmds,
342  * walkers, and to create named variables for registers
343  */
344 extern int mdb_tgt_register_dcmds(mdb_tgt_t *, const mdb_dcmd_t *, int);
345 extern int mdb_tgt_register_walkers(mdb_tgt_t *, const mdb_walker_t *, int);
346 extern void mdb_tgt_register_regvars(mdb_tgt_t *, const mdb_tgt_regdesc_t *,
347     const mdb_nv_disc_t *, int);
348 
349 /*
350  * Utility functions that target implementations can use to fill in the
351  * mdb_se_ops_t structure and vespec destructor.  Each software event specifier
352  * must minimally supply its own constructor, info function, and match function.
353  */
354 
355 extern void no_ve_dtor(mdb_vespec_t *);
356 extern void no_se_dtor(mdb_tgt_t *, mdb_sespec_t *);
357 
358 extern int no_se_secmp(mdb_tgt_t *, mdb_sespec_t *, void *);
359 extern int no_se_vecmp(mdb_tgt_t *, mdb_vespec_t *, void *);
360 extern int no_se_arm(mdb_tgt_t *, mdb_sespec_t *);
361 extern int no_se_disarm(mdb_tgt_t *, mdb_sespec_t *);
362 extern int no_se_cont(mdb_tgt_t *, mdb_sespec_t *, mdb_tgt_status_t *);
363 
364 /*
365  * In the initial version of MDB, the data model property is not part of the
366  * public API.  However, I am providing this as a hidden part of the ABI as
367  * one way we can handle the situation.  If this turns out to be the right
368  * decision, we can document it later without having to rev the API version.
369  */
370 #define	MDB_TGT_MODEL_UNKNOWN	0	/* Unknown data model */
371 #define	MDB_TGT_MODEL_ILP32	1	/* Target data model is ILP32 */
372 #define	MDB_TGT_MODEL_LP64	2	/* Target data model is LP64 */
373 
374 #ifdef _LP64
375 #define	MDB_TGT_MODEL_NATIVE	MDB_TGT_MODEL_LP64
376 #else
377 #define	MDB_TGT_MODEL_NATIVE	MDB_TGT_MODEL_ILP32
378 #endif
379 
380 extern int mdb_prop_datamodel;
381 
382 #endif /* _MDB */
383 
384 #ifdef	__cplusplus
385 }
386 #endif
387 
388 #endif	/* _MDB_TARGET_IMPL_H */
389