dbg.h@ 29286

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

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

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

Download in other formats: