VirtualBox

source: vbox/trunk/include/VBox/dbg.h@ 76507

Last change on this file since 76507 was 76507, checked in by vboxsync, 5 years ago

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use