dbg.h@ 8464

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

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

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

Download in other formats: