dbg.h@ 17911

Last change on this file since 17911 was 13411, checked in by vboxsync, 16 years ago
VBOX_WITH_DEBUGGER is defined in Config.kmk now.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 25.0 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 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	__BEGIN_DECLS
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 helper functions for commands. */
299	typedef struct DBGCCMDHLP *PDBGCCMDHLP;
300
301	/**
302	* Command helper for writing text to the debug console.
303	*
304	* @returns VBox status.
305	* @param pCmdHlp Pointer to the command callback structure.
306	* @param pvBuf What to write.
307	* @param cbBuf Number of bytes to write.
308	* @param pcbWritten Where to store the number of bytes actually written.
309	* If NULL the entire buffer must be successfully written.
310	*/
311	typedef DECLCALLBACK(int) FNDBGCHLPWRITE(PDBGCCMDHLP pCmdHlp, const void pvBuf, size_t cbBuf, size_t pcbWritten);
312	/** Pointer to a FNDBGCHLPWRITE() function. */
313	typedef FNDBGCHLPWRITE *PFNDBGCHLPWRITE;
314
315	/**
316	* Command helper for writing formatted text to the debug console.
317	*
318	* @returns VBox status.
319	* @param pCmdHlp Pointer to the command callback structure.
320	* @param pcb Where to store the number of bytes written.
321	* @param pszFormat The format string.
322	* This is using the log formatter, so it's format extensions can be used.
323	* @param ... Arguments specified in the format string.
324	*/
325	typedef DECLCALLBACK(int) FNDBGCHLPPRINTF(PDBGCCMDHLP pCmdHlp, size_t pcbWritten, const char pszFormat, ...);
326	/** Pointer to a FNDBGCHLPPRINTF() function. */
327	typedef FNDBGCHLPPRINTF *PFNDBGCHLPPRINTF;
328
329	/**
330	* Command helper for writing formatted text to the debug console.
331	*
332	* @returns VBox status.
333	* @param pCmdHlp Pointer to the command callback structure.
334	* @param pcb Where to store the number of bytes written.
335	* @param pszFormat The format string.
336	* This is using the log formatter, so it's format extensions can be used.
337	* @param args Arguments specified in the format string.
338	*/
339	typedef DECLCALLBACK(int) FNDBGCHLPPRINTFV(PDBGCCMDHLP pCmdHlp, size_t pcbWritten, const char pszFormat, va_list args);
340	/** Pointer to a FNDBGCHLPPRINTFV() function. */
341	typedef FNDBGCHLPPRINTFV *PFNDBGCHLPPRINTFV;
342
343	/**
344	* Command helper for formatting and error message for a VBox status code.
345	*
346	* @returns VBox status code appropriate to return from a command.
347	* @param pCmdHlp Pointer to the command callback structure.
348	* @param rc The VBox status code.
349	* @param pcb Where to store the number of bytes written.
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	* Evaluates an expression.
410	* (Hopefully the parser and functions are fully reentrant.)
411	*
412	* @returns VBox status code appropriate to return from a command.
413	* @param pCmdHlp Pointer to the command callback structure.
414	* @param pResult Where to store the result.
415	* @param pszExpr The expression. Format string with the format DBGC extensions.
416	* @param ... Format arguments.
417	*/
418	typedef DECLCALLBACK(int) FNDBGCHLPEVAL(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, ...);
419	/** Pointer to a FNDBGCHLPEVAL() function. */
420	typedef FNDBGCHLPEVAL *PFNDBGCHLPEVAL;
421
422
423	/**
424	* Executes command an expression.
425	* (Hopefully the parser and functions are fully reentrant.)
426	*
427	* @returns VBox status code appropriate to return from a command.
428	* @param pCmdHlp Pointer to the command callback structure.
429	* @param pszExpr The expression. Format string with the format DBGC extensions.
430	* @param ... Format arguments.
431	*/
432	typedef DECLCALLBACK(int) FNDBGCHLPEXEC(PDBGCCMDHLP pCmdHlp, const char *pszExpr, ...);
433	/** Pointer to a FNDBGCHLPEVAL() function. */
434	typedef FNDBGCHLPEXEC *PFNDBGCHLPEXEC;
435
436
437	/**
438	* Helper functions for commands.
439	*/
440	typedef struct DBGCCMDHLP
441	{
442	/** Pointer to a FNDBCHLPWRITE() function. */
443	PFNDBGCHLPWRITE pfnWrite;
444	/** Pointer to a FNDBGCHLPPRINTF() function. */
445	PFNDBGCHLPPRINTF pfnPrintf;
446	/** Pointer to a FNDBGCHLPPRINTFV() function. */
447	PFNDBGCHLPPRINTFV pfnPrintfV;
448	/** Pointer to a FNDBGCHLPVBOXERROR() function. */
449	PFNDBGCHLPVBOXERROR pfnVBoxError;
450	/** Pointer to a FNDBGCHLPVBOXERRORV() function. */
451	PFNDBGCHLPVBOXERRORV pfnVBoxErrorV;
452	/** Pointer to a FNDBGCHLPMEMREAD() function. */
453	PFNDBGCHLPMEMREAD pfnMemRead;
454	/** Pointer to a FNDBGCHLPMEMWRITE() function. */
455	PFNDBGCHLPMEMWRITE pfnMemWrite;
456	/** Pointer to a FNDBGCHLPEVAL() function. */
457	PFNDBGCHLPEVAL pfnEval;
458	/** Pointer to a FNDBGCHLPEXEC() function. */
459	PFNDBGCHLPEXEC pfnExec;
460
461	/**
462	* Converts a DBGC variable to a DBGF address structure.
463	*
464	* @returns VBox status code.
465	* @param pCmdHlp Pointer to the command callback structure.
466	* @param pVar The variable to convert.
467	* @param pAddress The target address.
468	*/
469	DECLCALLBACKMEMBER(int, pfnVarToDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress);
470
471	/**
472	* Converts a DBGC variable to a boolean.
473	*
474	* @returns VBox status code.
475	* @param pCmdHlp Pointer to the command callback structure.
476	* @param pVar The variable to convert.
477	* @param pf Where to store the boolean.
478	*/
479	DECLCALLBACKMEMBER(int, pfnVarToBool)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf);
480
481	} DBGCCMDHLP;
482
483
484	#ifdef IN_RING3
485	/**
486	* Command helper for writing formatted text to the debug console.
487	*
488	* @returns VBox status.
489	* @param pCmdHlp Pointer to the command callback structure.
490	* @param pszFormat The format string.
491	* This is using the log formatter, so it's format extensions can be used.
492	* @param ... Arguments specified in the format string.
493	*/
494	DECLINLINE(int) DBGCCmdHlpPrintf(PDBGCCMDHLP pCmdHlp, const char *pszFormat, ...)
495	{
496	va_list va;
497	int rc;
498	va_start(va, pszFormat);
499	rc = pCmdHlp->pfnPrintfV(pCmdHlp, NULL, pszFormat, va);
500	va_end(va);
501	return rc;
502	}
503
504	/**
505	* @copydoc FNDBGCHLPVBOXERROR
506	*/
507	DECLINLINE(int) DBGCCmdHlpVBoxError(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...)
508	{
509	va_list va;
510	va_start(va, pszFormat);
511	rc = pCmdHlp->pfnVBoxErrorV(pCmdHlp, rc, pszFormat, va);
512	va_end(va);
513	return rc;
514	}
515
516	/**
517	* @copydoc FNDBGCHLPMEMREAD
518	*/
519	DECLINLINE(int) DBGCCmdHlpMemRead(PDBGCCMDHLP pCmdHlp, PVM pVM, void pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t pcbRead)
520	{
521	return pCmdHlp->pfnMemRead(pCmdHlp, pVM, pvBuffer, cbRead, pVarPointer, pcbRead);
522	}
523	#endif /* IN_RING3 */
524
525
526	/** Pointer to command descriptor. */
527	typedef struct DBGCCMD *PDBGCCMD;
528	/** Pointer to const command descriptor. */
529	typedef const struct DBGCCMD *PCDBGCCMD;
530
531	/**
532	* Command handler.
533	*
534	* The console will call the handler for a command once it's finished
535	* parsing the user input. The command handler function is responsible
536	* for executing the command itself.
537	*
538	* @returns VBox status.
539	* @param pCmd Pointer to the command descriptor (as registered).
540	* @param pCmdHlp Pointer to command helper functions.
541	* @param pVM Pointer to the current VM (if any).
542	* @param paArgs Pointer to (readonly) array of arguments.
543	* @param cArgs Number of arguments in the array.
544	* @param pResult Where to store the result. NULL if no result descriptor was specified.
545	*/
546	typedef DECLCALLBACK(int) FNDBGCCMD(PCDBGCCMD pCmd, PDBGCCMDHLP pCmdHlp, PVM pVM, PCDBGCVAR pArgs, unsigned cArgs, PDBGCVAR pResult);
547	/** Pointer to a FNDBGCCMD() function. */
548	typedef FNDBGCCMD *PFNDBGCCMD;
549
550	/**
551	* DBGC command descriptor.
552	*
553	* If a pResultDesc is specified the command can be called and used
554	* as a function too. If it's a pure function, set fFlags to
555	* DBGCCMD_FLAGS_FUNCTION.
556	*/
557	typedef struct DBGCCMD
558	{
559	/** Command string. */
560	const char *pszCmd;
561	/** Minimum number of arguments. */
562	unsigned cArgsMin;
563	/** Max number of arguments. */
564	unsigned cArgsMax;
565	/** Argument descriptors (array). */
566	PCDBGCVARDESC paArgDescs;
567	/** Number of argument descriptors. */
568	unsigned cArgDescs;
569	/** Result descriptor. */
570	PCDBGCVARDESC pResultDesc;
571	/** flags. (reserved for now) */
572	unsigned fFlags;
573	/** Handler function. */
574	PFNDBGCCMD pfnHandler;
575	/** Command syntax. */
576	const char *pszSyntax;
577	/** Command description. */
578	const char *pszDescription;
579	} DBGCCMD;
580
581	/** DBGCCMD Flags.
582	* @{
583	*/
584	/** The description is of a pure function which cannot be invoked
585	* as a command from the commandline. */
586	#define DBGCCMD_FLAGS_FUNCTION 1
587	/** @} */
588
589
590
591	/** Pointer to a DBGC backend. */
592	typedef struct DBGCBACK *PDBGCBACK;
593
594	/**
595	* Checks if there is input.
596	*
597	* @returns true if there is input ready.
598	* @returns false if there not input ready.
599	* @param pBack Pointer to the backend structure supplied by
600	* the backend. The backend can use this to find
601	* it's instance data.
602	* @param cMillies Number of milliseconds to wait on input data.
603	*/
604	typedef DECLCALLBACK(bool) FNDBGCBACKINPUT(PDBGCBACK pBack, uint32_t cMillies);
605	/** Pointer to a FNDBGCBACKINPUT() callback. */
606	typedef FNDBGCBACKINPUT *PFNDBGCBACKINPUT;
607
608	/**
609	* Read input.
610	*
611	* @returns VBox status code.
612	* @param pBack Pointer to the backend structure supplied by
613	* the backend. The backend can use this to find
614	* it's instance data.
615	* @param pvBuf Where to put the bytes we read.
616	* @param cbBuf Maximum nymber of bytes to read.
617	* @param pcbRead Where to store the number of bytes actually read.
618	* If NULL the entire buffer must be filled for a
619	* successful return.
620	*/
621	typedef DECLCALLBACK(int) FNDBGCBACKREAD(PDBGCBACK pBack, void pvBuf, size_t cbBuf, size_t pcbRead);
622	/** Pointer to a FNDBGCBACKREAD() callback. */
623	typedef FNDBGCBACKREAD *PFNDBGCBACKREAD;
624
625	/**
626	* Write (output).
627	*
628	* @returns VBox status code.
629	* @param pBack Pointer to the backend structure supplied by
630	* the backend. The backend can use this to find
631	* it's instance data.
632	* @param pvBuf What to write.
633	* @param cbBuf Number of bytes to write.
634	* @param pcbWritten Where to store the number of bytes actually written.
635	* If NULL the entire buffer must be successfully written.
636	*/
637	typedef DECLCALLBACK(int) FNDBGCBACKWRITE(PDBGCBACK pBack, const void pvBuf, size_t cbBuf, size_t pcbWritten);
638	/** Pointer to a FNDBGCBACKWRITE() callback. */
639	typedef FNDBGCBACKWRITE *PFNDBGCBACKWRITE;
640
641	/**
642	* Ready / busy notification.
643	*
644	* @param pBack Pointer to the backend structure supplied by
645	* the backend. The backend can use this to find
646	* it's instance data.
647	* @param fReady Whether it's ready (true) or busy (false).
648	*/
649	typedef DECLCALLBACK(void) FNDBGCBACKSETREADY(PDBGCBACK pBack, bool fReady);
650	/** Pointer to a FNDBGCBACKSETREADY() callback. */
651	typedef FNDBGCBACKSETREADY *PFNDBGCBACKSETREADY;
652
653
654	/**
655	* The communication backend provides the console with a number of callbacks
656	* which can be used
657	*/
658	typedef struct DBGCBACK
659	{
660	/** Check for input. */
661	PFNDBGCBACKINPUT pfnInput;
662	/** Read input. */
663	PFNDBGCBACKREAD pfnRead;
664	/** Write output. */
665	PFNDBGCBACKWRITE pfnWrite;
666	/** Ready / busy notification. */
667	PFNDBGCBACKSETREADY pfnSetReady;
668	} DBGCBACK;
669
670
671	/**
672	* Make a console instance.
673	*
674	* This will not return until either an 'exit' command is issued or a error code
675	* indicating connection loss is encountered.
676	*
677	* @returns VINF_SUCCESS if console termination caused by the 'exit' command.
678	* @returns The VBox status code causing the console termination.
679	*
680	* @param pVM VM Handle.
681	* @param pBack Pointer to the backend structure. This must contain
682	* a full set of function pointers to service the console.
683	* @param fFlags Reserved, must be zero.
684	* @remark A forced termination of the console is easiest done by forcing the
685	* callbacks to return fatal failures.
686	*/
687	DBGDECL(int) DBGCCreate(PVM pVM, PDBGCBACK pBack, unsigned fFlags);
688
689
690	/**
691	* Register one or more external commands.
692	*
693	* @returns VBox status.
694	* @param paCommands Pointer to an array of command descriptors.
695	* The commands must be unique. It's not possible
696	* to register the same commands more than once.
697	* @param cCommands Number of commands.
698	*/
699	DBGDECL(int) DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
700
701
702	/**
703	* Deregister one or more external commands previously registered by
704	* DBGCRegisterCommands().
705	*
706	* @returns VBox status.
707	* @param paCommands Pointer to an array of command descriptors
708	* as given to DBGCRegisterCommands().
709	* @param cCommands Number of commands.
710	*/
711	DBGDECL(int) DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
712
713
714	/**
715	* Spawns a new thread with a TCP based debugging console service.
716	*
717	* @returns VBox status.
718	* @param pVM VM handle.
719	* @param ppvData Where to store the pointer to instance data.
720	*/
721	DBGDECL(int) DBGCTcpCreate(PVM pVM, void **ppvUser);
722
723	/**
724	* Terminates any running TCP base debugger consolse service.
725	*
726	* @returns VBox status.
727	* @param pVM VM handle.
728	* @param pvData Instance data set by DBGCTcpCreate().
729	*/
730	DBGDECL(int) DBGCTcpTerminate(PVM pVM, void *pvData);
731
732
733	__END_DECLS
734
735	#endif

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

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

Download in other formats: