3 * VBox Host Guest Shared Memory Interface (HGSMI).
4 * Host/Guest shared part.
8 * Copyright (C) 2006-2016 Oracle Corporation
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.
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.
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.
29 #ifndef ___VBox_HGSMI_HGSMI_h
30 #define ___VBox_HGSMI_HGSMI_h
32 #include <iprt/assert.h>
33 #include <iprt/types.h>
35 #include <VBox/HGSMI/HGSMIDefs.h>
36 #include <VBox/HGSMI/HGSMIChannels.h>
37 #include <VBox/HGSMI/HGSMIMemAlloc.h>
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.
43 * Every shared memory buffer passed between the guest/host has the following structure:
45 * HGSMIBUFFERHEADER header;
46 * uint8_t data[header.u32BufferSize];
47 * HGSMIBUFFERTAIL tail;
49 * Note: Offset of the 'header' in the memory is used for virtual hardware IO.
51 * Buffers are verifyed using the offset and the content of the header and the tail,
52 * which are constant during a call.
54 * Invalid buffers are ignored.
56 * Actual 'data' is not verifyed, as it is expected that the data can be changed by the
59 * Since only the offset of the buffer is passed in a IO operation, the header and tail
61 * * size of data in this buffer;
62 * * checksum for buffer verification.
64 * For segmented transfers:
65 * * the sequence identifier;
66 * * offset of the current segment in the sequence;
67 * * total bytes in the transfer.
69 * Additionally contains:
71 * * the channel information.
74 typedef struct HGSMIHEAP
76 HGSMIAREA area
; /* Description. */
77 HGSMIMADATA ma
; /* Memory allocator */
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
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
;
87 /* Information about a handler: pfn + context. */
88 typedef struct _HGSMICHANNELHANDLER
90 PFNHGSMICHANNELHANDLER pfnHandler
;
92 } HGSMICHANNELHANDLER
;
94 /* Channel description. */
95 typedef struct _HGSMICHANNEL
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_* */
103 typedef struct _HGSMICHANNELINFO
105 HGSMICHANNEL Channels
[HGSMI_NUMBER_OF_CHANNELS
]; /* Channel handlers indexed by the channel id.
106 * The array is accessed under the instance lock.
113 DECLINLINE(HGSMIBUFFERHEADER
*) HGSMIBufferHeaderFromPtr(void *pvBuffer
)
115 return (HGSMIBUFFERHEADER
*)pvBuffer
;
118 DECLINLINE(uint8_t *) HGSMIBufferDataFromPtr(void *pvBuffer
)
120 return (uint8_t *)pvBuffer
+ sizeof(HGSMIBUFFERHEADER
);
123 DECLINLINE(HGSMIBUFFERTAIL
*) HGSMIBufferTailFromPtr(void *pvBuffer
,
124 uint32_t u32DataSize
)
126 return (HGSMIBUFFERTAIL
*)(HGSMIBufferDataFromPtr(pvBuffer
) + u32DataSize
);
129 DECLINLINE(HGSMISIZE
) HGSMIBufferMinimumSize(void)
131 return sizeof(HGSMIBUFFERHEADER
) + sizeof(HGSMIBUFFERTAIL
);
134 DECLINLINE(HGSMIBUFFERHEADER
*) HGSMIBufferHeaderFromData(const void *pvData
)
136 return (HGSMIBUFFERHEADER
*)((uint8_t *)pvData
- sizeof(HGSMIBUFFERHEADER
));
139 DECLINLINE(HGSMISIZE
) HGSMIBufferRequiredSize(uint32_t u32DataSize
)
141 return HGSMIBufferMinimumSize() + u32DataSize
;
144 DECLINLINE(HGSMIOFFSET
) HGSMIPointerToOffset(const HGSMIAREA
*pArea
,
147 return pArea
->offBase
+ (HGSMIOFFSET
)((uint8_t *)pv
- pArea
->pu8Base
);
150 DECLINLINE(void *) HGSMIOffsetToPointer(const HGSMIAREA
*pArea
,
151 HGSMIOFFSET offBuffer
)
153 return pArea
->pu8Base
+ (offBuffer
- pArea
->offBase
);
156 DECLINLINE(uint8_t *) HGSMIBufferDataFromOffset(const HGSMIAREA
*pArea
,
157 HGSMIOFFSET offBuffer
)
159 void *pvBuffer
= HGSMIOffsetToPointer(pArea
, offBuffer
);
160 return HGSMIBufferDataFromPtr(pvBuffer
);
163 DECLINLINE(HGSMIOFFSET
) HGSMIBufferOffsetFromData(const HGSMIAREA
*pArea
,
166 HGSMIBUFFERHEADER
*pHeader
= HGSMIBufferHeaderFromData(pvData
);
167 return HGSMIPointerToOffset(pArea
, pHeader
);
170 DECLINLINE(uint8_t *) HGSMIBufferDataAndChInfoFromOffset(const HGSMIAREA
*pArea
,
171 HGSMIOFFSET offBuffer
,
172 uint16_t *pu16ChannelInfo
)
174 HGSMIBUFFERHEADER
*pHeader
= (HGSMIBUFFERHEADER
*)HGSMIOffsetToPointer(pArea
, offBuffer
);
175 *pu16ChannelInfo
= pHeader
->u16ChannelInfo
;
176 return HGSMIBufferDataFromPtr(pHeader
);
179 uint32_t HGSMIChecksum(HGSMIOFFSET offBuffer
,
180 const HGSMIBUFFERHEADER
*pHeader
,
181 const HGSMIBUFFERTAIL
*pTail
);
183 int HGSMIAreaInitialize(HGSMIAREA
*pArea
,
186 HGSMIOFFSET offBase
);
188 void HGSMIAreaClear(HGSMIAREA
*pArea
);
190 DECLINLINE(bool) HGSMIAreaContainsOffset(const HGSMIAREA
*pArea
, HGSMIOFFSET off
)
192 return off
>= pArea
->offBase
&& off
- pArea
->offBase
< pArea
->cbArea
;
195 DECLINLINE(bool) HGSMIAreaContainsPointer(const HGSMIAREA
*pArea
, const void *pv
)
197 return (uintptr_t)pv
>= (uintptr_t)pArea
->pu8Base
&& (uintptr_t)pv
- (uintptr_t)pArea
->pu8Base
< pArea
->cbArea
;
200 HGSMIOFFSET
HGSMIBufferInitializeSingle(const HGSMIAREA
*pArea
,
201 HGSMIBUFFERHEADER
*pHeader
,
204 uint16_t u16ChannelInfo
);
206 int HGSMIHeapSetup(HGSMIHEAP
*pHeap
,
210 const HGSMIENV
*pEnv
);
212 void HGSMIHeapDestroy(HGSMIHEAP
*pHeap
);
214 void *HGSMIHeapBufferAlloc(HGSMIHEAP
*pHeap
,
217 void HGSMIHeapBufferFree(HGSMIHEAP
*pHeap
,
220 void *HGSMIHeapAlloc(HGSMIHEAP
*pHeap
,
223 uint16_t u16ChannelInfo
);
225 void HGSMIHeapFree(HGSMIHEAP
*pHeap
,
228 DECLINLINE(const HGSMIAREA
*) HGSMIHeapArea(HGSMIHEAP
*pHeap
)
233 DECLINLINE(HGSMIOFFSET
) HGSMIHeapOffset(HGSMIHEAP
*pHeap
)
235 return HGSMIHeapArea(pHeap
)->offBase
;
238 DECLINLINE(HGSMISIZE
) HGSMIHeapSize(HGSMIHEAP
*pHeap
)
240 return HGSMIHeapArea(pHeap
)->cbArea
;
243 DECLINLINE(HGSMIOFFSET
) HGSMIHeapBufferOffset(HGSMIHEAP
*pHeap
,
246 return HGSMIBufferOffsetFromData(HGSMIHeapArea(pHeap
), pvData
);
249 HGSMICHANNEL
*HGSMIChannelFindById(HGSMICHANNELINFO
*pChannelInfo
,
252 int HGSMIChannelRegister(HGSMICHANNELINFO
*pChannelInfo
,
255 PFNHGSMICHANNELHANDLER pfnChannelHandler
,
256 void *pvChannelHandler
);
258 int HGSMIBufferProcess(const HGSMIAREA
*pArea
,
259 HGSMICHANNELINFO
*pChannelInfo
,
260 HGSMIOFFSET offBuffer
);
263 #endif /* !___VBox_HGSMI_HGSMI_h */