VirtualBox

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

Last change on this file since 8155 was 8155, checked in by vboxsync, 16 years ago

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use