dbg.h@ 55969

Last change on this file since 55969 was 55881, checked in by vboxsync, 10 years ago
DBGF,DBGC: Moved the plug-ins from DBGC to DBGF so we can make use of them via IMachineDebugger.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 36.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-2015 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
45	#ifdef IN_RING3 /* The debugger stuff is ring-3 only. */
46
47	/** @defgroup grp_dbgc The Debugger Console API
48	* @{
49	*/
50
51	/** @def VBOX_WITH_DEBUGGER
52	* The build is with debugger module. Test if this is defined before registering
53	* external debugger commands. This is normally defined in Config.kmk.
54	*/
55	#ifdef DOXYGEN_RUNNING
56	# define VBOX_WITH_DEBUGGER
57	#endif
58
59
60	/**
61	* DBGC variable category.
62	*
63	* Used to describe an argument to a command or function and a functions
64	* return value.
65	*/
66	typedef enum DBGCVARCAT
67	{
68	/** Any type is fine. */
69	DBGCVAR_CAT_ANY = 0,
70	/** Any kind of pointer or number. */
71	DBGCVAR_CAT_POINTER_NUMBER,
72	/** Any kind of pointer or number, no range. */
73	DBGCVAR_CAT_POINTER_NUMBER_NO_RANGE,
74	/** Any kind of pointer. */
75	DBGCVAR_CAT_POINTER,
76	/** Any kind of pointer with no range option. */
77	DBGCVAR_CAT_POINTER_NO_RANGE,
78	/** GC pointer. */
79	DBGCVAR_CAT_GC_POINTER,
80	/** GC pointer with no range option. */
81	DBGCVAR_CAT_GC_POINTER_NO_RANGE,
82	/** Numeric argument. */
83	DBGCVAR_CAT_NUMBER,
84	/** Numeric argument with no range option. */
85	DBGCVAR_CAT_NUMBER_NO_RANGE,
86	/** String. */
87	DBGCVAR_CAT_STRING,
88	/** Symbol. */
89	DBGCVAR_CAT_SYMBOL,
90	/** Option. */
91	DBGCVAR_CAT_OPTION,
92	/** Option + string. */
93	DBGCVAR_CAT_OPTION_STRING,
94	/** Option + number. */
95	DBGCVAR_CAT_OPTION_NUMBER
96	} DBGCVARCAT;
97
98
99	/**
100	* DBGC variable type.
101	*/
102	typedef enum DBGCVARTYPE
103	{
104	/** unknown... */
105	DBGCVAR_TYPE_UNKNOWN = 0,
106	/** Flat GC pointer. */
107	DBGCVAR_TYPE_GC_FLAT,
108	/** Segmented GC pointer. */
109	DBGCVAR_TYPE_GC_FAR,
110	/** Physical GC pointer. */
111	DBGCVAR_TYPE_GC_PHYS,
112	/** Flat HC pointer. */
113	DBGCVAR_TYPE_HC_FLAT,
114	/** Physical HC pointer. */
115	DBGCVAR_TYPE_HC_PHYS,
116	/** Number. */
117	DBGCVAR_TYPE_NUMBER,
118	/** String. */
119	DBGCVAR_TYPE_STRING,
120	/** Symbol. */
121	DBGCVAR_TYPE_SYMBOL,
122	/** Special type used when querying symbols. */
123	DBGCVAR_TYPE_ANY
124	} DBGCVARTYPE;
125
126	/** @todo Rename to DBGCVAR_IS_xyz. */
127
128	/** Checks if the specified variable type is of a pointer persuasion. */
129	#define DBGCVAR_ISPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && enmType <= DBGCVAR_TYPE_HC_PHYS)
130	/** Checks if the specified variable type is of a pointer persuasion. */
131	#define DBGCVAR_IS_FAR_PTR(enmType) ((enmType) == DBGCVAR_TYPE_GC_FAR)
132	/** Checks if the specified variable type is of a pointer persuasion and of the guest context sort. */
133	#define DBGCVAR_ISGCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && (enmType) <= DBGCVAR_TYPE_GC_PHYS)
134	/** Checks if the specified variable type is of a pointer persuasion and of the host context sort. */
135	#define DBGCVAR_ISHCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_HC_FLAT && (enmType) <= DBGCVAR_TYPE_HC_PHYS)
136
137
138	/**
139	* DBGC variable range type.
140	*/
141	typedef enum DBGCVARRANGETYPE
142	{
143	/** No range appliable or no range specified. */
144	DBGCVAR_RANGE_NONE = 0,
145	/** Number of elements. */
146	DBGCVAR_RANGE_ELEMENTS,
147	/** Number of bytes. */
148	DBGCVAR_RANGE_BYTES
149	} DBGCVARRANGETYPE;
150
151
152	/**
153	* Variable descriptor.
154	*/
155	typedef struct DBGCVARDESC
156	{
157	/** The minimal number of times this argument may occur.
158	* Use 0 here to inidicate that the argument is optional. */
159	unsigned cTimesMin;
160	/** Maximum number of occurrences.
161	* Use ~0 here to indicate infinite. */
162	unsigned cTimesMax;
163	/** Argument category. */
164	DBGCVARCAT enmCategory;
165	/** Flags, DBGCVD_FLAGS_* */
166	unsigned fFlags;
167	/** Argument name. */
168	const char *pszName;
169	/** Argument name. */
170	const char *pszDescription;
171	} DBGCVARDESC;
172	/** Pointer to an argument descriptor. */
173	typedef DBGCVARDESC *PDBGCVARDESC;
174	/** Pointer to a const argument descriptor. */
175	typedef const DBGCVARDESC *PCDBGCVARDESC;
176
177	/** Variable descriptor flags.
178	* @{ */
179	/** Indicates that the variable depends on the previous being present. */
180	#define DBGCVD_FLAGS_DEP_PREV RT_BIT(1)
181	/** @} */
182
183
184	/**
185	* DBGC variable.
186	*/
187	typedef struct DBGCVAR
188	{
189	/** Pointer to the argument descriptor. */
190	PCDBGCVARDESC pDesc;
191	/** Pointer to the next argument. */
192	struct DBGCVAR *pNext;
193
194	/** Argument type. */
195	DBGCVARTYPE enmType;
196	/** Type specific. */
197	union
198	{
199	/** Flat GC Address. (DBGCVAR_TYPE_GC_FLAT) */
200	RTGCPTR GCFlat;
201	/** Far (16:32) GC Address. (DBGCVAR_TYPE_GC_FAR) */
202	RTFAR32 GCFar;
203	/** Physical GC Address. (DBGCVAR_TYPE_GC_PHYS) */
204	RTGCPHYS GCPhys;
205	/** Flat HC Address. (DBGCVAR_TYPE_HC_FLAT) */
206	void *pvHCFlat;
207	/** Physical GC Address. (DBGCVAR_TYPE_HC_PHYS) */
208	RTHCPHYS HCPhys;
209	/** String. (DBGCVAR_TYPE_STRING)
210	* The basic idea is the the this is a pointer to the expression we're
211	* parsing, so no messing with freeing. */
212	const char *pszString;
213	/** Number. (DBGCVAR_TYPE_NUMBER) */
214	uint64_t u64Number;
215	} u;
216
217	/** Range type. */
218	DBGCVARRANGETYPE enmRangeType;
219	/** Range. The use of the content depends on the enmRangeType. */
220	uint64_t u64Range;
221	} DBGCVAR;
222	/** Pointer to a command argument. */
223	typedef DBGCVAR *PDBGCVAR;
224	/** Pointer to a const command argument. */
225	typedef const DBGCVAR *PCDBGCVAR;
226
227
228	/**
229	* Macro for initializing a DBGC variable with defaults.
230	* The result is an unknown variable type without any range.
231	*/
232	#define DBGCVAR_INIT(pVar) \
233	do { \
234	(pVar)->pDesc = NULL;\
235	(pVar)->pNext = NULL; \
236	(pVar)->enmType = DBGCVAR_TYPE_UNKNOWN; \
237	(pVar)->u.u64Number = 0; \
238	(pVar)->enmRangeType = DBGCVAR_RANGE_NONE; \
239	(pVar)->u64Range = 0; \
240	} while (0)
241
242	/**
243	* Macro for initializing a DBGC variable with a HC physical address.
244	*/
245	#define DBGCVAR_INIT_HC_PHYS(pVar, Phys) \
246	do { \
247	DBGCVAR_INIT(pVar); \
248	(pVar)->enmType = DBGCVAR_TYPE_HC_PHYS; \
249	(pVar)->u.HCPhys = (Phys); \
250	} while (0)
251
252	/**
253	* Macro for initializing a DBGC variable with a HC flat address.
254	*/
255	#define DBGCVAR_INIT_HC_FLAT(pVar, Flat) \
256	do { \
257	DBGCVAR_INIT(pVar); \
258	(pVar)->enmType = DBGCVAR_TYPE_HC_FLAT; \
259	(pVar)->u.pvHCFlat = (Flat); \
260	} while (0)
261
262	/**
263	* Macro for initializing a DBGC variable with a GC physical address.
264	*/
265	#define DBGCVAR_INIT_GC_PHYS(pVar, Phys) \
266	do { \
267	DBGCVAR_INIT(pVar); \
268	(pVar)->enmType = DBGCVAR_TYPE_GC_PHYS; \
269	(pVar)->u.GCPhys = (Phys); \
270	} while (0)
271
272	/**
273	* Macro for initializing a DBGC variable with a GC flat address.
274	*/
275	#define DBGCVAR_INIT_GC_FLAT(pVar, Flat) \
276	do { \
277	DBGCVAR_INIT(pVar); \
278	(pVar)->enmType = DBGCVAR_TYPE_GC_FLAT; \
279	(pVar)->u.GCFlat = (Flat); \
280	} while (0)
281
282	/**
283	* Macro for initializing a DBGC variable with a GC flat address.
284	*/
285	#define DBGCVAR_INIT_GC_FLAT_BYTE_RANGE(pVar, Flat, cbRange) \
286	do { \
287	DBGCVAR_INIT(pVar); \
288	(pVar)->enmType = DBGCVAR_TYPE_GC_FLAT; \
289	(pVar)->u.GCFlat = (Flat); \
290	DBGCVAR_SET_RANGE(pVar, DBGCVAR_RANGE_BYTES, cbRange); \
291	} while (0)
292
293	/**
294	* Macro for initializing a DBGC variable with a GC far address.
295	*/
296	#define DBGCVAR_INIT_GC_FAR(pVar, _sel, _off) \
297	do { \
298	DBGCVAR_INIT(pVar); \
299	(pVar)->enmType = DBGCVAR_TYPE_GC_FAR; \
300	(pVar)->u.GCFar.sel = (_sel); \
301	(pVar)->u.GCFar.off = (_off); \
302	} while (0)
303
304	/**
305	* Macro for initializing a DBGC variable with a number.
306	*/
307	#define DBGCVAR_INIT_NUMBER(pVar, Value) \
308	do { \
309	DBGCVAR_INIT(pVar); \
310	(pVar)->enmType = DBGCVAR_TYPE_NUMBER; \
311	(pVar)->u.u64Number = (Value); \
312	} while (0)
313
314	/**
315	* Macro for initializing a DBGC variable with a string.
316	*/
317	#define DBGCVAR_INIT_STRING(pVar, a_pszString) \
318	do { \
319	DBGCVAR_INIT(pVar); \
320	(pVar)->enmType = DBGCVAR_TYPE_STRING; \
321	(pVar)->enmRangeType = DBGCVAR_RANGE_BYTES; \
322	(pVar)->u.pszString = (a_pszString); \
323	(pVar)->u64Range = strlen(a_pszString); \
324	} while (0)
325
326
327	/**
328	* Macro for initializing a DBGC variable with a symbol.
329	*/
330	#define DBGCVAR_INIT_SYMBOL(pVar, a_pszSymbol) \
331	do { \
332	DBGCVAR_INIT(pVar); \
333	(pVar)->enmType = DBGCVAR_TYPE_SYMBOL; \
334	(pVar)->enmRangeType = DBGCVAR_RANGE_BYTES; \
335	(pVar)->u.pszString = (a_pszSymbol); \
336	(pVar)->u64Range = strlen(a_pszSymbol); \
337	} while (0)
338
339
340	/**
341	* Macro for setting the range of a DBGC variable.
342	* @param pVar The variable.
343	* @param _enmRangeType The range type.
344	* @param Value The range length value.
345	*/
346	#define DBGCVAR_SET_RANGE(pVar, _enmRangeType, Value) \
347	do { \
348	(pVar)->enmRangeType = (_enmRangeType); \
349	(pVar)->u64Range = (Value); \
350	} while (0)
351
352
353	/**
354	* Macro for setting the range of a DBGC variable.
355	* @param a_pVar The variable.
356	* @param a_cbRange The range, in bytes.
357	*/
358	#define DBGCVAR_SET_BYTE_RANGE(a_pVar, a_cbRange) \
359	DBGCVAR_SET_RANGE(a_pVar, DBGCVAR_RANGE_BYTES, a_cbRange)
360
361
362	/**
363	* Macro for resetting the range a DBGC variable.
364	* @param a_pVar The variable.
365	*/
366	#define DBGCVAR_ZAP_RANGE(a_pVar) \
367	do { \
368	(a_pVar)->enmRangeType = DBGCVAR_RANGE_NONE; \
369	(a_pVar)->u64Range = 0; \
370	} while (0)
371
372
373	/**
374	* Macro for assigning one DBGC variable to another.
375	* @param a_pResult The result (target) variable.
376	* @param a_pVar The source variable.
377	*/
378	#define DBGCVAR_ASSIGN(a_pResult, a_pVar) \
379	do { \
380	(a_pResult) = (a_pVar); \
381	} while (0)
382
383
384	/** Pointer to a command descriptor. */
385	typedef struct DBGCCMD *PDBGCCMD;
386	/** Pointer to a const command descriptor. */
387	typedef const struct DBGCCMD *PCDBGCCMD;
388
389	/** Pointer to a function descriptor. */
390	typedef struct DBGCFUNC *PDBGCFUNC;
391	/** Pointer to a const function descriptor. */
392	typedef const struct DBGCFUNC *PCDBGCFUNC;
393
394	/** Pointer to helper functions for commands. */
395	typedef struct DBGCCMDHLP *PDBGCCMDHLP;
396
397
398	/**
399	* Helper functions for commands.
400	*/
401	typedef struct DBGCCMDHLP
402	{
403	/** Magic value (DBGCCMDHLP_MAGIC). */
404	uint32_t u32Magic;
405
406	/**
407	* Command helper for writing formatted text to the debug console.
408	*
409	* @returns VBox status.
410	* @param pCmdHlp Pointer to the command callback structure.
411	* @param pcb Where to store the number of bytes written.
412	* @param pszFormat The format string. This may use all IPRT extensions as
413	* well as the debugger ones.
414	* @param ... Arguments specified in the format string.
415	*/
416	DECLCALLBACKMEMBER(int, pfnPrintf)(PDBGCCMDHLP pCmdHlp, size_t pcbWritten, const char pszFormat, ...);
417
418	/**
419	* Command helper for writing formatted text to the debug console.
420	*
421	* @returns VBox status.
422	* @param pCmdHlp Pointer to the command callback structure.
423	* @param pcb Where to store the number of bytes written.
424	* @param pszFormat The format string. This may use all IPRT extensions as
425	* well as the debugger ones.
426	* @param args Arguments specified in the format string.
427	*/
428	DECLCALLBACKMEMBER(int, pfnPrintfV)(PDBGCCMDHLP pCmdHlp, size_t pcbWritten, const char pszFormat, va_list args);
429
430	/**
431	* Command helper for formatting a string with debugger format specifiers.
432	*
433	* @returns The number of bytes written.
434	* @param pCmdHlp Pointer to the command callback structure.
435	* @param pszBuf The output buffer.
436	* @param cbBuf The size of the output buffer.
437	* @param pszFormat The format string. This may use all IPRT extensions as
438	* well as the debugger ones.
439	* @param ... Arguments specified in the format string.
440	*/
441	DECLCALLBACKMEMBER(size_t, pfnStrPrintf)(PDBGCCMDHLP pCmdHlp, char pszBuf, size_t cbBuf, const char pszFormat, ...);
442
443	/**
444	* Command helper for formatting a string with debugger format specifiers.
445	*
446	* @returns The number of bytes written.
447	* @param pCmdHlp Pointer to the command callback structure.
448	* @param pszBuf The output buffer.
449	* @param cbBuf The size of the output buffer.
450	* @param pszFormat The format string. This may use all IPRT extensions as
451	* well as the debugger ones.
452	* @param va Arguments specified in the format string.
453	*/
454	DECLCALLBACKMEMBER(size_t, pfnStrPrintfV)(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
455	const char *pszFormat, va_list va);
456
457	/**
458	* Command helper for formatting and error message for a VBox status code.
459	*
460	* @returns VBox status code appropriate to return from a command.
461	* @param pCmdHlp Pointer to the command callback structure.
462	* @param rc The VBox status code.
463	* @param pszFormat Format string for additional messages. Can be NULL.
464	* @param ... Format arguments, optional.
465	*/
466	DECLCALLBACKMEMBER(int, pfnVBoxError)(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...);
467
468	/**
469	* Command helper for formatting and error message for a VBox status code.
470	*
471	* @returns VBox status code appropriate to return from a command.
472	* @param pCmdHlp Pointer to the command callback structure.
473	* @param rc The VBox status code.
474	* @param pcb Where to store the number of bytes written.
475	* @param pszFormat Format string for additional messages. Can be NULL.
476	* @param args Format arguments, optional.
477	*/
478	DECLCALLBACKMEMBER(int, pfnVBoxErrorV)(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, va_list args);
479
480	/**
481	* Command helper for reading memory specified by a DBGC variable.
482	*
483	* @returns VBox status code appropriate to return from a command.
484	* @param pCmdHlp Pointer to the command callback structure.
485	* @param pvBuffer Where to store the read data.
486	* @param cbRead Number of bytes to read.
487	* @param pVarPointer DBGC variable specifying where to start reading.
488	* @param pcbRead Where to store the number of bytes actually read.
489	* This optional, but it's useful when read GC virtual memory where a
490	* page in the requested range might not be present.
491	* If not specified not-present failure or end of a HC physical page
492	* will cause failure.
493	*/
494	DECLCALLBACKMEMBER(int, pfnMemRead)(PDBGCCMDHLP pCmdHlp, void pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t pcbRead);
495
496	/**
497	* Command helper for writing memory specified by a DBGC variable.
498	*
499	* @returns VBox status code appropriate to return from a command.
500	* @param pCmdHlp Pointer to the command callback structure.
501	* @param pvBuffer What to write.
502	* @param cbWrite Number of bytes to write.
503	* @param pVarPointer DBGC variable specifying where to start reading.
504	* @param pcbWritten Where to store the number of bytes written.
505	* This is optional. If NULL be aware that some of the buffer
506	* might have been written to the specified address.
507	*/
508	DECLCALLBACKMEMBER(int, pfnMemWrite)(PDBGCCMDHLP pCmdHlp, const void pvBuffer, size_t cbWrite, PCDBGCVAR pVarPointer, size_t pcbWritten);
509
510	/**
511	* Executes command an expression.
512	* (Hopefully the parser and functions are fully reentrant.)
513	*
514	* @returns VBox status code appropriate to return from a command.
515	* @param pCmdHlp Pointer to the command callback structure.
516	* @param pszExpr The expression. Format string with the format DBGC extensions.
517	* @param ... Format arguments.
518	*/
519	DECLCALLBACKMEMBER(int, pfnExec)(PDBGCCMDHLP pCmdHlp, const char *pszExpr, ...);
520
521	/**
522	* Evaluates an expression.
523	* (Hopefully the parser and functions are fully reentrant.)
524	*
525	* @returns VBox status code appropriate to return from a command.
526	* @param pCmdHlp Pointer to the command callback structure.
527	* @param pResult Where to store the result.
528	* @param pszExpr The expression. Format string with the format DBGC extensions.
529	* @param va Format arguments.
530	*/
531	DECLCALLBACKMEMBER(int, pfnEvalV)(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, va_list va);
532
533	/**
534	* Print an error and fail the current command.
535	*
536	* @returns VBox status code to pass upwards.
537	*
538	* @param pCmdHlp Pointer to the command callback structure.
539	* @param pCmd The failing command.
540	* @param pszFormat The error message format string.
541	* @param va Format arguments.
542	*/
543	DECLCALLBACKMEMBER(int, pfnFailV)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, va_list va);
544
545	/**
546	* Print an error and fail the current command.
547	*
548	* @returns VBox status code to pass upwards.
549	*
550	* @param pCmdHlp Pointer to the command callback structure.
551	* @param pCmd The failing command.
552	* @param rc The status code indicating the failure. This will
553	* be appended to the message after a colon (': ').
554	* @param pszFormat The error message format string.
555	* @param va Format arguments.
556	*
557	* @see DBGCCmdHlpFailRc
558	*/
559	DECLCALLBACKMEMBER(int, pfnFailRcV)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc, const char *pszFormat, va_list va);
560
561	/**
562	* Parser error.
563	*
564	* @returns VBox status code to pass upwards.
565	*
566	* @param pCmdHlp Pointer to the command callback structure.
567	* @param pCmd The failing command, can be NULL but shouldn't.
568	* @param iArg The offending argument, -1 when lazy.
569	* @param pszExpr The expression.
570	* @param iLine The line number.
571	*/
572	DECLCALLBACKMEMBER(int, pfnParserError)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int iArg, const char *pszExpr, unsigned iLine);
573
574	/**
575	* Converts a DBGC variable to a DBGF address structure.
576	*
577	* @returns VBox status code.
578	* @param pCmdHlp Pointer to the command callback structure.
579	* @param pVar The variable to convert.
580	* @param pAddress The target address.
581	*/
582	DECLCALLBACKMEMBER(int, pfnVarToDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress);
583
584	/**
585	* Converts a DBGF address structure to a DBGC variable.
586	*
587	* @returns VBox status code.
588	* @param pCmdHlp Pointer to the command callback structure.
589	* @param pAddress The source address.
590	* @param pResult The result variable.
591	*/
592	DECLCALLBACKMEMBER(int, pfnVarFromDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGFADDRESS pAddress, PDBGCVAR pResult);
593
594	/**
595	* Converts a DBGC variable to a 64-bit number.
596	*
597	* @returns VBox status code.
598	* @param pCmdHlp Pointer to the command callback structure.
599	* @param pVar The variable to convert.
600	* @param pu64Number Where to store the number.
601	*/
602	DECLCALLBACKMEMBER(int, pfnVarToNumber)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number);
603
604	/**
605	* Converts a DBGC variable to a boolean.
606	*
607	* @returns VBox status code.
608	* @param pCmdHlp Pointer to the command callback structure.
609	* @param pVar The variable to convert.
610	* @param pf Where to store the boolean.
611	*/
612	DECLCALLBACKMEMBER(int, pfnVarToBool)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf);
613
614	/**
615	* Get the range of a variable in bytes, resolving symbols if necessary.
616	*
617	* @returns VBox status code.
618	* @param pCmdHlp Pointer to the command callback structure.
619	* @param pVar The variable to convert.
620	* @param cbElement Conversion factor for element ranges.
621	* @param cbDefault The default range.
622	* @param pcbRange The length of the range.
623	*/
624	DECLCALLBACKMEMBER(int, pfnVarGetRange)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault,
625	uint64_t *pcbRange);
626
627	/**
628	* Converts a variable to one with the specified type.
629	*
630	* This preserves the range.
631	*
632	* @returns VBox status code.
633	* @param pCmdHlp Pointer to the command callback structure.
634	* @param pVar The variable to convert.
635	* @param enmToType The target type.
636	* @param fConvSyms If @c true, then attempt to resolve symbols.
637	* @param pResult The output variable. Can be the same as @a pVar.
638	*/
639	DECLCALLBACKMEMBER(int, pfnVarConvert)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms,
640	PDBGCVAR pResult);
641
642	/**
643	* Gets a DBGF output helper that directs the output to the debugger
644	* console.
645	*
646	* @returns Pointer to the helper structure.
647	* @param pCmdHlp Pointer to the command callback structure.
648	*/
649	DECLCALLBACKMEMBER(PCDBGFINFOHLP, pfnGetDbgfOutputHlp)(PDBGCCMDHLP pCmdHlp);
650
651	/**
652	* Gets the ID currently selected CPU.
653	*
654	* @returns Current CPU ID.
655	* @param pCmdHlp Pointer to the command callback structure.
656	*/
657	DECLCALLBACKMEMBER(VMCPUID, pfnGetCurrentCpu)(PDBGCCMDHLP pCmdHlp);
658
659	/**
660	* Gets the mode the currently selected CPU is running in, in the current
661	* context.
662	*
663	* @returns Current CPU mode.
664	* @param pCmdHlp Pointer to the command callback structure.
665	*/
666	DECLCALLBACKMEMBER(CPUMMODE, pfnGetCpuMode)(PDBGCCMDHLP pCmdHlp);
667
668	/** End marker (DBGCCMDHLP_MAGIC). */
669	uint32_t u32EndMarker;
670	} DBGCCMDHLP;
671
672	/** Magic value for DBGCCMDHLP::u32Magic. (Fyodor Mikhaylovich Dostoyevsky) */
673	#define DBGCCMDHLP_MAGIC UINT32_C(18211111)
674
675
676	#ifdef IN_RING3
677
678	/**
679	* @copydoc DBGCCMDHLP::pfnPrintf
680	*/
681	DECLINLINE(int) DBGCCmdHlpPrintf(PDBGCCMDHLP pCmdHlp, const char *pszFormat, ...)
682	{
683	va_list va;
684	int rc;
685
686	va_start(va, pszFormat);
687	rc = pCmdHlp->pfnPrintfV(pCmdHlp, NULL, pszFormat, va);
688	va_end(va);
689
690	return rc;
691	}
692
693
694	/**
695	* @copydoc DBGCCMDHLP::pfnStrPrintf
696	*/
697	DECLINLINE(size_t) DBGCCmdHlpStrPrintf(PDBGCCMDHLP pCmdHlp, char pszBuf, size_t cbBuf, const char pszFormat, ...)
698	{
699	va_list va;
700	size_t cch;
701
702	va_start(va, pszFormat);
703	cch = pCmdHlp->pfnStrPrintfV(pCmdHlp, pszBuf, cbBuf, pszFormat, va);
704	va_end(va);
705
706	return cch;
707	}
708
709	/**
710	* @copydoc FNDBGCHLPVBOXERROR
711	*/
712	DECLINLINE(int) DBGCCmdHlpVBoxError(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...)
713	{
714	va_list va;
715
716	va_start(va, pszFormat);
717	rc = pCmdHlp->pfnVBoxErrorV(pCmdHlp, rc, pszFormat, va);
718	va_end(va);
719
720	return rc;
721	}
722
723	/**
724	* @copydoc FNDBGCHLPMEMREAD
725	*/
726	DECLINLINE(int) DBGCCmdHlpMemRead(PDBGCCMDHLP pCmdHlp, void pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t pcbRead)
727	{
728	return pCmdHlp->pfnMemRead(pCmdHlp, pvBuffer, cbRead, pVarPointer, pcbRead);
729	}
730
731	/**
732	* Evaluates an expression.
733	* (Hopefully the parser and functions are fully reentrant.)
734	*
735	* @returns VBox status code appropriate to return from a command.
736	* @param pCmdHlp Pointer to the command callback structure.
737	* @param pResult Where to store the result.
738	* @param pszExpr The expression. Format string with the format DBGC extensions.
739	* @param ... Format arguments.
740	*/
741	DECLINLINE(int) DBGCCmdHlpEval(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, ...)
742	{
743	va_list va;
744	int rc;
745
746	va_start(va, pszExpr);
747	rc = pCmdHlp->pfnEvalV(pCmdHlp, pResult, pszExpr, va);
748	va_end(va);
749
750	return rc;
751	}
752
753	/**
754	* Print an error and fail the current command.
755	*
756	* @returns VBox status code to pass upwards.
757	*
758	* @param pCmdHlp Pointer to the command callback structure.
759	* @param pCmd The failing command.
760	* @param pszFormat The error message format string.
761	* @param ... Format arguments.
762	*/
763	DECLINLINE(int) DBGCCmdHlpFail(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, ...)
764	{
765	va_list va;
766	int rc;
767
768	va_start(va, pszFormat);
769	rc = pCmdHlp->pfnFailV(pCmdHlp, pCmd, pszFormat, va);
770	va_end(va);
771
772	return rc;
773	}
774
775	/**
776	* Print an error and fail the current command.
777	*
778	* Usage example:
779	* @code
780	int rc = VMMR3Something(pVM);
781	if (RT_FAILURE(rc))
782	return DBGCCmdHlpFailRc(pCmdHlp, pCmd, rc, "VMMR3Something");
783	return VINF_SUCCESS;
784	* @endcode
785	*
786	* @returns VBox status code to pass upwards.
787	*
788	* @param pCmdHlp Pointer to the command callback structure.
789	* @param pCmd The failing command.
790	* @param rc The status code indicating the failure.
791	* @param pszFormat The error message format string.
792	* @param ... Format arguments.
793	*/
794	DECLINLINE(int) DBGCCmdHlpFailRc(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc, const char *pszFormat, ...)
795	{
796	va_list va;
797
798	va_start(va, pszFormat);
799	rc = pCmdHlp->pfnFailRcV(pCmdHlp, pCmd, rc, pszFormat, va);
800	va_end(va);
801
802	return rc;
803	}
804
805	/**
806	* @copydoc DBGCCMDHLP::pfnParserError
807	*/
808	DECLINLINE(int) DBGCCmdHlpParserError(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int iArg, const char *pszExpr, unsigned iLine)
809	{
810	return pCmdHlp->pfnParserError(pCmdHlp, pCmd, iArg, pszExpr, iLine);
811	}
812
813	/** Assert+return like macro for checking parser sanity.
814	* Returns with failure if the precodition is not met. */
815	#define DBGC_CMDHLP_ASSERT_PARSER_RET(pCmdHlp, pCmd, iArg, expr) \
816	do { \
817	if (!(expr)) \
818	return DBGCCmdHlpParserError(pCmdHlp, pCmd, iArg, #expr, __LINE__); \
819	} while (0)
820
821	/** Assert+return like macro that the VM handle is present.
822	* Returns with failure if the VM handle is NIL. */
823	#define DBGC_CMDHLP_REQ_UVM_RET(pCmdHlp, pCmd, pUVM) \
824	do { \
825	if (!(pUVM)) \
826	return DBGCCmdHlpFail(pCmdHlp, pCmd, "No VM selected"); \
827	} while (0)
828
829	/**
830	* @copydoc DBGCCMDHLP::pfnVarToDbgfAddr
831	*/
832	DECLINLINE(int) DBGCCmdHlpVarToDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress)
833	{
834	return pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, pAddress);
835	}
836
837	/**
838	* @copydoc DBGCCMDHLP::pfnVarToDbgfAddr
839	*/
840	DECLINLINE(int) DBGCCmdHlpVarFromDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGFADDRESS pAddress, PDBGCVAR pResult)
841	{
842	return pCmdHlp->pfnVarFromDbgfAddr(pCmdHlp, pAddress, pResult);
843	}
844
845	/**
846	* Converts an variable to a flat address.
847	*
848	* @returns VBox status code.
849	* @param pCmdHlp Pointer to the command callback structure.
850	* @param pVar The variable to convert.
851	* @param pFlatPtr Where to store the flat address.
852	*/
853	DECLINLINE(int) DBGCCmdHlpVarToFlatAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PRTGCPTR pFlatPtr)
854	{
855	DBGFADDRESS Addr;
856	int rc = pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, &Addr);
857	if (RT_SUCCESS(rc))
858	*pFlatPtr = Addr.FlatPtr;
859	return rc;
860	}
861
862	/**
863	* @copydoc DBGCCMDHLP::pfnVarToNumber
864	*/
865	DECLINLINE(int) DBGCCmdHlpVarToNumber(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number)
866	{
867	return pCmdHlp->pfnVarToNumber(pCmdHlp, pVar, pu64Number);
868	}
869
870	/**
871	* @copydoc DBGCCMDHLP::pfnVarToBool
872	*/
873	DECLINLINE(int) DBGCCmdHlpVarToBool(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf)
874	{
875	return pCmdHlp->pfnVarToBool(pCmdHlp, pVar, pf);
876	}
877
878	/**
879	* @copydoc DBGCCMDHLP::pfnVarGetRange
880	*/
881	DECLINLINE(int) DBGCCmdHlpVarGetRange(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault, uint64_t *pcbRange)
882	{
883	return pCmdHlp->pfnVarGetRange(pCmdHlp, pVar, cbElement, cbDefault, pcbRange);
884	}
885
886	/**
887	* @copydoc DBGCCMDHLP::pfnVarConvert
888	*/
889	DECLINLINE(int) DBGCCmdHlpConvert(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms, PDBGCVAR pResult)
890	{
891	return pCmdHlp->pfnVarConvert(pCmdHlp, pVar, enmToType, fConvSyms, pResult);
892	}
893
894	/**
895	* @copydoc DBGCCMDHLP::pfnGetDbgfOutputHlp
896	*/
897	DECLINLINE(PCDBGFINFOHLP) DBGCCmdHlpGetDbgfOutputHlp(PDBGCCMDHLP pCmdHlp)
898	{
899	return pCmdHlp->pfnGetDbgfOutputHlp(pCmdHlp);
900	}
901
902	/**
903	* @copydoc DBGCCMDHLP::pfnGetCurrentCpu
904	*/
905	DECLINLINE(VMCPUID) DBGCCmdHlpGetCurrentCpu(PDBGCCMDHLP pCmdHlp)
906	{
907	return pCmdHlp->pfnGetCurrentCpu(pCmdHlp);
908	}
909
910	/**
911	* @copydoc DBGCCMDHLP::pfnGetCpuMode
912	*/
913	DECLINLINE(CPUMMODE) DBGCCmdHlpGetCpuMode(PDBGCCMDHLP pCmdHlp)
914	{
915	return pCmdHlp->pfnGetCpuMode(pCmdHlp);
916	}
917
918	#endif /* IN_RING3 */
919
920
921
922	/**
923	* Command handler.
924	*
925	* The console will call the handler for a command once it's finished
926	* parsing the user input. The command handler function is responsible
927	* for executing the command itself.
928	*
929	* @returns VBox status.
930	* @param pCmd Pointer to the command descriptor (as registered).
931	* @param pCmdHlp Pointer to command helper functions.
932	* @param pUVM The user mode VM handle, can in theory be NULL.
933	* @param paArgs Pointer to (readonly) array of arguments.
934	* @param cArgs Number of arguments in the array.
935	*/
936	typedef DECLCALLBACK(int) FNDBGCCMD(PCDBGCCMD pCmd, PDBGCCMDHLP pCmdHlp, PUVM pUVM, PCDBGCVAR paArgs, unsigned cArgs);
937	/** Pointer to a FNDBGCCMD() function. */
938	typedef FNDBGCCMD *PFNDBGCCMD;
939
940	/**
941	* DBGC command descriptor.
942	*/
943	typedef struct DBGCCMD
944	{
945	/** Command string. */
946	const char *pszCmd;
947	/** Minimum number of arguments. */
948	unsigned cArgsMin;
949	/** Max number of arguments. */
950	unsigned cArgsMax;
951	/** Argument descriptors (array). */
952	PCDBGCVARDESC paArgDescs;
953	/** Number of argument descriptors. */
954	unsigned cArgDescs;
955	/** flags. (reserved for now) */
956	unsigned fFlags;
957	/** Handler function. */
958	PFNDBGCCMD pfnHandler;
959	/** Command syntax. */
960	const char *pszSyntax;
961	/** Command description. */
962	const char *pszDescription;
963	} DBGCCMD;
964
965	/** DBGCCMD Flags.
966	* @{
967	*/
968	/** @} */
969
970
971	/**
972	* Function handler.
973	*
974	* The console will call the handler for a command once it's finished
975	* parsing the user input. The command handler function is responsible
976	* for executing the command itself.
977	*
978	* @returns VBox status.
979	* @param pCmd Pointer to the command descriptor (as registered).
980	* @param pCmdHlp Pointer to command helper functions.
981	* @param pUVM The user mode VM handle, can in theory be NULL.
982	* @param paArgs Pointer to (readonly) array of arguments.
983	* @param cArgs Number of arguments in the array.
984	* @param pResult Where to return the result.
985	*/
986	typedef DECLCALLBACK(int) FNDBGCFUNC(PCDBGCFUNC pFunc, PDBGCCMDHLP pCmdHlp, PUVM pUVM, PCDBGCVAR paArgs, unsigned cArgs,
987	PDBGCVAR pResult);
988	/** Pointer to a FNDBGCFUNC() function. */
989	typedef FNDBGCFUNC *PFNDBGCFUNC;
990
991	/**
992	* DBGC function descriptor.
993	*/
994	typedef struct DBGCFUNC
995	{
996	/** Command string. */
997	const char *pszFuncNm;
998	/** Minimum number of arguments. */
999	unsigned cArgsMin;
1000	/** Max number of arguments. */
1001	unsigned cArgsMax;
1002	/** Argument descriptors (array). */
1003	PCDBGCVARDESC paArgDescs;
1004	/** Number of argument descriptors. */
1005	unsigned cArgDescs;
1006	/** flags. (reserved for now) */
1007	unsigned fFlags;
1008	/** Handler function. */
1009	PFNDBGCFUNC pfnHandler;
1010	/** Function syntax. */
1011	const char *pszSyntax;
1012	/** Function description. */
1013	const char *pszDescription;
1014	} DBGCFUNC;
1015
1016
1017
1018	/** Pointer to a DBGC backend. */
1019	typedef struct DBGCBACK *PDBGCBACK;
1020
1021	/**
1022	* Checks if there is input.
1023	*
1024	* @returns true if there is input ready.
1025	* @returns false if there not input ready.
1026	* @param pBack Pointer to the backend structure supplied by
1027	* the backend. The backend can use this to find
1028	* it's instance data.
1029	* @param cMillies Number of milliseconds to wait on input data.
1030	*/
1031	typedef DECLCALLBACK(bool) FNDBGCBACKINPUT(PDBGCBACK pBack, uint32_t cMillies);
1032	/** Pointer to a FNDBGCBACKINPUT() callback. */
1033	typedef FNDBGCBACKINPUT *PFNDBGCBACKINPUT;
1034
1035	/**
1036	* Read input.
1037	*
1038	* @returns VBox status code.
1039	* @param pBack Pointer to the backend structure supplied by
1040	* the backend. The backend can use this to find
1041	* it's instance data.
1042	* @param pvBuf Where to put the bytes we read.
1043	* @param cbBuf Maximum nymber of bytes to read.
1044	* @param pcbRead Where to store the number of bytes actually read.
1045	* If NULL the entire buffer must be filled for a
1046	* successful return.
1047	*/
1048	typedef DECLCALLBACK(int) FNDBGCBACKREAD(PDBGCBACK pBack, void pvBuf, size_t cbBuf, size_t pcbRead);
1049	/** Pointer to a FNDBGCBACKREAD() callback. */
1050	typedef FNDBGCBACKREAD *PFNDBGCBACKREAD;
1051
1052	/**
1053	* Write (output).
1054	*
1055	* @returns VBox status code.
1056	* @param pBack Pointer to the backend structure supplied by
1057	* the backend. The backend can use this to find
1058	* it's instance data.
1059	* @param pvBuf What to write.
1060	* @param cbBuf Number of bytes to write.
1061	* @param pcbWritten Where to store the number of bytes actually written.
1062	* If NULL the entire buffer must be successfully written.
1063	*/
1064	typedef DECLCALLBACK(int) FNDBGCBACKWRITE(PDBGCBACK pBack, const void pvBuf, size_t cbBuf, size_t pcbWritten);
1065	/** Pointer to a FNDBGCBACKWRITE() callback. */
1066	typedef FNDBGCBACKWRITE *PFNDBGCBACKWRITE;
1067
1068	/**
1069	* Ready / busy notification.
1070	*
1071	* @param pBack Pointer to the backend structure supplied by
1072	* the backend. The backend can use this to find
1073	* it's instance data.
1074	* @param fReady Whether it's ready (true) or busy (false).
1075	*/
1076	typedef DECLCALLBACK(void) FNDBGCBACKSETREADY(PDBGCBACK pBack, bool fReady);
1077	/** Pointer to a FNDBGCBACKSETREADY() callback. */
1078	typedef FNDBGCBACKSETREADY *PFNDBGCBACKSETREADY;
1079
1080
1081	/**
1082	* The communication backend provides the console with a number of callbacks
1083	* which can be used
1084	*/
1085	typedef struct DBGCBACK
1086	{
1087	/** Check for input. */
1088	PFNDBGCBACKINPUT pfnInput;
1089	/** Read input. */
1090	PFNDBGCBACKREAD pfnRead;
1091	/** Write output. */
1092	PFNDBGCBACKWRITE pfnWrite;
1093	/** Ready / busy notification. */
1094	PFNDBGCBACKSETREADY pfnSetReady;
1095	} DBGCBACK;
1096
1097	DBGDECL(int) DBGCCreate(PUVM pUVM, PDBGCBACK pBack, unsigned fFlags);
1098	DBGDECL(int) DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
1099	DBGDECL(int) DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
1100	DBGDECL(int) DBGCTcpCreate(PUVM pUVM, void **ppvUser);
1101	DBGDECL(int) DBGCTcpTerminate(PUVM pUVM, void *pvData);
1102
1103	/** @} */
1104
1105	#endif /* IN_RING3 */
1106
1107	RT_C_DECLS_END
1108
1109	#endif

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

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

Download in other formats: