VirtualBox

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

Last change on this file since 5846 was 5731, checked in by vboxsync, 17 years ago

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