dbg.h@ 27149

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

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

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

Download in other formats: