]> git.proxmox.com Git - mirror_edk2.git/blob - OvmfPkg/VirtioGpuDxe/VirtioGpu.h
MdeModulePkg/Core: Merge memory map after filtering paging capability
[mirror_edk2.git] / OvmfPkg / VirtioGpuDxe / VirtioGpu.h
1 /** @file
2
3 Internal type and macro definitions for the Virtio GPU hybrid driver.
4
5 Copyright (C) 2016, Red Hat, Inc.
6
7 This program and the accompanying materials are licensed and made available
8 under the terms and conditions of the BSD License which accompanies this
9 distribution. The full text of the license may be found at
10 http://opensource.org/licenses/bsd-license.php
11
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
13 WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
14
15 **/
16
17 #ifndef _VIRTIO_GPU_DXE_H_
18 #define _VIRTIO_GPU_DXE_H_
19
20 #include <IndustryStandard/VirtioGpu.h>
21 #include <Library/BaseMemoryLib.h>
22 #include <Library/DebugLib.h>
23 #include <Library/UefiLib.h>
24 #include <Protocol/GraphicsOutput.h>
25 #include <Protocol/VirtioDevice.h>
26
27 //
28 // Forward declaration of VGPU_GOP.
29 //
30 typedef struct VGPU_GOP_STRUCT VGPU_GOP;
31
32 //
33 // The abstraction that directly corresponds to a Virtio GPU device.
34 //
35 // This structure will be installed on the handle that has the VirtIo Device
36 // Protocol interface, with GUID gEfiCallerIdGuid. A similar trick is employed
37 // in TerminalDxe, and it is necessary so that we can look up VGPU_DEV just
38 // from the VirtIo Device Protocol handle in the Component Name 2 Protocol
39 // implementation.
40 //
41 typedef struct {
42 //
43 // VirtIo represents access to the Virtio GPU device. Never NULL.
44 //
45 VIRTIO_DEVICE_PROTOCOL *VirtIo;
46
47 //
48 // BusName carries a customized name for
49 // EFI_COMPONENT_NAME2_PROTOCOL.GetControllerName(). It is expressed in table
50 // form because it can theoretically support several languages. Never NULL.
51 //
52 EFI_UNICODE_STRING_TABLE *BusName;
53
54 //
55 // VirtIo ring used for VirtIo communication.
56 //
57 VRING Ring;
58
59 //
60 // Token associated with Ring's mapping for bus master common buffer
61 // operation, from VirtioRingMap().
62 //
63 VOID *RingMap;
64
65 //
66 // Event to be signaled at ExitBootServices().
67 //
68 EFI_EVENT ExitBoot;
69
70 //
71 // Common running counter for all VirtIo GPU requests that ask for fencing.
72 //
73 UINT64 FenceId;
74
75 //
76 // The Child field references the GOP wrapper structure. If this pointer is
77 // NULL, then the hybrid driver has bound (i.e., started) the
78 // VIRTIO_DEVICE_PROTOCOL controller without producing the child GOP
79 // controller (that is, after Start() was called with RemainingDevicePath
80 // pointing to and End of Device Path node). Child can be created and
81 // destroyed, even repeatedly, independently of VGPU_DEV.
82 //
83 // In practice, this field represents the single head (scanout) that we
84 // support.
85 //
86 VGPU_GOP *Child;
87 } VGPU_DEV;
88
89 //
90 // The Graphics Output Protocol wrapper structure.
91 //
92 #define VGPU_GOP_SIG SIGNATURE_64 ('V', 'G', 'P', 'U', '_', 'G', 'O', 'P')
93
94 struct VGPU_GOP_STRUCT {
95 UINT64 Signature;
96
97 //
98 // ParentBus points to the parent VGPU_DEV object. Never NULL.
99 //
100 VGPU_DEV *ParentBus;
101
102 //
103 // GopName carries a customized name for
104 // EFI_COMPONENT_NAME2_PROTOCOL.GetControllerName(). It is expressed in table
105 // form because it can theoretically support several languages. Never NULL.
106 //
107 EFI_UNICODE_STRING_TABLE *GopName;
108
109 //
110 // GopHandle is the UEFI child handle that carries the device path ending
111 // with the ACPI ADR node, and the Graphics Output Protocol. Never NULL.
112 //
113 EFI_HANDLE GopHandle;
114
115 //
116 // The GopDevicePath field is the device path installed on GopHandle,
117 // ending with an ACPI ADR node. Never NULL.
118 //
119 EFI_DEVICE_PATH_PROTOCOL *GopDevicePath;
120
121 //
122 // The Gop field is installed on the child handle as Graphics Output Protocol
123 // interface.
124 //
125 EFI_GRAPHICS_OUTPUT_PROTOCOL Gop;
126
127 //
128 // Referenced by Gop.Mode, GopMode provides a summary about the supported
129 // graphics modes, and the current mode.
130 //
131 EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE GopMode;
132
133 //
134 // Referenced by GopMode.Info, GopModeInfo provides detailed information
135 // about the current mode.
136 //
137 EFI_GRAPHICS_OUTPUT_MODE_INFORMATION GopModeInfo;
138
139 //
140 // Identifier of the 2D host resource that is in use by this head (scanout)
141 // of the VirtIo GPU device. Zero until the first successful -- internal --
142 // Gop.SetMode() call, never zero afterwards.
143 //
144 UINT32 ResourceId;
145
146 //
147 // A number of whole pages providing the backing store for the 2D host
148 // resource identified by ResourceId above. NULL until the first successful
149 // -- internal -- Gop.SetMode() call, never NULL afterwards.
150 //
151 UINT32 *BackingStore;
152 UINTN NumberOfPages;
153
154 //
155 // Token associated with BackingStore's mapping for bus master common
156 // buffer operation. BackingStoreMap is valid if, and only if,
157 // BackingStore is non-NULL.
158 //
159 VOID *BackingStoreMap;
160 };
161
162 //
163 // VirtIo GPU initialization, and commands (primitives) for the GPU device.
164 //
165 /**
166 Configure the VirtIo GPU device that underlies VgpuDev.
167
168 @param[in,out] VgpuDev The VGPU_DEV object to set up VirtIo messaging for.
169 On input, the caller is responsible for having
170 initialized VgpuDev->VirtIo. On output, VgpuDev->Ring
171 has been initialized, and synchronous VirtIo GPU
172 commands (primitives) can be submitted to the device.
173
174 @retval EFI_SUCCESS VirtIo GPU configuration successful.
175
176 @retval EFI_UNSUPPORTED The host-side configuration of the VirtIo GPU is not
177 supported by this driver.
178
179 @retval Error codes from underlying functions.
180 **/
181 EFI_STATUS
182 VirtioGpuInit (
183 IN OUT VGPU_DEV *VgpuDev
184 );
185
186 /**
187 De-configure the VirtIo GPU device that underlies VgpuDev.
188
189 @param[in,out] VgpuDev The VGPU_DEV object to tear down VirtIo messaging
190 for. On input, the caller is responsible for having
191 called VirtioGpuInit(). On output, VgpuDev->Ring has
192 been uninitialized; VirtIo GPU commands (primitives)
193 can no longer be submitted to the device.
194 **/
195 VOID
196 VirtioGpuUninit (
197 IN OUT VGPU_DEV *VgpuDev
198 );
199
200 /**
201 Allocate, zero and map memory, for bus master common buffer operation, to be
202 attached as backing store to a host-side VirtIo GPU resource.
203
204 @param[in] VgpuDev The VGPU_DEV object that represents the VirtIo GPU
205 device.
206
207 @param[in] NumberOfPages The number of whole pages to allocate and map.
208
209 @param[out] HostAddress The system memory address of the allocated area.
210
211 @param[out] DeviceAddress The bus master device address of the allocated
212 area. The VirtIo GPU device may be programmed to
213 access the allocated area through DeviceAddress;
214 DeviceAddress is to be passed to the
215 VirtioGpuResourceAttachBacking() function, as the
216 BackingStoreDeviceAddress parameter.
217
218 @param[out] Mapping A resulting token to pass to
219 VirtioGpuUnmapAndFreeBackingStore().
220
221 @retval EFI_SUCCESS The requested number of pages has been allocated, zeroed
222 and mapped.
223
224 @return Status codes propagated from
225 VgpuDev->VirtIo->AllocateSharedPages() and
226 VirtioMapAllBytesInSharedBuffer().
227 **/
228 EFI_STATUS
229 VirtioGpuAllocateZeroAndMapBackingStore (
230 IN VGPU_DEV *VgpuDev,
231 IN UINTN NumberOfPages,
232 OUT VOID **HostAddress,
233 OUT EFI_PHYSICAL_ADDRESS *DeviceAddress,
234 OUT VOID **Mapping
235 );
236
237 /**
238 Unmap and free memory originally allocated and mapped with
239 VirtioGpuAllocateZeroAndMapBackingStore().
240
241 If the memory allocated and mapped with
242 VirtioGpuAllocateZeroAndMapBackingStore() was attached to a host-side VirtIo
243 GPU resource with VirtioGpuResourceAttachBacking(), then the caller is
244 responsible for detaching the backing store from the same resource, with
245 VirtioGpuResourceDetachBacking(), before calling this function.
246
247 @param[in] VgpuDev The VGPU_DEV object that represents the VirtIo GPU
248 device.
249
250 @param[in] NumberOfPages The NumberOfPages parameter originally passed to
251 VirtioGpuAllocateZeroAndMapBackingStore().
252
253 @param[in] HostAddress The HostAddress value originally output by
254 VirtioGpuAllocateZeroAndMapBackingStore().
255
256 @param[in] Mapping The token that was originally output by
257 VirtioGpuAllocateZeroAndMapBackingStore().
258 **/
259 VOID
260 VirtioGpuUnmapAndFreeBackingStore (
261 IN VGPU_DEV *VgpuDev,
262 IN UINTN NumberOfPages,
263 IN VOID *HostAddress,
264 IN VOID *Mapping
265 );
266
267 /**
268 EFI_EVENT_NOTIFY function for the VGPU_DEV.ExitBoot event. It resets the
269 VirtIo device, causing it to release its resources and to forget its
270 configuration.
271
272 This function may only be called (that is, VGPU_DEV.ExitBoot may only be
273 signaled) after VirtioGpuInit() returns and before VirtioGpuUninit() is
274 called.
275
276 @param[in] Event Event whose notification function is being invoked.
277
278 @param[in] Context Pointer to the associated VGPU_DEV object.
279 **/
280 VOID
281 EFIAPI
282 VirtioGpuExitBoot (
283 IN EFI_EVENT Event,
284 IN VOID *Context
285 );
286
287 /**
288 The following functions send requests to the VirtIo GPU device model, await
289 the answer from the host, and return a status. They share the following
290 interface details:
291
292 @param[in,out] VgpuDev The VGPU_DEV object that represents the VirtIo GPU
293 device. The caller is responsible to have
294 successfully invoked VirtioGpuInit() on VgpuDev
295 previously, while VirtioGpuUninit() must not have
296 been called on VgpuDev.
297
298 @retval EFI_INVALID_PARAMETER Invalid command-specific parameters were
299 detected by this driver.
300
301 @retval EFI_SUCCESS Operation successful.
302
303 @retval EFI_DEVICE_ERROR The host rejected the request. The host error
304 code has been logged on the EFI_D_ERROR level.
305
306 @return Codes for unexpected errors in VirtIo
307 messaging.
308
309 For the command-specific parameters, please consult the GPU Device section of
310 the VirtIo 1.0 specification (see references in
311 "OvmfPkg/Include/IndustryStandard/VirtioGpu.h").
312 **/
313 EFI_STATUS
314 VirtioGpuResourceCreate2d (
315 IN OUT VGPU_DEV *VgpuDev,
316 IN UINT32 ResourceId,
317 IN VIRTIO_GPU_FORMATS Format,
318 IN UINT32 Width,
319 IN UINT32 Height
320 );
321
322 EFI_STATUS
323 VirtioGpuResourceUnref (
324 IN OUT VGPU_DEV *VgpuDev,
325 IN UINT32 ResourceId
326 );
327
328 EFI_STATUS
329 VirtioGpuResourceAttachBacking (
330 IN OUT VGPU_DEV *VgpuDev,
331 IN UINT32 ResourceId,
332 IN EFI_PHYSICAL_ADDRESS BackingStoreDeviceAddress,
333 IN UINTN NumberOfPages
334 );
335
336 EFI_STATUS
337 VirtioGpuResourceDetachBacking (
338 IN OUT VGPU_DEV *VgpuDev,
339 IN UINT32 ResourceId
340 );
341
342 EFI_STATUS
343 VirtioGpuSetScanout (
344 IN OUT VGPU_DEV *VgpuDev,
345 IN UINT32 X,
346 IN UINT32 Y,
347 IN UINT32 Width,
348 IN UINT32 Height,
349 IN UINT32 ScanoutId,
350 IN UINT32 ResourceId
351 );
352
353 EFI_STATUS
354 VirtioGpuTransferToHost2d (
355 IN OUT VGPU_DEV *VgpuDev,
356 IN UINT32 X,
357 IN UINT32 Y,
358 IN UINT32 Width,
359 IN UINT32 Height,
360 IN UINT64 Offset,
361 IN UINT32 ResourceId
362 );
363
364 EFI_STATUS
365 VirtioGpuResourceFlush (
366 IN OUT VGPU_DEV *VgpuDev,
367 IN UINT32 X,
368 IN UINT32 Y,
369 IN UINT32 Width,
370 IN UINT32 Height,
371 IN UINT32 ResourceId
372 );
373
374 /**
375 Release guest-side and host-side resources that are related to an initialized
376 VGPU_GOP.Gop.
377
378 param[in,out] VgpuGop The VGPU_GOP object to release resources for.
379
380 On input, the caller is responsible for having called
381 VgpuGop->Gop.SetMode() at least once successfully.
382 (This is equivalent to the requirement that
383 VgpuGop->BackingStore be non-NULL. It is also
384 equivalent to the requirement that VgpuGop->ResourceId
385 be nonzero.)
386
387 On output, resources will be released, and
388 VgpuGop->BackingStore and VgpuGop->ResourceId will be
389 nulled.
390
391 param[in] DisableHead Whether this head (scanout) currently references the
392 resource identified by VgpuGop->ResourceId. Only pass
393 FALSE when VgpuGop->Gop.SetMode() calls this function
394 while switching between modes, and set it to TRUE
395 every other time.
396 **/
397 VOID
398 ReleaseGopResources (
399 IN OUT VGPU_GOP *VgpuGop,
400 IN BOOLEAN DisableHead
401 );
402
403 //
404 // Template for initializing VGPU_GOP.Gop.
405 //
406 extern CONST EFI_GRAPHICS_OUTPUT_PROTOCOL mGopTemplate;
407
408 #endif // _VIRTIO_GPU_DXE_H_