summaryrefslogtreecommitdiffstats
path: root/src/VBox/Storage/testcase/VDScript.h
blob: 6c9507ba9b3da7318a418b90d1c7a0a28417c902 (plain)
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
236
/** @file
 *
 * VBox HDD container test utility - scripting engine.
 */

/*
 * Copyright (C) 2013-2022 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.
 *
 * @returns nothing.
 * @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 */