dbg.h@ 38643

Last change on this file since 38643 was 35696, checked in by vboxsync, 14 years ago
PCDBGCCMD & PFNDBGCCMD: Drop the return type & variable. Functions will be added separately from commands (superset of DBGCCMD).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 35.0 KB

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

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

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

Download in other formats: