dbg.h@ 35625

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

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

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

Download in other formats: