HGSMI.h revision 6a97c5c107ea1c9935054f25a4fb5ca59a214b72
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync * VBox Host Guest Shared Memory Interface (HGSMI).
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync * Host/Guest shared part.
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync * Copyright (C) 2006-2008 Sun Microsystems, Inc.
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync * Sun Microsystems, Inc. confidential
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync * All rights reserved
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync/* HGSMI uses 32 bit offsets and sizes. */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync * Basic mechanism for the HGSMI is to prepare and pass data buffer to the host and the guest.
ee4d840f54fd2dcea8a73b1b86d5ec0db370b05dvboxsync * Data inside these buffers are opaque for the HGSMI and are interpreted by higher levels.
ee4d840f54fd2dcea8a73b1b86d5ec0db370b05dvboxsync * Every shared memory buffer passed between the guest/host has the following structure:
5dcae142d05d0d6307e097f026b53a048b8ef949vboxsync * HGSMIBUFFERHEADER header;
e554e8c589d84d4df49504e096f81dfa48c2a06evboxsync * uint8_t data[header.u32BufferSize];
0deaf9b7b14fd7b44a999419acd224f002a2b13bvboxsync * HGSMIBUFFERTAIL tail;
0deaf9b7b14fd7b44a999419acd224f002a2b13bvboxsync * Note: Offset of the 'header' in the memory is used for virtual hardware IO.
0deaf9b7b14fd7b44a999419acd224f002a2b13bvboxsync * Buffers are verifyed using the offset and the content of the header and the tail,
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync * which are constant during a call.
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync * Invalid buffers are ignored.
ccc1001951ecd639b15b3034260c6012423349b3vboxsync * Actual 'data' is not verifyed, as it is expected that the data can be changed by the
ccc1001951ecd639b15b3034260c6012423349b3vboxsync * called function.
ccc1001951ecd639b15b3034260c6012423349b3vboxsync * Since only the offset of the buffer is passed in a IO operation, the header and tail
ccc1001951ecd639b15b3034260c6012423349b3vboxsync * must contain:
4a61dadcdd5fbace94426335d7a985ff31936a2cvboxsync * * size of data in this buffer;
fb34b57e69a76bea498e3a3b9adebe1d526d7f78vboxsync * * checksum for buffer verification.
6a713fdf2e42488a1179d8c5a9d9cc62e484b1f0vboxsync * For segmented transfers:
4a61dadcdd5fbace94426335d7a985ff31936a2cvboxsync * * the sequence identifier;
4a61dadcdd5fbace94426335d7a985ff31936a2cvboxsync * * offset of the current segment in the sequence;
4a61dadcdd5fbace94426335d7a985ff31936a2cvboxsync * * total bytes in the transfer.
4a61dadcdd5fbace94426335d7a985ff31936a2cvboxsync * Additionally contains:
6a713fdf2e42488a1179d8c5a9d9cc62e484b1f0vboxsync * * the channel ID;
6a713fdf2e42488a1179d8c5a9d9cc62e484b1f0vboxsync * * the channel information.
6a713fdf2e42488a1179d8c5a9d9cc62e484b1f0vboxsync/* Describes a shared memory area buffer.
4a61dadcdd5fbace94426335d7a985ff31936a2cvboxsync * Used for calculations with offsets and for buffers verification.
6a713fdf2e42488a1179d8c5a9d9cc62e484b1f0vboxsynctypedef struct _HGSMIAREA
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync uint8_t *pu8Base; /* The starting address of the area. Corresponds to offset 'offBase'. */
f5e53763b0a581b0299e98028c6c52192eb06785vboxsync HGSMIOFFSET offBase; /* The starting offset of the area. */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync * offBase + cbArea - 1 - (sizeof (header) + sizeof (tail)).
d3144b8e0e6d348fc2d93462fcb0a3df2d373d36vboxsync/* The buffer description flags. */
d3144b8e0e6d348fc2d93462fcb0a3df2d373d36vboxsync#define HGSMI_BUFFER_HEADER_F_SEQ_MASK 0x03 /* Buffer sequence type mask. */
d3144b8e0e6d348fc2d93462fcb0a3df2d373d36vboxsync#define HGSMI_BUFFER_HEADER_F_SEQ_SINGLE 0x00 /* Single buffer, not a part of a sequence. */
d3144b8e0e6d348fc2d93462fcb0a3df2d373d36vboxsync#define HGSMI_BUFFER_HEADER_F_SEQ_START 0x01 /* The first buffer in a sequence. */
d3144b8e0e6d348fc2d93462fcb0a3df2d373d36vboxsync#define HGSMI_BUFFER_HEADER_F_SEQ_CONTINUE 0x02 /* A middle buffer in a sequence. */
d3144b8e0e6d348fc2d93462fcb0a3df2d373d36vboxsync#define HGSMI_BUFFER_HEADER_F_SEQ_END 0x03 /* The last buffer in a sequence. */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync/* 16 bytes buffer header. */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync uint32_t u32DataSize; /* Size of data that follows the header. */
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync uint8_t u8Flags; /* The buffer description: HGSMI_BUFFER_HEADER_F_* */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync uint8_t u8Channel; /* The channel the data must be routed to. */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync uint16_t u16ChannelInfo; /* Opaque to the HGSMI, used by the channel. */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync uint8_t au8Union[8]; /* Opaque placeholder to make the union 8 bytes. */
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync { /* HGSMI_BUFFER_HEADER_F_SEQ_SINGLE */
e554e8c589d84d4df49504e096f81dfa48c2a06evboxsync uint32_t u32Reserved1; /* A reserved field, initialize to 0. */
9f9f83ee5948916d644046a79836873db40bfc88vboxsync uint32_t u32Reserved2; /* A reserved field, initialize to 0. */
4a61dadcdd5fbace94426335d7a985ff31936a2cvboxsync { /* HGSMI_BUFFER_HEADER_F_SEQ_START */
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync uint32_t u32SequenceNumber; /* The sequence number, the same for all buffers in the sequence. */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync uint32_t u32SequenceSize; /* The total size of the sequence. */
e554e8c589d84d4df49504e096f81dfa48c2a06evboxsync { /* HGSMI_BUFFER_HEADER_F_SEQ_CONTINUE and HGSMI_BUFFER_HEADER_F_SEQ_END */
5dcae142d05d0d6307e097f026b53a048b8ef949vboxsync uint32_t u32SequenceNumber; /* The sequence number, the same for all buffers in the sequence. */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync uint32_t u32SequenceOffset; /* Data offset in the entire sequence. */
d3144b8e0e6d348fc2d93462fcb0a3df2d373d36vboxsync/* 8 bytes buffer tail. */
e554e8c589d84d4df49504e096f81dfa48c2a06evboxsync uint32_t u32Reserved; /* Reserved, must be initialized to 0. */
e554e8c589d84d4df49504e096f81dfa48c2a06evboxsync uint32_t u32Checksum; /* Verifyer for the buffer header and offset and for first 4 bytes of the tail. */
e554e8c589d84d4df49504e096f81dfa48c2a06evboxsynctypedef struct _HGSMIHEAP
9f9f83ee5948916d644046a79836873db40bfc88vboxsync/* The size of the array of channels. Array indexes are uint8_t. Note: the value must not be changed. */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync/* Channel handler called when the guest submits a buffer. */
4e12eda9a6e918332bb14827546097d878ef8a2dvboxsynctypedef DECLCALLBACK(int) FNHGSMICHANNELHANDLER(void *pvHandler, uint16_t u16ChannelInfo, void *pvBuffer, HGSMISIZE cbBuffer);
4e12eda9a6e918332bb14827546097d878ef8a2dvboxsynctypedef FNHGSMICHANNELHANDLER *PFNHGSMICHANNELHANDLER;
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync/* Information about a handler: pfn + context. */
1f72a47e266d9b7498b6a06aacf53a23ff874bc2vboxsync/* Channel description. */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync HGSMICHANNELHANDLER handler; /* The channel handler. */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync const char *pszName; /* NULL for hardcoded channels or RTStrDup'ed name. */
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync uint8_t u8Channel; /* The channel id, equal to the channel index in the array. */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync HGSMICHANNEL Channels[HGSMI_NUMBER_OF_CHANNELS]; /* Channel handlers indexed by the channel id.
ee4d840f54fd2dcea8a73b1b86d5ec0db370b05dvboxsync * The array is accessed under the instance lock.
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync return sizeof (HGSMIBUFFERHEADER) + sizeof (HGSMIBUFFERTAIL);
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsyncDECLINLINE(uint8_t *) HGSMIBufferData (const HGSMIBUFFERHEADER *pHeader)
0f1e77149ab5ab40fa2bd74a5330e087416b3c7bvboxsync return (uint8_t *)pHeader + sizeof (HGSMIBUFFERHEADER);
548ca31b6b47c36bacce49bed3339cb8075b9681vboxsyncDECLINLINE(HGSMIBUFFERTAIL *) HGSMIBufferTail (const HGSMIBUFFERHEADER *pHeader)
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync return (HGSMIBUFFERTAIL *)(HGSMIBufferData (pHeader) + pHeader->u32DataSize);
4e12eda9a6e918332bb14827546097d878ef8a2dvboxsyncDECLINLINE(HGSMIBUFFERHEADER *) HGSMIBufferHeaderFromData (const void *pvData)
4e12eda9a6e918332bb14827546097d878ef8a2dvboxsync return (HGSMIBUFFERHEADER *)((uint8_t *)pvData - sizeof (HGSMIBUFFERHEADER));
4e12eda9a6e918332bb14827546097d878ef8a2dvboxsyncDECLINLINE(HGSMISIZE) HGSMIBufferRequiredSize (uint32_t u32DataSize)
99195a756879b8f6a7810e5b06ea505d766d3651vboxsyncDECLINLINE(HGSMIOFFSET) HGSMIPointerToOffset (const HGSMIAREA *pArea,
cb130fe54ffed3568729e3546b9aa73190e1c1advboxsync return pArea->offBase + (HGSMIOFFSET)((uint8_t *)pHeader - pArea->pu8Base);
4e12eda9a6e918332bb14827546097d878ef8a2dvboxsyncDECLINLINE(HGSMIBUFFERHEADER *) HGSMIOffsetToPointer (const HGSMIAREA *pArea,
4e12eda9a6e918332bb14827546097d878ef8a2dvboxsync return (HGSMIBUFFERHEADER *)(pArea->pu8Base + (offBuffer - pArea->offBase));
4e12eda9a6e918332bb14827546097d878ef8a2dvboxsyncDECLINLINE(uint8_t *) HGSMIBufferDataFromOffset (const HGSMIAREA *pArea, HGSMIOFFSET offBuffer)
4e12eda9a6e918332bb14827546097d878ef8a2dvboxsync HGSMIBUFFERHEADER *pHeader = HGSMIOffsetToPointer (pArea, offBuffer);
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsyncHGSMICHANNEL *HGSMIChannelFindById (HGSMICHANNELINFO * pChannelInfo, uint8_t u8Channel);
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsyncHGSMIOFFSET HGSMIBufferInitializeSingle (const HGSMIAREA *pArea,
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsyncHGSMIOFFSET HGSMIHeapBufferOffset (HGSMIHEAP *pHeap,
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsyncDECLINLINE(HGSMIOFFSET) HGSMIHeapOffset(HGSMIHEAP *pHeap)
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync/* needed for heap relocation */
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsyncDECLINLINE(HGSMIOFFSET) HGSMIHeapHandleLocationOffset(HGSMIHEAP *pHeap)
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync return pHeap->heap != NIL_RTHEAPSIMPLE ? (uint32_t)(pHeap->area.pu8Base - (uint8_t*)pHeap->heap) : HGSMIOFFSET_VOID;
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsyncDECLINLINE(HGSMISIZE) HGSMIHeapSize(HGSMIHEAP *pHeap)
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsyncint HGSMIChannelRegister (HGSMICHANNELINFO * pChannelInfo,
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync const char *pszName,
a2e6357e0295f680b36aaf31bedd6409a5336165vboxsync#endif /* __HGSMI_h__*/