HGSMI.h revision e64031e20c39650a7bc902a3e1aba613b9415dee
/** @file
*
* VBox Host Guest Shared Memory Interface (HGSMI).
*/
/*
* Copyright (C) 2006-2008 Oracle Corporation
*
* 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 (GPL) 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.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#ifndef __HGSMI_h__
#define __HGSMI_h__
/* HGSMI uses 32 bit offsets and sizes. */
typedef uint32_t HGSMIOFFSET;
#define HGSMIOFFSET_VOID ((HGSMIOFFSET)~0)
/*
* Basic mechanism for the HGSMI is to prepare and pass data buffer to the host and the guest.
* Data inside these buffers are opaque for the HGSMI and are interpreted by higher levels.
*
*
* HGSMIBUFFERHEADER header;
* uint8_t data[header.u32BufferSize];
* HGSMIBUFFERTAIL tail;
*
* Note: Offset of the 'header' in the memory is used for virtual hardware IO.
*
* Buffers are verifyed using the offset and the content of the header and the tail,
* which are constant during a call.
*
* Invalid buffers are ignored.
*
* Actual 'data' is not verifyed, as it is expected that the data can be changed by the
* called function.
*
* Since only the offset of the buffer is passed in a IO operation, the header and tail
* must contain:
* * size of data in this buffer;
* * checksum for buffer verification.
*
* For segmented transfers:
* * the sequence identifier;
* * offset of the current segment in the sequence;
* * total bytes in the transfer.
*
* Additionally contains:
* * the channel ID;
* * the channel information.
*/
/* Describes a shared memory area buffer.
* Used for calculations with offsets and for buffers verification.
*/
typedef struct _HGSMIAREA
{
* offBase + cbArea - 1 - (sizeof (header) + sizeof (tail)).
*/
} HGSMIAREA;
/* The buffer description flags. */
#pragma pack(1)
/* 16 bytes buffer header. */
typedef struct _HGSMIBUFFERHEADER
{
union {
struct
{ /* HGSMI_BUFFER_HEADER_F_SEQ_SINGLE */
} Buffer;
struct
{ /* HGSMI_BUFFER_HEADER_F_SEQ_START */
struct
{ /* HGSMI_BUFFER_HEADER_F_SEQ_CONTINUE and HGSMI_BUFFER_HEADER_F_SEQ_END */
} u;
/* 8 bytes buffer tail. */
typedef struct _HGSMIBUFFERTAIL
{
uint32_t u32Checksum; /* Verifyer for the buffer header and offset and for first 4 bytes of the tail. */
#pragma pack()
#pragma pack(1)
typedef struct _HGSMIHEAP
{
union
{
} u;
int cRefs; /**< Number of heap allocations. */
bool fOffsetBased; /**< Set if offset based. */
} HGSMIHEAP;
#pragma pack()
#pragma pack(1)
/* The size of the array of channels. Array indexes are uint8_t. Note: the value must not be changed. */
#define HGSMI_NUMBER_OF_CHANNELS 0x100
/* Channel handler called when the guest submits a buffer. */
typedef DECLCALLBACK(int) FNHGSMICHANNELHANDLER(void *pvHandler, uint16_t u16ChannelInfo, void *pvBuffer, HGSMISIZE cbBuffer);
typedef FNHGSMICHANNELHANDLER *PFNHGSMICHANNELHANDLER;
/* Information about a handler: pfn + context. */
typedef struct _HGSMICHANNELHANDLER
{
void *pvHandler;
/* Channel description. */
typedef struct _HGSMICHANNEL
{
const char *pszName; /* NULL for hardcoded channels or RTStrDup'ed name. */
} HGSMICHANNEL;
typedef struct _HGSMICHANNELINFO
{
* The array is accessed under the instance lock.
*/
#pragma pack()
{
return sizeof (HGSMIBUFFERHEADER) + sizeof (HGSMIBUFFERTAIL);
}
{
}
{
}
{
}
{
return HGSMIBufferMinimumSize () + u32DataSize;
}
const HGSMIBUFFERHEADER *pHeader)
{
}
{
}
{
if(pHeader)
return HGSMIBufferData(pHeader);
return NULL;
}
const HGSMIBUFFERHEADER *pHeader,
const HGSMIBUFFERTAIL *pTail);
void *pvBase,
{
}
void *pvBase,
bool fOffsetBased);
void *pvBase,
bool fOffsetBased);
void *pvData);
void *pvData);
{
}
/* needed for heap relocation */
{
}
{
}
const char *pszName,
void *pvChannelHandler,
#endif /* __HGSMI_h__*/