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