VirtualBox

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

Last change on this file since 24130 was 22108, checked in by vboxsync, 15 years ago

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