VirtualBox

source: vbox/trunk/include/VBox/VBoxGuestLib.h@ 17537

Last change on this file since 17537 was 15704, checked in by vboxsync, 16 years ago

Introduced VbglHCGMCall32 for supporting 32 bits clients on 64 bits guests.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 9.9 KB
Line 
1/** @file
2 * VBoxGuestLib - Support library header for VirtualBox
3 * Additions: Public header.
4 */
5
6/*
7 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 *
26 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
27 * Clara, CA 95054 USA or visit http://www.sun.com if you need
28 * additional information or have any questions.
29 */
30
31#ifndef ___VBox_VBoxGuestLib_h
32#define ___VBox_VBoxGuestLib_h
33
34#include <VBox/VBoxGuest.h>
35
36#include <VBox/err.h>
37
38#ifndef IN_RING0
39#error VBoxGuestLib is only suitable for ring-0!
40#endif
41
42/** @defgroup grp_guest_lib VirtualBox Guest Library
43 * @{
44 */
45
46/** @page pg_guest_lib VirtualBox Guest Library
47 *
48 * The library has 2 versions for each platform:
49 * 1) for VBoxGuest main driver, who is responsible for managing the VMMDev virtual hardware;
50 * 2) for other guest drivers.
51 *
52 * Library therefore consists of:
53 * common code to be used by both VBoxGuest and other drivers;
54 * VBoxGuest specific code;
55 * code for other drivers which communicate with VBoxGuest via an IOCTL.
56 *
57 * The library sources produce 2 libs VBoxGuestLib and VBoxGuestLibBase,
58 * the latter one is for VBoxGuest.
59 *
60 * Drivers must choose right library in their makefiles.
61 *
62 * Library source code and the header have a define VBGL_VBOXGUEST,
63 * which is defined for VBoxGuest and undefined for other drivers.
64 *
65 */
66
67#define DECLVBGL(type) type VBOXCALL
68
69typedef uint32_t VBGLIOPORT;
70
71__BEGIN_DECLS
72
73#ifdef VBGL_VBOXGUEST
74
75/**
76 * The library initialization function to be used by the main
77 * VBoxGuest system driver.
78 *
79 * @return VBox status code.
80 */
81DECLVBGL(int) VbglInit (VBGLIOPORT portVMMDev, VMMDevMemory *pVMMDevMemory);
82
83#else
84
85/**
86 * The library initialization function to be used by all drivers
87 * other than the main VBoxGuest system driver.
88 *
89 * @return VBox status code.
90 */
91DECLVBGL(int) VbglInit (void);
92
93#endif
94
95/**
96 * The library termination function.
97 */
98DECLVBGL(void) VbglTerminate (void);
99
100/** @name Generic request functions.
101 * @{
102 */
103
104/**
105 * Allocate memory for generic request and initialize the request header.
106 *
107 * @param ppReq pointer to resulting memory address.
108 * @param cbSize size of memory block required for the request.
109 * @param reqType the generic request type.
110 *
111 * @return VBox status code.
112 */
113DECLVBGL(int) VbglGRAlloc (VMMDevRequestHeader **ppReq, uint32_t cbSize, VMMDevRequestType reqType);
114
115/**
116 * Perform the generic request.
117 *
118 * @param pReq pointer the request structure.
119 *
120 * @return VBox status code.
121 */
122DECLVBGL(int) VbglGRPerform (VMMDevRequestHeader *pReq);
123
124/**
125 * Free the generic request memory.
126 *
127 * @param pReq pointer the request structure.
128 *
129 * @return VBox status code.
130 */
131DECLVBGL(void) VbglGRFree (VMMDevRequestHeader *pReq);
132/** @} */
133
134#ifdef VBOX_WITH_HGCM
135
136#ifdef VBGL_VBOXGUEST
137
138/**
139 * Callback function called from HGCM helpers when a wait for request
140 * completion IRQ is required.
141 *
142 * @param pvData VBoxGuest pointer to be passed to callback.
143 * @param u32Data VBoxGuest 32 bit value to be passed to callback.
144 */
145
146typedef DECLVBGL(void) VBGLHGCMCALLBACK(VMMDevHGCMRequestHeader *pHeader, void *pvData, uint32_t u32Data);
147
148/**
149 * Perform a connect request. That is locate required service and
150 * obtain a client identifier for future access.
151 *
152 * @note This function can NOT handle cancelled requests!
153 *
154 * @param pConnectInfo The request data.
155 * @param pAsyncCallback Required pointer to function that is called when
156 * host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
157 * implements waiting for an IRQ in this function.
158 * @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
159 * @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
160 *
161 * @return VBox status code.
162 */
163
164DECLVBGL(int) VbglHGCMConnect (VBoxGuestHGCMConnectInfo *pConnectInfo,
165 VBGLHGCMCALLBACK *pAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
166
167
168/**
169 * Perform a disconnect request. That is tell the host that
170 * the client will not call the service anymore.
171 *
172 * @note This function can NOT handle cancelled requests!
173 *
174 * @param pDisconnectInfo The request data.
175 * @param pAsyncCallback Required pointer to function that is called when
176 * host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
177 * implements waiting for an IRQ in this function.
178 * @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
179 * @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
180 *
181 * @return VBox status code.
182 */
183
184DECLVBGL(int) VbglHGCMDisconnect (VBoxGuestHGCMDisconnectInfo *pDisconnectInfo,
185 VBGLHGCMCALLBACK *pAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
186
187/** Call a HGCM service.
188 *
189 * @note This function can deal with cancelled requests.
190 *
191 * @param pCallInfo The request data.
192 * @param pAsyncCallback Required pointer to function that is called when
193 * host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
194 * implements waiting for an IRQ in this function.
195 * @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
196 * @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
197 *
198 * @return VBox status code.
199 */
200DECLVBGL(int) VbglHGCMCall (VBoxGuestHGCMCallInfo *pCallInfo,
201 VBGLHGCMCALLBACK *pAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
202
203/** Call a HGCM service. (32 bits packet structure in a 64 bits guest)
204 *
205 * @note This function can deal with cancelled requests.
206 *
207 * @param pCallInfo The request data.
208 * @param pAsyncCallback Required pointer to function that is called when
209 * host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
210 * implements waiting for an IRQ in this function.
211 * @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
212 * @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
213 *
214 * @return VBox status code.
215 */
216DECLVBGL(int) VbglHGCMCall32 (VBoxGuestHGCMCallInfo *pCallInfo,
217 VBGLHGCMCALLBACK *pAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
218
219#else /* !VBGL_VBOXGUEST */
220
221struct VBGLHGCMHANDLEDATA;
222typedef struct VBGLHGCMHANDLEDATA *VBGLHGCMHANDLE;
223
224/** @name HGCM functions
225 * @{
226 */
227
228/**
229 * Connect to a service.
230 *
231 * @param pHandle Pointer to variable that will hold a handle to be used
232 * further in VbglHGCMCall and VbglHGCMClose.
233 * @param pData Connection information structure.
234 *
235 * @return VBox status code.
236 */
237DECLVBGL(int) VbglHGCMConnect (VBGLHGCMHANDLE *pHandle, VBoxGuestHGCMConnectInfo *pData);
238
239/**
240 * Connect to a service.
241 *
242 * @param handle Handle of the connection.
243 * @param pData Disconnect request information structure.
244 *
245 * @return VBox status code.
246 */
247DECLVBGL(int) VbglHGCMDisconnect (VBGLHGCMHANDLE handle, VBoxGuestHGCMDisconnectInfo *pData);
248
249/**
250 * Call to a service.
251 *
252 * @param handle Handle of the connection.
253 * @param pData Call request information structure, including function parameters.
254 * @param cbData Length in bytes of data.
255 *
256 * @return VBox status code.
257 */
258DECLVBGL(int) VbglHGCMCall (VBGLHGCMHANDLE handle, VBoxGuestHGCMCallInfo *pData, uint32_t cbData);
259
260/**
261 * Call to a service with timeout.
262 *
263 * @param handle Handle of the connection.
264 * @param pData Call request information structure, including function parameters.
265 * @param cbData Length in bytes of data.
266 * @param cMillies Timeout in milliseconds. Use RT_INDEFINITE_WAIT to wait forever.
267 *
268 * @return VBox status code.
269 */
270DECLVBGL(int) VbglHGCMCallTimed (VBGLHGCMHANDLE handle,
271 VBoxGuestHGCMCallInfoTimed *pData, uint32_t cbData);
272/** @} */
273
274#endif /* !VBGL_VBOXGUEST */
275
276#endif /* VBOX_WITH_HGCM */
277
278
279/**
280 * Initialize the heap.
281 *
282 * @return VBox error code.
283 */
284DECLVBGL(int) VbglPhysHeapInit (void);
285
286/**
287 * Shutdown the heap.
288 */
289DECLVBGL(void) VbglPhysHeapTerminate (void);
290
291
292/**
293 * Allocate a memory block.
294 *
295 * @param cbSize Size of block to be allocated.
296 * @return Virtual address of allocated memory block.
297 */
298DECLVBGL(void *) VbglPhysHeapAlloc (uint32_t cbSize);
299
300/**
301 * Get physical address of memory block pointed by
302 * the virtual address.
303 *
304 * @note WARNING!
305 * The function does not acquire the Heap mutex!
306 * When calling the function make sure that
307 * the pointer is a valid one and is not being
308 * deallocated.
309 * This function can NOT be used for verifying
310 * if the given pointer is a valid one allocated
311 * from the heap.
312 *
313 *
314 * @param p Virtual address of memory block.
315 * @return Physical memory block.
316 */
317DECLVBGL(RTCCPHYS) VbglPhysHeapGetPhysAddr (void *p);
318
319/**
320 * Free a memory block.
321 *
322 * @param p Virtual address of memory block.
323 */
324DECLVBGL(void) VbglPhysHeapFree (void *p);
325
326DECLVBGL(int) VbglQueryVMMDevMemory (VMMDevMemory **ppVMMDevMemory);
327
328__END_DECLS
329
330/** @} */
331
332#endif
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette