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 |
|
---|