1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
/** @file
*
* VBox HDD container test utility - scripting engine.
*/
/*
* Copyright (C) 2013-2023 Oracle and/or its affiliates.
*
* This file is part of VirtualBox base platform packages, as
* available from https://www.virtualbox.org.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, in version 3 of the
* License.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses>.
*
* SPDX-License-Identifier: GPL-3.0-only
*/
#ifndef VBOX_INCLUDED_SRC_testcase_VDScript_h
#define VBOX_INCLUDED_SRC_testcase_VDScript_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
/** Handle to the scripting context. */
typedef struct VDSCRIPTCTXINT *VDSCRIPTCTX;
/** Pointer to a scripting context handle. */
typedef VDSCRIPTCTX *PVDSCRIPTCTX;
/**
* Supprted primitive types in the scripting engine.
*/
typedef enum VDSCRIPTTYPE
{
/** Invalid type, do not use. */
VDSCRIPTTYPE_INVALID = 0,
/** void type, used for no return value of methods. */
VDSCRIPTTYPE_VOID,
/** unsigned 8bit integer. */
VDSCRIPTTYPE_UINT8,
VDSCRIPTTYPE_INT8,
VDSCRIPTTYPE_UINT16,
VDSCRIPTTYPE_INT16,
VDSCRIPTTYPE_UINT32,
VDSCRIPTTYPE_INT32,
VDSCRIPTTYPE_UINT64,
VDSCRIPTTYPE_INT64,
VDSCRIPTTYPE_STRING,
VDSCRIPTTYPE_BOOL,
VDSCRIPTTYPE_POINTER,
/** As usual, the 32bit blowup hack. */
VDSCRIPTTYPE_32BIT_HACK = 0x7fffffff
} VDSCRIPTTYPE;
/** Pointer to a type. */
typedef VDSCRIPTTYPE *PVDSCRIPTTYPE;
/** Pointer to a const type. */
typedef const VDSCRIPTTYPE *PCVDSCRIPTTYPE;
/**
* Script argument.
*/
typedef struct VDSCRIPTARG
{
/** Type of the argument. */
VDSCRIPTTYPE enmType;
/** Value */
union
{
uint8_t u8;
int8_t i8;
uint16_t u16;
int16_t i16;
uint32_t u32;
int32_t i32;
uint64_t u64;
int64_t i64;
const char *psz;
bool f;
void *p;
};
} VDSCRIPTARG;
/** Pointer to an argument. */
typedef VDSCRIPTARG *PVDSCRIPTARG;
/** Script callback. */
typedef DECLCALLBACKTYPE(int, FNVDSCRIPTCALLBACK,(PVDSCRIPTARG paScriptArgs, void *pvUser));
/** Pointer to a script callback. */
typedef FNVDSCRIPTCALLBACK *PFNVDSCRIPTCALLBACK;
/**
* Callback registration structure.
*/
typedef struct VDSCRIPTCALLBACK
{
/** The function name. */
const char *pszFnName;
/** The return type of the function. */
VDSCRIPTTYPE enmTypeReturn;
/** Pointer to the array of argument types. */
PCVDSCRIPTTYPE paArgs;
/** Number of arguments this method takes. */
unsigned cArgs;
/** The callback handler. */
PFNVDSCRIPTCALLBACK pfnCallback;
} VDSCRIPTCALLBACK;
/** Pointer to a callback register entry. */
typedef VDSCRIPTCALLBACK *PVDSCRIPTCALLBACK;
/** Pointer to a const callback register entry. */
typedef const VDSCRIPTCALLBACK *PCVDSCRIPTCALLBACK;
/**
* @{
*/
/** The address space stays assigned to a variable
* even if the pointer is casted to another type.
*/
#define VDSCRIPT_AS_FLAGS_TRANSITIVE RT_BIT(0)
/** @} */
/**
* Address space read callback
*
* @returns VBox status code.
* @param pvUser Opaque user data given on registration.
* @param Address The address to read from, address is stored in the member for
* base type given on registration.
* @param pvBuf Where to store the read bits.
* @param cbRead How much to read.
*/
typedef DECLCALLBACKTYPE(int, FNVDSCRIPTASREAD,(void *pvUser, VDSCRIPTARG Address, void *pvBuf, size_t cbRead));
/** Pointer to a read callback. */
typedef FNVDSCRIPTASREAD *PFNVDSCRIPTASREAD;
/**
* Address space write callback
*
* @returns VBox status code.
* @param pvUser Opaque user data given on registration.
* @param Address The address to write to, address is stored in the member for
* base type given on registration.
* @param pvBuf Data to write.
* @param cbWrite How much to write.
*/
typedef DECLCALLBACKTYPE(int, FNVDSCRIPTASWRITE,(void *pvUser, VDSCRIPTARG Address, const void *pvBuf, size_t cbWrite));
/** Pointer to a write callback. */
typedef FNVDSCRIPTASWRITE *PFNVDSCRIPTASWRITE;
/**
* Create a new scripting context.
*
* @returns VBox status code.
* @param phScriptCtx Where to store the scripting context on success.
*/
DECLHIDDEN(int) VDScriptCtxCreate(PVDSCRIPTCTX phScriptCtx);
/**
* Destroys the given scripting context.
*
* @param hScriptCtx The script context to destroy.
*/
DECLHIDDEN(void) VDScriptCtxDestroy(VDSCRIPTCTX hScriptCtx);
/**
* Register callbacks for the scripting context.
*
* @returns VBox status code.
* @param hScriptCtx The script context handle.
* @param paCallbacks Pointer to the callbacks to register.
* @param cCallbacks Number of callbacks in the array.
* @param pvUser Opaque user data to pass on the callback invocation.
*/
DECLHIDDEN(int) VDScriptCtxCallbacksRegister(VDSCRIPTCTX hScriptCtx, PCVDSCRIPTCALLBACK paCallbacks,
unsigned cCallbacks, void *pvUser);
/**
* Load a given script into the context.
*
* @returns VBox status code.
* @param hScriptCtx The script context handle.
* @param pszScript Pointer to the char buffer containing the script.
*/
DECLHIDDEN(int) VDScriptCtxLoadScript(VDSCRIPTCTX hScriptCtx, const char *pszScript);
/**
* Execute a given method in the script context.
*
* @returns VBox status code.
* @param hScriptCtx The script context handle.
* @param pszFnCall The method to call.
* @param paArgs Pointer to arguments to pass.
* @param cArgs Number of arguments.
*/
DECLHIDDEN(int) VDScriptCtxCallFn(VDSCRIPTCTX hScriptCtx, const char *pszFnCall,
PVDSCRIPTARG paArgs, unsigned cArgs);
/**
* Registers a new address space provider.
*
* @returns VBox status code.
* @param hScriptCtx The script context handle.
* @param pszType The type string.
* @param enmBaseType The base integer type to use for the address space.
* Bool and String are not supported of course.
* @param pfnRead The read callback for the registered address space.
* @param pfnWrite The write callback for the registered address space.
* @param pvUser Opaque user data to pass to the read and write callbacks.
* @param fFlags Flags, see VDSCRIPT_AS_FLAGS_*.
*
* @note This will automatically register a new type with the identifier given in pszType
* used for the pointer. Every variable with this type is automatically treated as a pointer.
*
* @note If the transitive flag is set the address space stays assigned even if the pointer value
* is casted to another pointer type.
* In the following example the pointer pStruct will use the registered address space for RTGCPHYS
* and dereferencing the pointer causes the read/write callbacks to be triggered.
*
* ...
* Struct *pStruct = (Struct *)(RTGCPHYS)0x12345678;
* pStruct->count++;
* ...
*/
DECLHIDDEN(int) VDScriptCtxAsRegister(VDSCRIPTCTX hScriptCtx, const char *pszType, VDSCRIPTTYPE enmBaseType,
PFNVDSCRIPTASREAD pfnRead, PFNVDSCRIPTASWRITE pfnWrite, void *pvUser,
uint32_t fFlags);
#endif /* !VBOX_INCLUDED_SRC_testcase_VDScript_h */
|
