dbg.h@ 101598

Last change on this file since 101598 was 99739, checked in by vboxsync, 19 months ago
*: doxygen corrections (mostly about removing @returns from functions returning void).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 40.7 KB

Line
1	/** @file
2	* Debugger Interfaces. (VBoxDbg)
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-2023 Oracle and/or its affiliates.
11	*
12	* This file is part of VirtualBox base platform packages, as
13	* available from https://www.virtualbox.org.
14	*
15	* This program is free software; you can redistribute it and/or
16	* modify it under the terms of the GNU General Public License
17	* as published by the Free Software Foundation, in version 3 of the
18	* License.
19	*
20	* This program is distributed in the hope that it will be useful, but
21	* WITHOUT ANY WARRANTY; without even the implied warranty of
22	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
23	* General Public License for more details.
24	*
25	* You should have received a copy of the GNU General Public License
26	* along with this program; if not, see <https://www.gnu.org/licenses>.
27	*
28	* The contents of this file may alternatively be used under the terms
29	* of the Common Development and Distribution License Version 1.0
30	* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
31	* in the VirtualBox distribution, in which case the provisions of the
32	* CDDL are applicable instead of those of the GPL.
33	*
34	* You may elect to license modified versions of this file under the
35	* terms and conditions of either the GPL or the CDDL or both.
36	*
37	* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
38	*/
39
40	#ifndef VBOX_INCLUDED_dbg_h
41	#define VBOX_INCLUDED_dbg_h
42	#ifndef RT_WITHOUT_PRAGMA_ONCE
43	# pragma once
44	#endif
45
46	#include <VBox/cdefs.h>
47	#include <VBox/types.h>
48	#include <VBox/vmm/dbgf.h>
49
50	#include <iprt/stdarg.h>
51	#ifdef IN_RING3
52	# include <iprt/errcore.h>
53	#endif
54
55	RT_C_DECLS_BEGIN
56
57
58
59	/** @defgroup grp_dbg The VirtualBox Debugger
60	* @{
61	*/
62
63	#ifdef IN_RING3 /* The debugger stuff is ring-3 only. */
64
65	/** @defgroup grp_dbgc The Debugger Console API
66	* @{
67	*/
68
69	/** @def VBOX_WITH_DEBUGGER
70	* The build is with debugger module. Test if this is defined before registering
71	* external debugger commands. This is normally defined in Config.kmk.
72	*/
73	#ifdef DOXYGEN_RUNNING
74	# define VBOX_WITH_DEBUGGER
75	#endif
76
77
78	/**
79	* DBGC variable category.
80	*
81	* Used to describe an argument to a command or function and a functions
82	* return value.
83	*/
84	typedef enum DBGCVARCAT
85	{
86	/** Any type is fine. */
87	DBGCVAR_CAT_ANY = 0,
88	/** Any kind of pointer or number. */
89	DBGCVAR_CAT_POINTER_NUMBER,
90	/** Any kind of pointer or number, no range. */
91	DBGCVAR_CAT_POINTER_NUMBER_NO_RANGE,
92	/** Any kind of pointer. */
93	DBGCVAR_CAT_POINTER,
94	/** Any kind of pointer with no range option. */
95	DBGCVAR_CAT_POINTER_NO_RANGE,
96	/** GC pointer. */
97	DBGCVAR_CAT_GC_POINTER,
98	/** GC pointer with no range option. */
99	DBGCVAR_CAT_GC_POINTER_NO_RANGE,
100	/** Numeric argument. */
101	DBGCVAR_CAT_NUMBER,
102	/** Numeric argument with no range option. */
103	DBGCVAR_CAT_NUMBER_NO_RANGE,
104	/** String. */
105	DBGCVAR_CAT_STRING,
106	/** Symbol. */
107	DBGCVAR_CAT_SYMBOL,
108	/** Option. */
109	DBGCVAR_CAT_OPTION,
110	/** Option + string. */
111	DBGCVAR_CAT_OPTION_STRING,
112	/** Option + number. */
113	DBGCVAR_CAT_OPTION_NUMBER
114	} DBGCVARCAT;
115
116
117	/**
118	* DBGC variable type.
119	*/
120	typedef enum DBGCVARTYPE
121	{
122	/** unknown... */
123	DBGCVAR_TYPE_UNKNOWN = 0,
124	/** Flat GC pointer. */
125	DBGCVAR_TYPE_GC_FLAT,
126	/** Segmented GC pointer. */
127	DBGCVAR_TYPE_GC_FAR,
128	/** Physical GC pointer. */
129	DBGCVAR_TYPE_GC_PHYS,
130	/** Flat HC pointer. */
131	DBGCVAR_TYPE_HC_FLAT,
132	/** Physical HC pointer. */
133	DBGCVAR_TYPE_HC_PHYS,
134	/** Number. */
135	DBGCVAR_TYPE_NUMBER,
136	/** String. */
137	DBGCVAR_TYPE_STRING,
138	/** Symbol. */
139	DBGCVAR_TYPE_SYMBOL,
140	/** Special type used when querying symbols. */
141	DBGCVAR_TYPE_ANY
142	} DBGCVARTYPE;
143
144	/** @todo Rename to DBGCVAR_IS_xyz. */
145
146	/** Checks if the specified variable type is of a pointer persuasion. */
147	#define DBGCVAR_ISPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && enmType <= DBGCVAR_TYPE_HC_PHYS)
148	/** Checks if the specified variable type is of a pointer persuasion. */
149	#define DBGCVAR_IS_FAR_PTR(enmType) ((enmType) == DBGCVAR_TYPE_GC_FAR)
150	/** Checks if the specified variable type is of a pointer persuasion and of the guest context sort. */
151	#define DBGCVAR_ISGCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && (enmType) <= DBGCVAR_TYPE_GC_PHYS)
152	/** Checks if the specified variable type is of a pointer persuasion and of the host context sort. */
153	#define DBGCVAR_ISHCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_HC_FLAT && (enmType) <= DBGCVAR_TYPE_HC_PHYS)
154
155
156	/**
157	* DBGC variable range type.
158	*/
159	typedef enum DBGCVARRANGETYPE
160	{
161	/** No range appliable or no range specified. */
162	DBGCVAR_RANGE_NONE = 0,
163	/** Number of elements. */
164	DBGCVAR_RANGE_ELEMENTS,
165	/** Number of bytes. */
166	DBGCVAR_RANGE_BYTES
167	} DBGCVARRANGETYPE;
168
169
170	/**
171	* Variable descriptor.
172	*/
173	typedef struct DBGCVARDESC
174	{
175	/** The minimal number of times this argument may occur.
176	* Use 0 here to inidicate that the argument is optional. */
177	unsigned cTimesMin;
178	/** Maximum number of occurrences.
179	* Use ~0 here to indicate infinite. */
180	unsigned cTimesMax;
181	/** Argument category. */
182	DBGCVARCAT enmCategory;
183	/** Flags, DBGCVD_FLAGS_* */
184	unsigned fFlags;
185	/** Argument name. */
186	const char *pszName;
187	/** Argument name. */
188	const char *pszDescription;
189	} DBGCVARDESC;
190	/** Pointer to an argument descriptor. */
191	typedef DBGCVARDESC *PDBGCVARDESC;
192	/** Pointer to a const argument descriptor. */
193	typedef const DBGCVARDESC *PCDBGCVARDESC;
194
195	/** Variable descriptor flags.
196	* @{ */
197	/** Indicates that the variable depends on the previous being present. */
198	#define DBGCVD_FLAGS_DEP_PREV RT_BIT(1)
199	/** @} */
200
201
202	/**
203	* DBGC variable.
204	*/
205	typedef struct DBGCVAR
206	{
207	/** Pointer to the argument descriptor. */
208	PCDBGCVARDESC pDesc;
209	/** Pointer to the next argument. */
210	struct DBGCVAR *pNext;
211
212	/** Argument type. */
213	DBGCVARTYPE enmType;
214	/** Type specific. */
215	union
216	{
217	/** Flat GC Address. (DBGCVAR_TYPE_GC_FLAT) */
218	RTGCPTR GCFlat;
219	/** Far (16:32) GC Address. (DBGCVAR_TYPE_GC_FAR) */
220	RTFAR32 GCFar;
221	/** Physical GC Address. (DBGCVAR_TYPE_GC_PHYS) */
222	RTGCPHYS GCPhys;
223	/** Flat HC Address. (DBGCVAR_TYPE_HC_FLAT) */
224	void *pvHCFlat;
225	/** Physical GC Address. (DBGCVAR_TYPE_HC_PHYS) */
226	RTHCPHYS HCPhys;
227	/** String. (DBGCVAR_TYPE_STRING)
228	* The basic idea is the the this is a pointer to the expression we're
229	* parsing, so no messing with freeing. */
230	const char *pszString;
231	/** Number. (DBGCVAR_TYPE_NUMBER) */
232	uint64_t u64Number;
233	} u;
234
235	/** Range type. */
236	DBGCVARRANGETYPE enmRangeType;
237	/** Range. The use of the content depends on the enmRangeType. */
238	uint64_t u64Range;
239	} DBGCVAR;
240	/** Pointer to a command argument. */
241	typedef DBGCVAR *PDBGCVAR;
242	/** Pointer to a const command argument. */
243	typedef const DBGCVAR *PCDBGCVAR;
244
245
246	/**
247	* Macro for initializing a DBGC variable with defaults.
248	* The result is an unknown variable type without any range.
249	*/
250	#define DBGCVAR_INIT(pVar) \
251	do { \
252	(pVar)->pDesc = NULL;\
253	(pVar)->pNext = NULL; \
254	(pVar)->enmType = DBGCVAR_TYPE_UNKNOWN; \
255	(pVar)->u.u64Number = 0; \
256	(pVar)->enmRangeType = DBGCVAR_RANGE_NONE; \
257	(pVar)->u64Range = 0; \
258	} while (0)
259
260	/**
261	* Macro for initializing a DBGC variable with a HC physical address.
262	*/
263	#define DBGCVAR_INIT_HC_PHYS(pVar, Phys) \
264	do { \
265	DBGCVAR_INIT(pVar); \
266	(pVar)->enmType = DBGCVAR_TYPE_HC_PHYS; \
267	(pVar)->u.HCPhys = (Phys); \
268	} while (0)
269
270	/**
271	* Macro for initializing a DBGC variable with a HC flat address.
272	*/
273	#define DBGCVAR_INIT_HC_FLAT(pVar, Flat) \
274	do { \
275	DBGCVAR_INIT(pVar); \
276	(pVar)->enmType = DBGCVAR_TYPE_HC_FLAT; \
277	(pVar)->u.pvHCFlat = (Flat); \
278	} while (0)
279
280	/**
281	* Macro for initializing a DBGC variable with a GC physical address.
282	*/
283	#define DBGCVAR_INIT_GC_PHYS(pVar, Phys) \
284	do { \
285	DBGCVAR_INIT(pVar); \
286	(pVar)->enmType = DBGCVAR_TYPE_GC_PHYS; \
287	(pVar)->u.GCPhys = (Phys); \
288	} while (0)
289
290	/**
291	* Macro for initializing a DBGC variable with a GC flat address.
292	*/
293	#define DBGCVAR_INIT_GC_FLAT(pVar, Flat) \
294	do { \
295	DBGCVAR_INIT(pVar); \
296	(pVar)->enmType = DBGCVAR_TYPE_GC_FLAT; \
297	(pVar)->u.GCFlat = (Flat); \
298	} while (0)
299
300	/**
301	* Macro for initializing a DBGC variable with a GC flat address.
302	*/
303	#define DBGCVAR_INIT_GC_FLAT_BYTE_RANGE(pVar, Flat, cbRange) \
304	do { \
305	DBGCVAR_INIT(pVar); \
306	(pVar)->enmType = DBGCVAR_TYPE_GC_FLAT; \
307	(pVar)->u.GCFlat = (Flat); \
308	DBGCVAR_SET_RANGE(pVar, DBGCVAR_RANGE_BYTES, cbRange); \
309	} while (0)
310
311	/**
312	* Macro for initializing a DBGC variable with a GC far address.
313	*/
314	#define DBGCVAR_INIT_GC_FAR(pVar, _sel, _off) \
315	do { \
316	DBGCVAR_INIT(pVar); \
317	(pVar)->enmType = DBGCVAR_TYPE_GC_FAR; \
318	(pVar)->u.GCFar.sel = (_sel); \
319	(pVar)->u.GCFar.off = (_off); \
320	} while (0)
321
322	/**
323	* Macro for initializing a DBGC variable with a number.
324	*/
325	#define DBGCVAR_INIT_NUMBER(pVar, Value) \
326	do { \
327	DBGCVAR_INIT(pVar); \
328	(pVar)->enmType = DBGCVAR_TYPE_NUMBER; \
329	(pVar)->u.u64Number = (Value); \
330	} while (0)
331
332	/**
333	* Macro for initializing a DBGC variable with a string.
334	*/
335	#define DBGCVAR_INIT_STRING(pVar, a_pszString) \
336	do { \
337	DBGCVAR_INIT(pVar); \
338	(pVar)->enmType = DBGCVAR_TYPE_STRING; \
339	(pVar)->enmRangeType = DBGCVAR_RANGE_BYTES; \
340	(pVar)->u.pszString = (a_pszString); \
341	(pVar)->u64Range = strlen(a_pszString); \
342	} while (0)
343
344
345	/**
346	* Macro for initializing a DBGC variable with a symbol.
347	*/
348	#define DBGCVAR_INIT_SYMBOL(pVar, a_pszSymbol) \
349	do { \
350	DBGCVAR_INIT(pVar); \
351	(pVar)->enmType = DBGCVAR_TYPE_SYMBOL; \
352	(pVar)->enmRangeType = DBGCVAR_RANGE_BYTES; \
353	(pVar)->u.pszString = (a_pszSymbol); \
354	(pVar)->u64Range = strlen(a_pszSymbol); \
355	} while (0)
356
357
358	/**
359	* Macro for setting the range of a DBGC variable.
360	* @param pVar The variable.
361	* @param _enmRangeType The range type.
362	* @param Value The range length value.
363	*/
364	#define DBGCVAR_SET_RANGE(pVar, _enmRangeType, Value) \
365	do { \
366	(pVar)->enmRangeType = (_enmRangeType); \
367	(pVar)->u64Range = (Value); \
368	} while (0)
369
370
371	/**
372	* Macro for setting the range of a DBGC variable.
373	* @param a_pVar The variable.
374	* @param a_cbRange The range, in bytes.
375	*/
376	#define DBGCVAR_SET_BYTE_RANGE(a_pVar, a_cbRange) \
377	DBGCVAR_SET_RANGE(a_pVar, DBGCVAR_RANGE_BYTES, a_cbRange)
378
379
380	/**
381	* Macro for resetting the range a DBGC variable.
382	* @param a_pVar The variable.
383	*/
384	#define DBGCVAR_ZAP_RANGE(a_pVar) \
385	do { \
386	(a_pVar)->enmRangeType = DBGCVAR_RANGE_NONE; \
387	(a_pVar)->u64Range = 0; \
388	} while (0)
389
390
391	/**
392	* Macro for assigning one DBGC variable to another.
393	* @param a_pResult The result (target) variable.
394	* @param a_pVar The source variable.
395	*/
396	#define DBGCVAR_ASSIGN(a_pResult, a_pVar) \
397	do { \
398	(a_pResult) = (a_pVar); \
399	} while (0)
400
401
402	/** Pointer to a command descriptor. */
403	typedef struct DBGCCMD *PDBGCCMD;
404	/** Pointer to a const command descriptor. */
405	typedef const struct DBGCCMD *PCDBGCCMD;
406
407	/** Pointer to a function descriptor. */
408	typedef struct DBGCFUNC *PDBGCFUNC;
409	/** Pointer to a const function descriptor. */
410	typedef const struct DBGCFUNC *PCDBGCFUNC;
411
412	/** Pointer to helper functions for commands. */
413	typedef struct DBGCCMDHLP *PDBGCCMDHLP;
414
415
416	/**
417	* Helper functions for commands.
418	*/
419	typedef struct DBGCCMDHLP
420	{
421	/** Magic value (DBGCCMDHLP_MAGIC). */
422	uint32_t u32Magic;
423
424	/**
425	* Command helper for writing formatted text to the debug console.
426	*
427	* @returns VBox status.
428	* @param pCmdHlp Pointer to the command callback structure.
429	* @param pcbWritten Where to store the number of bytes written.
430	* This is optional.
431	* @param pszFormat The format string. This may use all IPRT extensions as
432	* well as the debugger ones.
433	* @param ... Arguments specified in the format string.
434	*/
435	DECLCALLBACKMEMBER(int, pfnPrintf,(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten,
436	const char *pszFormat, ...)) RT_IPRT_FORMAT_ATTR(3, 4);
437
438	/**
439	* Command helper for writing formatted text to the debug console.
440	*
441	* @returns VBox status.
442	* @param pCmdHlp Pointer to the command callback structure.
443	* @param pcbWritten Where to store the number of bytes written.
444	* This is optional.
445	* @param pszFormat The format string. This may use all IPRT extensions as
446	* well as the debugger ones.
447	* @param args Arguments specified in the format string.
448	*/
449	DECLCALLBACKMEMBER(int, pfnPrintfV,(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten,
450	const char *pszFormat, va_list args)) RT_IPRT_FORMAT_ATTR(3, 0);
451
452	/**
453	* Command helper for formatting a string with debugger format specifiers.
454	*
455	* @returns The number of bytes written.
456	* @param pCmdHlp Pointer to the command callback structure.
457	* @param pszBuf The output buffer.
458	* @param cbBuf The size of the output buffer.
459	* @param pszFormat The format string. This may use all IPRT extensions as
460	* well as the debugger ones.
461	* @param ... Arguments specified in the format string.
462	*/
463	DECLCALLBACKMEMBER(size_t, pfnStrPrintf,(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
464	const char *pszFormat, ...)) RT_IPRT_FORMAT_ATTR(4, 5);
465
466	/**
467	* Command helper for formatting a string with debugger format specifiers.
468	*
469	* @returns The number of bytes written.
470	* @param pCmdHlp Pointer to the command callback structure.
471	* @param pszBuf The output buffer.
472	* @param cbBuf The size of the output buffer.
473	* @param pszFormat The format string. This may use all IPRT extensions as
474	* well as the debugger ones.
475	* @param va Arguments specified in the format string.
476	*/
477	DECLCALLBACKMEMBER(size_t, pfnStrPrintfV,(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
478	const char *pszFormat, va_list va)) RT_IPRT_FORMAT_ATTR(4, 0);
479
480	/**
481	* Command helper for formatting and error message for a VBox status code.
482	*
483	* @returns VBox status code appropriate to return from a command.
484	* @param pCmdHlp Pointer to the command callback structure.
485	* @param rc The VBox status code.
486	* @param pszFormat Format string for additional messages. Can be NULL.
487	* @param ... Format arguments, optional.
488	*/
489	DECLCALLBACKMEMBER(int, pfnVBoxError,(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...)) RT_IPRT_FORMAT_ATTR(3, 4);
490
491	/**
492	* Command helper for formatting and error message for a VBox status code.
493	*
494	* @returns VBox status code appropriate to return from a command.
495	* @param pCmdHlp Pointer to the command callback structure.
496	* @param rc The VBox status code.
497	* @param pszFormat Format string for additional messages. Can be NULL.
498	* @param args Format arguments, optional.
499	*/
500	DECLCALLBACKMEMBER(int, pfnVBoxErrorV,(PDBGCCMDHLP pCmdHlp, int rc,
501	const char *pszFormat, va_list args)) RT_IPRT_FORMAT_ATTR(3, 0);
502
503	/**
504	* Command helper for reading memory specified by a DBGC variable.
505	*
506	* @returns VBox status code appropriate to return from a command.
507	* @param pCmdHlp Pointer to the command callback structure.
508	* @param pvBuffer Where to store the read data.
509	* @param cbRead Number of bytes to read.
510	* @param pVarPointer DBGC variable specifying where to start reading.
511	* @param pcbRead Where to store the number of bytes actually read.
512	* This optional, but it's useful when read GC virtual memory where a
513	* page in the requested range might not be present.
514	* If not specified not-present failure or end of a HC physical page
515	* will cause failure.
516	*/
517	DECLCALLBACKMEMBER(int, pfnMemRead,(PDBGCCMDHLP pCmdHlp, void pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t pcbRead));
518
519	/**
520	* Command helper for writing memory specified by a DBGC variable.
521	*
522	* @returns VBox status code appropriate to return from a command.
523	* @param pCmdHlp Pointer to the command callback structure.
524	* @param pvBuffer What to write.
525	* @param cbWrite Number of bytes to write.
526	* @param pVarPointer DBGC variable specifying where to start reading.
527	* @param pcbWritten Where to store the number of bytes written.
528	* This is optional. If NULL be aware that some of the buffer
529	* might have been written to the specified address.
530	*/
531	DECLCALLBACKMEMBER(int, pfnMemWrite,(PDBGCCMDHLP pCmdHlp, const void pvBuffer, size_t cbWrite, PCDBGCVAR pVarPointer, size_t pcbWritten));
532
533	/**
534	* Executes command an expression.
535	* (Hopefully the parser and functions are fully reentrant.)
536	*
537	* @returns VBox status code appropriate to return from a command.
538	* @param pCmdHlp Pointer to the command callback structure.
539	* @param pszExpr The expression. Format string with the format DBGC extensions.
540	* @param ... Format arguments.
541	*/
542	DECLCALLBACKMEMBER(int, pfnExec,(PDBGCCMDHLP pCmdHlp, const char *pszExpr, ...)) RT_IPRT_FORMAT_ATTR(2, 3);
543
544	/**
545	* Evaluates an expression.
546	* (Hopefully the parser and functions are fully reentrant.)
547	*
548	* @returns VBox status code appropriate to return from a command.
549	* @param pCmdHlp Pointer to the command callback structure.
550	* @param pResult Where to store the result.
551	* @param pszExpr The expression. Format string with the format DBGC extensions.
552	* @param va Format arguments.
553	*/
554	DECLCALLBACKMEMBER(int, pfnEvalV,(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult,
555	const char *pszExpr, va_list va)) RT_IPRT_FORMAT_ATTR(3, 0);
556
557	/**
558	* Print an error and fail the current command.
559	*
560	* @returns VBox status code to pass upwards.
561	*
562	* @param pCmdHlp Pointer to the command callback structure.
563	* @param pCmd The failing command.
564	* @param pszFormat The error message format string.
565	* @param va Format arguments.
566	*/
567	DECLCALLBACKMEMBER(int, pfnFailV,(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd,
568	const char *pszFormat, va_list va)) RT_IPRT_FORMAT_ATTR(3, 0);
569
570	/**
571	* Print an error and fail the current command.
572	*
573	* @returns VBox status code to pass upwards.
574	*
575	* @param pCmdHlp Pointer to the command callback structure.
576	* @param pCmd The failing command.
577	* @param rc The status code indicating the failure. This will
578	* be appended to the message after a colon (': ').
579	* @param pszFormat The error message format string.
580	* @param va Format arguments.
581	*
582	* @see DBGCCmdHlpFailRc
583	*/
584	DECLCALLBACKMEMBER(int, pfnFailRcV,(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc,
585	const char *pszFormat, va_list va)) RT_IPRT_FORMAT_ATTR(4, 0);
586
587	/**
588	* Parser error.
589	*
590	* @returns VBox status code to pass upwards.
591	*
592	* @param pCmdHlp Pointer to the command callback structure.
593	* @param pCmd The failing command, can be NULL but shouldn't.
594	* @param iArg The offending argument, -1 when lazy.
595	* @param pszExpr The expression.
596	* @param iLine The line number.
597	*/
598	DECLCALLBACKMEMBER(int, pfnParserError,(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int iArg, const char *pszExpr, unsigned iLine));
599
600	/**
601	* Converts a DBGC variable to a DBGF address structure.
602	*
603	* @returns VBox status code.
604	* @param pCmdHlp Pointer to the command callback structure.
605	* @param pVar The variable to convert.
606	* @param pAddress The target address.
607	*/
608	DECLCALLBACKMEMBER(int, pfnVarToDbgfAddr,(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress));
609
610	/**
611	* Converts a DBGF address structure to a DBGC variable.
612	*
613	* @returns VBox status code.
614	* @param pCmdHlp Pointer to the command callback structure.
615	* @param pAddress The source address.
616	* @param pResult The result variable.
617	*/
618	DECLCALLBACKMEMBER(int, pfnVarFromDbgfAddr,(PDBGCCMDHLP pCmdHlp, PCDBGFADDRESS pAddress, PDBGCVAR pResult));
619
620	/**
621	* Converts a DBGC variable to a 64-bit number.
622	*
623	* @returns VBox status code.
624	* @param pCmdHlp Pointer to the command callback structure.
625	* @param pVar The variable to convert.
626	* @param pu64Number Where to store the number.
627	*/
628	DECLCALLBACKMEMBER(int, pfnVarToNumber,(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number));
629
630	/**
631	* Converts a DBGC variable to a boolean.
632	*
633	* @returns VBox status code.
634	* @param pCmdHlp Pointer to the command callback structure.
635	* @param pVar The variable to convert.
636	* @param pf Where to store the boolean.
637	*/
638	DECLCALLBACKMEMBER(int, pfnVarToBool,(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf));
639
640	/**
641	* Get the range of a variable in bytes, resolving symbols if necessary.
642	*
643	* @returns VBox status code.
644	* @param pCmdHlp Pointer to the command callback structure.
645	* @param pVar The variable to convert.
646	* @param cbElement Conversion factor for element ranges.
647	* @param cbDefault The default range.
648	* @param pcbRange The length of the range.
649	*/
650	DECLCALLBACKMEMBER(int, pfnVarGetRange,(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault,
651	uint64_t *pcbRange));
652
653	/**
654	* Converts a variable to one with the specified type.
655	*
656	* This preserves the range.
657	*
658	* @returns VBox status code.
659	* @param pCmdHlp Pointer to the command callback structure.
660	* @param pVar The variable to convert.
661	* @param enmToType The target type.
662	* @param fConvSyms If @c true, then attempt to resolve symbols.
663	* @param pResult The output variable. Can be the same as @a pVar.
664	*/
665	DECLCALLBACKMEMBER(int, pfnVarConvert,(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms,
666	PDBGCVAR pResult));
667
668	/**
669	* Gets a DBGF output helper that directs the output to the debugger
670	* console.
671	*
672	* @returns Pointer to the helper structure.
673	* @param pCmdHlp Pointer to the command callback structure.
674	*/
675	DECLCALLBACKMEMBER(PCDBGFINFOHLP, pfnGetDbgfOutputHlp,(PDBGCCMDHLP pCmdHlp));
676
677	/**
678	* Gets the ID currently selected CPU.
679	*
680	* @returns Current CPU ID.
681	* @param pCmdHlp Pointer to the command callback structure.
682	*/
683	DECLCALLBACKMEMBER(VMCPUID, pfnGetCurrentCpu,(PDBGCCMDHLP pCmdHlp));
684
685	/**
686	* Gets the mode the currently selected CPU is running in, in the current
687	* context.
688	*
689	* @returns Current CPU mode.
690	* @param pCmdHlp Pointer to the command callback structure.
691	*/
692	DECLCALLBACKMEMBER(CPUMMODE, pfnGetCpuMode,(PDBGCCMDHLP pCmdHlp));
693
694	/**
695	* Prints the register set of the given CPU.
696	*
697	* @returns VBox status code.
698	* @param pCmdHlp Pointer to the command callback structure.
699	* @param idCpu The CPU ID to print the register set of.
700	* @param f64BitMode True to dump 64-bit state, false to dump 32-bit state,
701	* -1 to use the current CPU mode.
702	* @param fTerse Flag to indicate whether to dump the complete register set.
703	*/
704	DECLCALLBACKMEMBER(int, pfnRegPrintf, (PDBGCCMDHLP pCmdHlp, VMCPUID idCpu, int f64BitMode, bool fTerse));
705
706	/** End marker (DBGCCMDHLP_MAGIC). */
707	uint32_t u32EndMarker;
708	} DBGCCMDHLP;
709
710	/** Magic value for DBGCCMDHLP::u32Magic. (Fyodor Mikhaylovich Dostoyevsky) */
711	#define DBGCCMDHLP_MAGIC UINT32_C(18211111)
712
713
714	#if defined(IN_RING3) \|\| defined(IN_SLICKEDIT)
715
716	/**
717	* Command helper for writing formatted text to the debug console.
718	*
719	* @returns VBox status.
720	* @param pCmdHlp Pointer to the command callback structure.
721	* @param pszFormat The format string. This may use all IPRT extensions as
722	* well as the debugger ones.
723	* @param ... Arguments specified in the format string.
724	*/
725	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) DBGCCmdHlpPrintf(PDBGCCMDHLP pCmdHlp, const char *pszFormat, ...)
726	{
727	va_list va;
728	int rc;
729
730	va_start(va, pszFormat);
731	rc = pCmdHlp->pfnPrintfV(pCmdHlp, NULL, pszFormat, va);
732	va_end(va);
733
734	return rc;
735	}
736
737	/**
738	* Command helper for writing formatted text to the debug console.
739	*
740	* @returns VBox status.
741	* @param pCmdHlp Pointer to the command callback structure.
742	* @param pcbWritten Where to store the amount of written characters on success.
743	* @param pszFormat The format string. This may use all IPRT extensions as
744	* well as the debugger ones.
745	* @param ... Arguments specified in the format string.
746	*/
747	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpPrintfEx(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten,
748	const char *pszFormat, ...)
749	{
750	va_list va;
751	int rc;
752
753	va_start(va, pszFormat);
754	rc = pCmdHlp->pfnPrintfV(pCmdHlp, pcbWritten, pszFormat, va);
755	va_end(va);
756
757	return rc;
758	}
759
760	/**
761	* Command helper for writing formatted text to the debug console.
762	*
763	* @returns Number of bytes written.
764	* @param pCmdHlp Pointer to the command callback structure.
765	* @param pszFormat The format string. This may use all IPRT extensions as
766	* well as the debugger ones.
767	* @param ... Arguments specified in the format string.
768	*/
769	DECLINLINE(size_t) RT_IPRT_FORMAT_ATTR(2, 3) DBGCCmdHlpPrintfLen(PDBGCCMDHLP pCmdHlp, const char *pszFormat, ...)
770	{
771	va_list va;
772	int rc;
773	size_t cbWritten = 0;
774
775	va_start(va, pszFormat);
776	rc = pCmdHlp->pfnPrintfV(pCmdHlp, &cbWritten, pszFormat, va);
777	va_end(va);
778
779	return RT_SUCCESS(rc) ? cbWritten : 0;
780	}
781
782	/**
783	* @copydoc DBGCCMDHLP::pfnStrPrintf
784	*/
785	DECLINLINE(size_t) RT_IPRT_FORMAT_ATTR(4, 5) DBGCCmdHlpStrPrintf(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf,
786	const char *pszFormat, ...)
787	{
788	va_list va;
789	size_t cch;
790
791	va_start(va, pszFormat);
792	cch = pCmdHlp->pfnStrPrintfV(pCmdHlp, pszBuf, cbBuf, pszFormat, va);
793	va_end(va);
794
795	return cch;
796	}
797
798	/**
799	* @copydoc DBGCCMDHLP::pfnVBoxError
800	*/
801	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpVBoxError(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...)
802	{
803	va_list va;
804
805	va_start(va, pszFormat);
806	rc = pCmdHlp->pfnVBoxErrorV(pCmdHlp, rc, pszFormat, va);
807	va_end(va);
808
809	return rc;
810	}
811
812	/**
813	* @copydoc DBGCCMDHLP::pfnMemRead
814	*/
815	DECLINLINE(int) DBGCCmdHlpMemRead(PDBGCCMDHLP pCmdHlp, void pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t pcbRead)
816	{
817	return pCmdHlp->pfnMemRead(pCmdHlp, pvBuffer, cbRead, pVarPointer, pcbRead);
818	}
819
820	/**
821	* Evaluates an expression.
822	* (Hopefully the parser and functions are fully reentrant.)
823	*
824	* @returns VBox status code appropriate to return from a command.
825	* @param pCmdHlp Pointer to the command callback structure.
826	* @param pResult Where to store the result.
827	* @param pszExpr The expression. Format string with the format DBGC extensions.
828	* @param ... Format arguments.
829	*/
830	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpEval(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, ...)
831	{
832	va_list va;
833	int rc;
834
835	va_start(va, pszExpr);
836	rc = pCmdHlp->pfnEvalV(pCmdHlp, pResult, pszExpr, va);
837	va_end(va);
838
839	return rc;
840	}
841
842	/**
843	* Print an error and fail the current command.
844	*
845	* @returns VBox status code to pass upwards.
846	*
847	* @param pCmdHlp Pointer to the command callback structure.
848	* @param pCmd The failing command.
849	* @param pszFormat The error message format string.
850	* @param ... Format arguments.
851	*/
852	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) DBGCCmdHlpFail(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, ...)
853	{
854	va_list va;
855	int rc;
856
857	va_start(va, pszFormat);
858	rc = pCmdHlp->pfnFailV(pCmdHlp, pCmd, pszFormat, va);
859	va_end(va);
860
861	return rc;
862	}
863
864	/**
865	* Print an error and fail the current command.
866	*
867	* Usage example:
868	* @code
869	int rc = VMMR3Something(pVM);
870	if (RT_FAILURE(rc))
871	return DBGCCmdHlpFailRc(pCmdHlp, pCmd, rc, "VMMR3Something");
872	return VINF_SUCCESS;
873	* @endcode
874	*
875	* @returns VBox status code to pass upwards.
876	*
877	* @param pCmdHlp Pointer to the command callback structure.
878	* @param pCmd The failing command.
879	* @param rc The status code indicating the failure.
880	* @param pszFormat The error message format string.
881	* @param ... Format arguments.
882	*/
883	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(4, 5) DBGCCmdHlpFailRc(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc,
884	const char *pszFormat, ...)
885	{
886	va_list va;
887
888	va_start(va, pszFormat);
889	rc = pCmdHlp->pfnFailRcV(pCmdHlp, pCmd, rc, pszFormat, va);
890	va_end(va);
891
892	return rc;
893	}
894
895	/**
896	* @copydoc DBGCCMDHLP::pfnParserError
897	*/
898	DECLINLINE(int) DBGCCmdHlpParserError(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int iArg, const char *pszExpr, unsigned iLine)
899	{
900	return pCmdHlp->pfnParserError(pCmdHlp, pCmd, iArg, pszExpr, iLine);
901	}
902
903	/** Assert+return like macro for checking parser sanity.
904	* Returns with failure if the precodition is not met. */
905	#define DBGC_CMDHLP_ASSERT_PARSER_RET(pCmdHlp, pCmd, iArg, expr) \
906	do { \
907	if (!(expr)) \
908	return DBGCCmdHlpParserError(pCmdHlp, pCmd, iArg, #expr, __LINE__); \
909	} while (0)
910
911	/** Assert+return like macro that the VM handle is present.
912	* Returns with failure if the VM handle is NIL. */
913	#define DBGC_CMDHLP_REQ_UVM_RET(pCmdHlp, pCmd, pUVM) \
914	do { \
915	if (!(pUVM)) \
916	return DBGCCmdHlpFail(pCmdHlp, pCmd, "No VM selected"); \
917	} while (0)
918
919	/**
920	* @copydoc DBGCCMDHLP::pfnVarToDbgfAddr
921	*/
922	DECLINLINE(int) DBGCCmdHlpVarToDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress)
923	{
924	return pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, pAddress);
925	}
926
927	/**
928	* @copydoc DBGCCMDHLP::pfnVarFromDbgfAddr
929	*/
930	DECLINLINE(int) DBGCCmdHlpVarFromDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGFADDRESS pAddress, PDBGCVAR pResult)
931	{
932	return pCmdHlp->pfnVarFromDbgfAddr(pCmdHlp, pAddress, pResult);
933	}
934
935	/**
936	* Converts an variable to a flat address.
937	*
938	* @returns VBox status code.
939	* @param pCmdHlp Pointer to the command callback structure.
940	* @param pVar The variable to convert.
941	* @param pFlatPtr Where to store the flat address.
942	*/
943	DECLINLINE(int) DBGCCmdHlpVarToFlatAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PRTGCPTR pFlatPtr)
944	{
945	DBGFADDRESS Addr;
946	int rc = pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, &Addr);
947	if (RT_SUCCESS(rc))
948	*pFlatPtr = Addr.FlatPtr;
949	return rc;
950	}
951
952	/**
953	* @copydoc DBGCCMDHLP::pfnVarToNumber
954	*/
955	DECLINLINE(int) DBGCCmdHlpVarToNumber(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number)
956	{
957	return pCmdHlp->pfnVarToNumber(pCmdHlp, pVar, pu64Number);
958	}
959
960	/**
961	* @copydoc DBGCCMDHLP::pfnVarToBool
962	*/
963	DECLINLINE(int) DBGCCmdHlpVarToBool(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf)
964	{
965	return pCmdHlp->pfnVarToBool(pCmdHlp, pVar, pf);
966	}
967
968	/**
969	* @copydoc DBGCCMDHLP::pfnVarGetRange
970	*/
971	DECLINLINE(int) DBGCCmdHlpVarGetRange(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault, uint64_t *pcbRange)
972	{
973	return pCmdHlp->pfnVarGetRange(pCmdHlp, pVar, cbElement, cbDefault, pcbRange);
974	}
975
976	/**
977	* @copydoc DBGCCMDHLP::pfnVarConvert
978	*/
979	DECLINLINE(int) DBGCCmdHlpConvert(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms, PDBGCVAR pResult)
980	{
981	return pCmdHlp->pfnVarConvert(pCmdHlp, pVar, enmToType, fConvSyms, pResult);
982	}
983
984	/**
985	* @copydoc DBGCCMDHLP::pfnGetDbgfOutputHlp
986	*/
987	DECLINLINE(PCDBGFINFOHLP) DBGCCmdHlpGetDbgfOutputHlp(PDBGCCMDHLP pCmdHlp)
988	{
989	return pCmdHlp->pfnGetDbgfOutputHlp(pCmdHlp);
990	}
991
992	/**
993	* @copydoc DBGCCMDHLP::pfnGetCurrentCpu
994	*/
995	DECLINLINE(VMCPUID) DBGCCmdHlpGetCurrentCpu(PDBGCCMDHLP pCmdHlp)
996	{
997	return pCmdHlp->pfnGetCurrentCpu(pCmdHlp);
998	}
999
1000	/**
1001	* @copydoc DBGCCMDHLP::pfnGetCpuMode
1002	*/
1003	DECLINLINE(CPUMMODE) DBGCCmdHlpGetCpuMode(PDBGCCMDHLP pCmdHlp)
1004	{
1005	return pCmdHlp->pfnGetCpuMode(pCmdHlp);
1006	}
1007
1008	/**
1009	* @copydoc DBGCCMDHLP::pfnRegPrintf
1010	*/
1011	DECLINLINE(int) DBGCCmdHlpRegPrintf(PDBGCCMDHLP pCmdHlp, VMCPUID idCpu, int f64BitMode, bool fTerse)
1012	{
1013	return pCmdHlp->pfnRegPrintf(pCmdHlp, idCpu, f64BitMode, fTerse);
1014	}
1015
1016	#endif /* IN_RING3 */
1017
1018
1019
1020	/**
1021	* Command handler.
1022	*
1023	* The console will call the handler for a command once it's finished
1024	* parsing the user input. The command handler function is responsible
1025	* for executing the command itself.
1026	*
1027	* @returns VBox status.
1028	* @param pCmd Pointer to the command descriptor (as registered).
1029	* @param pCmdHlp Pointer to command helper functions.
1030	* @param pUVM The user mode VM handle, can in theory be NULL.
1031	* @param paArgs Pointer to (readonly) array of arguments.
1032	* @param cArgs Number of arguments in the array.
1033	*/
1034	typedef DECLCALLBACKTYPE(int, FNDBGCCMD,(PCDBGCCMD pCmd, PDBGCCMDHLP pCmdHlp, PUVM pUVM, PCDBGCVAR paArgs, unsigned cArgs));
1035	/** Pointer to a FNDBGCCMD() function. */
1036	typedef FNDBGCCMD *PFNDBGCCMD;
1037
1038	/**
1039	* DBGC command descriptor.
1040	*/
1041	typedef struct DBGCCMD
1042	{
1043	/** Command string. */
1044	const char *pszCmd;
1045	/** Minimum number of arguments. */
1046	unsigned cArgsMin;
1047	/** Max number of arguments. */
1048	unsigned cArgsMax;
1049	/** Argument descriptors (array). */
1050	PCDBGCVARDESC paArgDescs;
1051	/** Number of argument descriptors. */
1052	unsigned cArgDescs;
1053	/** flags. (reserved for now) */
1054	unsigned fFlags;
1055	/** Handler function. */
1056	PFNDBGCCMD pfnHandler;
1057	/** Command syntax. */
1058	const char *pszSyntax;
1059	/** Command description. */
1060	const char *pszDescription;
1061	} DBGCCMD;
1062
1063	/** DBGCCMD Flags.
1064	* @{
1065	*/
1066	/** @} */
1067
1068
1069	/**
1070	* Function handler.
1071	*
1072	* The console will call the handler for a command once it's finished
1073	* parsing the user input. The command handler function is responsible
1074	* for executing the command itself.
1075	*
1076	* @returns VBox status.
1077	* @param pFunc Pointer to the function descriptor (as registered).
1078	* @param pCmdHlp Pointer to command helper functions.
1079	* @param pUVM The user mode VM handle, can in theory be NULL.
1080	* @param paArgs Pointer to (readonly) array of arguments.
1081	* @param cArgs Number of arguments in the array.
1082	* @param pResult Where to return the result.
1083	*/
1084	typedef DECLCALLBACKTYPE(int, FNDBGCFUNC,(PCDBGCFUNC pFunc, PDBGCCMDHLP pCmdHlp, PUVM pUVM, PCDBGCVAR paArgs, unsigned cArgs,
1085	PDBGCVAR pResult));
1086	/** Pointer to a FNDBGCFUNC() function. */
1087	typedef FNDBGCFUNC *PFNDBGCFUNC;
1088
1089	/**
1090	* DBGC function descriptor.
1091	*/
1092	typedef struct DBGCFUNC
1093	{
1094	/** Command string. */
1095	const char *pszFuncNm;
1096	/** Minimum number of arguments. */
1097	unsigned cArgsMin;
1098	/** Max number of arguments. */
1099	unsigned cArgsMax;
1100	/** Argument descriptors (array). */
1101	PCDBGCVARDESC paArgDescs;
1102	/** Number of argument descriptors. */
1103	unsigned cArgDescs;
1104	/** flags. (reserved for now) */
1105	unsigned fFlags;
1106	/** Handler function. */
1107	PFNDBGCFUNC pfnHandler;
1108	/** Function syntax. */
1109	const char *pszSyntax;
1110	/** Function description. */
1111	const char *pszDescription;
1112	} DBGCFUNC;
1113
1114
1115	/** Pointer to a const I/O callback table. */
1116	typedef const struct DBGCIO *PCDBGCIO;
1117
1118	/**
1119	* I/O callback table.
1120	*/
1121	typedef struct DBGCIO
1122	{
1123	/**
1124	* Destroys the given I/O instance.
1125	*
1126	* @param pIo Pointer to the I/O structure supplied by the I/O provider.
1127	*/
1128	DECLCALLBACKMEMBER(void, pfnDestroy, (PCDBGCIO pIo));
1129
1130	/**
1131	* Wait for input available for reading.
1132	*
1133	* @returns Flag whether there is input ready upon return.
1134	* @retval true if there is input ready.
1135	* @retval false if there not input ready.
1136	* @param pIo Pointer to the I/O structure supplied by
1137	* the I/O provider. The backend can use this to find it's instance data.
1138	* @param cMillies Number of milliseconds to wait on input data.
1139	*/
1140	DECLCALLBACKMEMBER(bool, pfnInput, (PCDBGCIO pIo, uint32_t cMillies));
1141
1142	/**
1143	* Read input.
1144	*
1145	* @returns VBox status code.
1146	* @param pIo Pointer to the I/O structure supplied by
1147	* the I/O provider. The backend can use this to find it's instance data.
1148	* @param pvBuf Where to put the bytes we read.
1149	* @param cbBuf Maximum nymber of bytes to read.
1150	* @param pcbRead Where to store the number of bytes actually read.
1151	* If NULL the entire buffer must be filled for a
1152	* successful return.
1153	*/
1154	DECLCALLBACKMEMBER(int, pfnRead, (PCDBGCIO pIo, void pvBuf, size_t cbBuf, size_t pcbRead));
1155
1156	/**
1157	* Write (output).
1158	*
1159	* @returns VBox status code.
1160	* @param pIo Pointer to the I/O structure supplied by
1161	* the I/O provider. The backend can use this to find it's instance data.
1162	* @param pvBuf What to write.
1163	* @param cbBuf Number of bytes to write.
1164	* @param pcbWritten Where to store the number of bytes actually written.
1165	* If NULL the entire buffer must be successfully written.
1166	*/
1167	DECLCALLBACKMEMBER(int, pfnWrite, (PCDBGCIO pIo, const void pvBuf, size_t cbBuf, size_t pcbWritten));
1168
1169	/**
1170	* Marks the beginning of a new packet being sent - optional.
1171	*
1172	* @returns VBox status code.
1173	* @param pIo Pointer to the I/O structure supplied by
1174	* the I/O provider. The backend can use this to find it's instance data.
1175	* @param cbPktHint Size of the packet in bytes, serves as a hint for the I/O provider to arrange buffers.
1176	* Give 0 if size is unknown upfront.
1177	*/
1178	DECLCALLBACKMEMBER(int, pfnPktBegin, (PCDBGCIO pIo, size_t cbPktHint));
1179
1180	/**
1181	* Marks the end of the packet - optional.
1182	*
1183	* @returns VBox status code.
1184	* @param pIo Pointer to the I/O structure supplied by
1185	* the I/O provider. The backend can use this to find it's instance data.
1186	*
1187	* @note Some I/O providers might decide to send data only when this is called not in the
1188	* DBGCIO::pfnWrite callback.
1189	*/
1190	DECLCALLBACKMEMBER(int, pfnPktEnd, (PCDBGCIO pIo));
1191
1192	/**
1193	* Ready / busy notification.
1194	*
1195	* @param pIo Pointer to the I/O structure supplied by
1196	* the I/O provider. The backend can use this to find it's instance data.
1197	* @param fReady Whether it's ready (true) or busy (false).
1198	*/
1199	DECLCALLBACKMEMBER(void, pfnSetReady, (PCDBGCIO pIo, bool fReady));
1200
1201	} DBGCIO;
1202	/** Pointer to an I/O callback table. */
1203	typedef DBGCIO *PDBGCIO;
1204
1205
1206	DBGDECL(int) DBGCCreate(PUVM pUVM, PCDBGCIO pIo, unsigned fFlags);
1207	DBGDECL(int) DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
1208	DBGDECL(int) DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
1209
1210	DBGDECL(int) DBGCIoCreate(PUVM pUVM, void **ppvData);
1211	DBGDECL(int) DBGCIoTerminate(PUVM pUVM, void *pvData);
1212
1213	/** @} */
1214
1215	#endif /* IN_RING3 */
1216
1217	/** @} */
1218	RT_C_DECLS_END
1219
1220	#endif /* !VBOX_INCLUDED_dbg_h */

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

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

Download in other formats: