VirtualBox

source: vbox/trunk/include/VBox/Graphics/HGSMI.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 9.4 KB
Line 
1/* $Id: HGSMI.h 98103 2023-01-17 14:15:46Z vboxsync $ */
2/** @file
3 * VBox Host Guest Shared Memory Interface (HGSMI) - Host/Guest shared part.
4 */
5
6/*
7 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
8 *
9 * Permission is hereby granted, free of charge, to any person
10 * obtaining a copy of this software and associated documentation
11 * files (the "Software"), to deal in the Software without
12 * restriction, including without limitation the rights to use,
13 * copy, modify, merge, publish, distribute, sublicense, and/or sell
14 * copies of the Software, and to permit persons to whom the
15 * Software is furnished to do so, subject to the following
16 * conditions:
17 *
18 * The above copyright notice and this permission notice shall be
19 * included in all copies or substantial portions of the Software.
20 *
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
23 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
24 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
25 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
26 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
27 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
28 * OTHER DEALINGS IN THE SOFTWARE.
29 */
30
31#ifndef VBOX_INCLUDED_Graphics_HGSMI_h
32#define VBOX_INCLUDED_Graphics_HGSMI_h
33#ifndef RT_WITHOUT_PRAGMA_ONCE
34# pragma once
35#endif
36
37#include "VBoxVideoIPRT.h"
38
39#include "HGSMIDefs.h"
40#include "HGSMIChannels.h"
41#include "HGSMIMemAlloc.h"
42
43/**
44 * Basic mechanism for the HGSMI is to prepare and pass data buffer to the host and the guest.
45 * Data inside these buffers are opaque for the HGSMI and are interpreted by higher levels.
46 *
47 * Every shared memory buffer passed between the guest/host has the following structure:
48 *
49 * HGSMIBUFFERHEADER header;
50 * uint8_t data[header.u32BufferSize];
51 * HGSMIBUFFERTAIL tail;
52 *
53 * Note: Offset of the 'header' in the memory is used for virtual hardware IO.
54 *
55 * Buffers are verifyed using the offset and the content of the header and the tail,
56 * which are constant during a call.
57 *
58 * Invalid buffers are ignored.
59 *
60 * Actual 'data' is not verifyed, as it is expected that the data can be changed by the
61 * called function.
62 *
63 * Since only the offset of the buffer is passed in a IO operation, the header and tail
64 * must contain:
65 * * size of data in this buffer;
66 * * checksum for buffer verification.
67 *
68 * For segmented transfers:
69 * * the sequence identifier;
70 * * offset of the current segment in the sequence;
71 * * total bytes in the transfer.
72 *
73 * Additionally contains:
74 * * the channel ID;
75 * * the channel information.
76 */
77
78typedef struct HGSMIHEAP
79{
80 HGSMIAREA area; /**< Description. */
81 HGSMIMADATA ma; /**< Memory allocator */
82} HGSMIHEAP;
83
84/* The size of the array of channels. Array indexes are uint8_t. Note: the value must not be changed. */
85#define HGSMI_NUMBER_OF_CHANNELS 0x100
86
87/**
88 * Channel handler called when the guest submits a buffer.
89 *
90 * @returns stuff
91 * @param pvHandler Value specified when registring.
92 * @param u16ChannelInfo Command code.
93 * @param pvBuffer HGSMI buffer with command data. This is shared with
94 * the guest. Consider untrusted and volatile!
95 * @param cbBuffer Size of command data.
96 * @thread EMT on the host side.
97 */
98typedef DECLCALLBACKTYPE(int, FNHGSMICHANNELHANDLER,(void *pvHandler, uint16_t u16ChannelInfo,
99 RT_UNTRUSTED_VOLATILE_HSTGST void *pvBuffer, HGSMISIZE cbBuffer));
100/** Pointer to a channel handler callback. */
101typedef FNHGSMICHANNELHANDLER *PFNHGSMICHANNELHANDLER;
102
103/** Information about a handler: pfn + context. */
104typedef struct _HGSMICHANNELHANDLER
105{
106 PFNHGSMICHANNELHANDLER pfnHandler;
107 void *pvHandler;
108} HGSMICHANNELHANDLER;
109
110/** Channel description. */
111typedef struct _HGSMICHANNEL
112{
113 HGSMICHANNELHANDLER handler; /**< The channel handler. */
114 const char *pszName; /**< NULL for hardcoded channels or RTStrDup'ed name. */
115 uint8_t u8Channel; /**< The channel id, equal to the channel index in the array. */
116 uint8_t u8Flags; /**< HGSMI_CH_F_* */
117} HGSMICHANNEL;
118
119typedef struct _HGSMICHANNELINFO
120{
121 /** Channel handlers indexed by the channel id.
122 * The array is accessed under the instance lock. */
123 HGSMICHANNEL Channels[HGSMI_NUMBER_OF_CHANNELS];
124} HGSMICHANNELINFO;
125
126
127RT_C_DECLS_BEGIN
128
129DECLINLINE(HGSMIBUFFERHEADER *) HGSMIBufferHeaderFromPtr(void RT_UNTRUSTED_VOLATILE_HSTGST *pvBuffer)
130{
131 return (HGSMIBUFFERHEADER *)pvBuffer;
132}
133
134DECLINLINE(uint8_t RT_UNTRUSTED_VOLATILE_HSTGST *) HGSMIBufferDataFromPtr(void RT_UNTRUSTED_VOLATILE_HSTGST *pvBuffer)
135{
136 return (uint8_t RT_UNTRUSTED_VOLATILE_HSTGST *)pvBuffer + sizeof(HGSMIBUFFERHEADER);
137}
138
139DECLINLINE(HGSMIBUFFERTAIL RT_UNTRUSTED_VOLATILE_HSTGST *)
140HGSMIBufferTailFromPtr(void RT_UNTRUSTED_VOLATILE_HSTGST *pvBuffer, uint32_t u32DataSize)
141{
142 return (HGSMIBUFFERTAIL RT_UNTRUSTED_VOLATILE_HSTGST *)(HGSMIBufferDataFromPtr(pvBuffer) + u32DataSize);
143}
144
145DECLINLINE(HGSMISIZE) HGSMIBufferMinimumSize(void)
146{
147 return sizeof(HGSMIBUFFERHEADER) + sizeof(HGSMIBUFFERTAIL);
148}
149
150DECLINLINE(HGSMIBUFFERHEADER RT_UNTRUSTED_VOLATILE_HSTGST *) HGSMIBufferHeaderFromData(const void RT_UNTRUSTED_VOLATILE_HSTGST *pvData)
151{
152 return (HGSMIBUFFERHEADER RT_UNTRUSTED_VOLATILE_HSTGST *)((uint8_t *)pvData - sizeof(HGSMIBUFFERHEADER));
153}
154
155DECLINLINE(HGSMISIZE) HGSMIBufferRequiredSize(uint32_t u32DataSize)
156{
157 return HGSMIBufferMinimumSize() + u32DataSize;
158}
159
160DECLINLINE(HGSMIOFFSET) HGSMIPointerToOffset(const HGSMIAREA *pArea, const void RT_UNTRUSTED_VOLATILE_HSTGST *pv)
161{
162 return pArea->offBase + (HGSMIOFFSET)((uint8_t *)pv - pArea->pu8Base);
163}
164
165DECLINLINE(void RT_UNTRUSTED_VOLATILE_HSTGST *) HGSMIOffsetToPointer(const HGSMIAREA *pArea, HGSMIOFFSET offBuffer)
166{
167 return pArea->pu8Base + (offBuffer - pArea->offBase);
168}
169
170DECLINLINE(uint8_t RT_UNTRUSTED_VOLATILE_HSTGST*) HGSMIBufferDataFromOffset(const HGSMIAREA *pArea, HGSMIOFFSET offBuffer)
171{
172 void RT_UNTRUSTED_VOLATILE_HSTGST *pvBuffer = HGSMIOffsetToPointer(pArea, offBuffer);
173 return HGSMIBufferDataFromPtr(pvBuffer);
174}
175
176DECLINLINE(HGSMIOFFSET) HGSMIBufferOffsetFromData(const HGSMIAREA *pArea, void RT_UNTRUSTED_VOLATILE_HSTGST *pvData)
177{
178 HGSMIBUFFERHEADER RT_UNTRUSTED_VOLATILE_HSTGST *pHeader = HGSMIBufferHeaderFromData(pvData);
179 return HGSMIPointerToOffset(pArea, pHeader);
180}
181
182DECLINLINE(uint8_t RT_UNTRUSTED_VOLATILE_HSTGST *) HGSMIBufferDataAndChInfoFromOffset(const HGSMIAREA *pArea,
183 HGSMIOFFSET offBuffer,
184 uint16_t *pu16ChannelInfo)
185{
186 HGSMIBUFFERHEADER RT_UNTRUSTED_VOLATILE_HSTGST *pHeader =
187 (HGSMIBUFFERHEADER RT_UNTRUSTED_VOLATILE_HSTGST *)HGSMIOffsetToPointer(pArea, offBuffer);
188 *pu16ChannelInfo = pHeader->u16ChannelInfo;
189 return HGSMIBufferDataFromPtr(pHeader);
190}
191
192uint32_t HGSMIChecksum(HGSMIOFFSET offBuffer, const HGSMIBUFFERHEADER RT_UNTRUSTED_VOLATILE_HSTGST *pHeader,
193 const HGSMIBUFFERTAIL RT_UNTRUSTED_VOLATILE_HSTGST *pTail);
194
195int HGSMIAreaInitialize(HGSMIAREA *pArea, void *pvBase, HGSMISIZE cbArea, HGSMIOFFSET offBase);
196void HGSMIAreaClear(HGSMIAREA *pArea);
197
198DECLINLINE(bool) HGSMIAreaContainsOffset(const HGSMIAREA *pArea, HGSMIOFFSET off)
199{
200 return off >= pArea->offBase && off - pArea->offBase < pArea->cbArea;
201}
202
203DECLINLINE(bool) HGSMIAreaContainsPointer(const HGSMIAREA *pArea, const void RT_UNTRUSTED_VOLATILE_HSTGST *pv)
204{
205 return (uintptr_t)pv - (uintptr_t)pArea->pu8Base < pArea->cbArea;
206}
207
208HGSMIOFFSET HGSMIBufferInitializeSingle(const HGSMIAREA *pArea, HGSMIBUFFERHEADER *pHeader, HGSMISIZE cbBuffer,
209 uint8_t u8Channel, uint16_t u16ChannelInfo);
210
211int HGSMIHeapSetup(HGSMIHEAP *pHeap, void *pvBase, HGSMISIZE cbArea, HGSMIOFFSET offBase, const HGSMIENV *pEnv);
212void HGSMIHeapDestroy(HGSMIHEAP *pHeap);
213void RT_UNTRUSTED_VOLATILE_HSTGST *HGSMIHeapBufferAlloc(HGSMIHEAP *pHeap, HGSMISIZE cbBuffer);
214void HGSMIHeapBufferFree(HGSMIHEAP *pHeap, void RT_UNTRUSTED_VOLATILE_HSTGST *pvBuf);
215
216void RT_UNTRUSTED_VOLATILE_HOST *HGSMIHeapAlloc(HGSMIHEAP *pHeap,
217 HGSMISIZE cbData,
218 uint8_t u8Channel,
219 uint16_t u16ChannelInfo);
220
221void HGSMIHeapFree(HGSMIHEAP *pHeap, void RT_UNTRUSTED_VOLATILE_HSTGST *pvData);
222
223DECLINLINE(const HGSMIAREA *) HGSMIHeapArea(HGSMIHEAP *pHeap)
224{
225 return &pHeap->area;
226}
227
228DECLINLINE(HGSMIOFFSET) HGSMIHeapOffset(HGSMIHEAP *pHeap)
229{
230 return HGSMIHeapArea(pHeap)->offBase;
231}
232
233DECLINLINE(HGSMISIZE) HGSMIHeapSize(HGSMIHEAP *pHeap)
234{
235 return HGSMIHeapArea(pHeap)->cbArea;
236}
237
238DECLINLINE(HGSMIOFFSET) HGSMIHeapBufferOffset(HGSMIHEAP *pHeap, void RT_UNTRUSTED_VOLATILE_HOST *pvData)
239{
240 return HGSMIBufferOffsetFromData(HGSMIHeapArea(pHeap), pvData);
241}
242
243HGSMICHANNEL *HGSMIChannelFindById(HGSMICHANNELINFO *pChannelInfo, uint8_t u8Channel);
244
245int HGSMIChannelRegister(HGSMICHANNELINFO *pChannelInfo, uint8_t u8Channel, const char *pszName,
246 PFNHGSMICHANNELHANDLER pfnChannelHandler, void *pvChannelHandler);
247int HGSMIBufferProcess(const HGSMIAREA *pArea, HGSMICHANNELINFO *pChannelInfo, HGSMIOFFSET offBuffer);
248RT_C_DECLS_END
249
250#endif /* !VBOX_INCLUDED_Graphics_HGSMI_h */
251
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette