VirtualBox

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

Last change on this file since 52664 was 44399, checked in by vboxsync, 12 years ago

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

© 2024 Oracle
Contact – Privacy/Do Not Sell My Info – Terms of Use