HGSMI.h revision 6c28ed70192c3f2d1edf978697ff0ee0276bf0ee
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * VBox Host Guest Shared Memory Interface (HGSMI).
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * Host/Guest shared part.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * Copyright (C) 2006-2014 Oracle Corporation
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * available from http://www.virtualbox.org. This file is free software;
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * you can redistribute it and/or modify it under the terms of the GNU
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * General Public License (GPL) as published by the Free Software
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * The contents of this file may alternatively be used under the terms
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * of the Common Development and Distribution License Version 1.0
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * VirtualBox OSE distribution, in which case the provisions of the
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * CDDL are applicable instead of those of the GPL.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * You may elect to license modified versions of this file under the
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * terms and conditions of either the GPL or the CDDL or both.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * Basic mechanism for the HGSMI is to prepare and pass data buffer to the host and the guest.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * Data inside these buffers are opaque for the HGSMI and are interpreted by higher levels.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * Every shared memory buffer passed between the guest/host has the following structure:
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * HGSMIBUFFERHEADER header;
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * uint8_t data[header.u32BufferSize];
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * HGSMIBUFFERTAIL tail;
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * Note: Offset of the 'header' in the memory is used for virtual hardware IO.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * Buffers are verifyed using the offset and the content of the header and the tail,
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * which are constant during a call.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * Invalid buffers are ignored.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * Actual 'data' is not verifyed, as it is expected that the data can be changed by the
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * called function.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * Since only the offset of the buffer is passed in a IO operation, the header and tail
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * must contain:
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * * size of data in this buffer;
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * * checksum for buffer verification.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * For segmented transfers:
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * * the sequence identifier;
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * * offset of the current segment in the sequence;
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * * total bytes in the transfer.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * Additionally contains:
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * * the channel ID;
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * * the channel information.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync/* Heap types. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync#define HGSMI_HEAP_TYPE_NULL 0 /* Heap not initialized. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync#define HGSMI_HEAP_TYPE_POINTER 1 /* Deprecated. RTHEAPSIMPLE. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync#define HGSMI_HEAP_TYPE_OFFSET 2 /* Deprecated. RTHEAPOFFSET. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync#define HGSMI_HEAP_TYPE_MA 3 /* Memory allocator. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsynctypedef struct HGSMIHEAP
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync/* The size of the array of channels. Array indexes are uint8_t. Note: the value must not be changed. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync/* Channel handler called when the guest submits a buffer. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsynctypedef DECLCALLBACK(int) FNHGSMICHANNELHANDLER(void *pvHandler, uint16_t u16ChannelInfo, void *pvBuffer, HGSMISIZE cbBuffer);
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsynctypedef FNHGSMICHANNELHANDLER *PFNHGSMICHANNELHANDLER;
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync/* Information about a handler: pfn + context. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync/* Channel description. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync HGSMICHANNELHANDLER handler; /* The channel handler. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync const char *pszName; /* NULL for hardcoded channels or RTStrDup'ed name. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync uint8_t u8Channel; /* The channel id, equal to the channel index in the array. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync HGSMICHANNEL Channels[HGSMI_NUMBER_OF_CHANNELS]; /* Channel handlers indexed by the channel id.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync * The array is accessed under the instance lock.
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync return sizeof (HGSMIBUFFERHEADER) + sizeof (HGSMIBUFFERTAIL);
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncDECLINLINE(uint8_t *) HGSMIBufferData (const HGSMIBUFFERHEADER *pHeader)
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync return (uint8_t *)pHeader + sizeof (HGSMIBUFFERHEADER);
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncDECLINLINE(HGSMIBUFFERTAIL *) HGSMIBufferTail (const HGSMIBUFFERHEADER *pHeader)
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync return (HGSMIBUFFERTAIL *)(HGSMIBufferData (pHeader) + pHeader->u32DataSize);
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncDECLINLINE(HGSMIBUFFERHEADER *) HGSMIBufferHeaderFromData (const void *pvData)
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync return (HGSMIBUFFERHEADER *)((uint8_t *)pvData - sizeof (HGSMIBUFFERHEADER));
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncDECLINLINE(HGSMISIZE) HGSMIBufferRequiredSize (uint32_t u32DataSize)
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncDECLINLINE(HGSMIOFFSET) HGSMIPointerToOffset(const HGSMIAREA *pArea,
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync const void *pv)
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync return pArea->offBase + (HGSMIOFFSET)((uint8_t *)pv - pArea->pu8Base);
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncDECLINLINE(void *) HGSMIOffsetToPointer(const HGSMIAREA *pArea,
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync return pArea->pu8Base + (offBuffer - pArea->offBase);
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncDECLINLINE(uint8_t *) HGSMIBufferDataFromOffset (const HGSMIAREA *pArea, HGSMIOFFSET offBuffer)
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync HGSMIBUFFERHEADER *pHeader = (HGSMIBUFFERHEADER *)HGSMIOffsetToPointer(pArea, offBuffer);
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncDECLINLINE(uint8_t *) HGSMIBufferDataAndChInfoFromOffset (const HGSMIAREA *pArea, HGSMIOFFSET offBuffer, uint16_t * pChInfo)
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync HGSMIBUFFERHEADER *pHeader = (HGSMIBUFFERHEADER *)HGSMIOffsetToPointer (pArea, offBuffer);
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncHGSMICHANNEL *HGSMIChannelFindById (HGSMICHANNELINFO * pChannelInfo, uint8_t u8Channel);
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncDECLINLINE(bool) HGSMIAreaContainsOffset(const HGSMIAREA *pArea, HGSMIOFFSET off)
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync return off >= pArea->offBase && off - pArea->offBase < pArea->cbArea;
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncDECLINLINE(bool) HGSMIAreaContainsPointer(const HGSMIAREA *pArea, const void *pv)
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync return (uintptr_t)pv >= (uintptr_t)pArea->pu8Base && (uintptr_t)pv - (uintptr_t)pArea->pu8Base < pArea->cbArea;
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncHGSMIOFFSET HGSMIBufferInitializeSingle (const HGSMIAREA *pArea,
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncvoid HGSMIHeapSetupUninitialized (HGSMIHEAP *pHeap);
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncHGSMIOFFSET HGSMIHeapBufferOffset (HGSMIHEAP *pHeap,
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncDECLINLINE(HGSMIOFFSET) HGSMIHeapOffset(HGSMIHEAP *pHeap)
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync/* Needed for heap relocation: offset of the heap handle relative to the start of heap area. */
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsyncDECLINLINE(HGSMIOFFSET) HGSMIHeapHandleLocationOffset(HGSMIHEAP *pHeap)
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync offHeapHandle = (HGSMIOFFSET)((uintptr_t)pHeap->u.hPtr - (uintptr_t)pHeap->area.pu8Base);
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync else if (pHeap->u32HeapType == HGSMI_HEAP_TYPE_OFFSET)
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync offHeapHandle = (HGSMIOFFSET)((uintptr_t)pHeap->u.hOff - (uintptr_t)pHeap->area.pu8Base);
7da9e7e719adde3baba3f6fa1d0bcfb170cf9911vboxsync#endif /* IN_RING3 */
const char *pszName,
void *pvChannelHandler,