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, Version 1.0 only 6 * (the "License"). You may not use this file except in compliance 7 * with the License. 8 * 9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10 * or http://www.opensolaris.org/os/licensing. 11 * See the License for the specific language governing permissions 12 * and limitations under the License. 13 * 14 * When distributing Covered Code, include this CDDL HEADER in each 15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16 * If applicable, add the following below this CDDL HEADER, with the 17 * fields enclosed by brackets "[]" replaced with your own identifying 18 * information: Portions Copyright [yyyy] [name of copyright owner] 19 * 20 * CDDL HEADER END 21 */ 22 /* 23 * Copyright 2005 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 27 #ifndef _MDB_MODAPI_H 28 #define _MDB_MODAPI_H 29 30 #pragma ident "%Z%%M% %I% %E% SMI" 31 32 /* 33 * MDB Module API 34 * 35 * The debugger provides a set of interfaces for use in writing loadable 36 * debugger modules. Modules that call functions not listed in this header 37 * file may not be compatible with future versions of the debugger. 38 */ 39 40 #include <sys/types.h> 41 #include <gelf.h> 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /* 48 * Make sure that NULL, TRUE, FALSE, MIN, and MAX have the usual definitions 49 * so module writers can depend on these macros and defines. 50 */ 51 #ifndef NULL 52 #if defined(_LP64) && !defined(__cplusplus) 53 #define NULL 0L 54 #else 55 #define NULL 0 56 #endif 57 #endif 58 59 #ifndef TRUE 60 #define TRUE 1 61 #endif 62 63 #ifndef FALSE 64 #define FALSE 0 65 #endif 66 67 #ifndef MIN 68 #define MIN(x, y) ((x) < (y) ? (x) : (y)) 69 #endif 70 71 #ifndef MAX 72 #define MAX(x, y) ((x) > (y) ? (x) : (y)) 73 #endif 74 75 #define MDB_API_VERSION 3 /* Current API version number */ 76 77 /* 78 * Debugger command function flags: 79 */ 80 #define DCMD_ADDRSPEC 0x01 /* Dcmd invoked with explicit address */ 81 #define DCMD_LOOP 0x02 /* Dcmd invoked in loop with ,cnt syntax */ 82 #define DCMD_LOOPFIRST 0x04 /* Dcmd invoked as first iteration of LOOP */ 83 #define DCMD_PIPE 0x08 /* Dcmd invoked with input from pipe */ 84 #define DCMD_PIPE_OUT 0x10 /* Dcmd invoked with output set to pipe */ 85 86 #define DCMD_HDRSPEC(fl) (((fl) & DCMD_LOOPFIRST) || !((fl) & DCMD_LOOP)) 87 88 /* 89 * Debugger command function return values: 90 */ 91 #define DCMD_OK 0 /* Dcmd completed successfully */ 92 #define DCMD_ERR 1 /* Dcmd failed due to an error */ 93 #define DCMD_USAGE 2 /* Dcmd usage error; abort and print usage */ 94 #define DCMD_NEXT 3 /* Invoke next dcmd in precedence list */ 95 #define DCMD_ABORT 4 /* Dcmd failed; abort current loop or pipe */ 96 97 #define OFFSETOF(s, m) (size_t)(&(((s *)0)->m)) 98 99 extern int mdb_prop_postmortem; /* Are we looking at a static dump? */ 100 extern int mdb_prop_kernel; /* Are we looking at a kernel? */ 101 102 typedef enum { 103 MDB_TYPE_STRING, /* a_un.a_str is valid */ 104 MDB_TYPE_IMMEDIATE, /* a_un.a_val is valid */ 105 MDB_TYPE_CHAR /* a_un.a_char is valid */ 106 } mdb_type_t; 107 108 typedef struct mdb_arg { 109 mdb_type_t a_type; 110 union { 111 const char *a_str; 112 uintmax_t a_val; 113 char a_char; 114 } a_un; 115 } mdb_arg_t; 116 117 typedef int mdb_dcmd_f(uintptr_t, uint_t, int, const mdb_arg_t *); 118 119 typedef struct mdb_dcmd { 120 const char *dc_name; /* Command name */ 121 const char *dc_usage; /* Usage message (optional) */ 122 const char *dc_descr; /* Description */ 123 mdb_dcmd_f *dc_funcp; /* Command function */ 124 void (*dc_help)(void); /* Command help function (or NULL) */ 125 } mdb_dcmd_t; 126 127 #define WALK_ERR -1 /* Walk fatal error (terminate walk) */ 128 #define WALK_NEXT 0 /* Walk should continue to next step */ 129 #define WALK_DONE 1 /* Walk is complete (no errors) */ 130 131 typedef int (*mdb_walk_cb_t)(uintptr_t, const void *, void *); 132 133 typedef struct mdb_walk_state { 134 mdb_walk_cb_t walk_callback; /* Callback to issue */ 135 void *walk_cbdata; /* Callback private data */ 136 uintptr_t walk_addr; /* Current address */ 137 void *walk_data; /* Walk private data */ 138 void *walk_arg; /* Walk private argument */ 139 const void *walk_layer; /* Data from underlying layer */ 140 } mdb_walk_state_t; 141 142 typedef struct mdb_walker { 143 const char *walk_name; /* Walk type name */ 144 const char *walk_descr; /* Walk description */ 145 int (*walk_init)(mdb_walk_state_t *); /* Walk constructor */ 146 int (*walk_step)(mdb_walk_state_t *); /* Walk iterator */ 147 void (*walk_fini)(mdb_walk_state_t *); /* Walk destructor */ 148 void *walk_init_arg; /* Walk constructor argument */ 149 } mdb_walker_t; 150 151 typedef struct mdb_modinfo { 152 ushort_t mi_dvers; /* Debugger version number */ 153 const mdb_dcmd_t *mi_dcmds; /* NULL-terminated list of dcmds */ 154 const mdb_walker_t *mi_walkers; /* NULL-terminated list of walks */ 155 } mdb_modinfo_t; 156 157 typedef struct mdb_bitmask { 158 const char *bm_name; /* String name to print */ 159 u_longlong_t bm_mask; /* Mask for bits */ 160 u_longlong_t bm_bits; /* Result required for value & mask */ 161 } mdb_bitmask_t; 162 163 typedef struct mdb_pipe { 164 uintptr_t *pipe_data; /* Array of pipe values */ 165 size_t pipe_len; /* Array length */ 166 } mdb_pipe_t; 167 168 extern int mdb_pwalk(const char *, mdb_walk_cb_t, void *, uintptr_t); 169 extern int mdb_walk(const char *, mdb_walk_cb_t, void *); 170 171 extern int mdb_pwalk_dcmd(const char *, const char *, 172 int, const mdb_arg_t *, uintptr_t); 173 174 extern int mdb_walk_dcmd(const char *, const char *, int, const mdb_arg_t *); 175 176 extern int mdb_layered_walk(const char *, mdb_walk_state_t *); 177 178 extern int mdb_call_dcmd(const char *, uintptr_t, 179 uint_t, int, const mdb_arg_t *); 180 181 extern int mdb_add_walker(const mdb_walker_t *); 182 extern int mdb_remove_walker(const char *); 183 184 extern ssize_t mdb_vread(void *, size_t, uintptr_t); 185 extern ssize_t mdb_vwrite(const void *, size_t, uintptr_t); 186 187 extern ssize_t mdb_fread(void *, size_t, uintptr_t); 188 extern ssize_t mdb_fwrite(const void *, size_t, uintptr_t); 189 190 extern ssize_t mdb_pread(void *, size_t, uint64_t); 191 extern ssize_t mdb_pwrite(const void *, size_t, uint64_t); 192 193 extern ssize_t mdb_readstr(char *, size_t, uintptr_t); 194 extern ssize_t mdb_writestr(const char *, uintptr_t); 195 196 extern ssize_t mdb_readsym(void *, size_t, const char *); 197 extern ssize_t mdb_writesym(const void *, size_t, const char *); 198 199 extern ssize_t mdb_readvar(void *, const char *); 200 extern ssize_t mdb_writevar(const void *, const char *); 201 202 #define MDB_SYM_NAMLEN 1024 /* Recommended max name len */ 203 204 #define MDB_SYM_FUZZY 0 /* Match closest address */ 205 #define MDB_SYM_EXACT 1 /* Match exact address only */ 206 207 #define MDB_OBJ_EXEC ((const char *)0L) /* Primary executable file */ 208 #define MDB_OBJ_RTLD ((const char *)1L) /* Run-time link-editor */ 209 #define MDB_OBJ_EVERY ((const char *)-1L) /* All known symbols */ 210 211 extern int mdb_lookup_by_name(const char *, GElf_Sym *); 212 extern int mdb_lookup_by_obj(const char *, const char *, GElf_Sym *); 213 extern int mdb_lookup_by_addr(uintptr_t, uint_t, char *, size_t, GElf_Sym *); 214 215 #define MDB_OPT_SETBITS 1 /* Set specified flag bits */ 216 #define MDB_OPT_CLRBITS 2 /* Clear specified flag bits */ 217 #define MDB_OPT_STR 3 /* const char * argument */ 218 #define MDB_OPT_UINTPTR 4 /* uintptr_t argument */ 219 #define MDB_OPT_UINT64 5 /* uint64_t argument */ 220 #define MDB_OPT_UINTPTR_SET 6 /* boolean_t+uintptr_t args */ 221 222 extern int mdb_getopts(int, const mdb_arg_t *, ...); 223 224 extern u_longlong_t mdb_strtoull(const char *); 225 226 #define UM_NOSLEEP 0x0 /* Do not call failure handler; may fail */ 227 #define UM_SLEEP 0x1 /* Can block for memory; will always succeed */ 228 #define UM_GC 0x2 /* Garbage-collect this block automatically */ 229 230 extern void *mdb_alloc(size_t, uint_t); 231 extern void *mdb_zalloc(size_t, uint_t); 232 extern void mdb_free(void *, size_t); 233 234 extern size_t mdb_snprintf(char *, size_t, const char *, ...); 235 extern void mdb_printf(const char *, ...); 236 extern void mdb_warn(const char *, ...); 237 extern void mdb_flush(void); 238 239 extern void mdb_nhconvert(void *, const void *, size_t); 240 241 #define MDB_DUMP_RELATIVE 0x0001 /* Start numbering at 0 */ 242 #define MDB_DUMP_ALIGN 0x0002 /* Enforce paragraph alignment */ 243 #define MDB_DUMP_PEDANT 0x0004 /* Full-width addresses */ 244 #define MDB_DUMP_ASCII 0x0008 /* Display ASCII values */ 245 #define MDB_DUMP_HEADER 0x0010 /* Display a header */ 246 #define MDB_DUMP_TRIM 0x0020 /* Trim at boundaries */ 247 #define MDB_DUMP_SQUISH 0x0040 /* Eliminate redundant lines */ 248 #define MDB_DUMP_NEWDOT 0x0080 /* Update dot when done */ 249 #define MDB_DUMP_ENDIAN 0x0100 /* Adjust for endianness */ 250 #define MDB_DUMP_WIDTH(x) ((((x) - 1) & 0xf) << 16) /* paragraphs/line */ 251 #define MDB_DUMP_GROUP(x) ((((x) - 1) & 0xff) << 20) /* bytes/group */ 252 253 typedef ssize_t (*mdb_dumpptr_cb_t)(void *, size_t, uintptr_t, void *); 254 typedef ssize_t (*mdb_dump64_cb_t)(void *, size_t, uint64_t, void *); 255 256 extern int mdb_dumpptr(uintptr_t, size_t, uint_t, mdb_dumpptr_cb_t, void *); 257 extern int mdb_dump64(uint64_t, uint64_t, uint_t, mdb_dump64_cb_t, void *); 258 259 extern const char *mdb_one_bit(int, int, int); 260 extern const char *mdb_inval_bits(int, int, int); 261 262 extern ulong_t mdb_inc_indent(ulong_t); 263 extern ulong_t mdb_dec_indent(ulong_t); 264 265 extern int mdb_eval(const char *); 266 extern void mdb_set_dot(uintmax_t); 267 extern uintmax_t mdb_get_dot(void); 268 269 extern void mdb_get_pipe(mdb_pipe_t *); 270 extern void mdb_set_pipe(const mdb_pipe_t *); 271 272 extern ssize_t mdb_get_xdata(const char *, void *, size_t); 273 274 #define MDB_STATE_IDLE 0 /* Target is idle (not running yet) */ 275 #define MDB_STATE_RUNNING 1 /* Target is currently executing */ 276 #define MDB_STATE_STOPPED 2 /* Target is stopped */ 277 #define MDB_STATE_UNDEAD 3 /* Target is undead (zombie) */ 278 #define MDB_STATE_DEAD 4 /* Target is dead (core dump) */ 279 #define MDB_STATE_LOST 5 /* Target lost by debugger */ 280 281 extern int mdb_get_state(void); 282 283 #define MDB_CALLBACK_STCHG 1 284 #define MDB_CALLBACK_PROMPT 2 285 286 typedef void (*mdb_callback_f)(void *); 287 288 extern void *mdb_callback_add(int, mdb_callback_f, void *); 289 extern void mdb_callback_remove(void *); 290 291 extern char *strcat(char *, const char *); 292 extern char *strcpy(char *, const char *); 293 extern char *strncpy(char *, const char *, size_t); 294 295 /* Need to be consistent with <string.h> C++ definitions */ 296 #if __cplusplus >= 199711L 297 extern const char *strchr(const char *, int); 298 #ifndef _STRCHR_INLINE 299 #define _STRCHR_INLINE 300 extern "C++" { 301 inline char *strchr(char *__s, int __c) { 302 return (char *)strchr((const char *)__s, __c); 303 } 304 } 305 #endif /* _STRCHR_INLINE */ 306 extern const char *strrchr(const char *, int); 307 #ifndef _STRRCHR_INLINE 308 #define _STRRCHR_INLINE 309 extern "C++" { 310 inline char *strrchr(char *__s, int __c) { 311 return (char *)strrchr((const char *)__s, __c); 312 } 313 } 314 #endif /* _STRRCHR_INLINE */ 315 extern const char *strstr(const char *, const char *); 316 #ifndef _STRSTR_INLINE 317 #define _STRSTR_INLINE 318 extern "C++" { 319 inline char *strstr(char *__s1, const char *__s2) { 320 return (char *)strstr((const char *)__s1, __s2); 321 } 322 } 323 #endif /* _STRSTR_INLINE */ 324 #else 325 extern char *strchr(const char *, int); 326 extern char *strrchr(const char *, int); 327 extern char *strstr(const char *, const char *); 328 #endif /* __cplusplus >= 199711L */ 329 330 extern int strcmp(const char *, const char *); 331 extern int strncmp(const char *, const char *, size_t); 332 extern int strcasecmp(const char *, const char *); 333 extern int strncasecmp(const char *, const char *, size_t); 334 335 extern size_t strlen(const char *); 336 337 extern int bcmp(const void *, const void *, size_t); 338 extern void bcopy(const void *, void *, size_t); 339 extern void bzero(void *, size_t); 340 341 extern void *memcpy(void *, const void *, size_t); 342 extern void *memmove(void *, const void *, size_t); 343 extern int memcmp(const void *, const void *, size_t); 344 /* Need to be consistent with <string.h> C++ definitions */ 345 #if __cplusplus >= 199711L 346 extern const void *memchr(const void *, int, size_t); 347 #ifndef _MEMCHR_INLINE 348 #define _MEMCHR_INLINE 349 extern "C++" { 350 inline void *memchr(void * __s, int __c, size_t __n) { 351 return (void *)memchr((const void *)__s, __c, __n); 352 } 353 } 354 #endif /* _MEMCHR_INLINE */ 355 #else 356 extern void *memchr(const void *, int, size_t); 357 #endif /* __cplusplus >= 199711L */ 358 extern void *memset(void *, int, size_t); 359 extern void *memccpy(void *, const void *, int, size_t); 360 361 extern void *bsearch(const void *, const void *, size_t, size_t, 362 int (*)(const void *, const void *)); 363 364 extern void qsort(void *, size_t, size_t, 365 int (*)(const void *, const void *)); 366 367 #ifdef __cplusplus 368 } 369 #endif 370 371 #endif /* _MDB_MODAPI_H */ 372