VBoxGuestLib.h revision 616637905fa2f00febb1acd553136d7e56316f7c
/** @file
* VBoxGuestLib - Support library header for VirtualBox
* Additions: Public header.
*/
/*
* Copyright (C) 2006-2007 innotek GmbH
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License as published by the Free Software Foundation,
* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
* distribution. VirtualBox OSE is distributed in the hope that it will
* be useful, but WITHOUT ANY WARRANTY of any kind.
*
* If you received this file as part of a commercial VirtualBox
* distribution, then only the terms of your commercial VirtualBox
* license agreement apply instead of the previous paragraph.
*/
#ifndef ___VBox_VBoxGuestLib_h
#define ___VBox_VBoxGuestLib_h
#include <VBox/VBoxGuest.h>
#ifndef IN_RING0
#endif
/** @defgroup grp_guest_lib VirtualBox Guest Library
* @{
*/
/** @page pg_guest_lib VirtualBox Guest Library
*
* The library has 2 versions for each platform:
* 1) for VBoxGuest main driver, who is responsible for managing the VMMDev virtual hardware;
* 2) for other guest drivers.
*
* Library therefore consists of:
* common code to be used by both VBoxGuest and other drivers;
* VBoxGuest specific code;
* code for other drivers which communicate with VBoxGuest via an IOCTL.
*
* The library sources produce 2 libs VBoxGuestLib and VBoxGuestLibBase,
* the latter one is for VBoxGuest.
*
* Drivers must choose right library in their makefiles.
*
* Library source code and the header have a define VBGL_VBOXGUEST,
* which is defined for VBoxGuest and undefined for other drivers.
*
*/
typedef uint32_t VBGLIOPORT;
#ifdef VBGL_VBOXGUEST
/**
* The library initialization function to be used by the main
* VBoxGuest system driver.
*
* @return VBox status code.
*/
#else
/**
* The library initialization function to be used by all drivers
* other than the main VBoxGuest system driver.
*
* @return VBox status code.
*/
#endif
/**
* The library termination function.
*/
DECLVBGL(void) VbglTerminate (void);
/** @name Generic request functions.
* @{
*/
/**
* Allocate memory for generic request and initialize the request header.
*
* @param ppReq pointer to resulting memory address.
* @param cbSize size of memory block required for the request.
* @param reqType the generic request type.
*
* @return VBox status code.
*/
DECLVBGL(int) VbglGRAlloc (VMMDevRequestHeader **ppReq, uint32_t cbSize, VMMDevRequestType reqType);
/**
* Perform the generic request.
*
* @param pReq pointer the request structure.
*
* @return VBox status code.
*/
/**
* Free the generic request memory.
*
* @param pReq pointer the request structure.
*
* @return VBox status code.
*/
/** @} */
#ifdef VBOX_HGCM
#ifdef VBGL_VBOXGUEST
/**
* Callback function called from HGCM helpers when a wait for request
* completion IRQ is required.
*
* @param pvData VBoxGuest pointer to be passed to callback.
* @param u32Data VBoxGuest 32 bit value to be passed to callback.
*/
typedef DECLVBGL(void) VBGLHGCMCALLBACK(VMMDevHGCMRequestHeader *pHeader, void *pvData, uint32_t u32Data);
/**
* Perform a connect request. That is locate required service and
* obtain a client identifier for future access.
*
* @param pConnectInfo The request data.
* @param pAsyncCallback Required pointer to function that is called when
* host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
* implements waiting for an IRQ in this function.
* @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
* @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
*
* @return VBox status code.
*/
/**
* Perform a disconnect request. That is tell the host that
* the client will not call the service anymore.
*
* @param pDisconnectInfo The request data.
* @param pAsyncCallback Required pointer to function that is called when
* host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
* implements waiting for an IRQ in this function.
* @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
* @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
*
* @return VBox status code.
*/
/* Call a HGCM service.
*
* @param pCallInfo The request data.
* @param pAsyncCallback Required pointer to function that is called when
* host returns VINF_HGCM_ASYNC_EXECUTE. VBoxGuest
* implements waiting for an IRQ in this function.
* @param pvAsyncData An arbitrary VBoxGuest pointer to be passed to callback.
* @param u32AsyncData An arbitrary VBoxGuest 32 bit value to be passed to callback.
*
* @return VBox status code.
*/
#else /* !VBGL_VBOXGUEST */
struct VBGLHGCMHANDLEDATA;
typedef struct VBGLHGCMHANDLEDATA *VBGLHGCMHANDLE;
/** @name HGCM functions
* @{
*/
/**
* Connect to a service.
*
* @param pHandle Pointer to variable that will hold a handle to be used
* further in VbglHGCMCall and VbglHGCMClose.
* @param pData Connection information structure.
*
* @return VBox status code.
*/
/**
* Connect to a service.
*
* @param handle Handle of the connection.
* @param pData Disconnect request information structure.
*
* @return VBox status code.
*/
/**
* Call to a service.
*
* @param handle Handle of the connection.
* @param pData Call request information structure, including function parameters.
* @param cbData Length in bytes of data.
*
* @return VBox status code.
*/
/** @} */
#endif /* !VBGL_VBOXGUEST */
#endif /* VBOX_HGCM */
/**
* Initialize the heap.
*
* @return VBox error code.
*/
DECLVBGL(int) VbglPhysHeapInit (void);
/**
* Shutdown the heap.
*/
DECLVBGL(void) VbglPhysHeapTerminate (void);
/**
* Allocate a memory block.
*
* @param cbSize Size of block to be allocated.
* @return Virtual address of allocated memory block.
*/
/**
* Get physical address of memory block pointed by
* the virtual address.
*
* @note WARNING!
* The function does not acquire the Heap mutex!
* When calling the function make sure that
* the pointer is a valid one and is not being
* deallocated.
* This function can NOT be used for verifying
* if the given pointer is a valid one allocated
* from the heap.
*
*
* @param p Virtual address of memory block.
* @return Physical memory block.
*/
/**
* Free a memory block.
*
* @param p Virtual address of memory block.
*/
DECLVBGL(void) VbglPhysHeapFree (void *p);
/** @} */
#endif /* __VBox_VBoxGuestLib_h__ */