dbg.h@ 7944

Last change on this file since 7944 was 5999, checked in by vboxsync, 17 years ago
The Giant CDDL Dual-License Header Change.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 24.2 KB

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

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

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

Download in other formats: