dbg.h@ 58110

Last change on this file since 58110 was 58106, checked in by vboxsync, 9 years ago
include,misc: Corrected a bunch of doxygen errors.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 37.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-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,
417	const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
418
419	/**
420	* Command helper for writing formatted text to the debug console.
421	*
422	* @returns VBox status.
423	* @param pCmdHlp Pointer to the command callback structure.
424	* @param pcb Where to store the number of bytes written.
425	* @param pszFormat The format string. This may use all IPRT extensions as
426	* well as the debugger ones.
427	* @param args Arguments specified in the format string.
428	*/
429	DECLCALLBACKMEMBER(int, pfnPrintfV)(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten,
430	const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
431
432	/**
433	* Command helper for formatting a string with debugger format specifiers.
434	*
435	* @returns The number of bytes written.
436	* @param pCmdHlp Pointer to the command callback structure.
437	* @param pszBuf The output buffer.
438	* @param cbBuf The size of the output buffer.
439	* @param pszFormat The format string. This may use all IPRT extensions as
440	* well as the debugger ones.
441	* @param ... Arguments specified in the format string.
442	*/
443	DECLCALLBACKMEMBER(size_t, pfnStrPrintf)(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
444	const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5);
445
446	/**
447	* Command helper for formatting a string with debugger format specifiers.
448	*
449	* @returns The number of bytes written.
450	* @param pCmdHlp Pointer to the command callback structure.
451	* @param pszBuf The output buffer.
452	* @param cbBuf The size of the output buffer.
453	* @param pszFormat The format string. This may use all IPRT extensions as
454	* well as the debugger ones.
455	* @param va Arguments specified in the format string.
456	*/
457	DECLCALLBACKMEMBER(size_t, pfnStrPrintfV)(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
458	const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0);
459
460	/**
461	* Command helper for formatting and error message for a VBox status code.
462	*
463	* @returns VBox status code appropriate to return from a command.
464	* @param pCmdHlp Pointer to the command callback structure.
465	* @param rc The VBox status code.
466	* @param pszFormat Format string for additional messages. Can be NULL.
467	* @param ... Format arguments, optional.
468	*/
469	DECLCALLBACKMEMBER(int, pfnVBoxError)(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
470
471	/**
472	* Command helper for formatting and error message for a VBox status code.
473	*
474	* @returns VBox status code appropriate to return from a command.
475	* @param pCmdHlp Pointer to the command callback structure.
476	* @param rc The VBox status code.
477	* @param pcb Where to store the number of bytes written.
478	* @param pszFormat Format string for additional messages. Can be NULL.
479	* @param args Format arguments, optional.
480	*/
481	DECLCALLBACKMEMBER(int, pfnVBoxErrorV)(PDBGCCMDHLP pCmdHlp, int rc,
482	const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
483
484	/**
485	* Command helper for reading memory specified by a DBGC variable.
486	*
487	* @returns VBox status code appropriate to return from a command.
488	* @param pCmdHlp Pointer to the command callback structure.
489	* @param pvBuffer Where to store the read data.
490	* @param cbRead Number of bytes to read.
491	* @param pVarPointer DBGC variable specifying where to start reading.
492	* @param pcbRead Where to store the number of bytes actually read.
493	* This optional, but it's useful when read GC virtual memory where a
494	* page in the requested range might not be present.
495	* If not specified not-present failure or end of a HC physical page
496	* will cause failure.
497	*/
498	DECLCALLBACKMEMBER(int, pfnMemRead)(PDBGCCMDHLP pCmdHlp, void pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t pcbRead);
499
500	/**
501	* Command helper for writing memory specified by a DBGC variable.
502	*
503	* @returns VBox status code appropriate to return from a command.
504	* @param pCmdHlp Pointer to the command callback structure.
505	* @param pvBuffer What to write.
506	* @param cbWrite Number of bytes to write.
507	* @param pVarPointer DBGC variable specifying where to start reading.
508	* @param pcbWritten Where to store the number of bytes written.
509	* This is optional. If NULL be aware that some of the buffer
510	* might have been written to the specified address.
511	*/
512	DECLCALLBACKMEMBER(int, pfnMemWrite)(PDBGCCMDHLP pCmdHlp, const void pvBuffer, size_t cbWrite, PCDBGCVAR pVarPointer, size_t pcbWritten);
513
514	/**
515	* Executes command an expression.
516	* (Hopefully the parser and functions are fully reentrant.)
517	*
518	* @returns VBox status code appropriate to return from a command.
519	* @param pCmdHlp Pointer to the command callback structure.
520	* @param pszExpr The expression. Format string with the format DBGC extensions.
521	* @param ... Format arguments.
522	*/
523	DECLCALLBACKMEMBER(int, pfnExec)(PDBGCCMDHLP pCmdHlp, const char *pszExpr, ...) RT_IPRT_FORMAT_ATTR(2, 3);
524
525	/**
526	* Evaluates an expression.
527	* (Hopefully the parser and functions are fully reentrant.)
528	*
529	* @returns VBox status code appropriate to return from a command.
530	* @param pCmdHlp Pointer to the command callback structure.
531	* @param pResult Where to store the result.
532	* @param pszExpr The expression. Format string with the format DBGC extensions.
533	* @param va Format arguments.
534	*/
535	DECLCALLBACKMEMBER(int, pfnEvalV)(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult,
536	const char *pszExpr, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
537
538	/**
539	* Print an error and fail the current command.
540	*
541	* @returns VBox status code to pass upwards.
542	*
543	* @param pCmdHlp Pointer to the command callback structure.
544	* @param pCmd The failing command.
545	* @param pszFormat The error message format string.
546	* @param va Format arguments.
547	*/
548	DECLCALLBACKMEMBER(int, pfnFailV)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd,
549	const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
550
551	/**
552	* Print an error and fail the current command.
553	*
554	* @returns VBox status code to pass upwards.
555	*
556	* @param pCmdHlp Pointer to the command callback structure.
557	* @param pCmd The failing command.
558	* @param rc The status code indicating the failure. This will
559	* be appended to the message after a colon (': ').
560	* @param pszFormat The error message format string.
561	* @param va Format arguments.
562	*
563	* @see DBGCCmdHlpFailRc
564	*/
565	DECLCALLBACKMEMBER(int, pfnFailRcV)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc,
566	const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0);
567
568	/**
569	* Parser error.
570	*
571	* @returns VBox status code to pass upwards.
572	*
573	* @param pCmdHlp Pointer to the command callback structure.
574	* @param pCmd The failing command, can be NULL but shouldn't.
575	* @param iArg The offending argument, -1 when lazy.
576	* @param pszExpr The expression.
577	* @param iLine The line number.
578	*/
579	DECLCALLBACKMEMBER(int, pfnParserError)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int iArg, const char *pszExpr, unsigned iLine);
580
581	/**
582	* Converts a DBGC variable to a DBGF address structure.
583	*
584	* @returns VBox status code.
585	* @param pCmdHlp Pointer to the command callback structure.
586	* @param pVar The variable to convert.
587	* @param pAddress The target address.
588	*/
589	DECLCALLBACKMEMBER(int, pfnVarToDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress);
590
591	/**
592	* Converts a DBGF address structure to a DBGC variable.
593	*
594	* @returns VBox status code.
595	* @param pCmdHlp Pointer to the command callback structure.
596	* @param pAddress The source address.
597	* @param pResult The result variable.
598	*/
599	DECLCALLBACKMEMBER(int, pfnVarFromDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGFADDRESS pAddress, PDBGCVAR pResult);
600
601	/**
602	* Converts a DBGC variable to a 64-bit number.
603	*
604	* @returns VBox status code.
605	* @param pCmdHlp Pointer to the command callback structure.
606	* @param pVar The variable to convert.
607	* @param pu64Number Where to store the number.
608	*/
609	DECLCALLBACKMEMBER(int, pfnVarToNumber)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number);
610
611	/**
612	* Converts a DBGC variable to a boolean.
613	*
614	* @returns VBox status code.
615	* @param pCmdHlp Pointer to the command callback structure.
616	* @param pVar The variable to convert.
617	* @param pf Where to store the boolean.
618	*/
619	DECLCALLBACKMEMBER(int, pfnVarToBool)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf);
620
621	/**
622	* Get the range of a variable in bytes, resolving symbols if necessary.
623	*
624	* @returns VBox status code.
625	* @param pCmdHlp Pointer to the command callback structure.
626	* @param pVar The variable to convert.
627	* @param cbElement Conversion factor for element ranges.
628	* @param cbDefault The default range.
629	* @param pcbRange The length of the range.
630	*/
631	DECLCALLBACKMEMBER(int, pfnVarGetRange)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault,
632	uint64_t *pcbRange);
633
634	/**
635	* Converts a variable to one with the specified type.
636	*
637	* This preserves the range.
638	*
639	* @returns VBox status code.
640	* @param pCmdHlp Pointer to the command callback structure.
641	* @param pVar The variable to convert.
642	* @param enmToType The target type.
643	* @param fConvSyms If @c true, then attempt to resolve symbols.
644	* @param pResult The output variable. Can be the same as @a pVar.
645	*/
646	DECLCALLBACKMEMBER(int, pfnVarConvert)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms,
647	PDBGCVAR pResult);
648
649	/**
650	* Gets a DBGF output helper that directs the output to the debugger
651	* console.
652	*
653	* @returns Pointer to the helper structure.
654	* @param pCmdHlp Pointer to the command callback structure.
655	*/
656	DECLCALLBACKMEMBER(PCDBGFINFOHLP, pfnGetDbgfOutputHlp)(PDBGCCMDHLP pCmdHlp);
657
658	/**
659	* Gets the ID currently selected CPU.
660	*
661	* @returns Current CPU ID.
662	* @param pCmdHlp Pointer to the command callback structure.
663	*/
664	DECLCALLBACKMEMBER(VMCPUID, pfnGetCurrentCpu)(PDBGCCMDHLP pCmdHlp);
665
666	/**
667	* Gets the mode the currently selected CPU is running in, in the current
668	* context.
669	*
670	* @returns Current CPU mode.
671	* @param pCmdHlp Pointer to the command callback structure.
672	*/
673	DECLCALLBACKMEMBER(CPUMMODE, pfnGetCpuMode)(PDBGCCMDHLP pCmdHlp);
674
675	/** End marker (DBGCCMDHLP_MAGIC). */
676	uint32_t u32EndMarker;
677	} DBGCCMDHLP;
678
679	/** Magic value for DBGCCMDHLP::u32Magic. (Fyodor Mikhaylovich Dostoyevsky) */
680	#define DBGCCMDHLP_MAGIC UINT32_C(18211111)
681
682
683	#ifdef IN_RING3
684
685	/**
686	* Command helper for writing formatted text to the debug console.
687	*
688	* @returns VBox status.
689	* @param pCmdHlp Pointer to the command callback structure.
690	* @param pszFormat The format string. This may use all IPRT extensions as
691	* well as the debugger ones.
692	* @param ... Arguments specified in the format string.
693	*/
694	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) DBGCCmdHlpPrintf(PDBGCCMDHLP pCmdHlp, const char *pszFormat, ...)
695	{
696	va_list va;
697	int rc;
698
699	va_start(va, pszFormat);
700	rc = pCmdHlp->pfnPrintfV(pCmdHlp, NULL, pszFormat, va);
701	va_end(va);
702
703	return rc;
704	}
705
706
707	/**
708	* @copydoc DBGCCMDHLP::pfnStrPrintf
709	*/
710	DECLINLINE(size_t) RT_IPRT_FORMAT_ATTR(4, 5) DBGCCmdHlpStrPrintf(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
711	const char *pszFormat, ...)
712	{
713	va_list va;
714	size_t cch;
715
716	va_start(va, pszFormat);
717	cch = pCmdHlp->pfnStrPrintfV(pCmdHlp, pszBuf, cbBuf, pszFormat, va);
718	va_end(va);
719
720	return cch;
721	}
722
723	/**
724	* @copydoc DBGCCMDHLP::pfnVBoxError
725	*/
726	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpVBoxError(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...)
727	{
728	va_list va;
729
730	va_start(va, pszFormat);
731	rc = pCmdHlp->pfnVBoxErrorV(pCmdHlp, rc, pszFormat, va);
732	va_end(va);
733
734	return rc;
735	}
736
737	/**
738	* @copydoc DBGCCMDHLP::pfnMemRead
739	*/
740	DECLINLINE(int) DBGCCmdHlpMemRead(PDBGCCMDHLP pCmdHlp, void pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t pcbRead)
741	{
742	return pCmdHlp->pfnMemRead(pCmdHlp, pvBuffer, cbRead, pVarPointer, pcbRead);
743	}
744
745	/**
746	* Evaluates an expression.
747	* (Hopefully the parser and functions are fully reentrant.)
748	*
749	* @returns VBox status code appropriate to return from a command.
750	* @param pCmdHlp Pointer to the command callback structure.
751	* @param pResult Where to store the result.
752	* @param pszExpr The expression. Format string with the format DBGC extensions.
753	* @param ... Format arguments.
754	*/
755	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpEval(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, ...)
756	{
757	va_list va;
758	int rc;
759
760	va_start(va, pszExpr);
761	rc = pCmdHlp->pfnEvalV(pCmdHlp, pResult, pszExpr, va);
762	va_end(va);
763
764	return rc;
765	}
766
767	/**
768	* Print an error and fail the current command.
769	*
770	* @returns VBox status code to pass upwards.
771	*
772	* @param pCmdHlp Pointer to the command callback structure.
773	* @param pCmd The failing command.
774	* @param pszFormat The error message format string.
775	* @param ... Format arguments.
776	*/
777	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpFail(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, ...)
778	{
779	va_list va;
780	int rc;
781
782	va_start(va, pszFormat);
783	rc = pCmdHlp->pfnFailV(pCmdHlp, pCmd, pszFormat, va);
784	va_end(va);
785
786	return rc;
787	}
788
789	/**
790	* Print an error and fail the current command.
791	*
792	* Usage example:
793	* @code
794	int rc = VMMR3Something(pVM);
795	if (RT_FAILURE(rc))
796	return DBGCCmdHlpFailRc(pCmdHlp, pCmd, rc, "VMMR3Something");
797	return VINF_SUCCESS;
798	* @endcode
799	*
800	* @returns VBox status code to pass upwards.
801	*
802	* @param pCmdHlp Pointer to the command callback structure.
803	* @param pCmd The failing command.
804	* @param rc The status code indicating the failure.
805	* @param pszFormat The error message format string.
806	* @param ... Format arguments.
807	*/
808	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(4, 5) DBGCCmdHlpFailRc(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc,
809	const char *pszFormat, ...)
810	{
811	va_list va;
812
813	va_start(va, pszFormat);
814	rc = pCmdHlp->pfnFailRcV(pCmdHlp, pCmd, rc, pszFormat, va);
815	va_end(va);
816
817	return rc;
818	}
819
820	/**
821	* @copydoc DBGCCMDHLP::pfnParserError
822	*/
823	DECLINLINE(int) DBGCCmdHlpParserError(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int iArg, const char *pszExpr, unsigned iLine)
824	{
825	return pCmdHlp->pfnParserError(pCmdHlp, pCmd, iArg, pszExpr, iLine);
826	}
827
828	/** Assert+return like macro for checking parser sanity.
829	* Returns with failure if the precodition is not met. */
830	#define DBGC_CMDHLP_ASSERT_PARSER_RET(pCmdHlp, pCmd, iArg, expr) \
831	do { \
832	if (!(expr)) \
833	return DBGCCmdHlpParserError(pCmdHlp, pCmd, iArg, #expr, __LINE__); \
834	} while (0)
835
836	/** Assert+return like macro that the VM handle is present.
837	* Returns with failure if the VM handle is NIL. */
838	#define DBGC_CMDHLP_REQ_UVM_RET(pCmdHlp, pCmd, pUVM) \
839	do { \
840	if (!(pUVM)) \
841	return DBGCCmdHlpFail(pCmdHlp, pCmd, "No VM selected"); \
842	} while (0)
843
844	/**
845	* @copydoc DBGCCMDHLP::pfnVarToDbgfAddr
846	*/
847	DECLINLINE(int) DBGCCmdHlpVarToDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress)
848	{
849	return pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, pAddress);
850	}
851
852	/**
853	* @copydoc DBGCCMDHLP::pfnVarFromDbgfAddr
854	*/
855	DECLINLINE(int) DBGCCmdHlpVarFromDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGFADDRESS pAddress, PDBGCVAR pResult)
856	{
857	return pCmdHlp->pfnVarFromDbgfAddr(pCmdHlp, pAddress, pResult);
858	}
859
860	/**
861	* Converts an variable to a flat address.
862	*
863	* @returns VBox status code.
864	* @param pCmdHlp Pointer to the command callback structure.
865	* @param pVar The variable to convert.
866	* @param pFlatPtr Where to store the flat address.
867	*/
868	DECLINLINE(int) DBGCCmdHlpVarToFlatAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PRTGCPTR pFlatPtr)
869	{
870	DBGFADDRESS Addr;
871	int rc = pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, &Addr);
872	if (RT_SUCCESS(rc))
873	*pFlatPtr = Addr.FlatPtr;
874	return rc;
875	}
876
877	/**
878	* @copydoc DBGCCMDHLP::pfnVarToNumber
879	*/
880	DECLINLINE(int) DBGCCmdHlpVarToNumber(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number)
881	{
882	return pCmdHlp->pfnVarToNumber(pCmdHlp, pVar, pu64Number);
883	}
884
885	/**
886	* @copydoc DBGCCMDHLP::pfnVarToBool
887	*/
888	DECLINLINE(int) DBGCCmdHlpVarToBool(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf)
889	{
890	return pCmdHlp->pfnVarToBool(pCmdHlp, pVar, pf);
891	}
892
893	/**
894	* @copydoc DBGCCMDHLP::pfnVarGetRange
895	*/
896	DECLINLINE(int) DBGCCmdHlpVarGetRange(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault, uint64_t *pcbRange)
897	{
898	return pCmdHlp->pfnVarGetRange(pCmdHlp, pVar, cbElement, cbDefault, pcbRange);
899	}
900
901	/**
902	* @copydoc DBGCCMDHLP::pfnVarConvert
903	*/
904	DECLINLINE(int) DBGCCmdHlpConvert(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms, PDBGCVAR pResult)
905	{
906	return pCmdHlp->pfnVarConvert(pCmdHlp, pVar, enmToType, fConvSyms, pResult);
907	}
908
909	/**
910	* @copydoc DBGCCMDHLP::pfnGetDbgfOutputHlp
911	*/
912	DECLINLINE(PCDBGFINFOHLP) DBGCCmdHlpGetDbgfOutputHlp(PDBGCCMDHLP pCmdHlp)
913	{
914	return pCmdHlp->pfnGetDbgfOutputHlp(pCmdHlp);
915	}
916
917	/**
918	* @copydoc DBGCCMDHLP::pfnGetCurrentCpu
919	*/
920	DECLINLINE(VMCPUID) DBGCCmdHlpGetCurrentCpu(PDBGCCMDHLP pCmdHlp)
921	{
922	return pCmdHlp->pfnGetCurrentCpu(pCmdHlp);
923	}
924
925	/**
926	* @copydoc DBGCCMDHLP::pfnGetCpuMode
927	*/
928	DECLINLINE(CPUMMODE) DBGCCmdHlpGetCpuMode(PDBGCCMDHLP pCmdHlp)
929	{
930	return pCmdHlp->pfnGetCpuMode(pCmdHlp);
931	}
932
933	#endif /* IN_RING3 */
934
935
936
937	/**
938	* Command handler.
939	*
940	* The console will call the handler for a command once it's finished
941	* parsing the user input. The command handler function is responsible
942	* for executing the command itself.
943	*
944	* @returns VBox status.
945	* @param pCmd Pointer to the command descriptor (as registered).
946	* @param pCmdHlp Pointer to command helper functions.
947	* @param pUVM The user mode VM handle, can in theory be NULL.
948	* @param paArgs Pointer to (readonly) array of arguments.
949	* @param cArgs Number of arguments in the array.
950	*/
951	typedef DECLCALLBACK(int) FNDBGCCMD(PCDBGCCMD pCmd, PDBGCCMDHLP pCmdHlp, PUVM pUVM, PCDBGCVAR paArgs, unsigned cArgs);
952	/** Pointer to a FNDBGCCMD() function. */
953	typedef FNDBGCCMD *PFNDBGCCMD;
954
955	/**
956	* DBGC command descriptor.
957	*/
958	typedef struct DBGCCMD
959	{
960	/** Command string. */
961	const char *pszCmd;
962	/** Minimum number of arguments. */
963	unsigned cArgsMin;
964	/** Max number of arguments. */
965	unsigned cArgsMax;
966	/** Argument descriptors (array). */
967	PCDBGCVARDESC paArgDescs;
968	/** Number of argument descriptors. */
969	unsigned cArgDescs;
970	/** flags. (reserved for now) */
971	unsigned fFlags;
972	/** Handler function. */
973	PFNDBGCCMD pfnHandler;
974	/** Command syntax. */
975	const char *pszSyntax;
976	/** Command description. */
977	const char *pszDescription;
978	} DBGCCMD;
979
980	/** DBGCCMD Flags.
981	* @{
982	*/
983	/** @} */
984
985
986	/**
987	* Function handler.
988	*
989	* The console will call the handler for a command once it's finished
990	* parsing the user input. The command handler function is responsible
991	* for executing the command itself.
992	*
993	* @returns VBox status.
994	* @param pCmd Pointer to the command descriptor (as registered).
995	* @param pCmdHlp Pointer to command helper functions.
996	* @param pUVM The user mode VM handle, can in theory be NULL.
997	* @param paArgs Pointer to (readonly) array of arguments.
998	* @param cArgs Number of arguments in the array.
999	* @param pResult Where to return the result.
1000	*/
1001	typedef DECLCALLBACK(int) FNDBGCFUNC(PCDBGCFUNC pFunc, PDBGCCMDHLP pCmdHlp, PUVM pUVM, PCDBGCVAR paArgs, unsigned cArgs,
1002	PDBGCVAR pResult);
1003	/** Pointer to a FNDBGCFUNC() function. */
1004	typedef FNDBGCFUNC *PFNDBGCFUNC;
1005
1006	/**
1007	* DBGC function descriptor.
1008	*/
1009	typedef struct DBGCFUNC
1010	{
1011	/** Command string. */
1012	const char *pszFuncNm;
1013	/** Minimum number of arguments. */
1014	unsigned cArgsMin;
1015	/** Max number of arguments. */
1016	unsigned cArgsMax;
1017	/** Argument descriptors (array). */
1018	PCDBGCVARDESC paArgDescs;
1019	/** Number of argument descriptors. */
1020	unsigned cArgDescs;
1021	/** flags. (reserved for now) */
1022	unsigned fFlags;
1023	/** Handler function. */
1024	PFNDBGCFUNC pfnHandler;
1025	/** Function syntax. */
1026	const char *pszSyntax;
1027	/** Function description. */
1028	const char *pszDescription;
1029	} DBGCFUNC;
1030
1031
1032
1033	/** Pointer to a DBGC backend. */
1034	typedef struct DBGCBACK *PDBGCBACK;
1035
1036	/**
1037	* Checks if there is input.
1038	*
1039	* @returns true if there is input ready.
1040	* @returns false if there not input ready.
1041	* @param pBack Pointer to the backend structure supplied by
1042	* the backend. The backend can use this to find
1043	* it's instance data.
1044	* @param cMillies Number of milliseconds to wait on input data.
1045	*/
1046	typedef DECLCALLBACK(bool) FNDBGCBACKINPUT(PDBGCBACK pBack, uint32_t cMillies);
1047	/** Pointer to a FNDBGCBACKINPUT() callback. */
1048	typedef FNDBGCBACKINPUT *PFNDBGCBACKINPUT;
1049
1050	/**
1051	* Read input.
1052	*
1053	* @returns VBox status code.
1054	* @param pBack Pointer to the backend structure supplied by
1055	* the backend. The backend can use this to find
1056	* it's instance data.
1057	* @param pvBuf Where to put the bytes we read.
1058	* @param cbBuf Maximum nymber of bytes to read.
1059	* @param pcbRead Where to store the number of bytes actually read.
1060	* If NULL the entire buffer must be filled for a
1061	* successful return.
1062	*/
1063	typedef DECLCALLBACK(int) FNDBGCBACKREAD(PDBGCBACK pBack, void pvBuf, size_t cbBuf, size_t pcbRead);
1064	/** Pointer to a FNDBGCBACKREAD() callback. */
1065	typedef FNDBGCBACKREAD *PFNDBGCBACKREAD;
1066
1067	/**
1068	* Write (output).
1069	*
1070	* @returns VBox status code.
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 pvBuf What to write.
1075	* @param cbBuf Number of bytes to write.
1076	* @param pcbWritten Where to store the number of bytes actually written.
1077	* If NULL the entire buffer must be successfully written.
1078	*/
1079	typedef DECLCALLBACK(int) FNDBGCBACKWRITE(PDBGCBACK pBack, const void pvBuf, size_t cbBuf, size_t pcbWritten);
1080	/** Pointer to a FNDBGCBACKWRITE() callback. */
1081	typedef FNDBGCBACKWRITE *PFNDBGCBACKWRITE;
1082
1083	/**
1084	* Ready / busy notification.
1085	*
1086	* @param pBack Pointer to the backend structure supplied by
1087	* the backend. The backend can use this to find
1088	* it's instance data.
1089	* @param fReady Whether it's ready (true) or busy (false).
1090	*/
1091	typedef DECLCALLBACK(void) FNDBGCBACKSETREADY(PDBGCBACK pBack, bool fReady);
1092	/** Pointer to a FNDBGCBACKSETREADY() callback. */
1093	typedef FNDBGCBACKSETREADY *PFNDBGCBACKSETREADY;
1094
1095
1096	/**
1097	* The communication backend provides the console with a number of callbacks
1098	* which can be used
1099	*/
1100	typedef struct DBGCBACK
1101	{
1102	/** Check for input. */
1103	PFNDBGCBACKINPUT pfnInput;
1104	/** Read input. */
1105	PFNDBGCBACKREAD pfnRead;
1106	/** Write output. */
1107	PFNDBGCBACKWRITE pfnWrite;
1108	/** Ready / busy notification. */
1109	PFNDBGCBACKSETREADY pfnSetReady;
1110	} DBGCBACK;
1111
1112	DBGDECL(int) DBGCCreate(PUVM pUVM, PDBGCBACK pBack, unsigned fFlags);
1113	DBGDECL(int) DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
1114	DBGDECL(int) DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
1115	DBGDECL(int) DBGCTcpCreate(PUVM pUVM, void **ppvUser);
1116	DBGDECL(int) DBGCTcpTerminate(PUVM pUVM, void *pvData);
1117
1118	/** @} */
1119
1120	#endif /* IN_RING3 */
1121
1122	RT_C_DECLS_END
1123
1124	#endif

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

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

Download in other formats: