VirtualBox

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

最後變更 在這個檔案從4172是 4071,由 vboxsync 提交於 18 年 前

Biggest check-in ever. New source code headers for all (C) innotek files.
  • 屬性 svn:eol-style 設為 native
  • 屬性 svn:keywords 設為 Author Date Id Revision
檔案大小: 20.1 KB
行 
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.alldomusa.eu.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} DBGCVARCAT;
70
71
72/**
73 * DBGC variable type.
74 */
75typedef enum DBGCVARTYPE
76{
77 /** unknown... */
78 DBGCVAR_TYPE_UNKNOWN = 0,
79 /** Flat GC pointer. */
80 DBGCVAR_TYPE_GC_FLAT,
81 /** Segmented GC pointer. */
82 DBGCVAR_TYPE_GC_FAR,
83 /** Physical GC pointer. */
84 DBGCVAR_TYPE_GC_PHYS,
85 /** Flat HC pointer. */
86 DBGCVAR_TYPE_HC_FLAT,
87 /** Segmented HC pointer. */
88 DBGCVAR_TYPE_HC_FAR,
89 /** Physical HC pointer. */
90 DBGCVAR_TYPE_HC_PHYS,
91 /** String. */
92 DBGCVAR_TYPE_STRING,
93 /** Number. */
94 DBGCVAR_TYPE_NUMBER,
95 /** Symbol. */
96 DBGCVAR_TYPE_SYMBOL,
97 /** Special type used when querying symbols. */
98 DBGCVAR_TYPE_ANY
99} DBGCVARTYPE;
100
101/** Checks if the specified variable type is of a pointer persuasion. */
102#define DBGCVAR_ISPOINTER(enmType) (enmType >= DBGCVAR_TYPE_GC_FLAT && enmType <= DBGCVAR_TYPE_HC_PHYS)
103/** Checks if the specified variable type is of a pointer persuasion and of the guest context sort. */
104#define DBGCVAR_ISGCPOINTER(enmType) (enmType >= DBGCVAR_TYPE_GC_FLAT && enmType <= DBGCVAR_TYPE_GC_PHYS)
105/** Checks if the specified variable type is of a pointer persuasion and of the host context sort. */
106#define DBGCVAR_ISHCPOINTER(enmType) (enmType >= DBGCVAR_TYPE_HC_FLAT && enmType <= DBGCVAR_TYPE_HC_PHYS)
107
108
109/**
110 * DBGC variable range type.
111 */
112typedef enum DBGCVARRANGETYPE
113{
114 /** No range appliable or no range specified. */
115 DBGCVAR_RANGE_NONE = 0,
116 /** Number of elements. */
117 DBGCVAR_RANGE_ELEMENTS,
118 /** Number of bytes. */
119 DBGCVAR_RANGE_BYTES
120} DBGCVARRANGETYPE;
121
122
123/**
124 * Variable descriptor.
125 */
126typedef struct DBGCVARDESC
127{
128 /** The minimal number of times this argument may occur.
129 * Use 0 here to inidicate that the argument is optional. */
130 unsigned cTimesMin;
131 /** Maximum number of occurences.
132 * Use ~0 here to indicate infinite. */
133 unsigned cTimesMax;
134 /** Argument category. */
135 DBGCVARCAT enmCategory;
136 /** Flags, DBGCVD_FLAGS_* */
137 unsigned fFlags;
138 /** Argument name. */
139 const char *pszName;
140 /** Argument name. */
141 const char *pszDescription;
142} DBGCVARDESC;
143/** Pointer to an argument descriptor. */
144typedef DBGCVARDESC *PDBGCVARDESC;
145/** Pointer to a const argument descriptor. */
146typedef const DBGCVARDESC *PCDBGCVARDESC;
147
148/** Variable descriptor flags.
149 * @{ */
150/** Indicates that the variable depends on the previous being present. */
151#define DBGCVD_FLAGS_DEP_PREV BIT(1)
152/** @} */
153
154
155/**
156 * DBGC variable.
157 */
158typedef struct DBGCVAR
159{
160 /** Pointer to the argument descriptor. */
161 PCDBGCVARDESC pDesc;
162 /** Pointer to the next argument. */
163 struct DBGCVAR *pNext;
164
165 /** Argument type. */
166 DBGCVARTYPE enmType;
167 /** Type specific. */
168 union
169 {
170 /** Flat GC Address. (DBGCVAR_TYPE_GC_FLAT) */
171 RTGCPTR GCFlat;
172 /** Far (16:32) GC Address. (DBGCVAR_TYPE_GC_FAR) */
173 RTFAR32 GCFar;
174 /** Physical GC Address. (DBGCVAR_TYPE_GC_PHYS) */
175 RTGCPHYS GCPhys;
176 /** Flat HC Address. (DBGCVAR_TYPE_HC_FLAT) */
177 void *pvHCFlat;
178 /** Far (16:32) HC Address. (DBGCVAR_TYPE_HC_FAR) */
179 RTFAR32 HCFar;
180 /** Physical GC Address. (DBGCVAR_TYPE_HC_PHYS) */
181 RTHCPHYS HCPhys;
182 /** String. (DBGCVAR_TYPE_STRING)
183 * The basic idea is the the this is a pointer to the expression we're
184 * parsing, so no messing with freeing. */
185 const char *pszString;
186 /** Number. (DBGCVAR_TYPE_NUMBER) */
187 uint64_t u64Number;
188 } u;
189
190 /** Range type. */
191 DBGCVARRANGETYPE enmRangeType;
192 /** Range. The use of the content depends on the enmRangeType. */
193 uint64_t u64Range;
194} DBGCVAR;
195/** Pointer to a command argument. */
196typedef DBGCVAR *PDBGCVAR;
197/** Pointer to a const command argument. */
198typedef const DBGCVAR *PCDBGCVAR;
199
200
201/** Pointer to helper functions for commands. */
202typedef struct DBGCCMDHLP *PDBGCCMDHLP;
203
204/**
205 * Command helper for writing text to the debug console.
206 *
207 * @returns VBox status.
208 * @param pCmdHlp Pointer to the command callback structure.
209 * @param pvBuf What to write.
210 * @param cbBuf Number of bytes to write.
211 * @param pcbWritten Where to store the number of bytes actually written.
212 * If NULL the entire buffer must be successfully written.
213 */
214typedef DECLCALLBACK(int) FNDBGCHLPWRITE(PDBGCCMDHLP pCmdHlp, const void *pvBuf, size_t cbBuf, size_t *pcbWritten);
215/** Pointer to a FNDBGCHLPWRITE() function. */
216typedef FNDBGCHLPWRITE *PFNDBGCHLPWRITE;
217
218/**
219 * Command helper for writing formatted text to the debug console.
220 *
221 * @returns VBox status.
222 * @param pCmdHlp Pointer to the command callback structure.
223 * @param pcb Where to store the number of bytes written.
224 * @param pszFormat The format string.
225 * This is using the log formatter, so it's format extensions can be used.
226 * @param ... Arguments specified in the format string.
227 */
228typedef DECLCALLBACK(int) FNDBGCHLPPRINTF(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten, const char *pszFormat, ...);
229/** Pointer to a FNDBGCHLPPRINTF() function. */
230typedef FNDBGCHLPPRINTF *PFNDBGCHLPPRINTF;
231
232/**
233 * Command helper for writing formatted text to the debug console.
234 *
235 * @returns VBox status.
236 * @param pCmdHlp Pointer to the command callback structure.
237 * @param pcb Where to store the number of bytes written.
238 * @param pszFormat The format string.
239 * This is using the log formatter, so it's format extensions can be used.
240 * @param args Arguments specified in the format string.
241 */
242typedef DECLCALLBACK(int) FNDBGCHLPPRINTFV(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten, const char *pszFormat, va_list args);
243/** Pointer to a FNDBGCHLPPRINTFV() function. */
244typedef FNDBGCHLPPRINTFV *PFNDBGCHLPPRINTFV;
245
246/**
247 * Command helper for formatting and error message for a VBox status code.
248 *
249 * @returns VBox status code appropriate to return from a command.
250 * @param pCmdHlp Pointer to the command callback structure.
251 * @param rc The VBox status code.
252 * @param pcb Where to store the number of bytes written.
253 * @param pszFormat Format string for additional messages. Can be NULL.
254 * @param ... Format arguments, optional.
255 */
256typedef DECLCALLBACK(int) FNDBGCHLPVBOXERROR(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...);
257/** Pointer to a FNDBGCHLPVBOXERROR() function. */
258typedef FNDBGCHLPVBOXERROR *PFNDBGCHLPVBOXERROR;
259
260/**
261 * Command helper for formatting and error message for a VBox status code.
262 *
263 * @returns VBox status code appropriate to return from a command.
264 * @param pCmdHlp Pointer to the command callback structure.
265 * @param rc The VBox status code.
266 * @param pcb Where to store the number of bytes written.
267 * @param pszFormat Format string for additional messages. Can be NULL.
268 * @param args Format arguments, optional.
269 */
270typedef DECLCALLBACK(int) FNDBGCHLPVBOXERRORV(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, va_list args);
271/** Pointer to a FNDBGCHLPVBOXERRORV() function. */
272typedef FNDBGCHLPVBOXERRORV *PFNDBGCHLPVBOXERRORV;
273
274/**
275 * Command helper for reading memory specified by a DBGC variable.
276 *
277 * @returns VBox status code appropriate to return from a command.
278 * @param pCmdHlp Pointer to the command callback structure.
279 * @param pVM VM handle if GC or physical HC address.
280 * @param pvBuffer Where to store the read data.
281 * @param cbRead Number of bytes to read.
282 * @param pVarPointer DBGC variable specifying where to start reading.
283 * @param pcbRead Where to store the number of bytes actually read.
284 * This optional, but it's useful when read GC virtual memory where a
285 * page in the requested range might not be present.
286 * If not specified not-present failure or end of a HC physical page
287 * will cause failure.
288 */
289typedef DECLCALLBACK(int) FNDBGCHLPMEMREAD(PDBGCCMDHLP pCmdHlp, PVM pVM, void *pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t *pcbRead);
290/** Pointer to a FNDBGCHLPMEMREAD() function. */
291typedef FNDBGCHLPMEMREAD *PFNDBGCHLPMEMREAD;
292
293/**
294 * Command helper for writing memory specified by a DBGC variable.
295 *
296 * @returns VBox status code appropriate to return from a command.
297 * @param pCmdHlp Pointer to the command callback structure.
298 * @param pVM VM handle if GC or physical HC address.
299 * @param pvBuffer What to write.
300 * @param cbWrite Number of bytes to write.
301 * @param pVarPointer DBGC variable specifying where to start reading.
302 * @param pcbWritten Where to store the number of bytes written.
303 * This is optional. If NULL be aware that some of the buffer
304 * might have been written to the specified address.
305 */
306typedef DECLCALLBACK(int) FNDBGCHLPMEMWRITE(PDBGCCMDHLP pCmdHlp, PVM pVM, const void *pvBuffer, size_t cbWrite, PCDBGCVAR pVarPointer, size_t *pcbWritten);
307/** Pointer to a FNDBGCHLPMEMWRITE() function. */
308typedef FNDBGCHLPMEMWRITE *PFNDBGCHLPMEMWRITE;
309
310
311/**
312 * Evaluates an expression.
313 * (Hopefully the parser and functions are fully reentrant.)
314 *
315 * @returns VBox status code appropriate to return from a command.
316 * @param pCmdHlp Pointer to the command callback structure.
317 * @param pResult Where to store the result.
318 * @param pszExpr The expression. Format string with the format DBGC extensions.
319 * @param ... Format arguments.
320 */
321typedef DECLCALLBACK(int) FNDBGCHLPEVAL(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, ...);
322/** Pointer to a FNDBGCHLPEVAL() function. */
323typedef FNDBGCHLPEVAL *PFNDBGCHLPEVAL;
324
325
326/**
327 * Executes command an expression.
328 * (Hopefully the parser and functions are fully reentrant.)
329 *
330 * @returns VBox status code appropriate to return from a command.
331 * @param pCmdHlp Pointer to the command callback structure.
332 * @param pszExpr The expression. Format string with the format DBGC extensions.
333 * @param ... Format arguments.
334 */
335typedef DECLCALLBACK(int) FNDBGCHLPEXEC(PDBGCCMDHLP pCmdHlp, const char *pszExpr, ...);
336/** Pointer to a FNDBGCHLPEVAL() function. */
337typedef FNDBGCHLPEXEC *PFNDBGCHLPEXEC;
338
339
340/**
341 * Helper functions for commands.
342 */
343typedef struct DBGCCMDHLP
344{
345 /** Pointer to a FNDBCHLPWRITE() function. */
346 PFNDBGCHLPWRITE pfnWrite;
347 /** Pointer to a FNDBGCHLPPRINTF() function. */
348 PFNDBGCHLPPRINTF pfnPrintf;
349 /** Pointer to a FNDBGCHLPPRINTFV() function. */
350 PFNDBGCHLPPRINTFV pfnPrintfV;
351 /** Pointer to a FNDBGCHLPVBOXERROR() function. */
352 PFNDBGCHLPVBOXERROR pfnVBoxError;
353 /** Pointer to a FNDBGCHLPVBOXERRORV() function. */
354 PFNDBGCHLPVBOXERRORV pfnVBoxErrorV;
355 /** Pointer to a FNDBGCHLPMEMREAD() function. */
356 PFNDBGCHLPMEMREAD pfnMemRead;
357 /** Pointer to a FNDBGCHLPMEMWRITE() function. */
358 PFNDBGCHLPMEMWRITE pfnMemWrite;
359 /** Pointer to a FNDBGCHLPEVAL() function. */
360 PFNDBGCHLPEVAL pfnEval;
361 /** Pointer to a FNDBGCHLPEXEC() function. */
362 PFNDBGCHLPEXEC pfnExec;
363
364 /**
365 * Converts a DBGC variable to a DBGF address structure.
366 *
367 * @returns VBox status code.
368 * @param pCmdHlp Pointer to the command callback structure.
369 * @param pVar The variable to convert.
370 * @param pAddress The target address.
371 */
372 DECLCALLBACKMEMBER(int, pfnVarToDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress);
373
374 /**
375 * Converts a DBGC variable to a boolean.
376 *
377 * @returns VBox status code.
378 * @param pCmdHlp Pointer to the command callback structure.
379 * @param pVar The variable to convert.
380 * @param pf Where to store the boolean.
381 */
382 DECLCALLBACKMEMBER(int, pfnVarToBool)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf);
383
384} DBGCCMDHLP;
385
386
387
388/** Pointer to command descriptor. */
389typedef struct DBGCCMD *PDBGCCMD;
390/** Pointer to const command descriptor. */
391typedef const struct DBGCCMD *PCDBGCCMD;
392
393/**
394 * Command handler.
395 *
396 * The console will call the handler for a command once it's finished
397 * parsing the user input. The command handler function is responsible
398 * for executing the command itself.
399 *
400 * @returns VBox status.
401 * @param pCmd Pointer to the command descriptor (as registered).
402 * @param pCmdHlp Pointer to command helper functions.
403 * @param pVM Pointer to the current VM (if any).
404 * @param paArgs Pointer to (readonly) array of arguments.
405 * @param cArgs Number of arguments in the array.
406 * @param pResult Where to store the result. NULL if no result descriptor was specified.
407 */
408typedef DECLCALLBACK(int) FNDBGCCMD(PCDBGCCMD pCmd, PDBGCCMDHLP pCmdHlp, PVM pVM, PCDBGCVAR pArgs, unsigned cArgs, PDBGCVAR pResult);
409/** Pointer to a FNDBGCCMD() function. */
410typedef FNDBGCCMD *PFNDBGCCMD;
411
412/**
413 * DBGC command descriptor.
414 *
415 * If a pResultDesc is specified the command can be called and used
416 * as a function too. If it's a pure function, set fFlags to
417 * DBGCCMD_FLAGS_FUNCTION.
418 */
419typedef struct DBGCCMD
420{
421 /** Command string. */
422 const char *pszCmd;
423 /** Minimum number of arguments. */
424 unsigned cArgsMin;
425 /** Max number of arguments. */
426 unsigned cArgsMax;
427 /** Argument descriptors (array). */
428 PCDBGCVARDESC paArgDescs;
429 /** Number of argument descriptors. */
430 unsigned cArgDescs;
431 /** Result descriptor. */
432 PCDBGCVARDESC pResultDesc;
433 /** flags. (reserved for now) */
434 unsigned fFlags;
435 /** Handler function. */
436 PFNDBGCCMD pfnHandler;
437 /** Command syntax. */
438 const char *pszSyntax;
439 /** Command description. */
440 const char *pszDescription;
441} DBGCCMD;
442
443/** DBGCCMD Flags.
444 * @{
445 */
446/** The description is of a pure function which cannot be invoked
447 * as a command from the commandline. */
448#define DBGCCMD_FLAGS_FUNCTION 1
449/** @} */
450
451
452
453/** Pointer to a DBGC backend. */
454typedef struct DBGCBACK *PDBGCBACK;
455
456/**
457 * Checks if there is input.
458 *
459 * @returns true if there is input ready.
460 * @returns false if there not input ready.
461 * @param pBack Pointer to the backend structure supplied by
462 * the backend. The backend can use this to find
463 * it's instance data.
464 * @param cMillies Number of milliseconds to wait on input data.
465 */
466typedef DECLCALLBACK(bool) FNDBGCBACKINPUT(PDBGCBACK pBack, uint32_t cMillies);
467/** Pointer to a FNDBGCBACKINPUT() callback. */
468typedef FNDBGCBACKINPUT *PFNDBGCBACKINPUT;
469
470/**
471 * Read input.
472 *
473 * @returns VBox status code.
474 * @param pBack Pointer to the backend structure supplied by
475 * the backend. The backend can use this to find
476 * it's instance data.
477 * @param pvBuf Where to put the bytes we read.
478 * @param cbBuf Maximum nymber of bytes to read.
479 * @param pcbRead Where to store the number of bytes actually read.
480 * If NULL the entire buffer must be filled for a
481 * successful return.
482 */
483typedef DECLCALLBACK(int) FNDBGCBACKREAD(PDBGCBACK pBack, void *pvBuf, size_t cbBuf, size_t *pcbRead);
484/** Pointer to a FNDBGCBACKREAD() callback. */
485typedef FNDBGCBACKREAD *PFNDBGCBACKREAD;
486
487/**
488 * Write (output).
489 *
490 * @returns VBox status code.
491 * @param pBack Pointer to the backend structure supplied by
492 * the backend. The backend can use this to find
493 * it's instance data.
494 * @param pvBuf What to write.
495 * @param cbBuf Number of bytes to write.
496 * @param pcbWritten Where to store the number of bytes actually written.
497 * If NULL the entire buffer must be successfully written.
498 */
499typedef DECLCALLBACK(int) FNDBGCBACKWRITE(PDBGCBACK pBack, const void *pvBuf, size_t cbBuf, size_t *pcbWritten);
500/** Pointer to a FNDBGCBACKWRITE() callback. */
501typedef FNDBGCBACKWRITE *PFNDBGCBACKWRITE;
502
503
504/**
505 * The communication backend provides the console with a number of callbacks
506 * which can be used
507 */
508typedef struct DBGCBACK
509{
510 /** Check for input. */
511 PFNDBGCBACKINPUT pfnInput;
512 /** Read input. */
513 PFNDBGCBACKREAD pfnRead;
514 /** Write output. */
515 PFNDBGCBACKWRITE pfnWrite;
516} DBGCBACK;
517
518
519/**
520 * Make a console instance.
521 *
522 * This will not return until either an 'exit' command is issued or a error code
523 * indicating connection loss is encountered.
524 *
525 * @returns VINF_SUCCESS if console termination caused by the 'exit' command.
526 * @returns The VBox status code causing the console termination.
527 *
528 * @param pVM VM Handle.
529 * @param pBack Pointer to the backend structure. This must contain
530 * a full set of function pointers to service the console.
531 * @param fFlags Reserved, must be zero.
532 * @remark A forced termination of the console is easiest done by forcing the
533 * callbacks to return fatal failures.
534 */
535DBGDECL(int) DBGCCreate(PVM pVM, PDBGCBACK pBack, unsigned fFlags);
536
537
538/**
539 * Register one or more external commands.
540 *
541 * @returns VBox status.
542 * @param paCommands Pointer to an array of command descriptors.
543 * The commands must be unique. It's not possible
544 * to register the same commands more than once.
545 * @param cCommands Number of commands.
546 */
547DBGDECL(int) DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
548
549
550/**
551 * Deregister one or more external commands previously registered by
552 * DBGCRegisterCommands().
553 *
554 * @returns VBox status.
555 * @param paCommands Pointer to an array of command descriptors
556 * as given to DBGCRegisterCommands().
557 * @param cCommands Number of commands.
558 */
559DBGDECL(int) DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
560
561
562/**
563 * Spawns a new thread with a TCP based debugging console service.
564 *
565 * @returns VBox status.
566 * @param pVM VM handle.
567 * @param ppvData Where to store the pointer to instance data.
568 */
569DBGDECL(int) DBGCTcpCreate(PVM pVM, void **ppvUser);
570
571/**
572 * Terminates any running TCP base debugger consolse service.
573 *
574 * @returns VBox status.
575 * @param pVM VM handle.
576 * @param pvData Instance data set by DBGCTcpCreate().
577 */
578DBGDECL(int) DBGCTcpTerminate(PVM pVM, void *pvData);
579
580
581__END_DECLS
582
583#endif
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette