ubuntu/vbox/include/VBox/HGSMI/HGSMI.h

   1 /** @file
   2  *
   3  * VBox Host Guest Shared Memory Interface (HGSMI).
   4  * Host/Guest shared part.
   5  */
   6
   7 /*
   8  * Copyright (C) 2006-2016 Oracle Corporation
   9  *
  10  * This file is part of VirtualBox Open Source Edition (OSE), as
  11  * available from http://www.virtualbox.org. This file is free software;
  12  * you can redistribute it and/or modify it under the terms of the GNU
  13  * General Public License (GPL) as published by the Free Software
  14  * Foundation, in version 2 as it comes in the "COPYING" file of the
  15  * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
  16  * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
  17  *
  18  * The contents of this file may alternatively be used under the terms
  19  * of the Common Development and Distribution License Version 1.0
  20  * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
  21  * VirtualBox OSE distribution, in which case the provisions of the
  22  * CDDL are applicable instead of those of the GPL.
  23  *
  24  * You may elect to license modified versions of this file under the
  25  * terms and conditions of either the GPL or the CDDL or both.
  26  */
  27
  28
  29 #ifndef ___VBox_HGSMI_HGSMI_h
  30 #define ___VBox_HGSMI_HGSMI_h
  31
  32 #include <iprt/assert.h>
  33 #include <iprt/types.h>
  34
  35 #include <VBox/HGSMI/HGSMIDefs.h>
  36 #include <VBox/HGSMI/HGSMIChannels.h>
  37 #include <VBox/HGSMI/HGSMIMemAlloc.h>
  38
  39 /*
  40  * Basic mechanism for the HGSMI is to prepare and pass data buffer to the host and the guest.
  41  * Data inside these buffers are opaque for the HGSMI and are interpreted by higher levels.
  42  *
  43  * Every shared memory buffer passed between the guest/host has the following structure:
  44  *
  45  * HGSMIBUFFERHEADER header;
  46  * uint8_t data[header.u32BufferSize];
  47  * HGSMIBUFFERTAIL tail;
  48  *
  49  * Note: Offset of the 'header' in the memory is used for virtual hardware IO.
  50  *
  51  * Buffers are verifyed using the offset and the content of the header and the tail,
  52  * which are constant during a call.
  53  *
  54  * Invalid buffers are ignored.
  55  *
  56  * Actual 'data' is not verifyed, as it is expected that the data can be changed by the
  57  * called function.
  58  *
  59  * Since only the offset of the buffer is passed in a IO operation, the header and tail
  60  * must contain:
  61  *     * size of data in this buffer;
  62  *     * checksum for buffer verification.
  63  *
  64  * For segmented transfers:
  65  *     * the sequence identifier;
  66  *     * offset of the current segment in the sequence;
  67  *     * total bytes in the transfer.
  68  *
  69  * Additionally contains:
  70  *     * the channel ID;
  71  *     * the channel information.
  72  */
  73
  74 typedef struct HGSMIHEAP
  75 {
  76     HGSMIAREA area; /* Description. */
  77     HGSMIMADATA ma; /* Memory allocator */
  78 } HGSMIHEAP;
  79
  80 /* The size of the array of channels. Array indexes are uint8_t. Note: the value must not be changed. */
  81 #define HGSMI_NUMBER_OF_CHANNELS 0x100
  82
  83 /* Channel handler called when the guest submits a buffer. */
  84 typedef DECLCALLBACK(int) FNHGSMICHANNELHANDLER(void *pvHandler, uint16_t u16ChannelInfo, void *pvBuffer, HGSMISIZE cbBuffer);
  85 typedef FNHGSMICHANNELHANDLER *PFNHGSMICHANNELHANDLER;
  86
  87 /* Information about a handler: pfn + context. */
  88 typedef struct _HGSMICHANNELHANDLER
  89 {
  90     PFNHGSMICHANNELHANDLER pfnHandler;
  91     void *pvHandler;
  92 } HGSMICHANNELHANDLER;
  93
  94 /* Channel description. */
  95 typedef struct _HGSMICHANNEL
  96 {
  97     HGSMICHANNELHANDLER handler;       /* The channel handler. */
  98     const char *pszName;               /* NULL for hardcoded channels or RTStrDup'ed name. */
  99     uint8_t u8Channel;                 /* The channel id, equal to the channel index in the array. */
 100     uint8_t u8Flags;                   /* HGSMI_CH_F_* */
 101 } HGSMICHANNEL;
 102
 103 typedef struct _HGSMICHANNELINFO
 104 {
 105     HGSMICHANNEL Channels[HGSMI_NUMBER_OF_CHANNELS]; /* Channel handlers indexed by the channel id.
 106                                                       * The array is accessed under the instance lock.
 107                                                       */
 108 }  HGSMICHANNELINFO;
 109
 110
 111 RT_C_DECLS_BEGIN
 112
 113 DECLINLINE(HGSMIBUFFERHEADER *) HGSMIBufferHeaderFromPtr(void *pvBuffer)
 114 {
 115     return (HGSMIBUFFERHEADER *)pvBuffer;
 116 }
 117
 118 DECLINLINE(uint8_t *) HGSMIBufferDataFromPtr(void *pvBuffer)
 119 {
 120     return (uint8_t *)pvBuffer + sizeof(HGSMIBUFFERHEADER);
 121 }
 122
 123 DECLINLINE(HGSMIBUFFERTAIL *) HGSMIBufferTailFromPtr(void *pvBuffer,
 124                                                      uint32_t u32DataSize)
 125 {
 126     return (HGSMIBUFFERTAIL *)(HGSMIBufferDataFromPtr(pvBuffer) + u32DataSize);
 127 }
 128
 129 DECLINLINE(HGSMISIZE) HGSMIBufferMinimumSize(void)
 130 {
 131     return sizeof(HGSMIBUFFERHEADER) + sizeof(HGSMIBUFFERTAIL);
 132 }
 133
 134 DECLINLINE(HGSMIBUFFERHEADER *) HGSMIBufferHeaderFromData(const void *pvData)
 135 {
 136     return (HGSMIBUFFERHEADER *)((uint8_t *)pvData - sizeof(HGSMIBUFFERHEADER));
 137 }
 138
 139 DECLINLINE(HGSMISIZE) HGSMIBufferRequiredSize(uint32_t u32DataSize)
 140 {
 141     return HGSMIBufferMinimumSize() + u32DataSize;
 142 }
 143
 144 DECLINLINE(HGSMIOFFSET) HGSMIPointerToOffset(const HGSMIAREA *pArea,
 145                                              const void *pv)
 146 {
 147     return pArea->offBase + (HGSMIOFFSET)((uint8_t *)pv - pArea->pu8Base);
 148 }
 149
 150 DECLINLINE(void *) HGSMIOffsetToPointer(const HGSMIAREA *pArea,
 151                                         HGSMIOFFSET offBuffer)
 152 {
 153     return pArea->pu8Base + (offBuffer - pArea->offBase);
 154 }
 155
 156 DECLINLINE(uint8_t *) HGSMIBufferDataFromOffset(const HGSMIAREA *pArea,
 157                                                 HGSMIOFFSET offBuffer)
 158 {
 159     void *pvBuffer = HGSMIOffsetToPointer(pArea, offBuffer);
 160     return HGSMIBufferDataFromPtr(pvBuffer);
 161 }
 162
 163 DECLINLINE(HGSMIOFFSET) HGSMIBufferOffsetFromData(const HGSMIAREA *pArea,
 164                                                   void *pvData)
 165 {
 166     HGSMIBUFFERHEADER *pHeader = HGSMIBufferHeaderFromData(pvData);
 167     return HGSMIPointerToOffset(pArea, pHeader);
 168 }
 169
 170 DECLINLINE(uint8_t *) HGSMIBufferDataAndChInfoFromOffset(const HGSMIAREA *pArea,
 171                                                          HGSMIOFFSET offBuffer,
 172                                                          uint16_t *pu16ChannelInfo)
 173 {
 174     HGSMIBUFFERHEADER *pHeader = (HGSMIBUFFERHEADER *)HGSMIOffsetToPointer(pArea, offBuffer);
 175     *pu16ChannelInfo = pHeader->u16ChannelInfo;
 176     return HGSMIBufferDataFromPtr(pHeader);
 177 }
 178
 179 uint32_t HGSMIChecksum(HGSMIOFFSET offBuffer,
 180                        const HGSMIBUFFERHEADER *pHeader,
 181                        const HGSMIBUFFERTAIL *pTail);
 182
 183 int HGSMIAreaInitialize(HGSMIAREA *pArea,
 184                         void *pvBase,
 185                         HGSMISIZE cbArea,
 186                         HGSMIOFFSET offBase);
 187
 188 void HGSMIAreaClear(HGSMIAREA *pArea);
 189
 190 DECLINLINE(bool) HGSMIAreaContainsOffset(const HGSMIAREA *pArea, HGSMIOFFSET off)
 191 {
 192     return off >= pArea->offBase && off - pArea->offBase < pArea->cbArea;
 193 }
 194
 195 DECLINLINE(bool) HGSMIAreaContainsPointer(const HGSMIAREA *pArea, const void *pv)
 196 {
 197     return (uintptr_t)pv >= (uintptr_t)pArea->pu8Base && (uintptr_t)pv - (uintptr_t)pArea->pu8Base < pArea->cbArea;
 198 }
 199
 200 HGSMIOFFSET HGSMIBufferInitializeSingle(const HGSMIAREA *pArea,
 201                                         HGSMIBUFFERHEADER *pHeader,
 202                                         HGSMISIZE cbBuffer,
 203                                         uint8_t u8Channel,
 204                                         uint16_t u16ChannelInfo);
 205
 206 int HGSMIHeapSetup(HGSMIHEAP *pHeap,
 207                    void *pvBase,
 208                    HGSMISIZE cbArea,
 209                    HGSMIOFFSET offBase,
 210                    const HGSMIENV *pEnv);
 211
 212 void HGSMIHeapDestroy(HGSMIHEAP *pHeap);
 213
 214 void *HGSMIHeapBufferAlloc(HGSMIHEAP *pHeap,
 215                            HGSMISIZE cbBuffer);
 216
 217 void HGSMIHeapBufferFree(HGSMIHEAP *pHeap,
 218                          void *pvBuf);
 219
 220 void *HGSMIHeapAlloc(HGSMIHEAP *pHeap,
 221                      HGSMISIZE cbData,
 222                      uint8_t u8Channel,
 223                      uint16_t u16ChannelInfo);
 224
 225 void HGSMIHeapFree(HGSMIHEAP *pHeap,
 226                    void *pvData);
 227
 228 DECLINLINE(const HGSMIAREA *) HGSMIHeapArea(HGSMIHEAP *pHeap)
 229 {
 230     return &pHeap->area;
 231 }
 232
 233 DECLINLINE(HGSMIOFFSET) HGSMIHeapOffset(HGSMIHEAP *pHeap)
 234 {
 235     return HGSMIHeapArea(pHeap)->offBase;
 236 }
 237
 238 DECLINLINE(HGSMISIZE) HGSMIHeapSize(HGSMIHEAP *pHeap)
 239 {
 240     return HGSMIHeapArea(pHeap)->cbArea;
 241 }
 242
 243 DECLINLINE(HGSMIOFFSET) HGSMIHeapBufferOffset(HGSMIHEAP *pHeap,
 244                                               void *pvData)
 245 {
 246     return HGSMIBufferOffsetFromData(HGSMIHeapArea(pHeap), pvData);
 247 }
 248
 249 HGSMICHANNEL *HGSMIChannelFindById(HGSMICHANNELINFO *pChannelInfo,
 250                                    uint8_t u8Channel);
 251
 252 int HGSMIChannelRegister(HGSMICHANNELINFO *pChannelInfo,
 253                          uint8_t u8Channel,
 254                          const char *pszName,
 255                          PFNHGSMICHANNELHANDLER pfnChannelHandler,
 256                          void *pvChannelHandler);
 257
 258 int HGSMIBufferProcess(const HGSMIAREA *pArea,
 259                        HGSMICHANNELINFO *pChannelInfo,
 260                        HGSMIOFFSET offBuffer);
 261 RT_C_DECLS_END
 262
 263 #endif /* !___VBox_HGSMI_HGSMI_h */
 264