[1] | 1 | /** @file
|
---|
[21217] | 2 | * Debugger Interfaces. (VBoxDbg)
|
---|
[1] | 3 | *
|
---|
| 4 | * This header covers all external interfaces of the Debugger module.
|
---|
| 5 | * However, it does not cover the DBGF interface since that part of the
|
---|
| 6 | * VMM. Use dbgf.h for that.
|
---|
| 7 | */
|
---|
| 8 |
|
---|
| 9 | /*
|
---|
[69107] | 10 | * Copyright (C) 2006-2017 Oracle Corporation
|
---|
[1] | 11 | *
|
---|
| 12 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
| 13 | * available from http://www.virtualbox.org. This file is free software;
|
---|
| 14 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
[5999] | 15 | * General Public License (GPL) as published by the Free Software
|
---|
| 16 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
| 17 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
| 18 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
| 19 | *
|
---|
| 20 | * The contents of this file may alternatively be used under the terms
|
---|
| 21 | * of the Common Development and Distribution License Version 1.0
|
---|
| 22 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
---|
| 23 | * VirtualBox OSE distribution, in which case the provisions of the
|
---|
| 24 | * CDDL are applicable instead of those of the GPL.
|
---|
| 25 | *
|
---|
| 26 | * You may elect to license modified versions of this file under the
|
---|
| 27 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[1] | 28 | */
|
---|
| 29 |
|
---|
[3632] | 30 | #ifndef ___VBox_dbg_h
|
---|
| 31 | #define ___VBox_dbg_h
|
---|
[1] | 32 |
|
---|
| 33 | #include <VBox/cdefs.h>
|
---|
| 34 | #include <VBox/types.h>
|
---|
[35346] | 35 | #include <VBox/vmm/dbgf.h>
|
---|
[1] | 36 |
|
---|
[665] | 37 | #include <iprt/stdarg.h>
|
---|
[31966] | 38 | #ifdef IN_RING3
|
---|
| 39 | # include <iprt/err.h>
|
---|
| 40 | #endif
|
---|
[665] | 41 |
|
---|
[20374] | 42 | RT_C_DECLS_BEGIN
|
---|
[1] | 43 |
|
---|
[55881] | 44 |
|
---|
[58111] | 45 |
|
---|
| 46 | /** @defgroup grp_dbg The VirtualBox Debugger
|
---|
| 47 | * @{
|
---|
| 48 | */
|
---|
| 49 |
|
---|
[39154] | 50 | #ifdef IN_RING3 /* The debugger stuff is ring-3 only. */
|
---|
| 51 |
|
---|
[55881] | 52 | /** @defgroup grp_dbgc The Debugger Console API
|
---|
| 53 | * @{
|
---|
| 54 | */
|
---|
| 55 |
|
---|
[1] | 56 | /** @def VBOX_WITH_DEBUGGER
|
---|
[13411] | 57 | * The build is with debugger module. Test if this is defined before registering
|
---|
| 58 | * external debugger commands. This is normally defined in Config.kmk.
|
---|
[1] | 59 | */
|
---|
[12653] | 60 | #ifdef DOXYGEN_RUNNING
|
---|
| 61 | # define VBOX_WITH_DEBUGGER
|
---|
| 62 | #endif
|
---|
[1] | 63 |
|
---|
| 64 |
|
---|
| 65 | /**
|
---|
| 66 | * DBGC variable category.
|
---|
| 67 | *
|
---|
| 68 | * Used to describe an argument to a command or function and a functions
|
---|
| 69 | * return value.
|
---|
| 70 | */
|
---|
| 71 | typedef enum DBGCVARCAT
|
---|
| 72 | {
|
---|
| 73 | /** Any type is fine. */
|
---|
| 74 | DBGCVAR_CAT_ANY = 0,
|
---|
[35637] | 75 | /** Any kind of pointer or number. */
|
---|
| 76 | DBGCVAR_CAT_POINTER_NUMBER,
|
---|
| 77 | /** Any kind of pointer or number, no range. */
|
---|
| 78 | DBGCVAR_CAT_POINTER_NUMBER_NO_RANGE,
|
---|
[1] | 79 | /** Any kind of pointer. */
|
---|
| 80 | DBGCVAR_CAT_POINTER,
|
---|
| 81 | /** Any kind of pointer with no range option. */
|
---|
| 82 | DBGCVAR_CAT_POINTER_NO_RANGE,
|
---|
| 83 | /** GC pointer. */
|
---|
| 84 | DBGCVAR_CAT_GC_POINTER,
|
---|
| 85 | /** GC pointer with no range option. */
|
---|
| 86 | DBGCVAR_CAT_GC_POINTER_NO_RANGE,
|
---|
| 87 | /** Numeric argument. */
|
---|
| 88 | DBGCVAR_CAT_NUMBER,
|
---|
| 89 | /** Numeric argument with no range option. */
|
---|
| 90 | DBGCVAR_CAT_NUMBER_NO_RANGE,
|
---|
| 91 | /** String. */
|
---|
| 92 | DBGCVAR_CAT_STRING,
|
---|
| 93 | /** Symbol. */
|
---|
[5731] | 94 | DBGCVAR_CAT_SYMBOL,
|
---|
| 95 | /** Option. */
|
---|
| 96 | DBGCVAR_CAT_OPTION,
|
---|
| 97 | /** Option + string. */
|
---|
| 98 | DBGCVAR_CAT_OPTION_STRING,
|
---|
| 99 | /** Option + number. */
|
---|
| 100 | DBGCVAR_CAT_OPTION_NUMBER
|
---|
[1] | 101 | } DBGCVARCAT;
|
---|
| 102 |
|
---|
| 103 |
|
---|
| 104 | /**
|
---|
| 105 | * DBGC variable type.
|
---|
| 106 | */
|
---|
| 107 | typedef enum DBGCVARTYPE
|
---|
| 108 | {
|
---|
| 109 | /** unknown... */
|
---|
| 110 | DBGCVAR_TYPE_UNKNOWN = 0,
|
---|
| 111 | /** Flat GC pointer. */
|
---|
| 112 | DBGCVAR_TYPE_GC_FLAT,
|
---|
| 113 | /** Segmented GC pointer. */
|
---|
| 114 | DBGCVAR_TYPE_GC_FAR,
|
---|
| 115 | /** Physical GC pointer. */
|
---|
| 116 | DBGCVAR_TYPE_GC_PHYS,
|
---|
| 117 | /** Flat HC pointer. */
|
---|
| 118 | DBGCVAR_TYPE_HC_FLAT,
|
---|
| 119 | /** Physical HC pointer. */
|
---|
| 120 | DBGCVAR_TYPE_HC_PHYS,
|
---|
[41573] | 121 | /** Number. */
|
---|
| 122 | DBGCVAR_TYPE_NUMBER,
|
---|
[1] | 123 | /** String. */
|
---|
| 124 | DBGCVAR_TYPE_STRING,
|
---|
[41573] | 125 | /** Symbol. */
|
---|
[1] | 126 | DBGCVAR_TYPE_SYMBOL,
|
---|
| 127 | /** Special type used when querying symbols. */
|
---|
| 128 | DBGCVAR_TYPE_ANY
|
---|
| 129 | } DBGCVARTYPE;
|
---|
| 130 |
|
---|
[4213] | 131 | /** @todo Rename to DBGCVAR_IS_xyz. */
|
---|
| 132 |
|
---|
[1] | 133 | /** Checks if the specified variable type is of a pointer persuasion. */
|
---|
[4213] | 134 | #define DBGCVAR_ISPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && enmType <= DBGCVAR_TYPE_HC_PHYS)
|
---|
| 135 | /** Checks if the specified variable type is of a pointer persuasion. */
|
---|
[35626] | 136 | #define DBGCVAR_IS_FAR_PTR(enmType) ((enmType) == DBGCVAR_TYPE_GC_FAR)
|
---|
[1] | 137 | /** Checks if the specified variable type is of a pointer persuasion and of the guest context sort. */
|
---|
[4213] | 138 | #define DBGCVAR_ISGCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && (enmType) <= DBGCVAR_TYPE_GC_PHYS)
|
---|
[1] | 139 | /** Checks if the specified variable type is of a pointer persuasion and of the host context sort. */
|
---|
[4213] | 140 | #define DBGCVAR_ISHCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_HC_FLAT && (enmType) <= DBGCVAR_TYPE_HC_PHYS)
|
---|
[1] | 141 |
|
---|
| 142 |
|
---|
| 143 | /**
|
---|
| 144 | * DBGC variable range type.
|
---|
| 145 | */
|
---|
| 146 | typedef enum DBGCVARRANGETYPE
|
---|
| 147 | {
|
---|
| 148 | /** No range appliable or no range specified. */
|
---|
| 149 | DBGCVAR_RANGE_NONE = 0,
|
---|
| 150 | /** Number of elements. */
|
---|
| 151 | DBGCVAR_RANGE_ELEMENTS,
|
---|
| 152 | /** Number of bytes. */
|
---|
| 153 | DBGCVAR_RANGE_BYTES
|
---|
| 154 | } DBGCVARRANGETYPE;
|
---|
| 155 |
|
---|
| 156 |
|
---|
| 157 | /**
|
---|
| 158 | * Variable descriptor.
|
---|
| 159 | */
|
---|
| 160 | typedef struct DBGCVARDESC
|
---|
| 161 | {
|
---|
| 162 | /** The minimal number of times this argument may occur.
|
---|
| 163 | * Use 0 here to inidicate that the argument is optional. */
|
---|
| 164 | unsigned cTimesMin;
|
---|
[33540] | 165 | /** Maximum number of occurrences.
|
---|
[1] | 166 | * Use ~0 here to indicate infinite. */
|
---|
| 167 | unsigned cTimesMax;
|
---|
| 168 | /** Argument category. */
|
---|
| 169 | DBGCVARCAT enmCategory;
|
---|
| 170 | /** Flags, DBGCVD_FLAGS_* */
|
---|
| 171 | unsigned fFlags;
|
---|
| 172 | /** Argument name. */
|
---|
| 173 | const char *pszName;
|
---|
| 174 | /** Argument name. */
|
---|
| 175 | const char *pszDescription;
|
---|
| 176 | } DBGCVARDESC;
|
---|
| 177 | /** Pointer to an argument descriptor. */
|
---|
| 178 | typedef DBGCVARDESC *PDBGCVARDESC;
|
---|
| 179 | /** Pointer to a const argument descriptor. */
|
---|
| 180 | typedef const DBGCVARDESC *PCDBGCVARDESC;
|
---|
| 181 |
|
---|
| 182 | /** Variable descriptor flags.
|
---|
| 183 | * @{ */
|
---|
| 184 | /** Indicates that the variable depends on the previous being present. */
|
---|
[5605] | 185 | #define DBGCVD_FLAGS_DEP_PREV RT_BIT(1)
|
---|
[1] | 186 | /** @} */
|
---|
| 187 |
|
---|
| 188 |
|
---|
| 189 | /**
|
---|
| 190 | * DBGC variable.
|
---|
| 191 | */
|
---|
| 192 | typedef struct DBGCVAR
|
---|
| 193 | {
|
---|
| 194 | /** Pointer to the argument descriptor. */
|
---|
| 195 | PCDBGCVARDESC pDesc;
|
---|
| 196 | /** Pointer to the next argument. */
|
---|
| 197 | struct DBGCVAR *pNext;
|
---|
| 198 |
|
---|
| 199 | /** Argument type. */
|
---|
| 200 | DBGCVARTYPE enmType;
|
---|
| 201 | /** Type specific. */
|
---|
| 202 | union
|
---|
| 203 | {
|
---|
| 204 | /** Flat GC Address. (DBGCVAR_TYPE_GC_FLAT) */
|
---|
| 205 | RTGCPTR GCFlat;
|
---|
| 206 | /** Far (16:32) GC Address. (DBGCVAR_TYPE_GC_FAR) */
|
---|
| 207 | RTFAR32 GCFar;
|
---|
| 208 | /** Physical GC Address. (DBGCVAR_TYPE_GC_PHYS) */
|
---|
| 209 | RTGCPHYS GCPhys;
|
---|
| 210 | /** Flat HC Address. (DBGCVAR_TYPE_HC_FLAT) */
|
---|
| 211 | void *pvHCFlat;
|
---|
| 212 | /** Physical GC Address. (DBGCVAR_TYPE_HC_PHYS) */
|
---|
| 213 | RTHCPHYS HCPhys;
|
---|
| 214 | /** String. (DBGCVAR_TYPE_STRING)
|
---|
| 215 | * The basic idea is the the this is a pointer to the expression we're
|
---|
| 216 | * parsing, so no messing with freeing. */
|
---|
| 217 | const char *pszString;
|
---|
| 218 | /** Number. (DBGCVAR_TYPE_NUMBER) */
|
---|
| 219 | uint64_t u64Number;
|
---|
| 220 | } u;
|
---|
| 221 |
|
---|
| 222 | /** Range type. */
|
---|
| 223 | DBGCVARRANGETYPE enmRangeType;
|
---|
| 224 | /** Range. The use of the content depends on the enmRangeType. */
|
---|
| 225 | uint64_t u64Range;
|
---|
| 226 | } DBGCVAR;
|
---|
| 227 | /** Pointer to a command argument. */
|
---|
| 228 | typedef DBGCVAR *PDBGCVAR;
|
---|
| 229 | /** Pointer to a const command argument. */
|
---|
| 230 | typedef const DBGCVAR *PCDBGCVAR;
|
---|
| 231 |
|
---|
| 232 |
|
---|
[5731] | 233 | /**
|
---|
[4329] | 234 | * Macro for initializing a DBGC variable with defaults.
|
---|
| 235 | * The result is an unknown variable type without any range.
|
---|
| 236 | */
|
---|
| 237 | #define DBGCVAR_INIT(pVar) \
|
---|
| 238 | do { \
|
---|
| 239 | (pVar)->pDesc = NULL;\
|
---|
| 240 | (pVar)->pNext = NULL; \
|
---|
| 241 | (pVar)->enmType = DBGCVAR_TYPE_UNKNOWN; \
|
---|
| 242 | (pVar)->u.u64Number = 0; \
|
---|
| 243 | (pVar)->enmRangeType = DBGCVAR_RANGE_NONE; \
|
---|
| 244 | (pVar)->u64Range = 0; \
|
---|
| 245 | } while (0)
|
---|
| 246 |
|
---|
| 247 | /**
|
---|
| 248 | * Macro for initializing a DBGC variable with a HC physical address.
|
---|
| 249 | */
|
---|
| 250 | #define DBGCVAR_INIT_HC_PHYS(pVar, Phys) \
|
---|
| 251 | do { \
|
---|
| 252 | DBGCVAR_INIT(pVar); \
|
---|
| 253 | (pVar)->enmType = DBGCVAR_TYPE_HC_PHYS; \
|
---|
| 254 | (pVar)->u.HCPhys = (Phys); \
|
---|
| 255 | } while (0)
|
---|
| 256 |
|
---|
| 257 | /**
|
---|
| 258 | * Macro for initializing a DBGC variable with a HC flat address.
|
---|
| 259 | */
|
---|
| 260 | #define DBGCVAR_INIT_HC_FLAT(pVar, Flat) \
|
---|
| 261 | do { \
|
---|
| 262 | DBGCVAR_INIT(pVar); \
|
---|
| 263 | (pVar)->enmType = DBGCVAR_TYPE_HC_FLAT; \
|
---|
| 264 | (pVar)->u.pvHCFlat = (Flat); \
|
---|
| 265 | } while (0)
|
---|
| 266 |
|
---|
| 267 | /**
|
---|
| 268 | * Macro for initializing a DBGC variable with a GC physical address.
|
---|
| 269 | */
|
---|
| 270 | #define DBGCVAR_INIT_GC_PHYS(pVar, Phys) \
|
---|
| 271 | do { \
|
---|
| 272 | DBGCVAR_INIT(pVar); \
|
---|
| 273 | (pVar)->enmType = DBGCVAR_TYPE_GC_PHYS; \
|
---|
| 274 | (pVar)->u.GCPhys = (Phys); \
|
---|
| 275 | } while (0)
|
---|
| 276 |
|
---|
| 277 | /**
|
---|
| 278 | * Macro for initializing a DBGC variable with a GC flat address.
|
---|
| 279 | */
|
---|
| 280 | #define DBGCVAR_INIT_GC_FLAT(pVar, Flat) \
|
---|
| 281 | do { \
|
---|
| 282 | DBGCVAR_INIT(pVar); \
|
---|
| 283 | (pVar)->enmType = DBGCVAR_TYPE_GC_FLAT; \
|
---|
| 284 | (pVar)->u.GCFlat = (Flat); \
|
---|
| 285 | } while (0)
|
---|
| 286 |
|
---|
| 287 | /**
|
---|
[35673] | 288 | * Macro for initializing a DBGC variable with a GC flat address.
|
---|
| 289 | */
|
---|
| 290 | #define DBGCVAR_INIT_GC_FLAT_BYTE_RANGE(pVar, Flat, cbRange) \
|
---|
| 291 | do { \
|
---|
| 292 | DBGCVAR_INIT(pVar); \
|
---|
| 293 | (pVar)->enmType = DBGCVAR_TYPE_GC_FLAT; \
|
---|
| 294 | (pVar)->u.GCFlat = (Flat); \
|
---|
| 295 | DBGCVAR_SET_RANGE(pVar, DBGCVAR_RANGE_BYTES, cbRange); \
|
---|
| 296 | } while (0)
|
---|
| 297 |
|
---|
| 298 | /**
|
---|
[4329] | 299 | * Macro for initializing a DBGC variable with a GC far address.
|
---|
| 300 | */
|
---|
| 301 | #define DBGCVAR_INIT_GC_FAR(pVar, _sel, _off) \
|
---|
| 302 | do { \
|
---|
| 303 | DBGCVAR_INIT(pVar); \
|
---|
| 304 | (pVar)->enmType = DBGCVAR_TYPE_GC_FAR; \
|
---|
| 305 | (pVar)->u.GCFar.sel = (_sel); \
|
---|
| 306 | (pVar)->u.GCFar.off = (_off); \
|
---|
| 307 | } while (0)
|
---|
| 308 |
|
---|
| 309 | /**
|
---|
[35625] | 310 | * Macro for initializing a DBGC variable with a number.
|
---|
[4329] | 311 | */
|
---|
| 312 | #define DBGCVAR_INIT_NUMBER(pVar, Value) \
|
---|
| 313 | do { \
|
---|
| 314 | DBGCVAR_INIT(pVar); \
|
---|
| 315 | (pVar)->enmType = DBGCVAR_TYPE_NUMBER; \
|
---|
[31927] | 316 | (pVar)->u.u64Number = (Value); \
|
---|
[4329] | 317 | } while (0)
|
---|
| 318 |
|
---|
[35625] | 319 | /**
|
---|
| 320 | * Macro for initializing a DBGC variable with a string.
|
---|
| 321 | */
|
---|
| 322 | #define DBGCVAR_INIT_STRING(pVar, a_pszString) \
|
---|
| 323 | do { \
|
---|
| 324 | DBGCVAR_INIT(pVar); \
|
---|
| 325 | (pVar)->enmType = DBGCVAR_TYPE_STRING; \
|
---|
| 326 | (pVar)->enmRangeType = DBGCVAR_RANGE_BYTES; \
|
---|
| 327 | (pVar)->u.pszString = (a_pszString); \
|
---|
| 328 | (pVar)->u64Range = strlen(a_pszString); \
|
---|
| 329 | } while (0)
|
---|
[4329] | 330 |
|
---|
[35625] | 331 |
|
---|
[31462] | 332 | /**
|
---|
[41573] | 333 | * Macro for initializing a DBGC variable with a symbol.
|
---|
| 334 | */
|
---|
| 335 | #define DBGCVAR_INIT_SYMBOL(pVar, a_pszSymbol) \
|
---|
| 336 | do { \
|
---|
| 337 | DBGCVAR_INIT(pVar); \
|
---|
| 338 | (pVar)->enmType = DBGCVAR_TYPE_SYMBOL; \
|
---|
| 339 | (pVar)->enmRangeType = DBGCVAR_RANGE_BYTES; \
|
---|
| 340 | (pVar)->u.pszString = (a_pszSymbol); \
|
---|
| 341 | (pVar)->u64Range = strlen(a_pszSymbol); \
|
---|
| 342 | } while (0)
|
---|
| 343 |
|
---|
| 344 |
|
---|
| 345 | /**
|
---|
[31462] | 346 | * Macro for setting the range of a DBGC variable.
|
---|
| 347 | * @param pVar The variable.
|
---|
| 348 | * @param _enmRangeType The range type.
|
---|
| 349 | * @param Value The range length value.
|
---|
| 350 | */
|
---|
| 351 | #define DBGCVAR_SET_RANGE(pVar, _enmRangeType, Value) \
|
---|
[35673] | 352 | do { \
|
---|
| 353 | (pVar)->enmRangeType = (_enmRangeType); \
|
---|
| 354 | (pVar)->u64Range = (Value); \
|
---|
| 355 | } while (0)
|
---|
[31462] | 356 |
|
---|
| 357 |
|
---|
[35673] | 358 | /**
|
---|
| 359 | * Macro for setting the range of a DBGC variable.
|
---|
| 360 | * @param a_pVar The variable.
|
---|
| 361 | * @param a_cbRange The range, in bytes.
|
---|
| 362 | */
|
---|
| 363 | #define DBGCVAR_SET_BYTE_RANGE(a_pVar, a_cbRange) \
|
---|
| 364 | DBGCVAR_SET_RANGE(a_pVar, DBGCVAR_RANGE_BYTES, a_cbRange)
|
---|
| 365 |
|
---|
| 366 |
|
---|
| 367 | /**
|
---|
| 368 | * Macro for resetting the range a DBGC variable.
|
---|
| 369 | * @param a_pVar The variable.
|
---|
| 370 | */
|
---|
| 371 | #define DBGCVAR_ZAP_RANGE(a_pVar) \
|
---|
| 372 | do { \
|
---|
| 373 | (a_pVar)->enmRangeType = DBGCVAR_RANGE_NONE; \
|
---|
| 374 | (a_pVar)->u64Range = 0; \
|
---|
| 375 | } while (0)
|
---|
| 376 |
|
---|
| 377 |
|
---|
| 378 | /**
|
---|
| 379 | * Macro for assigning one DBGC variable to another.
|
---|
| 380 | * @param a_pResult The result (target) variable.
|
---|
| 381 | * @param a_pVar The source variable.
|
---|
| 382 | */
|
---|
| 383 | #define DBGCVAR_ASSIGN(a_pResult, a_pVar) \
|
---|
| 384 | do { \
|
---|
| 385 | *(a_pResult) = *(a_pVar); \
|
---|
| 386 | } while (0)
|
---|
| 387 |
|
---|
| 388 |
|
---|
[41561] | 389 | /** Pointer to a command descriptor. */
|
---|
[22108] | 390 | typedef struct DBGCCMD *PDBGCCMD;
|
---|
[41561] | 391 | /** Pointer to a const command descriptor. */
|
---|
[22108] | 392 | typedef const struct DBGCCMD *PCDBGCCMD;
|
---|
| 393 |
|
---|
[41561] | 394 | /** Pointer to a function descriptor. */
|
---|
| 395 | typedef struct DBGCFUNC *PDBGCFUNC;
|
---|
| 396 | /** Pointer to a const function descriptor. */
|
---|
| 397 | typedef const struct DBGCFUNC *PCDBGCFUNC;
|
---|
| 398 |
|
---|
[1] | 399 | /** Pointer to helper functions for commands. */
|
---|
| 400 | typedef struct DBGCCMDHLP *PDBGCCMDHLP;
|
---|
| 401 |
|
---|
| 402 |
|
---|
| 403 | /**
|
---|
[35694] | 404 | * Helper functions for commands.
|
---|
[1] | 405 | */
|
---|
[35694] | 406 | typedef struct DBGCCMDHLP
|
---|
| 407 | {
|
---|
| 408 | /** Magic value (DBGCCMDHLP_MAGIC). */
|
---|
| 409 | uint32_t u32Magic;
|
---|
[1] | 410 |
|
---|
[35694] | 411 | /**
|
---|
| 412 | * Command helper for writing formatted text to the debug console.
|
---|
| 413 | *
|
---|
| 414 | * @returns VBox status.
|
---|
| 415 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
[65118] | 416 | * @param pcbWritten Where to store the number of bytes written.
|
---|
| 417 | * This is optional.
|
---|
[41558] | 418 | * @param pszFormat The format string. This may use all IPRT extensions as
|
---|
| 419 | * well as the debugger ones.
|
---|
[35694] | 420 | * @param ... Arguments specified in the format string.
|
---|
| 421 | */
|
---|
[57006] | 422 | DECLCALLBACKMEMBER(int, pfnPrintf)(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten,
|
---|
| 423 | const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
|
---|
[1] | 424 |
|
---|
[35694] | 425 | /**
|
---|
| 426 | * Command helper for writing formatted text to the debug console.
|
---|
| 427 | *
|
---|
| 428 | * @returns VBox status.
|
---|
| 429 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
[65118] | 430 | * @param pcbWritten Where to store the number of bytes written.
|
---|
[69181] | 431 | * This is optional.
|
---|
[41558] | 432 | * @param pszFormat The format string. This may use all IPRT extensions as
|
---|
| 433 | * well as the debugger ones.
|
---|
[35694] | 434 | * @param args Arguments specified in the format string.
|
---|
| 435 | */
|
---|
[57006] | 436 | DECLCALLBACKMEMBER(int, pfnPrintfV)(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten,
|
---|
| 437 | const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
|
---|
[1] | 438 |
|
---|
[35694] | 439 | /**
|
---|
[41558] | 440 | * Command helper for formatting a string with debugger format specifiers.
|
---|
| 441 | *
|
---|
| 442 | * @returns The number of bytes written.
|
---|
| 443 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 444 | * @param pszBuf The output buffer.
|
---|
| 445 | * @param cbBuf The size of the output buffer.
|
---|
| 446 | * @param pszFormat The format string. This may use all IPRT extensions as
|
---|
| 447 | * well as the debugger ones.
|
---|
| 448 | * @param ... Arguments specified in the format string.
|
---|
| 449 | */
|
---|
[57006] | 450 | DECLCALLBACKMEMBER(size_t, pfnStrPrintf)(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
|
---|
| 451 | const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5);
|
---|
[41558] | 452 |
|
---|
| 453 | /**
|
---|
| 454 | * Command helper for formatting a string with debugger format specifiers.
|
---|
| 455 | *
|
---|
| 456 | * @returns The number of bytes written.
|
---|
| 457 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 458 | * @param pszBuf The output buffer.
|
---|
| 459 | * @param cbBuf The size of the output buffer.
|
---|
| 460 | * @param pszFormat The format string. This may use all IPRT extensions as
|
---|
| 461 | * well as the debugger ones.
|
---|
| 462 | * @param va Arguments specified in the format string.
|
---|
| 463 | */
|
---|
| 464 | DECLCALLBACKMEMBER(size_t, pfnStrPrintfV)(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
|
---|
[57006] | 465 | const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0);
|
---|
[41558] | 466 |
|
---|
| 467 | /**
|
---|
[35694] | 468 | * Command helper for formatting and error message for a VBox status code.
|
---|
| 469 | *
|
---|
| 470 | * @returns VBox status code appropriate to return from a command.
|
---|
| 471 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 472 | * @param rc The VBox status code.
|
---|
| 473 | * @param pszFormat Format string for additional messages. Can be NULL.
|
---|
| 474 | * @param ... Format arguments, optional.
|
---|
| 475 | */
|
---|
[57006] | 476 | DECLCALLBACKMEMBER(int, pfnVBoxError)(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
|
---|
[1] | 477 |
|
---|
[35694] | 478 | /**
|
---|
| 479 | * Command helper for formatting and error message for a VBox status code.
|
---|
| 480 | *
|
---|
| 481 | * @returns VBox status code appropriate to return from a command.
|
---|
| 482 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 483 | * @param rc The VBox status code.
|
---|
| 484 | * @param pszFormat Format string for additional messages. Can be NULL.
|
---|
| 485 | * @param args Format arguments, optional.
|
---|
| 486 | */
|
---|
[57006] | 487 | DECLCALLBACKMEMBER(int, pfnVBoxErrorV)(PDBGCCMDHLP pCmdHlp, int rc,
|
---|
| 488 | const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
|
---|
[1] | 489 |
|
---|
[35694] | 490 | /**
|
---|
| 491 | * Command helper for reading memory specified by a DBGC variable.
|
---|
| 492 | *
|
---|
| 493 | * @returns VBox status code appropriate to return from a command.
|
---|
| 494 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 495 | * @param pvBuffer Where to store the read data.
|
---|
| 496 | * @param cbRead Number of bytes to read.
|
---|
| 497 | * @param pVarPointer DBGC variable specifying where to start reading.
|
---|
| 498 | * @param pcbRead Where to store the number of bytes actually read.
|
---|
| 499 | * This optional, but it's useful when read GC virtual memory where a
|
---|
| 500 | * page in the requested range might not be present.
|
---|
| 501 | * If not specified not-present failure or end of a HC physical page
|
---|
| 502 | * will cause failure.
|
---|
| 503 | */
|
---|
[44399] | 504 | DECLCALLBACKMEMBER(int, pfnMemRead)(PDBGCCMDHLP pCmdHlp, void *pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t *pcbRead);
|
---|
[1] | 505 |
|
---|
[35694] | 506 | /**
|
---|
| 507 | * Command helper for writing memory specified by a DBGC variable.
|
---|
| 508 | *
|
---|
| 509 | * @returns VBox status code appropriate to return from a command.
|
---|
| 510 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 511 | * @param pvBuffer What to write.
|
---|
| 512 | * @param cbWrite Number of bytes to write.
|
---|
| 513 | * @param pVarPointer DBGC variable specifying where to start reading.
|
---|
| 514 | * @param pcbWritten Where to store the number of bytes written.
|
---|
| 515 | * This is optional. If NULL be aware that some of the buffer
|
---|
| 516 | * might have been written to the specified address.
|
---|
| 517 | */
|
---|
[44399] | 518 | DECLCALLBACKMEMBER(int, pfnMemWrite)(PDBGCCMDHLP pCmdHlp, const void *pvBuffer, size_t cbWrite, PCDBGCVAR pVarPointer, size_t *pcbWritten);
|
---|
[1] | 519 |
|
---|
[35694] | 520 | /**
|
---|
| 521 | * Executes command an expression.
|
---|
| 522 | * (Hopefully the parser and functions are fully reentrant.)
|
---|
| 523 | *
|
---|
| 524 | * @returns VBox status code appropriate to return from a command.
|
---|
| 525 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 526 | * @param pszExpr The expression. Format string with the format DBGC extensions.
|
---|
| 527 | * @param ... Format arguments.
|
---|
| 528 | */
|
---|
[57006] | 529 | DECLCALLBACKMEMBER(int, pfnExec)(PDBGCCMDHLP pCmdHlp, const char *pszExpr, ...) RT_IPRT_FORMAT_ATTR(2, 3);
|
---|
[1] | 530 |
|
---|
| 531 | /**
|
---|
[22108] | 532 | * Evaluates an expression.
|
---|
| 533 | * (Hopefully the parser and functions are fully reentrant.)
|
---|
| 534 | *
|
---|
| 535 | * @returns VBox status code appropriate to return from a command.
|
---|
| 536 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 537 | * @param pResult Where to store the result.
|
---|
| 538 | * @param pszExpr The expression. Format string with the format DBGC extensions.
|
---|
| 539 | * @param va Format arguments.
|
---|
| 540 | */
|
---|
[57006] | 541 | DECLCALLBACKMEMBER(int, pfnEvalV)(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult,
|
---|
| 542 | const char *pszExpr, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
|
---|
[22108] | 543 |
|
---|
| 544 | /**
|
---|
| 545 | * Print an error and fail the current command.
|
---|
| 546 | *
|
---|
| 547 | * @returns VBox status code to pass upwards.
|
---|
| 548 | *
|
---|
| 549 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 550 | * @param pCmd The failing command.
|
---|
| 551 | * @param pszFormat The error message format string.
|
---|
| 552 | * @param va Format arguments.
|
---|
| 553 | */
|
---|
[57006] | 554 | DECLCALLBACKMEMBER(int, pfnFailV)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd,
|
---|
| 555 | const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
|
---|
[22108] | 556 |
|
---|
| 557 | /**
|
---|
[35694] | 558 | * Print an error and fail the current command.
|
---|
| 559 | *
|
---|
| 560 | * @returns VBox status code to pass upwards.
|
---|
| 561 | *
|
---|
| 562 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 563 | * @param pCmd The failing command.
|
---|
| 564 | * @param rc The status code indicating the failure. This will
|
---|
| 565 | * be appended to the message after a colon (': ').
|
---|
| 566 | * @param pszFormat The error message format string.
|
---|
| 567 | * @param va Format arguments.
|
---|
| 568 | *
|
---|
| 569 | * @see DBGCCmdHlpFailRc
|
---|
| 570 | */
|
---|
[57006] | 571 | DECLCALLBACKMEMBER(int, pfnFailRcV)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc,
|
---|
| 572 | const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0);
|
---|
[35694] | 573 |
|
---|
| 574 | /**
|
---|
| 575 | * Parser error.
|
---|
| 576 | *
|
---|
| 577 | * @returns VBox status code to pass upwards.
|
---|
| 578 | *
|
---|
| 579 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 580 | * @param pCmd The failing command, can be NULL but shouldn't.
|
---|
| 581 | * @param iArg The offending argument, -1 when lazy.
|
---|
| 582 | * @param pszExpr The expression.
|
---|
| 583 | * @param iLine The line number.
|
---|
| 584 | */
|
---|
| 585 | DECLCALLBACKMEMBER(int, pfnParserError)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int iArg, const char *pszExpr, unsigned iLine);
|
---|
| 586 |
|
---|
| 587 | /**
|
---|
[1] | 588 | * Converts a DBGC variable to a DBGF address structure.
|
---|
| 589 | *
|
---|
| 590 | * @returns VBox status code.
|
---|
| 591 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 592 | * @param pVar The variable to convert.
|
---|
| 593 | * @param pAddress The target address.
|
---|
| 594 | */
|
---|
| 595 | DECLCALLBACKMEMBER(int, pfnVarToDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress);
|
---|
| 596 |
|
---|
| 597 | /**
|
---|
[35673] | 598 | * Converts a DBGF address structure to a DBGC variable.
|
---|
| 599 | *
|
---|
| 600 | * @returns VBox status code.
|
---|
| 601 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 602 | * @param pAddress The source address.
|
---|
| 603 | * @param pResult The result variable.
|
---|
| 604 | */
|
---|
| 605 | DECLCALLBACKMEMBER(int, pfnVarFromDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGFADDRESS pAddress, PDBGCVAR pResult);
|
---|
| 606 |
|
---|
| 607 | /**
|
---|
[35625] | 608 | * Converts a DBGC variable to a 64-bit number.
|
---|
| 609 | *
|
---|
| 610 | * @returns VBox status code.
|
---|
| 611 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 612 | * @param pVar The variable to convert.
|
---|
| 613 | * @param pu64Number Where to store the number.
|
---|
| 614 | */
|
---|
| 615 | DECLCALLBACKMEMBER(int, pfnVarToNumber)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number);
|
---|
| 616 |
|
---|
| 617 | /**
|
---|
[1] | 618 | * Converts a DBGC variable to a boolean.
|
---|
| 619 | *
|
---|
| 620 | * @returns VBox status code.
|
---|
| 621 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 622 | * @param pVar The variable to convert.
|
---|
| 623 | * @param pf Where to store the boolean.
|
---|
| 624 | */
|
---|
| 625 | DECLCALLBACKMEMBER(int, pfnVarToBool)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf);
|
---|
| 626 |
|
---|
[31966] | 627 | /**
|
---|
| 628 | * Get the range of a variable in bytes, resolving symbols if necessary.
|
---|
| 629 | *
|
---|
| 630 | * @returns VBox status code.
|
---|
| 631 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 632 | * @param pVar The variable to convert.
|
---|
| 633 | * @param cbElement Conversion factor for element ranges.
|
---|
| 634 | * @param cbDefault The default range.
|
---|
| 635 | * @param pcbRange The length of the range.
|
---|
| 636 | */
|
---|
| 637 | DECLCALLBACKMEMBER(int, pfnVarGetRange)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault,
|
---|
| 638 | uint64_t *pcbRange);
|
---|
| 639 |
|
---|
| 640 | /**
|
---|
[35625] | 641 | * Converts a variable to one with the specified type.
|
---|
| 642 | *
|
---|
| 643 | * This preserves the range.
|
---|
| 644 | *
|
---|
| 645 | * @returns VBox status code.
|
---|
| 646 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 647 | * @param pVar The variable to convert.
|
---|
| 648 | * @param enmToType The target type.
|
---|
| 649 | * @param fConvSyms If @c true, then attempt to resolve symbols.
|
---|
| 650 | * @param pResult The output variable. Can be the same as @a pVar.
|
---|
| 651 | */
|
---|
| 652 | DECLCALLBACKMEMBER(int, pfnVarConvert)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms,
|
---|
| 653 | PDBGCVAR pResult);
|
---|
| 654 |
|
---|
| 655 | /**
|
---|
[31966] | 656 | * Gets a DBGF output helper that directs the output to the debugger
|
---|
| 657 | * console.
|
---|
| 658 | *
|
---|
| 659 | * @returns Pointer to the helper structure.
|
---|
| 660 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 661 | */
|
---|
| 662 | DECLCALLBACKMEMBER(PCDBGFINFOHLP, pfnGetDbgfOutputHlp)(PDBGCCMDHLP pCmdHlp);
|
---|
| 663 |
|
---|
[41565] | 664 | /**
|
---|
| 665 | * Gets the ID currently selected CPU.
|
---|
| 666 | *
|
---|
| 667 | * @returns Current CPU ID.
|
---|
| 668 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 669 | */
|
---|
| 670 | DECLCALLBACKMEMBER(VMCPUID, pfnGetCurrentCpu)(PDBGCCMDHLP pCmdHlp);
|
---|
| 671 |
|
---|
| 672 | /**
|
---|
| 673 | * Gets the mode the currently selected CPU is running in, in the current
|
---|
| 674 | * context.
|
---|
| 675 | *
|
---|
| 676 | * @returns Current CPU mode.
|
---|
| 677 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 678 | */
|
---|
| 679 | DECLCALLBACKMEMBER(CPUMMODE, pfnGetCpuMode)(PDBGCCMDHLP pCmdHlp);
|
---|
| 680 |
|
---|
[35694] | 681 | /** End marker (DBGCCMDHLP_MAGIC). */
|
---|
| 682 | uint32_t u32EndMarker;
|
---|
[1] | 683 | } DBGCCMDHLP;
|
---|
| 684 |
|
---|
[35694] | 685 | /** Magic value for DBGCCMDHLP::u32Magic. (Fyodor Mikhaylovich Dostoyevsky) */
|
---|
| 686 | #define DBGCCMDHLP_MAGIC UINT32_C(18211111)
|
---|
[1] | 687 |
|
---|
[35694] | 688 |
|
---|
[64721] | 689 | #if defined(IN_RING3) || defined(IN_SLICKEDIT)
|
---|
[22108] | 690 |
|
---|
[4329] | 691 | /**
|
---|
[58106] | 692 | * Command helper for writing formatted text to the debug console.
|
---|
| 693 | *
|
---|
| 694 | * @returns VBox status.
|
---|
| 695 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 696 | * @param pszFormat The format string. This may use all IPRT extensions as
|
---|
| 697 | * well as the debugger ones.
|
---|
| 698 | * @param ... Arguments specified in the format string.
|
---|
[4329] | 699 | */
|
---|
[57006] | 700 | DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) DBGCCmdHlpPrintf(PDBGCCMDHLP pCmdHlp, const char *pszFormat, ...)
|
---|
[4329] | 701 | {
|
---|
| 702 | va_list va;
|
---|
[22108] | 703 | int rc;
|
---|
| 704 |
|
---|
[4329] | 705 | va_start(va, pszFormat);
|
---|
| 706 | rc = pCmdHlp->pfnPrintfV(pCmdHlp, NULL, pszFormat, va);
|
---|
| 707 | va_end(va);
|
---|
[22108] | 708 |
|
---|
[4329] | 709 | return rc;
|
---|
| 710 | }
|
---|
[1] | 711 |
|
---|
[61679] | 712 | /**
|
---|
| 713 | * Command helper for writing formatted text to the debug console.
|
---|
| 714 | *
|
---|
| 715 | * @returns VBox status.
|
---|
| 716 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 717 | * @param pcbWritten Where to store the amount of written characters on success.
|
---|
| 718 | * @param pszFormat The format string. This may use all IPRT extensions as
|
---|
| 719 | * well as the debugger ones.
|
---|
| 720 | * @param ... Arguments specified in the format string.
|
---|
| 721 | */
|
---|
[73448] | 722 | DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpPrintfEx(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten,
|
---|
[61679] | 723 | const char *pszFormat, ...)
|
---|
| 724 | {
|
---|
| 725 | va_list va;
|
---|
| 726 | int rc;
|
---|
[41558] | 727 |
|
---|
[61679] | 728 | va_start(va, pszFormat);
|
---|
| 729 | rc = pCmdHlp->pfnPrintfV(pCmdHlp, pcbWritten, pszFormat, va);
|
---|
| 730 | va_end(va);
|
---|
| 731 |
|
---|
| 732 | return rc;
|
---|
| 733 | }
|
---|
| 734 |
|
---|
[4329] | 735 | /**
|
---|
[73445] | 736 | * Command helper for writing formatted text to the debug console.
|
---|
| 737 | *
|
---|
| 738 | * @returns Number of bytes written.
|
---|
| 739 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 740 | * @param pszFormat The format string. This may use all IPRT extensions as
|
---|
| 741 | * well as the debugger ones.
|
---|
| 742 | * @param ... Arguments specified in the format string.
|
---|
| 743 | */
|
---|
| 744 | DECLINLINE(size_t) RT_IPRT_FORMAT_ATTR(2, 3) DBGCCmdHlpPrintfLen(PDBGCCMDHLP pCmdHlp, const char *pszFormat, ...)
|
---|
| 745 | {
|
---|
| 746 | va_list va;
|
---|
| 747 | int rc;
|
---|
| 748 | size_t cbWritten = 0;
|
---|
| 749 |
|
---|
| 750 | va_start(va, pszFormat);
|
---|
| 751 | rc = pCmdHlp->pfnPrintfV(pCmdHlp, &cbWritten, pszFormat, va);
|
---|
| 752 | va_end(va);
|
---|
| 753 |
|
---|
| 754 | return RT_SUCCESS(rc) ? cbWritten : 0;
|
---|
| 755 | }
|
---|
| 756 |
|
---|
| 757 | /**
|
---|
[41558] | 758 | * @copydoc DBGCCMDHLP::pfnStrPrintf
|
---|
| 759 | */
|
---|
[57006] | 760 | DECLINLINE(size_t) RT_IPRT_FORMAT_ATTR(4, 5) DBGCCmdHlpStrPrintf(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
|
---|
| 761 | const char *pszFormat, ...)
|
---|
[41558] | 762 | {
|
---|
| 763 | va_list va;
|
---|
| 764 | size_t cch;
|
---|
| 765 |
|
---|
| 766 | va_start(va, pszFormat);
|
---|
| 767 | cch = pCmdHlp->pfnStrPrintfV(pCmdHlp, pszBuf, cbBuf, pszFormat, va);
|
---|
| 768 | va_end(va);
|
---|
| 769 |
|
---|
| 770 | return cch;
|
---|
| 771 | }
|
---|
| 772 |
|
---|
| 773 | /**
|
---|
[58106] | 774 | * @copydoc DBGCCMDHLP::pfnVBoxError
|
---|
[4329] | 775 | */
|
---|
[57006] | 776 | DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpVBoxError(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...)
|
---|
[4329] | 777 | {
|
---|
| 778 | va_list va;
|
---|
[22108] | 779 |
|
---|
[4329] | 780 | va_start(va, pszFormat);
|
---|
| 781 | rc = pCmdHlp->pfnVBoxErrorV(pCmdHlp, rc, pszFormat, va);
|
---|
| 782 | va_end(va);
|
---|
[22108] | 783 |
|
---|
[4329] | 784 | return rc;
|
---|
| 785 | }
|
---|
| 786 |
|
---|
| 787 | /**
|
---|
[58106] | 788 | * @copydoc DBGCCMDHLP::pfnMemRead
|
---|
[4329] | 789 | */
|
---|
[44399] | 790 | DECLINLINE(int) DBGCCmdHlpMemRead(PDBGCCMDHLP pCmdHlp, void *pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t *pcbRead)
|
---|
[4329] | 791 | {
|
---|
[44399] | 792 | return pCmdHlp->pfnMemRead(pCmdHlp, pvBuffer, cbRead, pVarPointer, pcbRead);
|
---|
[4329] | 793 | }
|
---|
[22108] | 794 |
|
---|
| 795 | /**
|
---|
| 796 | * Evaluates an expression.
|
---|
| 797 | * (Hopefully the parser and functions are fully reentrant.)
|
---|
| 798 | *
|
---|
| 799 | * @returns VBox status code appropriate to return from a command.
|
---|
| 800 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 801 | * @param pResult Where to store the result.
|
---|
| 802 | * @param pszExpr The expression. Format string with the format DBGC extensions.
|
---|
| 803 | * @param ... Format arguments.
|
---|
| 804 | */
|
---|
[57006] | 805 | DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpEval(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, ...)
|
---|
[22108] | 806 | {
|
---|
| 807 | va_list va;
|
---|
| 808 | int rc;
|
---|
| 809 |
|
---|
| 810 | va_start(va, pszExpr);
|
---|
| 811 | rc = pCmdHlp->pfnEvalV(pCmdHlp, pResult, pszExpr, va);
|
---|
| 812 | va_end(va);
|
---|
| 813 |
|
---|
| 814 | return rc;
|
---|
| 815 | }
|
---|
| 816 |
|
---|
| 817 | /**
|
---|
| 818 | * Print an error and fail the current command.
|
---|
| 819 | *
|
---|
| 820 | * @returns VBox status code to pass upwards.
|
---|
| 821 | *
|
---|
| 822 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 823 | * @param pCmd The failing command.
|
---|
| 824 | * @param pszFormat The error message format string.
|
---|
| 825 | * @param ... Format arguments.
|
---|
| 826 | */
|
---|
[57006] | 827 | DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpFail(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, ...)
|
---|
[22108] | 828 | {
|
---|
| 829 | va_list va;
|
---|
| 830 | int rc;
|
---|
| 831 |
|
---|
| 832 | va_start(va, pszFormat);
|
---|
| 833 | rc = pCmdHlp->pfnFailV(pCmdHlp, pCmd, pszFormat, va);
|
---|
| 834 | va_end(va);
|
---|
| 835 |
|
---|
| 836 | return rc;
|
---|
| 837 | }
|
---|
| 838 |
|
---|
[31966] | 839 | /**
|
---|
[35694] | 840 | * Print an error and fail the current command.
|
---|
| 841 | *
|
---|
| 842 | * Usage example:
|
---|
| 843 | * @code
|
---|
| 844 | int rc = VMMR3Something(pVM);
|
---|
| 845 | if (RT_FAILURE(rc))
|
---|
| 846 | return DBGCCmdHlpFailRc(pCmdHlp, pCmd, rc, "VMMR3Something");
|
---|
| 847 | return VINF_SUCCESS;
|
---|
| 848 | * @endcode
|
---|
| 849 | *
|
---|
| 850 | * @returns VBox status code to pass upwards.
|
---|
| 851 | *
|
---|
| 852 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 853 | * @param pCmd The failing command.
|
---|
| 854 | * @param rc The status code indicating the failure.
|
---|
| 855 | * @param pszFormat The error message format string.
|
---|
| 856 | * @param ... Format arguments.
|
---|
| 857 | */
|
---|
[57006] | 858 | DECLINLINE(int) RT_IPRT_FORMAT_ATTR(4, 5) DBGCCmdHlpFailRc(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc,
|
---|
| 859 | const char *pszFormat, ...)
|
---|
[35694] | 860 | {
|
---|
| 861 | va_list va;
|
---|
| 862 |
|
---|
| 863 | va_start(va, pszFormat);
|
---|
| 864 | rc = pCmdHlp->pfnFailRcV(pCmdHlp, pCmd, rc, pszFormat, va);
|
---|
| 865 | va_end(va);
|
---|
| 866 |
|
---|
| 867 | return rc;
|
---|
| 868 | }
|
---|
| 869 |
|
---|
| 870 | /**
|
---|
| 871 | * @copydoc DBGCCMDHLP::pfnParserError
|
---|
| 872 | */
|
---|
| 873 | DECLINLINE(int) DBGCCmdHlpParserError(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int iArg, const char *pszExpr, unsigned iLine)
|
---|
| 874 | {
|
---|
| 875 | return pCmdHlp->pfnParserError(pCmdHlp, pCmd, iArg, pszExpr, iLine);
|
---|
| 876 | }
|
---|
| 877 |
|
---|
| 878 | /** Assert+return like macro for checking parser sanity.
|
---|
| 879 | * Returns with failure if the precodition is not met. */
|
---|
| 880 | #define DBGC_CMDHLP_ASSERT_PARSER_RET(pCmdHlp, pCmd, iArg, expr) \
|
---|
| 881 | do { \
|
---|
| 882 | if (!(expr)) \
|
---|
| 883 | return DBGCCmdHlpParserError(pCmdHlp, pCmd, iArg, #expr, __LINE__); \
|
---|
| 884 | } while (0)
|
---|
| 885 |
|
---|
| 886 | /** Assert+return like macro that the VM handle is present.
|
---|
| 887 | * Returns with failure if the VM handle is NIL. */
|
---|
[44399] | 888 | #define DBGC_CMDHLP_REQ_UVM_RET(pCmdHlp, pCmd, pUVM) \
|
---|
[35694] | 889 | do { \
|
---|
[44399] | 890 | if (!(pUVM)) \
|
---|
[35694] | 891 | return DBGCCmdHlpFail(pCmdHlp, pCmd, "No VM selected"); \
|
---|
| 892 | } while (0)
|
---|
| 893 |
|
---|
| 894 | /**
|
---|
[31966] | 895 | * @copydoc DBGCCMDHLP::pfnVarToDbgfAddr
|
---|
| 896 | */
|
---|
| 897 | DECLINLINE(int) DBGCCmdHlpVarToDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress)
|
---|
| 898 | {
|
---|
| 899 | return pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, pAddress);
|
---|
| 900 | }
|
---|
| 901 |
|
---|
| 902 | /**
|
---|
[58106] | 903 | * @copydoc DBGCCMDHLP::pfnVarFromDbgfAddr
|
---|
[35673] | 904 | */
|
---|
| 905 | DECLINLINE(int) DBGCCmdHlpVarFromDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGFADDRESS pAddress, PDBGCVAR pResult)
|
---|
| 906 | {
|
---|
| 907 | return pCmdHlp->pfnVarFromDbgfAddr(pCmdHlp, pAddress, pResult);
|
---|
| 908 | }
|
---|
| 909 |
|
---|
| 910 | /**
|
---|
[31966] | 911 | * Converts an variable to a flat address.
|
---|
| 912 | *
|
---|
| 913 | * @returns VBox status code.
|
---|
| 914 | * @param pCmdHlp Pointer to the command callback structure.
|
---|
| 915 | * @param pVar The variable to convert.
|
---|
| 916 | * @param pFlatPtr Where to store the flat address.
|
---|
| 917 | */
|
---|
| 918 | DECLINLINE(int) DBGCCmdHlpVarToFlatAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PRTGCPTR pFlatPtr)
|
---|
| 919 | {
|
---|
| 920 | DBGFADDRESS Addr;
|
---|
| 921 | int rc = pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, &Addr);
|
---|
| 922 | if (RT_SUCCESS(rc))
|
---|
| 923 | *pFlatPtr = Addr.FlatPtr;
|
---|
| 924 | return rc;
|
---|
| 925 | }
|
---|
| 926 |
|
---|
| 927 | /**
|
---|
[35625] | 928 | * @copydoc DBGCCMDHLP::pfnVarToNumber
|
---|
| 929 | */
|
---|
| 930 | DECLINLINE(int) DBGCCmdHlpVarToNumber(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number)
|
---|
| 931 | {
|
---|
| 932 | return pCmdHlp->pfnVarToNumber(pCmdHlp, pVar, pu64Number);
|
---|
| 933 | }
|
---|
| 934 |
|
---|
| 935 | /**
|
---|
| 936 | * @copydoc DBGCCMDHLP::pfnVarToBool
|
---|
| 937 | */
|
---|
| 938 | DECLINLINE(int) DBGCCmdHlpVarToBool(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf)
|
---|
| 939 | {
|
---|
| 940 | return pCmdHlp->pfnVarToBool(pCmdHlp, pVar, pf);
|
---|
| 941 | }
|
---|
| 942 |
|
---|
| 943 | /**
|
---|
[31966] | 944 | * @copydoc DBGCCMDHLP::pfnVarGetRange
|
---|
| 945 | */
|
---|
| 946 | DECLINLINE(int) DBGCCmdHlpVarGetRange(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault, uint64_t *pcbRange)
|
---|
| 947 | {
|
---|
| 948 | return pCmdHlp->pfnVarGetRange(pCmdHlp, pVar, cbElement, cbDefault, pcbRange);
|
---|
| 949 | }
|
---|
| 950 |
|
---|
| 951 | /**
|
---|
[35625] | 952 | * @copydoc DBGCCMDHLP::pfnVarConvert
|
---|
| 953 | */
|
---|
| 954 | DECLINLINE(int) DBGCCmdHlpConvert(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms, PDBGCVAR pResult)
|
---|
| 955 | {
|
---|
| 956 | return pCmdHlp->pfnVarConvert(pCmdHlp, pVar, enmToType, fConvSyms, pResult);
|
---|
| 957 | }
|
---|
| 958 |
|
---|
| 959 | /**
|
---|
[31966] | 960 | * @copydoc DBGCCMDHLP::pfnGetDbgfOutputHlp
|
---|
| 961 | */
|
---|
| 962 | DECLINLINE(PCDBGFINFOHLP) DBGCCmdHlpGetDbgfOutputHlp(PDBGCCMDHLP pCmdHlp)
|
---|
| 963 | {
|
---|
| 964 | return pCmdHlp->pfnGetDbgfOutputHlp(pCmdHlp);
|
---|
| 965 | }
|
---|
| 966 |
|
---|
[41565] | 967 | /**
|
---|
| 968 | * @copydoc DBGCCMDHLP::pfnGetCurrentCpu
|
---|
| 969 | */
|
---|
| 970 | DECLINLINE(VMCPUID) DBGCCmdHlpGetCurrentCpu(PDBGCCMDHLP pCmdHlp)
|
---|
| 971 | {
|
---|
| 972 | return pCmdHlp->pfnGetCurrentCpu(pCmdHlp);
|
---|
| 973 | }
|
---|
| 974 |
|
---|
| 975 | /**
|
---|
| 976 | * @copydoc DBGCCMDHLP::pfnGetCpuMode
|
---|
| 977 | */
|
---|
| 978 | DECLINLINE(CPUMMODE) DBGCCmdHlpGetCpuMode(PDBGCCMDHLP pCmdHlp)
|
---|
| 979 | {
|
---|
| 980 | return pCmdHlp->pfnGetCpuMode(pCmdHlp);
|
---|
| 981 | }
|
---|
| 982 |
|
---|
[4329] | 983 | #endif /* IN_RING3 */
|
---|
| 984 |
|
---|
| 985 |
|
---|
[1] | 986 |
|
---|
| 987 | /**
|
---|
| 988 | * Command handler.
|
---|
| 989 | *
|
---|
| 990 | * The console will call the handler for a command once it's finished
|
---|
[35696] | 991 | * parsing the user input. The command handler function is responsible
|
---|
[1] | 992 | * for executing the command itself.
|
---|
| 993 | *
|
---|
| 994 | * @returns VBox status.
|
---|
| 995 | * @param pCmd Pointer to the command descriptor (as registered).
|
---|
| 996 | * @param pCmdHlp Pointer to command helper functions.
|
---|
[44399] | 997 | * @param pUVM The user mode VM handle, can in theory be NULL.
|
---|
[1] | 998 | * @param paArgs Pointer to (readonly) array of arguments.
|
---|
| 999 | * @param cArgs Number of arguments in the array.
|
---|
| 1000 | */
|
---|
[44399] | 1001 | typedef DECLCALLBACK(int) FNDBGCCMD(PCDBGCCMD pCmd, PDBGCCMDHLP pCmdHlp, PUVM pUVM, PCDBGCVAR paArgs, unsigned cArgs);
|
---|
[1] | 1002 | /** Pointer to a FNDBGCCMD() function. */
|
---|
| 1003 | typedef FNDBGCCMD *PFNDBGCCMD;
|
---|
| 1004 |
|
---|
| 1005 | /**
|
---|
| 1006 | * DBGC command descriptor.
|
---|
| 1007 | */
|
---|
| 1008 | typedef struct DBGCCMD
|
---|
| 1009 | {
|
---|
| 1010 | /** Command string. */
|
---|
| 1011 | const char *pszCmd;
|
---|
| 1012 | /** Minimum number of arguments. */
|
---|
| 1013 | unsigned cArgsMin;
|
---|
| 1014 | /** Max number of arguments. */
|
---|
| 1015 | unsigned cArgsMax;
|
---|
| 1016 | /** Argument descriptors (array). */
|
---|
| 1017 | PCDBGCVARDESC paArgDescs;
|
---|
| 1018 | /** Number of argument descriptors. */
|
---|
| 1019 | unsigned cArgDescs;
|
---|
| 1020 | /** flags. (reserved for now) */
|
---|
| 1021 | unsigned fFlags;
|
---|
| 1022 | /** Handler function. */
|
---|
| 1023 | PFNDBGCCMD pfnHandler;
|
---|
| 1024 | /** Command syntax. */
|
---|
| 1025 | const char *pszSyntax;
|
---|
| 1026 | /** Command description. */
|
---|
| 1027 | const char *pszDescription;
|
---|
| 1028 | } DBGCCMD;
|
---|
| 1029 |
|
---|
| 1030 | /** DBGCCMD Flags.
|
---|
| 1031 | * @{
|
---|
| 1032 | */
|
---|
| 1033 | /** @} */
|
---|
| 1034 |
|
---|
| 1035 |
|
---|
[41561] | 1036 | /**
|
---|
| 1037 | * Function handler.
|
---|
| 1038 | *
|
---|
| 1039 | * The console will call the handler for a command once it's finished
|
---|
| 1040 | * parsing the user input. The command handler function is responsible
|
---|
| 1041 | * for executing the command itself.
|
---|
| 1042 | *
|
---|
| 1043 | * @returns VBox status.
|
---|
| 1044 | * @param pCmd Pointer to the command descriptor (as registered).
|
---|
| 1045 | * @param pCmdHlp Pointer to command helper functions.
|
---|
[44399] | 1046 | * @param pUVM The user mode VM handle, can in theory be NULL.
|
---|
[41561] | 1047 | * @param paArgs Pointer to (readonly) array of arguments.
|
---|
| 1048 | * @param cArgs Number of arguments in the array.
|
---|
| 1049 | * @param pResult Where to return the result.
|
---|
| 1050 | */
|
---|
[44399] | 1051 | typedef DECLCALLBACK(int) FNDBGCFUNC(PCDBGCFUNC pFunc, PDBGCCMDHLP pCmdHlp, PUVM pUVM, PCDBGCVAR paArgs, unsigned cArgs,
|
---|
[41561] | 1052 | PDBGCVAR pResult);
|
---|
| 1053 | /** Pointer to a FNDBGCFUNC() function. */
|
---|
| 1054 | typedef FNDBGCFUNC *PFNDBGCFUNC;
|
---|
[1] | 1055 |
|
---|
[41561] | 1056 | /**
|
---|
| 1057 | * DBGC function descriptor.
|
---|
| 1058 | */
|
---|
| 1059 | typedef struct DBGCFUNC
|
---|
| 1060 | {
|
---|
| 1061 | /** Command string. */
|
---|
| 1062 | const char *pszFuncNm;
|
---|
| 1063 | /** Minimum number of arguments. */
|
---|
| 1064 | unsigned cArgsMin;
|
---|
| 1065 | /** Max number of arguments. */
|
---|
| 1066 | unsigned cArgsMax;
|
---|
| 1067 | /** Argument descriptors (array). */
|
---|
| 1068 | PCDBGCVARDESC paArgDescs;
|
---|
| 1069 | /** Number of argument descriptors. */
|
---|
| 1070 | unsigned cArgDescs;
|
---|
| 1071 | /** flags. (reserved for now) */
|
---|
| 1072 | unsigned fFlags;
|
---|
| 1073 | /** Handler function. */
|
---|
| 1074 | PFNDBGCFUNC pfnHandler;
|
---|
| 1075 | /** Function syntax. */
|
---|
| 1076 | const char *pszSyntax;
|
---|
| 1077 | /** Function description. */
|
---|
| 1078 | const char *pszDescription;
|
---|
| 1079 | } DBGCFUNC;
|
---|
| 1080 |
|
---|
| 1081 |
|
---|
| 1082 |
|
---|
[1] | 1083 | /** Pointer to a DBGC backend. */
|
---|
| 1084 | typedef struct DBGCBACK *PDBGCBACK;
|
---|
| 1085 |
|
---|
| 1086 | /**
|
---|
| 1087 | * Checks if there is input.
|
---|
| 1088 | *
|
---|
| 1089 | * @returns true if there is input ready.
|
---|
| 1090 | * @returns false if there not input ready.
|
---|
| 1091 | * @param pBack Pointer to the backend structure supplied by
|
---|
| 1092 | * the backend. The backend can use this to find
|
---|
| 1093 | * it's instance data.
|
---|
| 1094 | * @param cMillies Number of milliseconds to wait on input data.
|
---|
| 1095 | */
|
---|
| 1096 | typedef DECLCALLBACK(bool) FNDBGCBACKINPUT(PDBGCBACK pBack, uint32_t cMillies);
|
---|
| 1097 | /** Pointer to a FNDBGCBACKINPUT() callback. */
|
---|
| 1098 | typedef FNDBGCBACKINPUT *PFNDBGCBACKINPUT;
|
---|
| 1099 |
|
---|
| 1100 | /**
|
---|
| 1101 | * Read input.
|
---|
| 1102 | *
|
---|
| 1103 | * @returns VBox status code.
|
---|
| 1104 | * @param pBack Pointer to the backend structure supplied by
|
---|
| 1105 | * the backend. The backend can use this to find
|
---|
| 1106 | * it's instance data.
|
---|
| 1107 | * @param pvBuf Where to put the bytes we read.
|
---|
| 1108 | * @param cbBuf Maximum nymber of bytes to read.
|
---|
| 1109 | * @param pcbRead Where to store the number of bytes actually read.
|
---|
| 1110 | * If NULL the entire buffer must be filled for a
|
---|
| 1111 | * successful return.
|
---|
| 1112 | */
|
---|
| 1113 | typedef DECLCALLBACK(int) FNDBGCBACKREAD(PDBGCBACK pBack, void *pvBuf, size_t cbBuf, size_t *pcbRead);
|
---|
| 1114 | /** Pointer to a FNDBGCBACKREAD() callback. */
|
---|
| 1115 | typedef FNDBGCBACKREAD *PFNDBGCBACKREAD;
|
---|
| 1116 |
|
---|
| 1117 | /**
|
---|
| 1118 | * Write (output).
|
---|
| 1119 | *
|
---|
| 1120 | * @returns VBox status code.
|
---|
| 1121 | * @param pBack Pointer to the backend structure supplied by
|
---|
| 1122 | * the backend. The backend can use this to find
|
---|
| 1123 | * it's instance data.
|
---|
| 1124 | * @param pvBuf What to write.
|
---|
| 1125 | * @param cbBuf Number of bytes to write.
|
---|
| 1126 | * @param pcbWritten Where to store the number of bytes actually written.
|
---|
| 1127 | * If NULL the entire buffer must be successfully written.
|
---|
| 1128 | */
|
---|
| 1129 | typedef DECLCALLBACK(int) FNDBGCBACKWRITE(PDBGCBACK pBack, const void *pvBuf, size_t cbBuf, size_t *pcbWritten);
|
---|
| 1130 | /** Pointer to a FNDBGCBACKWRITE() callback. */
|
---|
| 1131 | typedef FNDBGCBACKWRITE *PFNDBGCBACKWRITE;
|
---|
| 1132 |
|
---|
[12880] | 1133 | /**
|
---|
| 1134 | * Ready / busy notification.
|
---|
| 1135 | *
|
---|
| 1136 | * @param pBack Pointer to the backend structure supplied by
|
---|
| 1137 | * the backend. The backend can use this to find
|
---|
| 1138 | * it's instance data.
|
---|
| 1139 | * @param fReady Whether it's ready (true) or busy (false).
|
---|
| 1140 | */
|
---|
| 1141 | typedef DECLCALLBACK(void) FNDBGCBACKSETREADY(PDBGCBACK pBack, bool fReady);
|
---|
| 1142 | /** Pointer to a FNDBGCBACKSETREADY() callback. */
|
---|
| 1143 | typedef FNDBGCBACKSETREADY *PFNDBGCBACKSETREADY;
|
---|
[1] | 1144 |
|
---|
[12880] | 1145 |
|
---|
[1] | 1146 | /**
|
---|
| 1147 | * The communication backend provides the console with a number of callbacks
|
---|
| 1148 | * which can be used
|
---|
| 1149 | */
|
---|
| 1150 | typedef struct DBGCBACK
|
---|
| 1151 | {
|
---|
| 1152 | /** Check for input. */
|
---|
| 1153 | PFNDBGCBACKINPUT pfnInput;
|
---|
| 1154 | /** Read input. */
|
---|
| 1155 | PFNDBGCBACKREAD pfnRead;
|
---|
| 1156 | /** Write output. */
|
---|
| 1157 | PFNDBGCBACKWRITE pfnWrite;
|
---|
[12880] | 1158 | /** Ready / busy notification. */
|
---|
| 1159 | PFNDBGCBACKSETREADY pfnSetReady;
|
---|
[1] | 1160 | } DBGCBACK;
|
---|
| 1161 |
|
---|
[44399] | 1162 | DBGDECL(int) DBGCCreate(PUVM pUVM, PDBGCBACK pBack, unsigned fFlags);
|
---|
[1] | 1163 | DBGDECL(int) DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
|
---|
| 1164 | DBGDECL(int) DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
|
---|
[44399] | 1165 | DBGDECL(int) DBGCTcpCreate(PUVM pUVM, void **ppvUser);
|
---|
| 1166 | DBGDECL(int) DBGCTcpTerminate(PUVM pUVM, void *pvData);
|
---|
[1] | 1167 |
|
---|
[55881] | 1168 | /** @} */
|
---|
[1] | 1169 |
|
---|
[39154] | 1170 | #endif /* IN_RING3 */
|
---|
| 1171 |
|
---|
[58111] | 1172 | /** @} */
|
---|
[20374] | 1173 | RT_C_DECLS_END
|
---|
[1] | 1174 |
|
---|
[3633] | 1175 | #endif
|
---|