VirtualBox

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

Last change on this file since 31948 was 31927, checked in by vboxsync, 14 years ago

dbg.h: Fixed DBGCVAR_INIT_NUMBER.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 28.0 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-2007 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/dbgf.h>
36
37#include <iprt/stdarg.h>
38
39RT_C_DECLS_BEGIN
40
41/** @def VBOX_WITH_DEBUGGER
42 * The build is with debugger module. Test if this is defined before registering
43 * external debugger commands. This is normally defined in Config.kmk.
44 */
45#ifdef DOXYGEN_RUNNING
46# define VBOX_WITH_DEBUGGER
47#endif
48
49
50/**
51 * DBGC variable category.
52 *
53 * Used to describe an argument to a command or function and a functions
54 * return value.
55 */
56typedef enum DBGCVARCAT
57{
58 /** Any type is fine. */
59 DBGCVAR_CAT_ANY = 0,
60 /** Any kind of pointer. */
61 DBGCVAR_CAT_POINTER,
62 /** Any kind of pointer with no range option. */
63 DBGCVAR_CAT_POINTER_NO_RANGE,
64 /** GC pointer. */
65 DBGCVAR_CAT_GC_POINTER,
66 /** GC pointer with no range option. */
67 DBGCVAR_CAT_GC_POINTER_NO_RANGE,
68 /** Numeric argument. */
69 DBGCVAR_CAT_NUMBER,
70 /** Numeric argument with no range option. */
71 DBGCVAR_CAT_NUMBER_NO_RANGE,
72 /** String. */
73 DBGCVAR_CAT_STRING,
74 /** Symbol. */
75 DBGCVAR_CAT_SYMBOL,
76 /** Option. */
77 DBGCVAR_CAT_OPTION,
78 /** Option + string. */
79 DBGCVAR_CAT_OPTION_STRING,
80 /** Option + number. */
81 DBGCVAR_CAT_OPTION_NUMBER
82} DBGCVARCAT;
83
84
85/**
86 * DBGC variable type.
87 */
88typedef enum DBGCVARTYPE
89{
90 /** unknown... */
91 DBGCVAR_TYPE_UNKNOWN = 0,
92 /** Flat GC pointer. */
93 DBGCVAR_TYPE_GC_FLAT,
94 /** Segmented GC pointer. */
95 DBGCVAR_TYPE_GC_FAR,
96 /** Physical GC pointer. */
97 DBGCVAR_TYPE_GC_PHYS,
98 /** Flat HC pointer. */
99 DBGCVAR_TYPE_HC_FLAT,
100 /** Segmented HC pointer. */
101 DBGCVAR_TYPE_HC_FAR,
102 /** Physical HC pointer. */
103 DBGCVAR_TYPE_HC_PHYS,
104 /** String. */
105 DBGCVAR_TYPE_STRING,
106 /** Number. */
107 DBGCVAR_TYPE_NUMBER,
108 /** Symbol. */
109 DBGCVAR_TYPE_SYMBOL,
110 /** Special type used when querying symbols. */
111 DBGCVAR_TYPE_ANY
112} DBGCVARTYPE;
113
114/** @todo Rename to DBGCVAR_IS_xyz. */
115
116/** Checks if the specified variable type is of a pointer persuasion. */
117#define DBGCVAR_ISPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && enmType <= DBGCVAR_TYPE_HC_PHYS)
118/** Checks if the specified variable type is of a pointer persuasion. */
119#define DBGCVAR_IS_FAR_PTR(enmType) ((enmType) == DBGCVAR_TYPE_GC_FAR || (enmType) == DBGCVAR_TYPE_HC_FAR)
120/** Checks if the specified variable type is of a pointer persuasion and of the guest context sort. */
121#define DBGCVAR_ISGCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && (enmType) <= DBGCVAR_TYPE_GC_PHYS)
122/** Checks if the specified variable type is of a pointer persuasion and of the host context sort. */
123#define DBGCVAR_ISHCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_HC_FLAT && (enmType) <= DBGCVAR_TYPE_HC_PHYS)
124
125
126/**
127 * DBGC variable range type.
128 */
129typedef enum DBGCVARRANGETYPE
130{
131 /** No range appliable or no range specified. */
132 DBGCVAR_RANGE_NONE = 0,
133 /** Number of elements. */
134 DBGCVAR_RANGE_ELEMENTS,
135 /** Number of bytes. */
136 DBGCVAR_RANGE_BYTES
137} DBGCVARRANGETYPE;
138
139
140/**
141 * Variable descriptor.
142 */
143typedef struct DBGCVARDESC
144{
145 /** The minimal number of times this argument may occur.
146 * Use 0 here to inidicate that the argument is optional. */
147 unsigned cTimesMin;
148 /** Maximum number of occurences.
149 * Use ~0 here to indicate infinite. */
150 unsigned cTimesMax;
151 /** Argument category. */
152 DBGCVARCAT enmCategory;
153 /** Flags, DBGCVD_FLAGS_* */
154 unsigned fFlags;
155 /** Argument name. */
156 const char *pszName;
157 /** Argument name. */
158 const char *pszDescription;
159} DBGCVARDESC;
160/** Pointer to an argument descriptor. */
161typedef DBGCVARDESC *PDBGCVARDESC;
162/** Pointer to a const argument descriptor. */
163typedef const DBGCVARDESC *PCDBGCVARDESC;
164
165/** Variable descriptor flags.
166 * @{ */
167/** Indicates that the variable depends on the previous being present. */
168#define DBGCVD_FLAGS_DEP_PREV RT_BIT(1)
169/** @} */
170
171
172/**
173 * DBGC variable.
174 */
175typedef struct DBGCVAR
176{
177 /** Pointer to the argument descriptor. */
178 PCDBGCVARDESC pDesc;
179 /** Pointer to the next argument. */
180 struct DBGCVAR *pNext;
181
182 /** Argument type. */
183 DBGCVARTYPE enmType;
184 /** Type specific. */
185 union
186 {
187 /** Flat GC Address. (DBGCVAR_TYPE_GC_FLAT) */
188 RTGCPTR GCFlat;
189 /** Far (16:32) GC Address. (DBGCVAR_TYPE_GC_FAR) */
190 RTFAR32 GCFar;
191 /** Physical GC Address. (DBGCVAR_TYPE_GC_PHYS) */
192 RTGCPHYS GCPhys;
193 /** Flat HC Address. (DBGCVAR_TYPE_HC_FLAT) */
194 void *pvHCFlat;
195 /** Far (16:32) HC Address. (DBGCVAR_TYPE_HC_FAR) */
196 RTFAR32 HCFar;
197 /** Physical GC Address. (DBGCVAR_TYPE_HC_PHYS) */
198 RTHCPHYS HCPhys;
199 /** String. (DBGCVAR_TYPE_STRING)
200 * The basic idea is the the this is a pointer to the expression we're
201 * parsing, so no messing with freeing. */
202 const char *pszString;
203 /** Number. (DBGCVAR_TYPE_NUMBER) */
204 uint64_t u64Number;
205 } u;
206
207 /** Range type. */
208 DBGCVARRANGETYPE enmRangeType;
209 /** Range. The use of the content depends on the enmRangeType. */
210 uint64_t u64Range;
211} DBGCVAR;
212/** Pointer to a command argument. */
213typedef DBGCVAR *PDBGCVAR;
214/** Pointer to a const command argument. */
215typedef const DBGCVAR *PCDBGCVAR;
216
217
218/**
219 * Macro for initializing a DBGC variable with defaults.
220 * The result is an unknown variable type without any range.
221 */
222#define DBGCVAR_INIT(pVar) \
223 do { \
224 (pVar)->pDesc = NULL;\
225 (pVar)->pNext = NULL; \
226 (pVar)->enmType = DBGCVAR_TYPE_UNKNOWN; \
227 (pVar)->u.u64Number = 0; \
228 (pVar)->enmRangeType = DBGCVAR_RANGE_NONE; \
229 (pVar)->u64Range = 0; \
230 } while (0)
231
232/**
233 * Macro for initializing a DBGC variable with a HC physical address.
234 */
235#define DBGCVAR_INIT_HC_PHYS(pVar, Phys) \
236 do { \
237 DBGCVAR_INIT(pVar); \
238 (pVar)->enmType = DBGCVAR_TYPE_HC_PHYS; \
239 (pVar)->u.HCPhys = (Phys); \
240 } while (0)
241
242/**
243 * Macro for initializing a DBGC variable with a HC flat address.
244 */
245#define DBGCVAR_INIT_HC_FLAT(pVar, Flat) \
246 do { \
247 DBGCVAR_INIT(pVar); \
248 (pVar)->enmType = DBGCVAR_TYPE_HC_FLAT; \
249 (pVar)->u.pvHCFlat = (Flat); \
250 } while (0)
251
252/**
253 * Macro for initializing a DBGC variable with a GC physical address.
254 */
255#define DBGCVAR_INIT_GC_PHYS(pVar, Phys) \
256 do { \
257 DBGCVAR_INIT(pVar); \
258 (pVar)->enmType = DBGCVAR_TYPE_GC_PHYS; \
259 (pVar)->u.GCPhys = (Phys); \
260 } while (0)
261
262/**
263 * Macro for initializing a DBGC variable with a GC flat address.
264 */
265#define DBGCVAR_INIT_GC_FLAT(pVar, Flat) \
266 do { \
267 DBGCVAR_INIT(pVar); \
268 (pVar)->enmType = DBGCVAR_TYPE_GC_FLAT; \
269 (pVar)->u.GCFlat = (Flat); \
270 } while (0)
271
272/**
273 * Macro for initializing a DBGC variable with a GC far address.
274 */
275#define DBGCVAR_INIT_GC_FAR(pVar, _sel, _off) \
276 do { \
277 DBGCVAR_INIT(pVar); \
278 (pVar)->enmType = DBGCVAR_TYPE_GC_FAR; \
279 (pVar)->u.GCFar.sel = (_sel); \
280 (pVar)->u.GCFar.off = (_off); \
281 } while (0)
282
283/**
284 * Macro for initializing a DBGC variable with a number
285 */
286#define DBGCVAR_INIT_NUMBER(pVar, Value) \
287 do { \
288 DBGCVAR_INIT(pVar); \
289 (pVar)->enmType = DBGCVAR_TYPE_NUMBER; \
290 (pVar)->u.u64Number = (Value); \
291 } while (0)
292
293
294/**
295 * Macro for setting the range of a DBGC variable.
296 * @param pVar The variable.
297 * @param _enmRangeType The range type.
298 * @param Value The range length value.
299 */
300#define DBGCVAR_SET_RANGE(pVar, _enmRangeType, Value) \
301 do { \
302 (pVar)->enmRangeType = (_enmRangeType); \
303 (pVar)->u64Range = (Value); \
304 } while (0)
305
306
307/** Pointer to command descriptor. */
308typedef struct DBGCCMD *PDBGCCMD;
309/** Pointer to const command descriptor. */
310typedef const struct DBGCCMD *PCDBGCCMD;
311
312/** Pointer to helper functions for commands. */
313typedef struct DBGCCMDHLP *PDBGCCMDHLP;
314
315/**
316 * Command helper for writing text to the debug console.
317 *
318 * @returns VBox status.
319 * @param pCmdHlp Pointer to the command callback structure.
320 * @param pvBuf What to write.
321 * @param cbBuf Number of bytes to write.
322 * @param pcbWritten Where to store the number of bytes actually written.
323 * If NULL the entire buffer must be successfully written.
324 */
325typedef DECLCALLBACK(int) FNDBGCHLPWRITE(PDBGCCMDHLP pCmdHlp, const void *pvBuf, size_t cbBuf, size_t *pcbWritten);
326/** Pointer to a FNDBGCHLPWRITE() function. */
327typedef FNDBGCHLPWRITE *PFNDBGCHLPWRITE;
328
329/**
330 * Command helper for writing formatted text to the debug console.
331 *
332 * @returns VBox status.
333 * @param pCmdHlp Pointer to the command callback structure.
334 * @param pcb Where to store the number of bytes written.
335 * @param pszFormat The format string.
336 * This is using the log formatter, so it's format extensions can be used.
337 * @param ... Arguments specified in the format string.
338 */
339typedef DECLCALLBACK(int) FNDBGCHLPPRINTF(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten, const char *pszFormat, ...);
340/** Pointer to a FNDBGCHLPPRINTF() function. */
341typedef FNDBGCHLPPRINTF *PFNDBGCHLPPRINTF;
342
343/**
344 * Command helper for writing formatted text to the debug console.
345 *
346 * @returns VBox status.
347 * @param pCmdHlp Pointer to the command callback structure.
348 * @param pcb Where to store the number of bytes written.
349 * @param pszFormat The format string.
350 * This is using the log formatter, so it's format extensions can be used.
351 * @param args Arguments specified in the format string.
352 */
353typedef DECLCALLBACK(int) FNDBGCHLPPRINTFV(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten, const char *pszFormat, va_list args);
354/** Pointer to a FNDBGCHLPPRINTFV() function. */
355typedef FNDBGCHLPPRINTFV *PFNDBGCHLPPRINTFV;
356
357/**
358 * Command helper for formatting and error message for a VBox status code.
359 *
360 * @returns VBox status code appropriate to return from a command.
361 * @param pCmdHlp Pointer to the command callback structure.
362 * @param rc The VBox status code.
363 * @param pszFormat Format string for additional messages. Can be NULL.
364 * @param ... Format arguments, optional.
365 */
366typedef DECLCALLBACK(int) FNDBGCHLPVBOXERROR(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...);
367/** Pointer to a FNDBGCHLPVBOXERROR() function. */
368typedef FNDBGCHLPVBOXERROR *PFNDBGCHLPVBOXERROR;
369
370/**
371 * Command helper for formatting and error message for a VBox status code.
372 *
373 * @returns VBox status code appropriate to return from a command.
374 * @param pCmdHlp Pointer to the command callback structure.
375 * @param rc The VBox status code.
376 * @param pcb Where to store the number of bytes written.
377 * @param pszFormat Format string for additional messages. Can be NULL.
378 * @param args Format arguments, optional.
379 */
380typedef DECLCALLBACK(int) FNDBGCHLPVBOXERRORV(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, va_list args);
381/** Pointer to a FNDBGCHLPVBOXERRORV() function. */
382typedef FNDBGCHLPVBOXERRORV *PFNDBGCHLPVBOXERRORV;
383
384/**
385 * Command helper for reading memory specified by a DBGC variable.
386 *
387 * @returns VBox status code appropriate to return from a command.
388 * @param pCmdHlp Pointer to the command callback structure.
389 * @param pVM VM handle if GC or physical HC address.
390 * @param pvBuffer Where to store the read data.
391 * @param cbRead Number of bytes to read.
392 * @param pVarPointer DBGC variable specifying where to start reading.
393 * @param pcbRead Where to store the number of bytes actually read.
394 * This optional, but it's useful when read GC virtual memory where a
395 * page in the requested range might not be present.
396 * If not specified not-present failure or end of a HC physical page
397 * will cause failure.
398 */
399typedef DECLCALLBACK(int) FNDBGCHLPMEMREAD(PDBGCCMDHLP pCmdHlp, PVM pVM, void *pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t *pcbRead);
400/** Pointer to a FNDBGCHLPMEMREAD() function. */
401typedef FNDBGCHLPMEMREAD *PFNDBGCHLPMEMREAD;
402
403/**
404 * Command helper for writing memory specified by a DBGC variable.
405 *
406 * @returns VBox status code appropriate to return from a command.
407 * @param pCmdHlp Pointer to the command callback structure.
408 * @param pVM VM handle if GC or physical HC address.
409 * @param pvBuffer What to write.
410 * @param cbWrite Number of bytes to write.
411 * @param pVarPointer DBGC variable specifying where to start reading.
412 * @param pcbWritten Where to store the number of bytes written.
413 * This is optional. If NULL be aware that some of the buffer
414 * might have been written to the specified address.
415 */
416typedef DECLCALLBACK(int) FNDBGCHLPMEMWRITE(PDBGCCMDHLP pCmdHlp, PVM pVM, const void *pvBuffer, size_t cbWrite, PCDBGCVAR pVarPointer, size_t *pcbWritten);
417/** Pointer to a FNDBGCHLPMEMWRITE() function. */
418typedef FNDBGCHLPMEMWRITE *PFNDBGCHLPMEMWRITE;
419
420
421
422/**
423 * Executes command an expression.
424 * (Hopefully the parser and functions are fully reentrant.)
425 *
426 * @returns VBox status code appropriate to return from a command.
427 * @param pCmdHlp Pointer to the command callback structure.
428 * @param pszExpr The expression. Format string with the format DBGC extensions.
429 * @param ... Format arguments.
430 */
431typedef DECLCALLBACK(int) FNDBGCHLPEXEC(PDBGCCMDHLP pCmdHlp, const char *pszExpr, ...);
432/** Pointer to a FNDBGCHLPEVAL() function. */
433typedef FNDBGCHLPEXEC *PFNDBGCHLPEXEC;
434
435
436/**
437 * Helper functions for commands.
438 */
439typedef struct DBGCCMDHLP
440{
441 /** Pointer to a FNDBCHLPWRITE() function. */
442 PFNDBGCHLPWRITE pfnWrite;
443 /** Pointer to a FNDBGCHLPPRINTF() function. */
444 PFNDBGCHLPPRINTF pfnPrintf;
445 /** Pointer to a FNDBGCHLPPRINTFV() function. */
446 PFNDBGCHLPPRINTFV pfnPrintfV;
447 /** Pointer to a FNDBGCHLPVBOXERROR() function. */
448 PFNDBGCHLPVBOXERROR pfnVBoxError;
449 /** Pointer to a FNDBGCHLPVBOXERRORV() function. */
450 PFNDBGCHLPVBOXERRORV pfnVBoxErrorV;
451 /** Pointer to a FNDBGCHLPMEMREAD() function. */
452 PFNDBGCHLPMEMREAD pfnMemRead;
453 /** Pointer to a FNDBGCHLPMEMWRITE() function. */
454 PFNDBGCHLPMEMWRITE pfnMemWrite;
455 /** Pointer to a FNDBGCHLPEXEC() function. */
456 PFNDBGCHLPEXEC pfnExec;
457
458 /**
459 * Evaluates an expression.
460 * (Hopefully the parser and functions are fully reentrant.)
461 *
462 * @returns VBox status code appropriate to return from a command.
463 * @param pCmdHlp Pointer to the command callback structure.
464 * @param pResult Where to store the result.
465 * @param pszExpr The expression. Format string with the format DBGC extensions.
466 * @param va Format arguments.
467 */
468 DECLCALLBACKMEMBER(int, pfnEvalV)(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, va_list va);
469
470 /**
471 * Print an error and fail the current command.
472 *
473 * @returns VBox status code to pass upwards.
474 *
475 * @param pCmdHlp Pointer to the command callback structure.
476 * @param pCmd The failing command.
477 * @param pszFormat The error message format string.
478 * @param va Format arguments.
479 */
480 DECLCALLBACKMEMBER(int, pfnFailV)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, va_list va);
481
482 /**
483 * Converts a DBGC variable to a DBGF address structure.
484 *
485 * @returns VBox status code.
486 * @param pCmdHlp Pointer to the command callback structure.
487 * @param pVar The variable to convert.
488 * @param pAddress The target address.
489 */
490 DECLCALLBACKMEMBER(int, pfnVarToDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress);
491
492 /**
493 * Converts a DBGC variable to a boolean.
494 *
495 * @returns VBox status code.
496 * @param pCmdHlp Pointer to the command callback structure.
497 * @param pVar The variable to convert.
498 * @param pf Where to store the boolean.
499 */
500 DECLCALLBACKMEMBER(int, pfnVarToBool)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf);
501
502} DBGCCMDHLP;
503
504
505#ifdef IN_RING3
506
507/**
508 * Command helper for writing formatted text to the debug console.
509 *
510 * @returns VBox status.
511 * @param pCmdHlp Pointer to the command callback structure.
512 * @param pszFormat The format string.
513 * This is using the log formatter, so it's format extensions can be used.
514 * @param ... Arguments specified in the format string.
515 */
516DECLINLINE(int) DBGCCmdHlpPrintf(PDBGCCMDHLP pCmdHlp, const char *pszFormat, ...)
517{
518 va_list va;
519 int rc;
520
521 va_start(va, pszFormat);
522 rc = pCmdHlp->pfnPrintfV(pCmdHlp, NULL, pszFormat, va);
523 va_end(va);
524
525 return rc;
526}
527
528/**
529 * @copydoc FNDBGCHLPVBOXERROR
530 */
531DECLINLINE(int) DBGCCmdHlpVBoxError(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...)
532{
533 va_list va;
534
535 va_start(va, pszFormat);
536 rc = pCmdHlp->pfnVBoxErrorV(pCmdHlp, rc, pszFormat, va);
537 va_end(va);
538
539 return rc;
540}
541
542/**
543 * @copydoc FNDBGCHLPMEMREAD
544 */
545DECLINLINE(int) DBGCCmdHlpMemRead(PDBGCCMDHLP pCmdHlp, PVM pVM, void *pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t *pcbRead)
546{
547 return pCmdHlp->pfnMemRead(pCmdHlp, pVM, pvBuffer, cbRead, pVarPointer, pcbRead);
548}
549
550/**
551 * Evaluates an expression.
552 * (Hopefully the parser and functions are fully reentrant.)
553 *
554 * @returns VBox status code appropriate to return from a command.
555 * @param pCmdHlp Pointer to the command callback structure.
556 * @param pResult Where to store the result.
557 * @param pszExpr The expression. Format string with the format DBGC extensions.
558 * @param ... Format arguments.
559 */
560DECLINLINE(int) DBGCCmdHlpEval(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, ...)
561{
562 va_list va;
563 int rc;
564
565 va_start(va, pszExpr);
566 rc = pCmdHlp->pfnEvalV(pCmdHlp, pResult, pszExpr, va);
567 va_end(va);
568
569 return rc;
570}
571
572/**
573 * Print an error and fail the current command.
574 *
575 * @returns VBox status code to pass upwards.
576 *
577 * @param pCmdHlp Pointer to the command callback structure.
578 * @param pCmd The failing command.
579 * @param pszFormat The error message format string.
580 * @param ... Format arguments.
581 */
582DECLINLINE(int) DBGCCmdHlpFail(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, ...)
583{
584 va_list va;
585 int rc;
586
587 va_start(va, pszFormat);
588 rc = pCmdHlp->pfnFailV(pCmdHlp, pCmd, pszFormat, va);
589 va_end(va);
590
591 return rc;
592}
593
594#endif /* IN_RING3 */
595
596
597
598/**
599 * Command handler.
600 *
601 * The console will call the handler for a command once it's finished
602 * parsing the user input. The command handler function is responsible
603 * for executing the command itself.
604 *
605 * @returns VBox status.
606 * @param pCmd Pointer to the command descriptor (as registered).
607 * @param pCmdHlp Pointer to command helper functions.
608 * @param pVM Pointer to the current VM (if any).
609 * @param paArgs Pointer to (readonly) array of arguments.
610 * @param cArgs Number of arguments in the array.
611 * @param pResult Where to store the result. NULL if no result descriptor was specified.
612 */
613typedef DECLCALLBACK(int) FNDBGCCMD(PCDBGCCMD pCmd, PDBGCCMDHLP pCmdHlp, PVM pVM, PCDBGCVAR pArgs, unsigned cArgs, PDBGCVAR pResult);
614/** Pointer to a FNDBGCCMD() function. */
615typedef FNDBGCCMD *PFNDBGCCMD;
616
617/**
618 * DBGC command descriptor.
619 *
620 * If a pResultDesc is specified the command can be called and used
621 * as a function too. If it's a pure function, set fFlags to
622 * DBGCCMD_FLAGS_FUNCTION.
623 */
624typedef struct DBGCCMD
625{
626 /** Command string. */
627 const char *pszCmd;
628 /** Minimum number of arguments. */
629 unsigned cArgsMin;
630 /** Max number of arguments. */
631 unsigned cArgsMax;
632 /** Argument descriptors (array). */
633 PCDBGCVARDESC paArgDescs;
634 /** Number of argument descriptors. */
635 unsigned cArgDescs;
636 /** Result descriptor. */
637 PCDBGCVARDESC pResultDesc;
638 /** flags. (reserved for now) */
639 unsigned fFlags;
640 /** Handler function. */
641 PFNDBGCCMD pfnHandler;
642 /** Command syntax. */
643 const char *pszSyntax;
644 /** Command description. */
645 const char *pszDescription;
646} DBGCCMD;
647
648/** DBGCCMD Flags.
649 * @{
650 */
651/** The description is of a pure function which cannot be invoked
652 * as a command from the commandline. */
653#define DBGCCMD_FLAGS_FUNCTION 1
654/** @} */
655
656
657
658/** Pointer to a DBGC backend. */
659typedef struct DBGCBACK *PDBGCBACK;
660
661/**
662 * Checks if there is input.
663 *
664 * @returns true if there is input ready.
665 * @returns false if there not input ready.
666 * @param pBack Pointer to the backend structure supplied by
667 * the backend. The backend can use this to find
668 * it's instance data.
669 * @param cMillies Number of milliseconds to wait on input data.
670 */
671typedef DECLCALLBACK(bool) FNDBGCBACKINPUT(PDBGCBACK pBack, uint32_t cMillies);
672/** Pointer to a FNDBGCBACKINPUT() callback. */
673typedef FNDBGCBACKINPUT *PFNDBGCBACKINPUT;
674
675/**
676 * Read input.
677 *
678 * @returns VBox status code.
679 * @param pBack Pointer to the backend structure supplied by
680 * the backend. The backend can use this to find
681 * it's instance data.
682 * @param pvBuf Where to put the bytes we read.
683 * @param cbBuf Maximum nymber of bytes to read.
684 * @param pcbRead Where to store the number of bytes actually read.
685 * If NULL the entire buffer must be filled for a
686 * successful return.
687 */
688typedef DECLCALLBACK(int) FNDBGCBACKREAD(PDBGCBACK pBack, void *pvBuf, size_t cbBuf, size_t *pcbRead);
689/** Pointer to a FNDBGCBACKREAD() callback. */
690typedef FNDBGCBACKREAD *PFNDBGCBACKREAD;
691
692/**
693 * Write (output).
694 *
695 * @returns VBox status code.
696 * @param pBack Pointer to the backend structure supplied by
697 * the backend. The backend can use this to find
698 * it's instance data.
699 * @param pvBuf What to write.
700 * @param cbBuf Number of bytes to write.
701 * @param pcbWritten Where to store the number of bytes actually written.
702 * If NULL the entire buffer must be successfully written.
703 */
704typedef DECLCALLBACK(int) FNDBGCBACKWRITE(PDBGCBACK pBack, const void *pvBuf, size_t cbBuf, size_t *pcbWritten);
705/** Pointer to a FNDBGCBACKWRITE() callback. */
706typedef FNDBGCBACKWRITE *PFNDBGCBACKWRITE;
707
708/**
709 * Ready / busy notification.
710 *
711 * @param pBack Pointer to the backend structure supplied by
712 * the backend. The backend can use this to find
713 * it's instance data.
714 * @param fReady Whether it's ready (true) or busy (false).
715 */
716typedef DECLCALLBACK(void) FNDBGCBACKSETREADY(PDBGCBACK pBack, bool fReady);
717/** Pointer to a FNDBGCBACKSETREADY() callback. */
718typedef FNDBGCBACKSETREADY *PFNDBGCBACKSETREADY;
719
720
721/**
722 * The communication backend provides the console with a number of callbacks
723 * which can be used
724 */
725typedef struct DBGCBACK
726{
727 /** Check for input. */
728 PFNDBGCBACKINPUT pfnInput;
729 /** Read input. */
730 PFNDBGCBACKREAD pfnRead;
731 /** Write output. */
732 PFNDBGCBACKWRITE pfnWrite;
733 /** Ready / busy notification. */
734 PFNDBGCBACKSETREADY pfnSetReady;
735} DBGCBACK;
736
737
738/**
739 * Make a console instance.
740 *
741 * This will not return until either an 'exit' command is issued or a error code
742 * indicating connection loss is encountered.
743 *
744 * @returns VINF_SUCCESS if console termination caused by the 'exit' command.
745 * @returns The VBox status code causing the console termination.
746 *
747 * @param pVM VM Handle.
748 * @param pBack Pointer to the backend structure. This must contain
749 * a full set of function pointers to service the console.
750 * @param fFlags Reserved, must be zero.
751 * @remark A forced termination of the console is easiest done by forcing the
752 * callbacks to return fatal failures.
753 */
754DBGDECL(int) DBGCCreate(PVM pVM, PDBGCBACK pBack, unsigned fFlags);
755
756
757/**
758 * Register one or more external commands.
759 *
760 * @returns VBox status.
761 * @param paCommands Pointer to an array of command descriptors.
762 * The commands must be unique. It's not possible
763 * to register the same commands more than once.
764 * @param cCommands Number of commands.
765 */
766DBGDECL(int) DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
767
768
769/**
770 * Deregister one or more external commands previously registered by
771 * DBGCRegisterCommands().
772 *
773 * @returns VBox status.
774 * @param paCommands Pointer to an array of command descriptors
775 * as given to DBGCRegisterCommands().
776 * @param cCommands Number of commands.
777 */
778DBGDECL(int) DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
779
780
781/**
782 * Spawns a new thread with a TCP based debugging console service.
783 *
784 * @returns VBox status.
785 * @param pVM VM handle.
786 * @param ppvData Where to store the pointer to instance data.
787 */
788DBGDECL(int) DBGCTcpCreate(PVM pVM, void **ppvUser);
789
790/**
791 * Terminates any running TCP base debugger consolse service.
792 *
793 * @returns VBox status.
794 * @param pVM VM handle.
795 * @param pvData Instance data set by DBGCTcpCreate().
796 */
797DBGDECL(int) DBGCTcpTerminate(PVM pVM, void *pvData);
798
799
800/** @defgroup grp_dbgc_plug_in The DBGC Plug-in Interface
801 * @{
802 */
803
804/** The plug-in module name prefix. */
805#define DBGC_PLUG_IN_PREFIX "DBGCPlugIn"
806
807/** The name of the plug-in entry point (FNDBGCPLUGIN) */
808#define DBGC_PLUG_IN_ENTRYPOINT "DBGCPlugInEntry"
809
810/**
811 * DBGC plug-in operations.
812 */
813typedef enum DBGCPLUGINOP
814{
815 /** The usual invalid first value. */
816 DBGCPLUGINOP_INVALID,
817 /** Initialize the plug-in, register all the stuff.
818 * The plug-in will be unloaded on failure.
819 * uArg: The VirtualBox version (major+minor). */
820 DBGCPLUGINOP_INIT,
821 /** Terminate the plug-ing, deregister all the stuff.
822 * The plug-in will be unloaded after this call regardless of the return
823 * code. */
824 DBGCPLUGINOP_TERM,
825 /** The usual 32-bit hack. */
826 DBGCPLUGINOP_32BIT_HACK = 0x7fffffff
827} DBGCPLUGINOP;
828
829/**
830 * DBGC plug-in main entry point.
831 *
832 * @returns VBox status code.
833 *
834 * @param enmOperation The operation.
835 * @param pVM The VM handle. This may be NULL.
836 * @param uArg Extra argument.
837 */
838typedef DECLCALLBACK(int) FNDBGCPLUGIN(DBGCPLUGINOP enmOperation, PVM pVM, uintptr_t uArg);
839/** Pointer to a FNDBGCPLUGIN. */
840typedef FNDBGCPLUGIN *PFNDBGCPLUGIN;
841
842/** @copydoc FNDBGCPLUGIN */
843DECLEXPORT(int) DBGCPlugInEntry(DBGCPLUGINOP enmOperation, PVM pVM, uintptr_t uArg);
844
845/** @} */
846
847
848RT_C_DECLS_END
849
850#endif
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette