dbg.h@ 35637

Last change on this file since 35637 was 35637, checked in by vboxsync, 14 years ago
Debugger console: Made the evaluator a bit smarter wrt to the register and variable operators (e.g. don't confuse @ah with a hexadecimal number).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 32.2 KB

Line
1	/** @file
2	* Debugger Interfaces. (VBoxDbg)
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 Oracle Corporation
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/vmm/dbgf.h>
36
37	#include <iprt/stdarg.h>
38	#ifdef IN_RING3
39	# include <iprt/err.h>
40	#endif
41
42	RT_C_DECLS_BEGIN
43
44	/** @def VBOX_WITH_DEBUGGER
45	* The build is with debugger module. Test if this is defined before registering
46	* external debugger commands. This is normally defined in Config.kmk.
47	*/
48	#ifdef DOXYGEN_RUNNING
49	# define VBOX_WITH_DEBUGGER
50	#endif
51
52
53	/**
54	* DBGC variable category.
55	*
56	* Used to describe an argument to a command or function and a functions
57	* return value.
58	*/
59	typedef enum DBGCVARCAT
60	{
61	/** Any type is fine. */
62	DBGCVAR_CAT_ANY = 0,
63	/** Any kind of pointer or number. */
64	DBGCVAR_CAT_POINTER_NUMBER,
65	/** Any kind of pointer or number, no range. */
66	DBGCVAR_CAT_POINTER_NUMBER_NO_RANGE,
67	/** Any kind of pointer. */
68	DBGCVAR_CAT_POINTER,
69	/** Any kind of pointer with no range option. */
70	DBGCVAR_CAT_POINTER_NO_RANGE,
71	/** GC pointer. */
72	DBGCVAR_CAT_GC_POINTER,
73	/** GC pointer with no range option. */
74	DBGCVAR_CAT_GC_POINTER_NO_RANGE,
75	/** Numeric argument. */
76	DBGCVAR_CAT_NUMBER,
77	/** Numeric argument with no range option. */
78	DBGCVAR_CAT_NUMBER_NO_RANGE,
79	/** String. */
80	DBGCVAR_CAT_STRING,
81	/** Symbol. */
82	DBGCVAR_CAT_SYMBOL,
83	/** Option. */
84	DBGCVAR_CAT_OPTION,
85	/** Option + string. */
86	DBGCVAR_CAT_OPTION_STRING,
87	/** Option + number. */
88	DBGCVAR_CAT_OPTION_NUMBER
89	} DBGCVARCAT;
90
91
92	/**
93	* DBGC variable type.
94	*/
95	typedef enum DBGCVARTYPE
96	{
97	/** unknown... */
98	DBGCVAR_TYPE_UNKNOWN = 0,
99	/** Flat GC pointer. */
100	DBGCVAR_TYPE_GC_FLAT,
101	/** Segmented GC pointer. */
102	DBGCVAR_TYPE_GC_FAR,
103	/** Physical GC pointer. */
104	DBGCVAR_TYPE_GC_PHYS,
105	/** Flat HC pointer. */
106	DBGCVAR_TYPE_HC_FLAT,
107	/** Physical HC pointer. */
108	DBGCVAR_TYPE_HC_PHYS,
109	/** String. */
110	DBGCVAR_TYPE_STRING,
111	/** Number. */
112	DBGCVAR_TYPE_NUMBER,
113	/** Symbol.
114	* @todo drop this */
115	DBGCVAR_TYPE_SYMBOL,
116	/** Special type used when querying symbols. */
117	DBGCVAR_TYPE_ANY
118	} DBGCVARTYPE;
119
120	/** @todo Rename to DBGCVAR_IS_xyz. */
121
122	/** Checks if the specified variable type is of a pointer persuasion. */
123	#define DBGCVAR_ISPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && enmType <= DBGCVAR_TYPE_HC_PHYS)
124	/** Checks if the specified variable type is of a pointer persuasion. */
125	#define DBGCVAR_IS_FAR_PTR(enmType) ((enmType) == DBGCVAR_TYPE_GC_FAR)
126	/** Checks if the specified variable type is of a pointer persuasion and of the guest context sort. */
127	#define DBGCVAR_ISGCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && (enmType) <= DBGCVAR_TYPE_GC_PHYS)
128	/** Checks if the specified variable type is of a pointer persuasion and of the host context sort. */
129	#define DBGCVAR_ISHCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_HC_FLAT && (enmType) <= DBGCVAR_TYPE_HC_PHYS)
130
131
132	/**
133	* DBGC variable range type.
134	*/
135	typedef enum DBGCVARRANGETYPE
136	{
137	/** No range appliable or no range specified. */
138	DBGCVAR_RANGE_NONE = 0,
139	/** Number of elements. */
140	DBGCVAR_RANGE_ELEMENTS,
141	/** Number of bytes. */
142	DBGCVAR_RANGE_BYTES
143	} DBGCVARRANGETYPE;
144
145
146	/**
147	* Variable descriptor.
148	*/
149	typedef struct DBGCVARDESC
150	{
151	/** The minimal number of times this argument may occur.
152	* Use 0 here to inidicate that the argument is optional. */
153	unsigned cTimesMin;
154	/** Maximum number of occurrences.
155	* Use ~0 here to indicate infinite. */
156	unsigned cTimesMax;
157	/** Argument category. */
158	DBGCVARCAT enmCategory;
159	/** Flags, DBGCVD_FLAGS_* */
160	unsigned fFlags;
161	/** Argument name. */
162	const char *pszName;
163	/** Argument name. */
164	const char *pszDescription;
165	} DBGCVARDESC;
166	/** Pointer to an argument descriptor. */
167	typedef DBGCVARDESC *PDBGCVARDESC;
168	/** Pointer to a const argument descriptor. */
169	typedef const DBGCVARDESC *PCDBGCVARDESC;
170
171	/** Variable descriptor flags.
172	* @{ */
173	/** Indicates that the variable depends on the previous being present. */
174	#define DBGCVD_FLAGS_DEP_PREV RT_BIT(1)
175	/** @} */
176
177
178	/**
179	* DBGC variable.
180	*/
181	typedef struct DBGCVAR
182	{
183	/** Pointer to the argument descriptor. */
184	PCDBGCVARDESC pDesc;
185	/** Pointer to the next argument. */
186	struct DBGCVAR *pNext;
187
188	/** Argument type. */
189	DBGCVARTYPE enmType;
190	/** Type specific. */
191	union
192	{
193	/** Flat GC Address. (DBGCVAR_TYPE_GC_FLAT) */
194	RTGCPTR GCFlat;
195	/** Far (16:32) GC Address. (DBGCVAR_TYPE_GC_FAR) */
196	RTFAR32 GCFar;
197	/** Physical GC Address. (DBGCVAR_TYPE_GC_PHYS) */
198	RTGCPHYS GCPhys;
199	/** Flat HC Address. (DBGCVAR_TYPE_HC_FLAT) */
200	void *pvHCFlat;
201	/** Physical GC Address. (DBGCVAR_TYPE_HC_PHYS) */
202	RTHCPHYS HCPhys;
203	/** String. (DBGCVAR_TYPE_STRING)
204	* The basic idea is the the this is a pointer to the expression we're
205	* parsing, so no messing with freeing. */
206	const char *pszString;
207	/** Number. (DBGCVAR_TYPE_NUMBER) */
208	uint64_t u64Number;
209	} u;
210
211	/** Range type. */
212	DBGCVARRANGETYPE enmRangeType;
213	/** Range. The use of the content depends on the enmRangeType. */
214	uint64_t u64Range;
215	} DBGCVAR;
216	/** Pointer to a command argument. */
217	typedef DBGCVAR *PDBGCVAR;
218	/** Pointer to a const command argument. */
219	typedef const DBGCVAR *PCDBGCVAR;
220
221
222	/**
223	* Macro for initializing a DBGC variable with defaults.
224	* The result is an unknown variable type without any range.
225	*/
226	#define DBGCVAR_INIT(pVar) \
227	do { \
228	(pVar)->pDesc = NULL;\
229	(pVar)->pNext = NULL; \
230	(pVar)->enmType = DBGCVAR_TYPE_UNKNOWN; \
231	(pVar)->u.u64Number = 0; \
232	(pVar)->enmRangeType = DBGCVAR_RANGE_NONE; \
233	(pVar)->u64Range = 0; \
234	} while (0)
235
236	/**
237	* Macro for initializing a DBGC variable with a HC physical address.
238	*/
239	#define DBGCVAR_INIT_HC_PHYS(pVar, Phys) \
240	do { \
241	DBGCVAR_INIT(pVar); \
242	(pVar)->enmType = DBGCVAR_TYPE_HC_PHYS; \
243	(pVar)->u.HCPhys = (Phys); \
244	} while (0)
245
246	/**
247	* Macro for initializing a DBGC variable with a HC flat address.
248	*/
249	#define DBGCVAR_INIT_HC_FLAT(pVar, Flat) \
250	do { \
251	DBGCVAR_INIT(pVar); \
252	(pVar)->enmType = DBGCVAR_TYPE_HC_FLAT; \
253	(pVar)->u.pvHCFlat = (Flat); \
254	} while (0)
255
256	/**
257	* Macro for initializing a DBGC variable with a GC physical address.
258	*/
259	#define DBGCVAR_INIT_GC_PHYS(pVar, Phys) \
260	do { \
261	DBGCVAR_INIT(pVar); \
262	(pVar)->enmType = DBGCVAR_TYPE_GC_PHYS; \
263	(pVar)->u.GCPhys = (Phys); \
264	} while (0)
265
266	/**
267	* Macro for initializing a DBGC variable with a GC flat address.
268	*/
269	#define DBGCVAR_INIT_GC_FLAT(pVar, Flat) \
270	do { \
271	DBGCVAR_INIT(pVar); \
272	(pVar)->enmType = DBGCVAR_TYPE_GC_FLAT; \
273	(pVar)->u.GCFlat = (Flat); \
274	} while (0)
275
276	/**
277	* Macro for initializing a DBGC variable with a GC far address.
278	*/
279	#define DBGCVAR_INIT_GC_FAR(pVar, _sel, _off) \
280	do { \
281	DBGCVAR_INIT(pVar); \
282	(pVar)->enmType = DBGCVAR_TYPE_GC_FAR; \
283	(pVar)->u.GCFar.sel = (_sel); \
284	(pVar)->u.GCFar.off = (_off); \
285	} while (0)
286
287	/**
288	* Macro for initializing a DBGC variable with a number.
289	*/
290	#define DBGCVAR_INIT_NUMBER(pVar, Value) \
291	do { \
292	DBGCVAR_INIT(pVar); \
293	(pVar)->enmType = DBGCVAR_TYPE_NUMBER; \
294	(pVar)->u.u64Number = (Value); \
295	} while (0)
296
297	/**
298	* Macro for initializing a DBGC variable with a string.
299	*/
300	#define DBGCVAR_INIT_STRING(pVar, a_pszString) \
301	do { \
302	DBGCVAR_INIT(pVar); \
303	(pVar)->enmType = DBGCVAR_TYPE_STRING; \
304	(pVar)->enmRangeType = DBGCVAR_RANGE_BYTES; \
305	(pVar)->u.pszString = (a_pszString); \
306	(pVar)->u64Range = strlen(a_pszString); \
307	} while (0)
308
309
310
311	/**
312	* Macro for setting the range of a DBGC variable.
313	* @param pVar The variable.
314	* @param _enmRangeType The range type.
315	* @param Value The range length value.
316	*/
317	#define DBGCVAR_SET_RANGE(pVar, _enmRangeType, Value) \
318	do { \
319	(pVar)->enmRangeType = (_enmRangeType); \
320	(pVar)->u64Range = (Value); \
321	} while (0)
322
323
324	/** Pointer to command descriptor. */
325	typedef struct DBGCCMD *PDBGCCMD;
326	/** Pointer to const command descriptor. */
327	typedef const struct DBGCCMD *PCDBGCCMD;
328
329	/** Pointer to helper functions for commands. */
330	typedef struct DBGCCMDHLP *PDBGCCMDHLP;
331
332	/**
333	* Command helper for writing text to the debug console.
334	*
335	* @returns VBox status.
336	* @param pCmdHlp Pointer to the command callback structure.
337	* @param pvBuf What to write.
338	* @param cbBuf Number of bytes to write.
339	* @param pcbWritten Where to store the number of bytes actually written.
340	* If NULL the entire buffer must be successfully written.
341	*/
342	typedef DECLCALLBACK(int) FNDBGCHLPWRITE(PDBGCCMDHLP pCmdHlp, const void pvBuf, size_t cbBuf, size_t pcbWritten);
343	/** Pointer to a FNDBGCHLPWRITE() function. */
344	typedef FNDBGCHLPWRITE *PFNDBGCHLPWRITE;
345
346	/**
347	* Command helper for writing formatted text to the debug console.
348	*
349	* @returns VBox status.
350	* @param pCmdHlp Pointer to the command callback structure.
351	* @param pcb Where to store the number of bytes written.
352	* @param pszFormat The format string.
353	* This is using the log formatter, so it's format extensions can be used.
354	* @param ... Arguments specified in the format string.
355	*/
356	typedef DECLCALLBACK(int) FNDBGCHLPPRINTF(PDBGCCMDHLP pCmdHlp, size_t pcbWritten, const char pszFormat, ...);
357	/** Pointer to a FNDBGCHLPPRINTF() function. */
358	typedef FNDBGCHLPPRINTF *PFNDBGCHLPPRINTF;
359
360	/**
361	* Command helper for writing formatted text to the debug console.
362	*
363	* @returns VBox status.
364	* @param pCmdHlp Pointer to the command callback structure.
365	* @param pcb Where to store the number of bytes written.
366	* @param pszFormat The format string.
367	* This is using the log formatter, so it's format extensions can be used.
368	* @param args Arguments specified in the format string.
369	*/
370	typedef DECLCALLBACK(int) FNDBGCHLPPRINTFV(PDBGCCMDHLP pCmdHlp, size_t pcbWritten, const char pszFormat, va_list args);
371	/** Pointer to a FNDBGCHLPPRINTFV() function. */
372	typedef FNDBGCHLPPRINTFV *PFNDBGCHLPPRINTFV;
373
374	/**
375	* Command helper for formatting and error message for a VBox status code.
376	*
377	* @returns VBox status code appropriate to return from a command.
378	* @param pCmdHlp Pointer to the command callback structure.
379	* @param rc The VBox status code.
380	* @param pszFormat Format string for additional messages. Can be NULL.
381	* @param ... Format arguments, optional.
382	*/
383	typedef DECLCALLBACK(int) FNDBGCHLPVBOXERROR(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...);
384	/** Pointer to a FNDBGCHLPVBOXERROR() function. */
385	typedef FNDBGCHLPVBOXERROR *PFNDBGCHLPVBOXERROR;
386
387	/**
388	* Command helper for formatting and error message for a VBox status code.
389	*
390	* @returns VBox status code appropriate to return from a command.
391	* @param pCmdHlp Pointer to the command callback structure.
392	* @param rc The VBox status code.
393	* @param pcb Where to store the number of bytes written.
394	* @param pszFormat Format string for additional messages. Can be NULL.
395	* @param args Format arguments, optional.
396	*/
397	typedef DECLCALLBACK(int) FNDBGCHLPVBOXERRORV(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, va_list args);
398	/** Pointer to a FNDBGCHLPVBOXERRORV() function. */
399	typedef FNDBGCHLPVBOXERRORV *PFNDBGCHLPVBOXERRORV;
400
401	/**
402	* Command helper for reading memory specified by a DBGC variable.
403	*
404	* @returns VBox status code appropriate to return from a command.
405	* @param pCmdHlp Pointer to the command callback structure.
406	* @param pVM VM handle if GC or physical HC address.
407	* @param pvBuffer Where to store the read data.
408	* @param cbRead Number of bytes to read.
409	* @param pVarPointer DBGC variable specifying where to start reading.
410	* @param pcbRead Where to store the number of bytes actually read.
411	* This optional, but it's useful when read GC virtual memory where a
412	* page in the requested range might not be present.
413	* If not specified not-present failure or end of a HC physical page
414	* will cause failure.
415	*/
416	typedef DECLCALLBACK(int) FNDBGCHLPMEMREAD(PDBGCCMDHLP pCmdHlp, PVM pVM, void pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t pcbRead);
417	/** Pointer to a FNDBGCHLPMEMREAD() function. */
418	typedef FNDBGCHLPMEMREAD *PFNDBGCHLPMEMREAD;
419
420	/**
421	* Command helper for writing memory specified by a DBGC variable.
422	*
423	* @returns VBox status code appropriate to return from a command.
424	* @param pCmdHlp Pointer to the command callback structure.
425	* @param pVM VM handle if GC or physical HC address.
426	* @param pvBuffer What to write.
427	* @param cbWrite Number of bytes to write.
428	* @param pVarPointer DBGC variable specifying where to start reading.
429	* @param pcbWritten Where to store the number of bytes written.
430	* This is optional. If NULL be aware that some of the buffer
431	* might have been written to the specified address.
432	*/
433	typedef DECLCALLBACK(int) FNDBGCHLPMEMWRITE(PDBGCCMDHLP pCmdHlp, PVM pVM, const void pvBuffer, size_t cbWrite, PCDBGCVAR pVarPointer, size_t pcbWritten);
434	/** Pointer to a FNDBGCHLPMEMWRITE() function. */
435	typedef FNDBGCHLPMEMWRITE *PFNDBGCHLPMEMWRITE;
436
437
438
439	/**
440	* Executes command an expression.
441	* (Hopefully the parser and functions are fully reentrant.)
442	*
443	* @returns VBox status code appropriate to return from a command.
444	* @param pCmdHlp Pointer to the command callback structure.
445	* @param pszExpr The expression. Format string with the format DBGC extensions.
446	* @param ... Format arguments.
447	*/
448	typedef DECLCALLBACK(int) FNDBGCHLPEXEC(PDBGCCMDHLP pCmdHlp, const char *pszExpr, ...);
449	/** Pointer to a FNDBGCHLPEVAL() function. */
450	typedef FNDBGCHLPEXEC *PFNDBGCHLPEXEC;
451
452
453	/**
454	* Helper functions for commands.
455	*/
456	typedef struct DBGCCMDHLP
457	{
458	/** Pointer to a FNDBCHLPWRITE() function. */
459	PFNDBGCHLPWRITE pfnWrite;
460	/** Pointer to a FNDBGCHLPPRINTF() function. */
461	PFNDBGCHLPPRINTF pfnPrintf;
462	/** Pointer to a FNDBGCHLPPRINTFV() function. */
463	PFNDBGCHLPPRINTFV pfnPrintfV;
464	/** Pointer to a FNDBGCHLPVBOXERROR() function. */
465	PFNDBGCHLPVBOXERROR pfnVBoxError;
466	/** Pointer to a FNDBGCHLPVBOXERRORV() function. */
467	PFNDBGCHLPVBOXERRORV pfnVBoxErrorV;
468	/** Pointer to a FNDBGCHLPMEMREAD() function. */
469	PFNDBGCHLPMEMREAD pfnMemRead;
470	/** Pointer to a FNDBGCHLPMEMWRITE() function. */
471	PFNDBGCHLPMEMWRITE pfnMemWrite;
472	/** Pointer to a FNDBGCHLPEXEC() function. */
473	PFNDBGCHLPEXEC pfnExec;
474
475	/**
476	* Evaluates an expression.
477	* (Hopefully the parser and functions are fully reentrant.)
478	*
479	* @returns VBox status code appropriate to return from a command.
480	* @param pCmdHlp Pointer to the command callback structure.
481	* @param pResult Where to store the result.
482	* @param pszExpr The expression. Format string with the format DBGC extensions.
483	* @param va Format arguments.
484	*/
485	DECLCALLBACKMEMBER(int, pfnEvalV)(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, va_list va);
486
487	/**
488	* Print an error and fail the current command.
489	*
490	* @returns VBox status code to pass upwards.
491	*
492	* @param pCmdHlp Pointer to the command callback structure.
493	* @param pCmd The failing command.
494	* @param pszFormat The error message format string.
495	* @param va Format arguments.
496	*/
497	DECLCALLBACKMEMBER(int, pfnFailV)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, va_list va);
498
499	/**
500	* Converts a DBGC variable to a DBGF address structure.
501	*
502	* @returns VBox status code.
503	* @param pCmdHlp Pointer to the command callback structure.
504	* @param pVar The variable to convert.
505	* @param pAddress The target address.
506	*/
507	DECLCALLBACKMEMBER(int, pfnVarToDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress);
508
509	/**
510	* Converts a DBGC variable to a 64-bit number.
511	*
512	* @returns VBox status code.
513	* @param pCmdHlp Pointer to the command callback structure.
514	* @param pVar The variable to convert.
515	* @param pu64Number Where to store the number.
516	*/
517	DECLCALLBACKMEMBER(int, pfnVarToNumber)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number);
518
519	/**
520	* Converts a DBGC variable to a boolean.
521	*
522	* @returns VBox status code.
523	* @param pCmdHlp Pointer to the command callback structure.
524	* @param pVar The variable to convert.
525	* @param pf Where to store the boolean.
526	*/
527	DECLCALLBACKMEMBER(int, pfnVarToBool)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf);
528
529	/**
530	* Get the range of a variable in bytes, resolving symbols if necessary.
531	*
532	* @returns VBox status code.
533	* @param pCmdHlp Pointer to the command callback structure.
534	* @param pVar The variable to convert.
535	* @param cbElement Conversion factor for element ranges.
536	* @param cbDefault The default range.
537	* @param pcbRange The length of the range.
538	*/
539	DECLCALLBACKMEMBER(int, pfnVarGetRange)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault,
540	uint64_t *pcbRange);
541
542	/**
543	* Converts a variable to one with the specified type.
544	*
545	* This preserves the range.
546	*
547	* @returns VBox status code.
548	* @param pCmdHlp Pointer to the command callback structure.
549	* @param pVar The variable to convert.
550	* @param enmToType The target type.
551	* @param fConvSyms If @c true, then attempt to resolve symbols.
552	* @param pResult The output variable. Can be the same as @a pVar.
553	*/
554	DECLCALLBACKMEMBER(int, pfnVarConvert)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms,
555	PDBGCVAR pResult);
556
557	/**
558	* Gets a DBGF output helper that directs the output to the debugger
559	* console.
560	*
561	* @returns Pointer to the helper structure.
562	* @param pCmdHlp Pointer to the command callback structure.
563	*/
564	DECLCALLBACKMEMBER(PCDBGFINFOHLP, pfnGetDbgfOutputHlp)(PDBGCCMDHLP pCmdHlp);
565
566	} DBGCCMDHLP;
567
568
569	#ifdef IN_RING3
570
571	/**
572	* Command helper for writing formatted text to the debug console.
573	*
574	* @returns VBox status.
575	* @param pCmdHlp Pointer to the command callback structure.
576	* @param pszFormat The format string.
577	* This is using the log formatter, so it's format extensions can be used.
578	* @param ... Arguments specified in the format string.
579	*/
580	DECLINLINE(int) DBGCCmdHlpPrintf(PDBGCCMDHLP pCmdHlp, const char *pszFormat, ...)
581	{
582	va_list va;
583	int rc;
584
585	va_start(va, pszFormat);
586	rc = pCmdHlp->pfnPrintfV(pCmdHlp, NULL, pszFormat, va);
587	va_end(va);
588
589	return rc;
590	}
591
592	/**
593	* @copydoc FNDBGCHLPVBOXERROR
594	*/
595	DECLINLINE(int) DBGCCmdHlpVBoxError(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...)
596	{
597	va_list va;
598
599	va_start(va, pszFormat);
600	rc = pCmdHlp->pfnVBoxErrorV(pCmdHlp, rc, pszFormat, va);
601	va_end(va);
602
603	return rc;
604	}
605
606	/**
607	* @copydoc FNDBGCHLPMEMREAD
608	*/
609	DECLINLINE(int) DBGCCmdHlpMemRead(PDBGCCMDHLP pCmdHlp, PVM pVM, void pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t pcbRead)
610	{
611	return pCmdHlp->pfnMemRead(pCmdHlp, pVM, pvBuffer, cbRead, pVarPointer, pcbRead);
612	}
613
614	/**
615	* Evaluates an expression.
616	* (Hopefully the parser and functions are fully reentrant.)
617	*
618	* @returns VBox status code appropriate to return from a command.
619	* @param pCmdHlp Pointer to the command callback structure.
620	* @param pResult Where to store the result.
621	* @param pszExpr The expression. Format string with the format DBGC extensions.
622	* @param ... Format arguments.
623	*/
624	DECLINLINE(int) DBGCCmdHlpEval(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, ...)
625	{
626	va_list va;
627	int rc;
628
629	va_start(va, pszExpr);
630	rc = pCmdHlp->pfnEvalV(pCmdHlp, pResult, pszExpr, va);
631	va_end(va);
632
633	return rc;
634	}
635
636	/**
637	* Print an error and fail the current command.
638	*
639	* @returns VBox status code to pass upwards.
640	*
641	* @param pCmdHlp Pointer to the command callback structure.
642	* @param pCmd The failing command.
643	* @param pszFormat The error message format string.
644	* @param ... Format arguments.
645	*/
646	DECLINLINE(int) DBGCCmdHlpFail(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, ...)
647	{
648	va_list va;
649	int rc;
650
651	va_start(va, pszFormat);
652	rc = pCmdHlp->pfnFailV(pCmdHlp, pCmd, pszFormat, va);
653	va_end(va);
654
655	return rc;
656	}
657
658	/**
659	* @copydoc DBGCCMDHLP::pfnVarToDbgfAddr
660	*/
661	DECLINLINE(int) DBGCCmdHlpVarToDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress)
662	{
663	return pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, pAddress);
664	}
665
666	/**
667	* Converts an variable to a flat address.
668	*
669	* @returns VBox status code.
670	* @param pCmdHlp Pointer to the command callback structure.
671	* @param pVar The variable to convert.
672	* @param pFlatPtr Where to store the flat address.
673	*/
674	DECLINLINE(int) DBGCCmdHlpVarToFlatAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PRTGCPTR pFlatPtr)
675	{
676	DBGFADDRESS Addr;
677	int rc = pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, &Addr);
678	if (RT_SUCCESS(rc))
679	*pFlatPtr = Addr.FlatPtr;
680	return rc;
681	}
682
683	/**
684	* @copydoc DBGCCMDHLP::pfnVarToNumber
685	*/
686	DECLINLINE(int) DBGCCmdHlpVarToNumber(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number)
687	{
688	return pCmdHlp->pfnVarToNumber(pCmdHlp, pVar, pu64Number);
689	}
690
691	/**
692	* @copydoc DBGCCMDHLP::pfnVarToBool
693	*/
694	DECLINLINE(int) DBGCCmdHlpVarToBool(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf)
695	{
696	return pCmdHlp->pfnVarToBool(pCmdHlp, pVar, pf);
697	}
698
699	/**
700	* @copydoc DBGCCMDHLP::pfnVarGetRange
701	*/
702	DECLINLINE(int) DBGCCmdHlpVarGetRange(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault, uint64_t *pcbRange)
703	{
704	return pCmdHlp->pfnVarGetRange(pCmdHlp, pVar, cbElement, cbDefault, pcbRange);
705	}
706
707	/**
708	* @copydoc DBGCCMDHLP::pfnVarConvert
709	*/
710	DECLINLINE(int) DBGCCmdHlpConvert(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms, PDBGCVAR pResult)
711	{
712	return pCmdHlp->pfnVarConvert(pCmdHlp, pVar, enmToType, fConvSyms, pResult);
713	}
714
715	/**
716	* @copydoc DBGCCMDHLP::pfnGetDbgfOutputHlp
717	*/
718	DECLINLINE(PCDBGFINFOHLP) DBGCCmdHlpGetDbgfOutputHlp(PDBGCCMDHLP pCmdHlp)
719	{
720	return pCmdHlp->pfnGetDbgfOutputHlp(pCmdHlp);
721	}
722
723	#endif /* IN_RING3 */
724
725
726
727	/**
728	* Command handler.
729	*
730	* The console will call the handler for a command once it's finished
731	* parsing the user input. The command handler function is responsible
732	* for executing the command itself.
733	*
734	* @returns VBox status.
735	* @param pCmd Pointer to the command descriptor (as registered).
736	* @param pCmdHlp Pointer to command helper functions.
737	* @param pVM Pointer to the current VM (if any).
738	* @param paArgs Pointer to (readonly) array of arguments.
739	* @param cArgs Number of arguments in the array.
740	* @param pResult Where to store the result. NULL if no result descriptor was specified.
741	*/
742	typedef DECLCALLBACK(int) FNDBGCCMD(PCDBGCCMD pCmd, PDBGCCMDHLP pCmdHlp, PVM pVM, PCDBGCVAR pArgs, unsigned cArgs, PDBGCVAR pResult);
743	/** Pointer to a FNDBGCCMD() function. */
744	typedef FNDBGCCMD *PFNDBGCCMD;
745
746	/**
747	* DBGC command descriptor.
748	*
749	* If a pResultDesc is specified the command can be called and used
750	* as a function too. If it's a pure function, set fFlags to
751	* DBGCCMD_FLAGS_FUNCTION.
752	*/
753	typedef struct DBGCCMD
754	{
755	/** Command string. */
756	const char *pszCmd;
757	/** Minimum number of arguments. */
758	unsigned cArgsMin;
759	/** Max number of arguments. */
760	unsigned cArgsMax;
761	/** Argument descriptors (array). */
762	PCDBGCVARDESC paArgDescs;
763	/** Number of argument descriptors. */
764	unsigned cArgDescs;
765	/** Result descriptor. */
766	PCDBGCVARDESC pResultDesc;
767	/** flags. (reserved for now) */
768	unsigned fFlags;
769	/** Handler function. */
770	PFNDBGCCMD pfnHandler;
771	/** Command syntax. */
772	const char *pszSyntax;
773	/** Command description. */
774	const char *pszDescription;
775	} DBGCCMD;
776
777	/** DBGCCMD Flags.
778	* @{
779	*/
780	/** The description is of a pure function which cannot be invoked
781	* as a command from the commandline. */
782	#define DBGCCMD_FLAGS_FUNCTION 1
783	/** @} */
784
785
786
787	/** Pointer to a DBGC backend. */
788	typedef struct DBGCBACK *PDBGCBACK;
789
790	/**
791	* Checks if there is input.
792	*
793	* @returns true if there is input ready.
794	* @returns false if there not input ready.
795	* @param pBack Pointer to the backend structure supplied by
796	* the backend. The backend can use this to find
797	* it's instance data.
798	* @param cMillies Number of milliseconds to wait on input data.
799	*/
800	typedef DECLCALLBACK(bool) FNDBGCBACKINPUT(PDBGCBACK pBack, uint32_t cMillies);
801	/** Pointer to a FNDBGCBACKINPUT() callback. */
802	typedef FNDBGCBACKINPUT *PFNDBGCBACKINPUT;
803
804	/**
805	* Read input.
806	*
807	* @returns VBox status code.
808	* @param pBack Pointer to the backend structure supplied by
809	* the backend. The backend can use this to find
810	* it's instance data.
811	* @param pvBuf Where to put the bytes we read.
812	* @param cbBuf Maximum nymber of bytes to read.
813	* @param pcbRead Where to store the number of bytes actually read.
814	* If NULL the entire buffer must be filled for a
815	* successful return.
816	*/
817	typedef DECLCALLBACK(int) FNDBGCBACKREAD(PDBGCBACK pBack, void pvBuf, size_t cbBuf, size_t pcbRead);
818	/** Pointer to a FNDBGCBACKREAD() callback. */
819	typedef FNDBGCBACKREAD *PFNDBGCBACKREAD;
820
821	/**
822	* Write (output).
823	*
824	* @returns VBox status code.
825	* @param pBack Pointer to the backend structure supplied by
826	* the backend. The backend can use this to find
827	* it's instance data.
828	* @param pvBuf What to write.
829	* @param cbBuf Number of bytes to write.
830	* @param pcbWritten Where to store the number of bytes actually written.
831	* If NULL the entire buffer must be successfully written.
832	*/
833	typedef DECLCALLBACK(int) FNDBGCBACKWRITE(PDBGCBACK pBack, const void pvBuf, size_t cbBuf, size_t pcbWritten);
834	/** Pointer to a FNDBGCBACKWRITE() callback. */
835	typedef FNDBGCBACKWRITE *PFNDBGCBACKWRITE;
836
837	/**
838	* Ready / busy notification.
839	*
840	* @param pBack Pointer to the backend structure supplied by
841	* the backend. The backend can use this to find
842	* it's instance data.
843	* @param fReady Whether it's ready (true) or busy (false).
844	*/
845	typedef DECLCALLBACK(void) FNDBGCBACKSETREADY(PDBGCBACK pBack, bool fReady);
846	/** Pointer to a FNDBGCBACKSETREADY() callback. */
847	typedef FNDBGCBACKSETREADY *PFNDBGCBACKSETREADY;
848
849
850	/**
851	* The communication backend provides the console with a number of callbacks
852	* which can be used
853	*/
854	typedef struct DBGCBACK
855	{
856	/** Check for input. */
857	PFNDBGCBACKINPUT pfnInput;
858	/** Read input. */
859	PFNDBGCBACKREAD pfnRead;
860	/** Write output. */
861	PFNDBGCBACKWRITE pfnWrite;
862	/** Ready / busy notification. */
863	PFNDBGCBACKSETREADY pfnSetReady;
864	} DBGCBACK;
865
866
867	/**
868	* Make a console instance.
869	*
870	* This will not return until either an 'exit' command is issued or a error code
871	* indicating connection loss is encountered.
872	*
873	* @returns VINF_SUCCESS if console termination caused by the 'exit' command.
874	* @returns The VBox status code causing the console termination.
875	*
876	* @param pVM VM Handle.
877	* @param pBack Pointer to the backend structure. This must contain
878	* a full set of function pointers to service the console.
879	* @param fFlags Reserved, must be zero.
880	* @remark A forced termination of the console is easiest done by forcing the
881	* callbacks to return fatal failures.
882	*/
883	DBGDECL(int) DBGCCreate(PVM pVM, PDBGCBACK pBack, unsigned fFlags);
884
885
886	/**
887	* Register one or more external commands.
888	*
889	* @returns VBox status.
890	* @param paCommands Pointer to an array of command descriptors.
891	* The commands must be unique. It's not possible
892	* to register the same commands more than once.
893	* @param cCommands Number of commands.
894	*/
895	DBGDECL(int) DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
896
897
898	/**
899	* Deregister one or more external commands previously registered by
900	* DBGCRegisterCommands().
901	*
902	* @returns VBox status.
903	* @param paCommands Pointer to an array of command descriptors
904	* as given to DBGCRegisterCommands().
905	* @param cCommands Number of commands.
906	*/
907	DBGDECL(int) DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
908
909
910	/**
911	* Spawns a new thread with a TCP based debugging console service.
912	*
913	* @returns VBox status.
914	* @param pVM VM handle.
915	* @param ppvData Where to store the pointer to instance data.
916	*/
917	DBGDECL(int) DBGCTcpCreate(PVM pVM, void **ppvUser);
918
919	/**
920	* Terminates any running TCP base debugger console service.
921	*
922	* @returns VBox status.
923	* @param pVM VM handle.
924	* @param pvData Instance data set by DBGCTcpCreate().
925	*/
926	DBGDECL(int) DBGCTcpTerminate(PVM pVM, void *pvData);
927
928
929	/** @defgroup grp_dbgc_plug_in The DBGC Plug-in Interface
930	* @{
931	*/
932
933	/** The plug-in module name prefix. */
934	#define DBGC_PLUG_IN_PREFIX "DBGCPlugIn"
935
936	/** The name of the plug-in entry point (FNDBGCPLUGIN) */
937	#define DBGC_PLUG_IN_ENTRYPOINT "DBGCPlugInEntry"
938
939	/**
940	* DBGC plug-in operations.
941	*/
942	typedef enum DBGCPLUGINOP
943	{
944	/** The usual invalid first value. */
945	DBGCPLUGINOP_INVALID,
946	/** Initialize the plug-in, register all the stuff.
947	* The plug-in will be unloaded on failure.
948	* uArg: The VirtualBox version (major+minor). */
949	DBGCPLUGINOP_INIT,
950	/** Terminate the plug-ing, deregister all the stuff.
951	* The plug-in will be unloaded after this call regardless of the return
952	* code. */
953	DBGCPLUGINOP_TERM,
954	/** The usual 32-bit hack. */
955	DBGCPLUGINOP_32BIT_HACK = 0x7fffffff
956	} DBGCPLUGINOP;
957
958	/**
959	* DBGC plug-in main entry point.
960	*
961	* @returns VBox status code.
962	*
963	* @param enmOperation The operation.
964	* @param pVM The VM handle. This may be NULL.
965	* @param uArg Extra argument.
966	*/
967	typedef DECLCALLBACK(int) FNDBGCPLUGIN(DBGCPLUGINOP enmOperation, PVM pVM, uintptr_t uArg);
968	/** Pointer to a FNDBGCPLUGIN. */
969	typedef FNDBGCPLUGIN *PFNDBGCPLUGIN;
970
971	/** @copydoc FNDBGCPLUGIN */
972	DECLEXPORT(int) DBGCPlugInEntry(DBGCPLUGINOP enmOperation, PVM pVM, uintptr_t uArg);
973
974	/** @} */
975
976
977	RT_C_DECLS_END
978
979	#endif

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: