dbg.h@ 34801

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

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

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

Download in other formats: