VirtualBox

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

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

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use