VirtualBox

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

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

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use