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