dbg.h@ 13360

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

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

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

Download in other formats: