VBoxGuestLib.h revision 32ad75b4af91dad97e4f6c0b1d9f2fd63d173f19
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * VBoxGuestLib - Support library header for VirtualBox
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Additions: Public header.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * available from http://www.virtualbox.org. This file is free software;
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * you can redistribute it and/or modify it under the terms of the GNU
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * General Public License (GPL) as published by the Free Software
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * The contents of this file may alternatively be used under the terms
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * of the Common Development and Distribution License Version 1.0
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * VirtualBox OSE distribution, in which case the provisions of the
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * CDDL are applicable instead of those of the GPL.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * You may elect to license modified versions of this file under the
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * terms and conditions of either the GPL or the CDDL or both.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * additional information or have any questions.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync/** @defgroup grp_guest_lib VirtualBox Guest Library
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync/** @page pg_guest_lib VirtualBox Guest Library
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * The library has 2 versions for each platform:
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * 1) for VBoxGuest main driver, who is responsible for managing the VMMDev virtual hardware;
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * 2) for other guest drivers.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Library therefore consists of:
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * common code to be used by both VBoxGuest and other drivers;
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * VBoxGuest specific code;
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * code for other drivers which communicate with VBoxGuest via an IOCTL.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * The library sources produce 2 libs VBoxGuestLib and VBoxGuestLibBase,
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * the latter one is for VBoxGuest.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Drivers must choose right library in their makefiles.
ba8a6598ceebe446c0b9e720f14e6eaeb76bd38avboxsync * Library source code and the header have a define VBGL_VBOXGUEST,
ba8a6598ceebe446c0b9e720f14e6eaeb76bd38avboxsync * which is defined for VBoxGuest and undefined for other drivers.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * The library initialization function to be used by the main
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * VBoxGuest system driver.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @return VBox status code.
ba8a6598ceebe446c0b9e720f14e6eaeb76bd38avboxsyncDECLVBGL(int) VbglInit (VBGLIOPORT portVMMDev, VMMDevMemory *pVMMDevMemory);
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * The library initialization function to be used by all drivers
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * other than the main VBoxGuest system driver.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @return VBox status code.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * The library termination function.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync/** @name Generic request functions.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Allocate memory for generic request and initialize the request header.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param ppReq pointer to resulting memory address.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param cbSize size of memory block required for the request.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param reqType the generic request type.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @return VBox status code.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsyncDECLVBGL(int) VbglGRAlloc (VMMDevRequestHeader **ppReq, uint32_t cbSize, VMMDevRequestType reqType);
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Perform the generic request.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pReq pointer the request structure.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @return VBox status code.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsyncDECLVBGL(int) VbglGRPerform (VMMDevRequestHeader *pReq);
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Free the generic request memory.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pReq pointer the request structure.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @return VBox status code.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsyncDECLVBGL(void) VbglGRFree (VMMDevRequestHeader *pReq);
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Callback function called from HGCM helpers when a wait for request
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * completion IRQ is required.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pvData VBoxGuest pointer to be passed to callback.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param u32Data VBoxGuest 32 bit value to be passed to callback.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsynctypedef DECLVBGL(void) VBGLHGCMCALLBACK(VMMDevHGCMRequestHeader *pHeader, void *pvData, uint32_t u32Data);
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Perform a connect request. That is locate required service and
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * obtain a client identifier for future access.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @note This function can NOT handle cancelled requests!
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pConnectInfo The request data.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pAsyncCallback Required pointer to function that is called when
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * implements waiting for an IRQ in this function.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
f6ad329825844da40e1a060321d503554cce7b12vboxsync * @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @return VBox status code.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsyncDECLVBGL(int) VbglHGCMConnect (VBoxGuestHGCMConnectInfo *pConnectInfo,
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync VBGLHGCMCALLBACK *pAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Perform a disconnect request. That is tell the host that
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * the client will not call the service anymore.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @note This function can NOT handle cancelled requests!
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pDisconnectInfo The request data.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pAsyncCallback Required pointer to function that is called when
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * implements waiting for an IRQ in this function.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @return VBox status code.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsyncDECLVBGL(int) VbglHGCMDisconnect (VBoxGuestHGCMDisconnectInfo *pDisconnectInfo,
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync VBGLHGCMCALLBACK *pAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync/** Call a HGCM service.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @note This function can deal with cancelled requests.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pCallInfo The request data.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pAsyncCallback Required pointer to function that is called when
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * implements waiting for an IRQ in this function.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @return VBox status code.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsyncDECLVBGL(int) VbglHGCMCall (VBoxGuestHGCMCallInfo *pCallInfo,
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync VBGLHGCMCALLBACK *pAsyncCallback, void *pvAsyncData, uint32_t u32AsyncData);
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync#else /* !VBGL_VBOXGUEST */
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync/** @name HGCM functions
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Connect to a service.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pHandle Pointer to variable that will hold a handle to be used
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * further in VbglHGCMCall and VbglHGCMClose.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param pData Connection information structure.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @return VBox status code.
f6ad329825844da40e1a060321d503554cce7b12vboxsyncDECLVBGL(int) VbglHGCMConnect (VBGLHGCMHANDLE *pHandle, VBoxGuestHGCMConnectInfo *pData);
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * Connect to a service.
0368e9c310393e82ef37c480b6acbd0f107cf0edvboxsync * @param handle Handle of the connection.