VirtualBox

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

Last change on this file since 69107 was 69107, checked in by vboxsync, 7 years ago

include/VBox/: (C) year
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 38.1 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
33#include <VBox/cdefs.h>
34#include <VBox/types.h>
35#include <VBox/vmm/dbgf.h>
36
37#include <iprt/stdarg.h>
38#ifdef IN_RING3
39# include <iprt/err.h>
40#endif
41
42RT_C_DECLS_BEGIN
43
44
45
46/** @defgroup grp_dbg The VirtualBox Debugger
47 * @{
48 */
49
50#ifdef IN_RING3 /* The debugger stuff is ring-3 only. */
51
52/** @defgroup grp_dbgc The Debugger Console API
53 * @{
54 */
55
56/** @def VBOX_WITH_DEBUGGER
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.
59 */
60#ifdef DOXYGEN_RUNNING
61# define VBOX_WITH_DEBUGGER
62#endif
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 */
71typedef enum DBGCVARCAT
72{
73 /** Any type is fine. */
74 DBGCVAR_CAT_ANY = 0,
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,
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. */
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
101} DBGCVARCAT;
102
103
104/**
105 * DBGC variable type.
106 */
107typedef 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,
121 /** Number. */
122 DBGCVAR_TYPE_NUMBER,
123 /** String. */
124 DBGCVAR_TYPE_STRING,
125 /** Symbol. */
126 DBGCVAR_TYPE_SYMBOL,
127 /** Special type used when querying symbols. */
128 DBGCVAR_TYPE_ANY
129} DBGCVARTYPE;
130
131/** @todo Rename to DBGCVAR_IS_xyz. */
132
133/** Checks if the specified variable type is of a pointer persuasion. */
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. */
136#define DBGCVAR_IS_FAR_PTR(enmType) ((enmType) == DBGCVAR_TYPE_GC_FAR)
137/** Checks if the specified variable type is of a pointer persuasion and of the guest context sort. */
138#define DBGCVAR_ISGCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && (enmType) <= DBGCVAR_TYPE_GC_PHYS)
139/** Checks if the specified variable type is of a pointer persuasion and of the host context sort. */
140#define DBGCVAR_ISHCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_HC_FLAT && (enmType) <= DBGCVAR_TYPE_HC_PHYS)
141
142
143/**
144 * DBGC variable range type.
145 */
146typedef 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 */
160typedef 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;
165 /** Maximum number of occurrences.
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. */
178typedef DBGCVARDESC *PDBGCVARDESC;
179/** Pointer to a const argument descriptor. */
180typedef const DBGCVARDESC *PCDBGCVARDESC;
181
182/** Variable descriptor flags.
183 * @{ */
184/** Indicates that the variable depends on the previous being present. */
185#define DBGCVD_FLAGS_DEP_PREV RT_BIT(1)
186/** @} */
187
188
189/**
190 * DBGC variable.
191 */
192typedef 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. */
228typedef DBGCVAR *PDBGCVAR;
229/** Pointer to a const command argument. */
230typedef const DBGCVAR *PCDBGCVAR;
231
232
233/**
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/**
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/**
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/**
310 * Macro for initializing a DBGC variable with a number.
311 */
312#define DBGCVAR_INIT_NUMBER(pVar, Value) \
313 do { \
314 DBGCVAR_INIT(pVar); \
315 (pVar)->enmType = DBGCVAR_TYPE_NUMBER; \
316 (pVar)->u.u64Number = (Value); \
317 } while (0)
318
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)
330
331
332/**
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/**
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) \
352 do { \
353 (pVar)->enmRangeType = (_enmRangeType); \
354 (pVar)->u64Range = (Value); \
355 } while (0)
356
357
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
389/** Pointer to a command descriptor. */
390typedef struct DBGCCMD *PDBGCCMD;
391/** Pointer to a const command descriptor. */
392typedef const struct DBGCCMD *PCDBGCCMD;
393
394/** Pointer to a function descriptor. */
395typedef struct DBGCFUNC *PDBGCFUNC;
396/** Pointer to a const function descriptor. */
397typedef const struct DBGCFUNC *PCDBGCFUNC;
398
399/** Pointer to helper functions for commands. */
400typedef struct DBGCCMDHLP *PDBGCCMDHLP;
401
402
403/**
404 * Helper functions for commands.
405 */
406typedef struct DBGCCMDHLP
407{
408 /** Magic value (DBGCCMDHLP_MAGIC). */
409 uint32_t u32Magic;
410
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.
416 * @param pcbWritten Where to store the number of bytes written.
417 * This is optional.
418 * @param pszFormat The format string. This may use all IPRT extensions as
419 * well as the debugger ones.
420 * @param ... Arguments specified in the format string.
421 */
422 DECLCALLBACKMEMBER(int, pfnPrintf)(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten,
423 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
424
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.
430 * @param pcbWritten Where to store the number of bytes written.
431 * This is optional.
432 * @param pszFormat The format string. This may use all IPRT extensions as
433 * well as the debugger ones.
434 * @param args Arguments specified in the format string.
435 */
436 DECLCALLBACKMEMBER(int, pfnPrintfV)(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten,
437 const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
438
439 /**
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 */
450 DECLCALLBACKMEMBER(size_t, pfnStrPrintf)(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
451 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5);
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,
465 const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0);
466
467 /**
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 */
476 DECLCALLBACKMEMBER(int, pfnVBoxError)(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
477
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 */
487 DECLCALLBACKMEMBER(int, pfnVBoxErrorV)(PDBGCCMDHLP pCmdHlp, int rc,
488 const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
489
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 */
504 DECLCALLBACKMEMBER(int, pfnMemRead)(PDBGCCMDHLP pCmdHlp, void *pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t *pcbRead);
505
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 */
518 DECLCALLBACKMEMBER(int, pfnMemWrite)(PDBGCCMDHLP pCmdHlp, const void *pvBuffer, size_t cbWrite, PCDBGCVAR pVarPointer, size_t *pcbWritten);
519
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 */
529 DECLCALLBACKMEMBER(int, pfnExec)(PDBGCCMDHLP pCmdHlp, const char *pszExpr, ...) RT_IPRT_FORMAT_ATTR(2, 3);
530
531 /**
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 */
541 DECLCALLBACKMEMBER(int, pfnEvalV)(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult,
542 const char *pszExpr, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
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 */
554 DECLCALLBACKMEMBER(int, pfnFailV)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd,
555 const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
556
557 /**
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 */
571 DECLCALLBACKMEMBER(int, pfnFailRcV)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc,
572 const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0);
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 /**
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 /**
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 /**
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 /**
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
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 /**
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 /**
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
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
681 /** End marker (DBGCCMDHLP_MAGIC). */
682 uint32_t u32EndMarker;
683} DBGCCMDHLP;
684
685/** Magic value for DBGCCMDHLP::u32Magic. (Fyodor Mikhaylovich Dostoyevsky) */
686#define DBGCCMDHLP_MAGIC UINT32_C(18211111)
687
688
689#if defined(IN_RING3) || defined(IN_SLICKEDIT)
690
691/**
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.
699 */
700DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) DBGCCmdHlpPrintf(PDBGCCMDHLP pCmdHlp, const char *pszFormat, ...)
701{
702 va_list va;
703 int rc;
704
705 va_start(va, pszFormat);
706 rc = pCmdHlp->pfnPrintfV(pCmdHlp, NULL, pszFormat, va);
707 va_end(va);
708
709 return rc;
710}
711
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 */
722DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) DBGCCmdHlpPrintfEx(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten,
723 const char *pszFormat, ...)
724{
725 va_list va;
726 int rc;
727
728 va_start(va, pszFormat);
729 rc = pCmdHlp->pfnPrintfV(pCmdHlp, pcbWritten, pszFormat, va);
730 va_end(va);
731
732 return rc;
733}
734
735/**
736 * @copydoc DBGCCMDHLP::pfnStrPrintf
737 */
738DECLINLINE(size_t) RT_IPRT_FORMAT_ATTR(4, 5) DBGCCmdHlpStrPrintf(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
739 const char *pszFormat, ...)
740{
741 va_list va;
742 size_t cch;
743
744 va_start(va, pszFormat);
745 cch = pCmdHlp->pfnStrPrintfV(pCmdHlp, pszBuf, cbBuf, pszFormat, va);
746 va_end(va);
747
748 return cch;
749}
750
751/**
752 * @copydoc DBGCCMDHLP::pfnVBoxError
753 */
754DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpVBoxError(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...)
755{
756 va_list va;
757
758 va_start(va, pszFormat);
759 rc = pCmdHlp->pfnVBoxErrorV(pCmdHlp, rc, pszFormat, va);
760 va_end(va);
761
762 return rc;
763}
764
765/**
766 * @copydoc DBGCCMDHLP::pfnMemRead
767 */
768DECLINLINE(int) DBGCCmdHlpMemRead(PDBGCCMDHLP pCmdHlp, void *pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t *pcbRead)
769{
770 return pCmdHlp->pfnMemRead(pCmdHlp, pvBuffer, cbRead, pVarPointer, pcbRead);
771}
772
773/**
774 * Evaluates an expression.
775 * (Hopefully the parser and functions are fully reentrant.)
776 *
777 * @returns VBox status code appropriate to return from a command.
778 * @param pCmdHlp Pointer to the command callback structure.
779 * @param pResult Where to store the result.
780 * @param pszExpr The expression. Format string with the format DBGC extensions.
781 * @param ... Format arguments.
782 */
783DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpEval(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, ...)
784{
785 va_list va;
786 int rc;
787
788 va_start(va, pszExpr);
789 rc = pCmdHlp->pfnEvalV(pCmdHlp, pResult, pszExpr, va);
790 va_end(va);
791
792 return rc;
793}
794
795/**
796 * Print an error and fail the current command.
797 *
798 * @returns VBox status code to pass upwards.
799 *
800 * @param pCmdHlp Pointer to the command callback structure.
801 * @param pCmd The failing command.
802 * @param pszFormat The error message format string.
803 * @param ... Format arguments.
804 */
805DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpFail(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, ...)
806{
807 va_list va;
808 int rc;
809
810 va_start(va, pszFormat);
811 rc = pCmdHlp->pfnFailV(pCmdHlp, pCmd, pszFormat, va);
812 va_end(va);
813
814 return rc;
815}
816
817/**
818 * Print an error and fail the current command.
819 *
820 * Usage example:
821 * @code
822 int rc = VMMR3Something(pVM);
823 if (RT_FAILURE(rc))
824 return DBGCCmdHlpFailRc(pCmdHlp, pCmd, rc, "VMMR3Something");
825 return VINF_SUCCESS;
826 * @endcode
827 *
828 * @returns VBox status code to pass upwards.
829 *
830 * @param pCmdHlp Pointer to the command callback structure.
831 * @param pCmd The failing command.
832 * @param rc The status code indicating the failure.
833 * @param pszFormat The error message format string.
834 * @param ... Format arguments.
835 */
836DECLINLINE(int) RT_IPRT_FORMAT_ATTR(4, 5) DBGCCmdHlpFailRc(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc,
837 const char *pszFormat, ...)
838{
839 va_list va;
840
841 va_start(va, pszFormat);
842 rc = pCmdHlp->pfnFailRcV(pCmdHlp, pCmd, rc, pszFormat, va);
843 va_end(va);
844
845 return rc;
846}
847
848/**
849 * @copydoc DBGCCMDHLP::pfnParserError
850 */
851DECLINLINE(int) DBGCCmdHlpParserError(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int iArg, const char *pszExpr, unsigned iLine)
852{
853 return pCmdHlp->pfnParserError(pCmdHlp, pCmd, iArg, pszExpr, iLine);
854}
855
856/** Assert+return like macro for checking parser sanity.
857 * Returns with failure if the precodition is not met. */
858#define DBGC_CMDHLP_ASSERT_PARSER_RET(pCmdHlp, pCmd, iArg, expr) \
859 do { \
860 if (!(expr)) \
861 return DBGCCmdHlpParserError(pCmdHlp, pCmd, iArg, #expr, __LINE__); \
862 } while (0)
863
864/** Assert+return like macro that the VM handle is present.
865 * Returns with failure if the VM handle is NIL. */
866#define DBGC_CMDHLP_REQ_UVM_RET(pCmdHlp, pCmd, pUVM) \
867 do { \
868 if (!(pUVM)) \
869 return DBGCCmdHlpFail(pCmdHlp, pCmd, "No VM selected"); \
870 } while (0)
871
872/**
873 * @copydoc DBGCCMDHLP::pfnVarToDbgfAddr
874 */
875DECLINLINE(int) DBGCCmdHlpVarToDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress)
876{
877 return pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, pAddress);
878}
879
880/**
881 * @copydoc DBGCCMDHLP::pfnVarFromDbgfAddr
882 */
883DECLINLINE(int) DBGCCmdHlpVarFromDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGFADDRESS pAddress, PDBGCVAR pResult)
884{
885 return pCmdHlp->pfnVarFromDbgfAddr(pCmdHlp, pAddress, pResult);
886}
887
888/**
889 * Converts an variable to a flat address.
890 *
891 * @returns VBox status code.
892 * @param pCmdHlp Pointer to the command callback structure.
893 * @param pVar The variable to convert.
894 * @param pFlatPtr Where to store the flat address.
895 */
896DECLINLINE(int) DBGCCmdHlpVarToFlatAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PRTGCPTR pFlatPtr)
897{
898 DBGFADDRESS Addr;
899 int rc = pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, &Addr);
900 if (RT_SUCCESS(rc))
901 *pFlatPtr = Addr.FlatPtr;
902 return rc;
903}
904
905/**
906 * @copydoc DBGCCMDHLP::pfnVarToNumber
907 */
908DECLINLINE(int) DBGCCmdHlpVarToNumber(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number)
909{
910 return pCmdHlp->pfnVarToNumber(pCmdHlp, pVar, pu64Number);
911}
912
913/**
914 * @copydoc DBGCCMDHLP::pfnVarToBool
915 */
916DECLINLINE(int) DBGCCmdHlpVarToBool(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf)
917{
918 return pCmdHlp->pfnVarToBool(pCmdHlp, pVar, pf);
919}
920
921/**
922 * @copydoc DBGCCMDHLP::pfnVarGetRange
923 */
924DECLINLINE(int) DBGCCmdHlpVarGetRange(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault, uint64_t *pcbRange)
925{
926 return pCmdHlp->pfnVarGetRange(pCmdHlp, pVar, cbElement, cbDefault, pcbRange);
927}
928
929/**
930 * @copydoc DBGCCMDHLP::pfnVarConvert
931 */
932DECLINLINE(int) DBGCCmdHlpConvert(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms, PDBGCVAR pResult)
933{
934 return pCmdHlp->pfnVarConvert(pCmdHlp, pVar, enmToType, fConvSyms, pResult);
935}
936
937/**
938 * @copydoc DBGCCMDHLP::pfnGetDbgfOutputHlp
939 */
940DECLINLINE(PCDBGFINFOHLP) DBGCCmdHlpGetDbgfOutputHlp(PDBGCCMDHLP pCmdHlp)
941{
942 return pCmdHlp->pfnGetDbgfOutputHlp(pCmdHlp);
943}
944
945/**
946 * @copydoc DBGCCMDHLP::pfnGetCurrentCpu
947 */
948DECLINLINE(VMCPUID) DBGCCmdHlpGetCurrentCpu(PDBGCCMDHLP pCmdHlp)
949{
950 return pCmdHlp->pfnGetCurrentCpu(pCmdHlp);
951}
952
953/**
954 * @copydoc DBGCCMDHLP::pfnGetCpuMode
955 */
956DECLINLINE(CPUMMODE) DBGCCmdHlpGetCpuMode(PDBGCCMDHLP pCmdHlp)
957{
958 return pCmdHlp->pfnGetCpuMode(pCmdHlp);
959}
960
961#endif /* IN_RING3 */
962
963
964
965/**
966 * Command handler.
967 *
968 * The console will call the handler for a command once it's finished
969 * parsing the user input. The command handler function is responsible
970 * for executing the command itself.
971 *
972 * @returns VBox status.
973 * @param pCmd Pointer to the command descriptor (as registered).
974 * @param pCmdHlp Pointer to command helper functions.
975 * @param pUVM The user mode VM handle, can in theory be NULL.
976 * @param paArgs Pointer to (readonly) array of arguments.
977 * @param cArgs Number of arguments in the array.
978 */
979typedef DECLCALLBACK(int) FNDBGCCMD(PCDBGCCMD pCmd, PDBGCCMDHLP pCmdHlp, PUVM pUVM, PCDBGCVAR paArgs, unsigned cArgs);
980/** Pointer to a FNDBGCCMD() function. */
981typedef FNDBGCCMD *PFNDBGCCMD;
982
983/**
984 * DBGC command descriptor.
985 */
986typedef struct DBGCCMD
987{
988 /** Command string. */
989 const char *pszCmd;
990 /** Minimum number of arguments. */
991 unsigned cArgsMin;
992 /** Max number of arguments. */
993 unsigned cArgsMax;
994 /** Argument descriptors (array). */
995 PCDBGCVARDESC paArgDescs;
996 /** Number of argument descriptors. */
997 unsigned cArgDescs;
998 /** flags. (reserved for now) */
999 unsigned fFlags;
1000 /** Handler function. */
1001 PFNDBGCCMD pfnHandler;
1002 /** Command syntax. */
1003 const char *pszSyntax;
1004 /** Command description. */
1005 const char *pszDescription;
1006} DBGCCMD;
1007
1008/** DBGCCMD Flags.
1009 * @{
1010 */
1011/** @} */
1012
1013
1014/**
1015 * Function handler.
1016 *
1017 * The console will call the handler for a command once it's finished
1018 * parsing the user input. The command handler function is responsible
1019 * for executing the command itself.
1020 *
1021 * @returns VBox status.
1022 * @param pCmd Pointer to the command descriptor (as registered).
1023 * @param pCmdHlp Pointer to command helper functions.
1024 * @param pUVM The user mode VM handle, can in theory be NULL.
1025 * @param paArgs Pointer to (readonly) array of arguments.
1026 * @param cArgs Number of arguments in the array.
1027 * @param pResult Where to return the result.
1028 */
1029typedef DECLCALLBACK(int) FNDBGCFUNC(PCDBGCFUNC pFunc, PDBGCCMDHLP pCmdHlp, PUVM pUVM, PCDBGCVAR paArgs, unsigned cArgs,
1030 PDBGCVAR pResult);
1031/** Pointer to a FNDBGCFUNC() function. */
1032typedef FNDBGCFUNC *PFNDBGCFUNC;
1033
1034/**
1035 * DBGC function descriptor.
1036 */
1037typedef struct DBGCFUNC
1038{
1039 /** Command string. */
1040 const char *pszFuncNm;
1041 /** Minimum number of arguments. */
1042 unsigned cArgsMin;
1043 /** Max number of arguments. */
1044 unsigned cArgsMax;
1045 /** Argument descriptors (array). */
1046 PCDBGCVARDESC paArgDescs;
1047 /** Number of argument descriptors. */
1048 unsigned cArgDescs;
1049 /** flags. (reserved for now) */
1050 unsigned fFlags;
1051 /** Handler function. */
1052 PFNDBGCFUNC pfnHandler;
1053 /** Function syntax. */
1054 const char *pszSyntax;
1055 /** Function description. */
1056 const char *pszDescription;
1057} DBGCFUNC;
1058
1059
1060
1061/** Pointer to a DBGC backend. */
1062typedef struct DBGCBACK *PDBGCBACK;
1063
1064/**
1065 * Checks if there is input.
1066 *
1067 * @returns true if there is input ready.
1068 * @returns false if there not input ready.
1069 * @param pBack Pointer to the backend structure supplied by
1070 * the backend. The backend can use this to find
1071 * it's instance data.
1072 * @param cMillies Number of milliseconds to wait on input data.
1073 */
1074typedef DECLCALLBACK(bool) FNDBGCBACKINPUT(PDBGCBACK pBack, uint32_t cMillies);
1075/** Pointer to a FNDBGCBACKINPUT() callback. */
1076typedef FNDBGCBACKINPUT *PFNDBGCBACKINPUT;
1077
1078/**
1079 * Read input.
1080 *
1081 * @returns VBox status code.
1082 * @param pBack Pointer to the backend structure supplied by
1083 * the backend. The backend can use this to find
1084 * it's instance data.
1085 * @param pvBuf Where to put the bytes we read.
1086 * @param cbBuf Maximum nymber of bytes to read.
1087 * @param pcbRead Where to store the number of bytes actually read.
1088 * If NULL the entire buffer must be filled for a
1089 * successful return.
1090 */
1091typedef DECLCALLBACK(int) FNDBGCBACKREAD(PDBGCBACK pBack, void *pvBuf, size_t cbBuf, size_t *pcbRead);
1092/** Pointer to a FNDBGCBACKREAD() callback. */
1093typedef FNDBGCBACKREAD *PFNDBGCBACKREAD;
1094
1095/**
1096 * Write (output).
1097 *
1098 * @returns VBox status code.
1099 * @param pBack Pointer to the backend structure supplied by
1100 * the backend. The backend can use this to find
1101 * it's instance data.
1102 * @param pvBuf What to write.
1103 * @param cbBuf Number of bytes to write.
1104 * @param pcbWritten Where to store the number of bytes actually written.
1105 * If NULL the entire buffer must be successfully written.
1106 */
1107typedef DECLCALLBACK(int) FNDBGCBACKWRITE(PDBGCBACK pBack, const void *pvBuf, size_t cbBuf, size_t *pcbWritten);
1108/** Pointer to a FNDBGCBACKWRITE() callback. */
1109typedef FNDBGCBACKWRITE *PFNDBGCBACKWRITE;
1110
1111/**
1112 * Ready / busy notification.
1113 *
1114 * @param pBack Pointer to the backend structure supplied by
1115 * the backend. The backend can use this to find
1116 * it's instance data.
1117 * @param fReady Whether it's ready (true) or busy (false).
1118 */
1119typedef DECLCALLBACK(void) FNDBGCBACKSETREADY(PDBGCBACK pBack, bool fReady);
1120/** Pointer to a FNDBGCBACKSETREADY() callback. */
1121typedef FNDBGCBACKSETREADY *PFNDBGCBACKSETREADY;
1122
1123
1124/**
1125 * The communication backend provides the console with a number of callbacks
1126 * which can be used
1127 */
1128typedef struct DBGCBACK
1129{
1130 /** Check for input. */
1131 PFNDBGCBACKINPUT pfnInput;
1132 /** Read input. */
1133 PFNDBGCBACKREAD pfnRead;
1134 /** Write output. */
1135 PFNDBGCBACKWRITE pfnWrite;
1136 /** Ready / busy notification. */
1137 PFNDBGCBACKSETREADY pfnSetReady;
1138} DBGCBACK;
1139
1140DBGDECL(int) DBGCCreate(PUVM pUVM, PDBGCBACK pBack, unsigned fFlags);
1141DBGDECL(int) DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
1142DBGDECL(int) DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
1143DBGDECL(int) DBGCTcpCreate(PUVM pUVM, void **ppvUser);
1144DBGDECL(int) DBGCTcpTerminate(PUVM pUVM, void *pvData);
1145
1146/** @} */
1147
1148#endif /* IN_RING3 */
1149
1150/** @} */
1151RT_C_DECLS_END
1152
1153#endif
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use