[1] | 1 | /** @file
|
---|
| 2 | * VBoxGuestLib - Support library header for VirtualBox
|
---|
| 3 | * Additions: Public header.
|
---|
| 4 | */
|
---|
| 5 |
|
---|
| 6 | /*
|
---|
[8155] | 7 | * Copyright (C) 2006-2007 Sun Microsystems, Inc.
|
---|
[1] | 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
|
---|
[5999] | 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.
|
---|
[8155] | 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.
|
---|
[1] | 29 | */
|
---|
| 30 |
|
---|
[3632] | 31 | #ifndef ___VBox_VBoxGuestLib_h
|
---|
| 32 | #define ___VBox_VBoxGuestLib_h
|
---|
[1] | 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 |
|
---|
| 69 | typedef 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 | */
|
---|
| 81 | DECLVBGL(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 | */
|
---|
| 91 | DECLVBGL(int) VbglInit (void);
|
---|
| 92 |
|
---|
| 93 | #endif
|
---|
| 94 |
|
---|
| 95 | /**
|
---|
| 96 | * The library termination function.
|
---|
| 97 | */
|
---|
| 98 | DECLVBGL(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 | */
|
---|
| 113 | DECLVBGL(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 | */
|
---|
| 122 | DECLVBGL(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 | */
|
---|
| 131 | DECLVBGL(void) VbglGRFree (VMMDevRequestHeader *pReq);
|
---|
| 132 | /** @} */
|
---|
| 133 |
|
---|
| 134 | #ifdef VBOX_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 |
|
---|
| 146 | typedef 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 | * @param pConnectInfo The request data.
|
---|
| 153 | * @param pAsyncCallback Required pointer to function that is called when
|
---|
| 154 | * host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
|
---|
| 155 | * implements waiting for an IRQ in this function.
|
---|
| 156 | * @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
|
---|
| 157 | * @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
|
---|
| 158 | *
|
---|
| 159 | * @return VBox status code.
|
---|
| 160 | */
|
---|
| 161 |
|
---|
| 162 | DECLVBGL(int) VbglHGCMConnect (VBoxGuestHGCMConnectInfo *pConnectInfo,
|
---|
[3193] | 163 | VBGLHGCMCALLBACK *pAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
|
---|
[1] | 164 |
|
---|
| 165 |
|
---|
| 166 | /**
|
---|
| 167 | * Perform a disconnect request. That is tell the host that
|
---|
| 168 | * the client will not call the service anymore.
|
---|
| 169 | *
|
---|
| 170 | * @param pDisconnectInfo The request data.
|
---|
| 171 | * @param pAsyncCallback Required pointer to function that is called when
|
---|
| 172 | * host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
|
---|
| 173 | * implements waiting for an IRQ in this function.
|
---|
| 174 | * @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
|
---|
| 175 | * @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
|
---|
| 176 | *
|
---|
| 177 | * @return VBox status code.
|
---|
| 178 | */
|
---|
| 179 |
|
---|
| 180 | DECLVBGL(int) VbglHGCMDisconnect (VBoxGuestHGCMDisconnectInfo *pDisconnectInfo,
|
---|
[3193] | 181 | VBGLHGCMCALLBACK *pAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
|
---|
[1] | 182 |
|
---|
| 183 | /* Call a HGCM service.
|
---|
| 184 | *
|
---|
| 185 | * @param pCallInfo The request data.
|
---|
| 186 | * @param pAsyncCallback Required pointer to function that is called when
|
---|
| 187 | * host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
|
---|
| 188 | * implements waiting for an IRQ in this function.
|
---|
| 189 | * @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
|
---|
| 190 | * @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
|
---|
| 191 | *
|
---|
| 192 | * @return VBox status code.
|
---|
| 193 | */
|
---|
| 194 | DECLVBGL(int) VbglHGCMCall (VBoxGuestHGCMCallInfo *pCallInfo,
|
---|
[3193] | 195 | VBGLHGCMCALLBACK *pAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
|
---|
[1] | 196 |
|
---|
[3193] | 197 | #else /* !VBGL_VBOXGUEST */
|
---|
[1] | 198 |
|
---|
| 199 | struct VBGLHGCMHANDLEDATA;
|
---|
| 200 | typedef struct VBGLHGCMHANDLEDATA *VBGLHGCMHANDLE;
|
---|
| 201 |
|
---|
| 202 | /** @name HGCM functions
|
---|
| 203 | * @{
|
---|
| 204 | */
|
---|
| 205 |
|
---|
| 206 | /**
|
---|
| 207 | * Connect to a service.
|
---|
| 208 | *
|
---|
| 209 | * @param pHandle Pointer to variable that will hold a handle to be used
|
---|
| 210 | * further in VbglHGCMCall and VbglHGCMClose.
|
---|
| 211 | * @param pData Connection information structure.
|
---|
| 212 | *
|
---|
| 213 | * @return VBox status code.
|
---|
| 214 | */
|
---|
| 215 | DECLVBGL(int) VbglHGCMConnect (VBGLHGCMHANDLE *pHandle, VBoxGuestHGCMConnectInfo *pData);
|
---|
| 216 |
|
---|
| 217 | /**
|
---|
| 218 | * Connect to a service.
|
---|
| 219 | *
|
---|
| 220 | * @param handle Handle of the connection.
|
---|
| 221 | * @param pData Disconnect request information structure.
|
---|
| 222 | *
|
---|
| 223 | * @return VBox status code.
|
---|
| 224 | */
|
---|
| 225 | DECLVBGL(int) VbglHGCMDisconnect (VBGLHGCMHANDLE handle, VBoxGuestHGCMDisconnectInfo *pData);
|
---|
| 226 |
|
---|
| 227 | /**
|
---|
| 228 | * Call to a service.
|
---|
| 229 | *
|
---|
| 230 | * @param handle Handle of the connection.
|
---|
| 231 | * @param pData Call request information structure, including function parameters.
|
---|
| 232 | * @param cbData Length in bytes of data.
|
---|
| 233 | *
|
---|
| 234 | * @return VBox status code.
|
---|
| 235 | */
|
---|
| 236 | DECLVBGL(int) VbglHGCMCall (VBGLHGCMHANDLE handle, VBoxGuestHGCMCallInfo *pData, uint32_t cbData);
|
---|
| 237 | /** @} */
|
---|
| 238 |
|
---|
[3193] | 239 | #endif /* !VBGL_VBOXGUEST */
|
---|
[1] | 240 |
|
---|
| 241 | #endif /* VBOX_HGCM */
|
---|
| 242 |
|
---|
| 243 |
|
---|
| 244 | /**
|
---|
| 245 | * Initialize the heap.
|
---|
| 246 | *
|
---|
| 247 | * @return VBox error code.
|
---|
| 248 | */
|
---|
| 249 | DECLVBGL(int) VbglPhysHeapInit (void);
|
---|
| 250 |
|
---|
| 251 | /**
|
---|
| 252 | * Shutdown the heap.
|
---|
| 253 | */
|
---|
| 254 | DECLVBGL(void) VbglPhysHeapTerminate (void);
|
---|
| 255 |
|
---|
| 256 |
|
---|
| 257 | /**
|
---|
| 258 | * Allocate a memory block.
|
---|
| 259 | *
|
---|
| 260 | * @param cbSize Size of block to be allocated.
|
---|
| 261 | * @return Virtual address of allocated memory block.
|
---|
| 262 | */
|
---|
| 263 | DECLVBGL(void *) VbglPhysHeapAlloc (uint32_t cbSize);
|
---|
| 264 |
|
---|
| 265 | /**
|
---|
| 266 | * Get physical address of memory block pointed by
|
---|
| 267 | * the virtual address.
|
---|
| 268 | *
|
---|
| 269 | * @note WARNING!
|
---|
| 270 | * The function does not acquire the Heap mutex!
|
---|
| 271 | * When calling the function make sure that
|
---|
| 272 | * the pointer is a valid one and is not being
|
---|
| 273 | * deallocated.
|
---|
| 274 | * This function can NOT be used for verifying
|
---|
| 275 | * if the given pointer is a valid one allocated
|
---|
| 276 | * from the heap.
|
---|
| 277 | *
|
---|
| 278 | *
|
---|
| 279 | * @param p Virtual address of memory block.
|
---|
| 280 | * @return Physical memory block.
|
---|
| 281 | */
|
---|
| 282 | DECLVBGL(RTCCPHYS) VbglPhysHeapGetPhysAddr (void *p);
|
---|
| 283 |
|
---|
| 284 | /**
|
---|
| 285 | * Free a memory block.
|
---|
| 286 | *
|
---|
| 287 | * @param p Virtual address of memory block.
|
---|
| 288 | */
|
---|
| 289 | DECLVBGL(void) VbglPhysHeapFree (void *p);
|
---|
| 290 |
|
---|
| 291 | DECLVBGL(int) VbglQueryVMMDevMemory (VMMDevMemory **ppVMMDevMemory);
|
---|
| 292 |
|
---|
| 293 | __END_DECLS
|
---|
| 294 |
|
---|
| 295 | /** @} */
|
---|
| 296 |
|
---|
[3633] | 297 | #endif
|
---|