dbg.h@ 53425

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

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

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

Download in other formats: