VirtualBox

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

Last change on this file since 73768 was 73448, checked in by vboxsync, 6 years ago

DBGCCmdHlpPrintfEx: format string markup fix.
  • 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
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(3, 4) 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 * 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 */
744DECLINLINE(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/**
758 * @copydoc DBGCCMDHLP::pfnStrPrintf
759 */
760DECLINLINE(size_t) RT_IPRT_FORMAT_ATTR(4, 5) DBGCCmdHlpStrPrintf(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
761 const char *pszFormat, ...)
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/**
774 * @copydoc DBGCCMDHLP::pfnVBoxError
775 */
776DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpVBoxError(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...)
777{
778 va_list va;
779
780 va_start(va, pszFormat);
781 rc = pCmdHlp->pfnVBoxErrorV(pCmdHlp, rc, pszFormat, va);
782 va_end(va);
783
784 return rc;
785}
786
787/**
788 * @copydoc DBGCCMDHLP::pfnMemRead
789 */
790DECLINLINE(int) DBGCCmdHlpMemRead(PDBGCCMDHLP pCmdHlp, void *pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t *pcbRead)
791{
792 return pCmdHlp->pfnMemRead(pCmdHlp, pvBuffer, cbRead, pVarPointer, pcbRead);
793}
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 */
805DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpEval(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, ...)
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 */
827DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpFail(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, ...)
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
839/**
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 */
858DECLINLINE(int) RT_IPRT_FORMAT_ATTR(4, 5) DBGCCmdHlpFailRc(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc,
859 const char *pszFormat, ...)
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 */
873DECLINLINE(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. */
888#define DBGC_CMDHLP_REQ_UVM_RET(pCmdHlp, pCmd, pUVM) \
889 do { \
890 if (!(pUVM)) \
891 return DBGCCmdHlpFail(pCmdHlp, pCmd, "No VM selected"); \
892 } while (0)
893
894/**
895 * @copydoc DBGCCMDHLP::pfnVarToDbgfAddr
896 */
897DECLINLINE(int) DBGCCmdHlpVarToDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress)
898{
899 return pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, pAddress);
900}
901
902/**
903 * @copydoc DBGCCMDHLP::pfnVarFromDbgfAddr
904 */
905DECLINLINE(int) DBGCCmdHlpVarFromDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGFADDRESS pAddress, PDBGCVAR pResult)
906{
907 return pCmdHlp->pfnVarFromDbgfAddr(pCmdHlp, pAddress, pResult);
908}
909
910/**
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 */
918DECLINLINE(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/**
928 * @copydoc DBGCCMDHLP::pfnVarToNumber
929 */
930DECLINLINE(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 */
938DECLINLINE(int) DBGCCmdHlpVarToBool(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf)
939{
940 return pCmdHlp->pfnVarToBool(pCmdHlp, pVar, pf);
941}
942
943/**
944 * @copydoc DBGCCMDHLP::pfnVarGetRange
945 */
946DECLINLINE(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/**
952 * @copydoc DBGCCMDHLP::pfnVarConvert
953 */
954DECLINLINE(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/**
960 * @copydoc DBGCCMDHLP::pfnGetDbgfOutputHlp
961 */
962DECLINLINE(PCDBGFINFOHLP) DBGCCmdHlpGetDbgfOutputHlp(PDBGCCMDHLP pCmdHlp)
963{
964 return pCmdHlp->pfnGetDbgfOutputHlp(pCmdHlp);
965}
966
967/**
968 * @copydoc DBGCCMDHLP::pfnGetCurrentCpu
969 */
970DECLINLINE(VMCPUID) DBGCCmdHlpGetCurrentCpu(PDBGCCMDHLP pCmdHlp)
971{
972 return pCmdHlp->pfnGetCurrentCpu(pCmdHlp);
973}
974
975/**
976 * @copydoc DBGCCMDHLP::pfnGetCpuMode
977 */
978DECLINLINE(CPUMMODE) DBGCCmdHlpGetCpuMode(PDBGCCMDHLP pCmdHlp)
979{
980 return pCmdHlp->pfnGetCpuMode(pCmdHlp);
981}
982
983#endif /* IN_RING3 */
984
985
986
987/**
988 * Command handler.
989 *
990 * The console will call the handler for a command once it's finished
991 * parsing the user input. The command handler function is responsible
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.
997 * @param pUVM The user mode VM handle, can in theory be NULL.
998 * @param paArgs Pointer to (readonly) array of arguments.
999 * @param cArgs Number of arguments in the array.
1000 */
1001typedef DECLCALLBACK(int) FNDBGCCMD(PCDBGCCMD pCmd, PDBGCCMDHLP pCmdHlp, PUVM pUVM, PCDBGCVAR paArgs, unsigned cArgs);
1002/** Pointer to a FNDBGCCMD() function. */
1003typedef FNDBGCCMD *PFNDBGCCMD;
1004
1005/**
1006 * DBGC command descriptor.
1007 */
1008typedef 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
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.
1046 * @param pUVM The user mode VM handle, can in theory be NULL.
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 */
1051typedef DECLCALLBACK(int) FNDBGCFUNC(PCDBGCFUNC pFunc, PDBGCCMDHLP pCmdHlp, PUVM pUVM, PCDBGCVAR paArgs, unsigned cArgs,
1052 PDBGCVAR pResult);
1053/** Pointer to a FNDBGCFUNC() function. */
1054typedef FNDBGCFUNC *PFNDBGCFUNC;
1055
1056/**
1057 * DBGC function descriptor.
1058 */
1059typedef 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
1083/** Pointer to a DBGC backend. */
1084typedef 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 */
1096typedef DECLCALLBACK(bool) FNDBGCBACKINPUT(PDBGCBACK pBack, uint32_t cMillies);
1097/** Pointer to a FNDBGCBACKINPUT() callback. */
1098typedef 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 */
1113typedef DECLCALLBACK(int) FNDBGCBACKREAD(PDBGCBACK pBack, void *pvBuf, size_t cbBuf, size_t *pcbRead);
1114/** Pointer to a FNDBGCBACKREAD() callback. */
1115typedef 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 */
1129typedef DECLCALLBACK(int) FNDBGCBACKWRITE(PDBGCBACK pBack, const void *pvBuf, size_t cbBuf, size_t *pcbWritten);
1130/** Pointer to a FNDBGCBACKWRITE() callback. */
1131typedef FNDBGCBACKWRITE *PFNDBGCBACKWRITE;
1132
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 */
1141typedef DECLCALLBACK(void) FNDBGCBACKSETREADY(PDBGCBACK pBack, bool fReady);
1142/** Pointer to a FNDBGCBACKSETREADY() callback. */
1143typedef FNDBGCBACKSETREADY *PFNDBGCBACKSETREADY;
1144
1145
1146/**
1147 * The communication backend provides the console with a number of callbacks
1148 * which can be used
1149 */
1150typedef struct DBGCBACK
1151{
1152 /** Check for input. */
1153 PFNDBGCBACKINPUT pfnInput;
1154 /** Read input. */
1155 PFNDBGCBACKREAD pfnRead;
1156 /** Write output. */
1157 PFNDBGCBACKWRITE pfnWrite;
1158 /** Ready / busy notification. */
1159 PFNDBGCBACKSETREADY pfnSetReady;
1160} DBGCBACK;
1161
1162DBGDECL(int) DBGCCreate(PUVM pUVM, PDBGCBACK pBack, unsigned fFlags);
1163DBGDECL(int) DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
1164DBGDECL(int) DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
1165DBGDECL(int) DBGCTcpCreate(PUVM pUVM, void **ppvUser);
1166DBGDECL(int) DBGCTcpTerminate(PUVM pUVM, void *pvData);
1167
1168/** @} */
1169
1170#endif /* IN_RING3 */
1171
1172/** @} */
1173RT_C_DECLS_END
1174
1175#endif
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use