dbg.h@ 4878

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

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

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

Download in other formats: