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/DebugLib.h> 22 #include <Library/UefiLib.h> 23 #include <Protocol/GraphicsOutput.h> 24 #include <Protocol/VirtioDevice.h> 25 26 // 27 // Forward declaration of VGPU_GOP. 28 // 29 typedef struct VGPU_GOP_STRUCT VGPU_GOP; 30 31 // 32 // The abstraction that directly corresponds to a Virtio GPU device. 33 // 34 // This structure will be installed on the handle that has the VirtIo Device 35 // Protocol interface, with GUID gEfiCallerIdGuid. A similar trick is employed 36 // in TerminalDxe, and it is necessary so that we can look up VGPU_DEV just 37 // from the VirtIo Device Protocol handle in the Component Name 2 Protocol 38 // implementation. 39 // 40 typedef struct { 41 // 42 // VirtIo represents access to the Virtio GPU device. Never NULL. 43 // 44 VIRTIO_DEVICE_PROTOCOL *VirtIo; 45 46 // 47 // BusName carries a customized name for 48 // EFI_COMPONENT_NAME2_PROTOCOL.GetControllerName(). It is expressed in table 49 // form because it can theoretically support several languages. Never NULL. 50 // 51 EFI_UNICODE_STRING_TABLE *BusName; 52 53 // 54 // VirtIo ring used for VirtIo communication. 55 // 56 VRING Ring; 57 58 // 59 // Event to be signaled at ExitBootServices(). 60 // 61 EFI_EVENT ExitBoot; 62 63 // 64 // Common running counter for all VirtIo GPU requests that ask for fencing. 65 // 66 UINT64 FenceId; 67 68 // 69 // The Child field references the GOP wrapper structure. If this pointer is 70 // NULL, then the hybrid driver has bound (i.e., started) the 71 // VIRTIO_DEVICE_PROTOCOL controller without producing the child GOP 72 // controller (that is, after Start() was called with RemainingDevicePath 73 // pointing to and End of Device Path node). Child can be created and 74 // destroyed, even repeatedly, independently of VGPU_DEV. 75 // 76 // In practice, this field represents the single head (scanout) that we 77 // support. 78 // 79 VGPU_GOP *Child; 80 } VGPU_DEV; 81 82 // 83 // The Graphics Output Protocol wrapper structure. 84 // 85 #define VGPU_GOP_SIG SIGNATURE_64 ('V', 'G', 'P', 'U', '_', 'G', 'O', 'P') 86 87 struct VGPU_GOP_STRUCT { 88 UINT64 Signature; 89 90 // 91 // ParentBus points to the parent VGPU_DEV object. Never NULL. 92 // 93 VGPU_DEV *ParentBus; 94 95 // 96 // GopName carries a customized name for 97 // EFI_COMPONENT_NAME2_PROTOCOL.GetControllerName(). It is expressed in table 98 // form because it can theoretically support several languages. Never NULL. 99 // 100 EFI_UNICODE_STRING_TABLE *GopName; 101 102 // 103 // GopHandle is the UEFI child handle that carries the device path ending 104 // with the ACPI ADR node, and the Graphics Output Protocol. Never NULL. 105 // 106 EFI_HANDLE GopHandle; 107 108 // 109 // The GopDevicePath field is the device path installed on GopHandle, 110 // ending with an ACPI ADR node. Never NULL. 111 // 112 EFI_DEVICE_PATH_PROTOCOL *GopDevicePath; 113 114 // 115 // The Gop field is installed on the child handle as Graphics Output Protocol 116 // interface. 117 // 118 EFI_GRAPHICS_OUTPUT_PROTOCOL Gop; 119 120 // 121 // Referenced by Gop.Mode, GopMode provides a summary about the supported 122 // graphics modes, and the current mode. 123 // 124 EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE GopMode; 125 126 // 127 // Referenced by GopMode.Info, GopModeInfo provides detailed information 128 // about the current mode. 129 // 130 EFI_GRAPHICS_OUTPUT_MODE_INFORMATION GopModeInfo; 131 132 // 133 // Identifier of the 2D host resource that is in use by this head (scanout) 134 // of the VirtIo GPU device. Zero until the first successful -- internal -- 135 // Gop.SetMode() call, never zero afterwards. 136 // 137 UINT32 ResourceId; 138 139 // 140 // A number of whole pages providing the backing store for the 2D host 141 // resource identified by ResourceId above. NULL until the first successful 142 // -- internal -- Gop.SetMode() call, never NULL afterwards. 143 // 144 UINT32 *BackingStore; 145 UINTN NumberOfPages; 146 }; 147 148 // 149 // VirtIo GPU initialization, and commands (primitives) for the GPU device. 150 // 151 /** 152 Configure the VirtIo GPU device that underlies VgpuDev. 153 154 @param[in,out] VgpuDev The VGPU_DEV object to set up VirtIo messaging for. 155 On input, the caller is responsible for having 156 initialized VgpuDev->VirtIo. On output, VgpuDev->Ring 157 has been initialized, and synchronous VirtIo GPU 158 commands (primitives) can be submitted to the device. 159 160 @retval EFI_SUCCESS VirtIo GPU configuration successful. 161 162 @retval EFI_UNSUPPORTED The host-side configuration of the VirtIo GPU is not 163 supported by this driver. 164 165 @retval Error codes from underlying functions. 166 **/ 167 EFI_STATUS 168 VirtioGpuInit ( 169 IN OUT VGPU_DEV *VgpuDev 170 ); 171 172 /** 173 De-configure the VirtIo GPU device that underlies VgpuDev. 174 175 @param[in,out] VgpuDev The VGPU_DEV object to tear down VirtIo messaging 176 for. On input, the caller is responsible for having 177 called VirtioGpuInit(). On output, VgpuDev->Ring has 178 been uninitialized; VirtIo GPU commands (primitives) 179 can no longer be submitted to the device. 180 **/ 181 VOID 182 VirtioGpuUninit ( 183 IN OUT VGPU_DEV *VgpuDev 184 ); 185 186 /** 187 EFI_EVENT_NOTIFY function for the VGPU_DEV.ExitBoot event. It resets the 188 VirtIo device, causing it to release its resources and to forget its 189 configuration. 190 191 This function may only be called (that is, VGPU_DEV.ExitBoot may only be 192 signaled) after VirtioGpuInit() returns and before VirtioGpuUninit() is 193 called. 194 195 @param[in] Event Event whose notification function is being invoked. 196 197 @param[in] Context Pointer to the associated VGPU_DEV object. 198 **/ 199 VOID 200 EFIAPI 201 VirtioGpuExitBoot ( 202 IN EFI_EVENT Event, 203 IN VOID *Context 204 ); 205 206 /** 207 The following functions send requests to the VirtIo GPU device model, await 208 the answer from the host, and return a status. They share the following 209 interface details: 210 211 @param[in,out] VgpuDev The VGPU_DEV object that represents the VirtIo GPU 212 device. The caller is responsible to have 213 successfully invoked VirtioGpuInit() on VgpuDev 214 previously, while VirtioGpuUninit() must not have 215 been called on VgpuDev. 216 217 @retval EFI_INVALID_PARAMETER Invalid command-specific parameters were 218 detected by this driver. 219 220 @retval EFI_SUCCESS Operation successful. 221 222 @retval EFI_DEVICE_ERROR The host rejected the request. The host error 223 code has been logged on the EFI_D_ERROR level. 224 225 @return Codes for unexpected errors in VirtIo 226 messaging. 227 228 For the command-specific parameters, please consult the GPU Device section of 229 the VirtIo 1.0 specification (see references in 230 "OvmfPkg/Include/IndustryStandard/VirtioGpu.h"). 231 **/ 232 EFI_STATUS 233 VirtioGpuResourceCreate2d ( 234 IN OUT VGPU_DEV *VgpuDev, 235 IN UINT32 ResourceId, 236 IN VIRTIO_GPU_FORMATS Format, 237 IN UINT32 Width, 238 IN UINT32 Height 239 ); 240 241 EFI_STATUS 242 VirtioGpuResourceUnref ( 243 IN OUT VGPU_DEV *VgpuDev, 244 IN UINT32 ResourceId 245 ); 246 247 EFI_STATUS 248 VirtioGpuResourceAttachBacking ( 249 IN OUT VGPU_DEV *VgpuDev, 250 IN UINT32 ResourceId, 251 IN VOID *FirstBackingPage, 252 IN UINTN NumberOfPages 253 ); 254 255 EFI_STATUS 256 VirtioGpuResourceDetachBacking ( 257 IN OUT VGPU_DEV *VgpuDev, 258 IN UINT32 ResourceId 259 ); 260 261 EFI_STATUS 262 VirtioGpuSetScanout ( 263 IN OUT VGPU_DEV *VgpuDev, 264 IN UINT32 X, 265 IN UINT32 Y, 266 IN UINT32 Width, 267 IN UINT32 Height, 268 IN UINT32 ScanoutId, 269 IN UINT32 ResourceId 270 ); 271 272 EFI_STATUS 273 VirtioGpuTransferToHost2d ( 274 IN OUT VGPU_DEV *VgpuDev, 275 IN UINT32 X, 276 IN UINT32 Y, 277 IN UINT32 Width, 278 IN UINT32 Height, 279 IN UINT64 Offset, 280 IN UINT32 ResourceId 281 ); 282 283 EFI_STATUS 284 VirtioGpuResourceFlush ( 285 IN OUT VGPU_DEV *VgpuDev, 286 IN UINT32 X, 287 IN UINT32 Y, 288 IN UINT32 Width, 289 IN UINT32 Height, 290 IN UINT32 ResourceId 291 ); 292 293 /** 294 Release guest-side and host-side resources that are related to an initialized 295 VGPU_GOP.Gop. 296 297 param[in,out] VgpuGop The VGPU_GOP object to release resources for. 298 299 On input, the caller is responsible for having called 300 VgpuGop->Gop.SetMode() at least once successfully. 301 (This is equivalent to the requirement that 302 VgpuGop->BackingStore be non-NULL. It is also 303 equivalent to the requirement that VgpuGop->ResourceId 304 be nonzero.) 305 306 On output, resources will be released, and 307 VgpuGop->BackingStore and VgpuGop->ResourceId will be 308 nulled. 309 310 param[in] DisableHead Whether this head (scanout) currently references the 311 resource identified by VgpuGop->ResourceId. Only pass 312 FALSE when VgpuGop->Gop.SetMode() calls this function 313 while switching between modes, and set it to TRUE 314 every other time. 315 **/ 316 VOID 317 ReleaseGopResources ( 318 IN OUT VGPU_GOP *VgpuGop, 319 IN BOOLEAN DisableHead 320 ); 321 322 // 323 // Template for initializing VGPU_GOP.Gop. 324 // 325 extern CONST EFI_GRAPHICS_OUTPUT_PROTOCOL mGopTemplate; 326 327 #endif // _VIRTIO_GPU_DXE_H_ 328
