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 //
 157 // VirtIo GPU initialization, and commands (primitives) for the GPU device.
 158 //
 159
 160 /**
 161   Configure the VirtIo GPU device that underlies VgpuDev.
 162
 163   @param[in,out] VgpuDev  The VGPU_DEV object to set up VirtIo messaging for.
 164                           On input, the caller is responsible for having
 165                           initialized VgpuDev->VirtIo. On output, VgpuDev->Ring
 166                           has been initialized, and synchronous VirtIo GPU
 167                           commands (primitives) can be submitted to the device.
 168
 169   @retval EFI_SUCCESS      VirtIo GPU configuration successful.
 170
 171   @retval EFI_UNSUPPORTED  The host-side configuration of the VirtIo GPU is not
 172                            supported by this driver.
 173
 174   @retval                  Error codes from underlying functions.
 175 **/
 176 EFI_STATUS
 177 VirtioGpuInit (
 178   IN OUT VGPU_DEV  *VgpuDev
 179   );
 180
 181 /**
 182   De-configure the VirtIo GPU device that underlies VgpuDev.
 183
 184   @param[in,out] VgpuDev  The VGPU_DEV object to tear down VirtIo messaging
 185                           for. On input, the caller is responsible for having
 186                           called VirtioGpuInit(). On output, VgpuDev->Ring has
 187                           been uninitialized; VirtIo GPU commands (primitives)
 188                           can no longer be submitted to the device.
 189 **/
 190 VOID
 191 VirtioGpuUninit (
 192   IN OUT VGPU_DEV  *VgpuDev
 193   );
 194
 195 /**
 196   Allocate, zero and map memory, for bus master common buffer operation, to be
 197   attached as backing store to a host-side VirtIo GPU resource.
 198
 199   @param[in]  VgpuDev        The VGPU_DEV object that represents the VirtIo GPU
 200                              device.
 201
 202   @param[in]  NumberOfPages  The number of whole pages to allocate and map.
 203
 204   @param[out] HostAddress    The system memory address of the allocated area.
 205
 206   @param[out] DeviceAddress  The bus master device address of the allocated
 207                              area. The VirtIo GPU device may be programmed to
 208                              access the allocated area through DeviceAddress;
 209                              DeviceAddress is to be passed to the
 210                              VirtioGpuResourceAttachBacking() function, as the
 211                              BackingStoreDeviceAddress parameter.
 212
 213   @param[out] Mapping        A resulting token to pass to
 214                              VirtioGpuUnmapAndFreeBackingStore().
 215
 216   @retval EFI_SUCCESS  The requested number of pages has been allocated, zeroed
 217                        and mapped.
 218
 219   @return              Status codes propagated from
 220                        VgpuDev->VirtIo->AllocateSharedPages() and
 221                        VirtioMapAllBytesInSharedBuffer().
 222 **/
 223 EFI_STATUS
 224 VirtioGpuAllocateZeroAndMapBackingStore (
 225   IN  VGPU_DEV              *VgpuDev,
 226   IN  UINTN                 NumberOfPages,
 227   OUT VOID                  **HostAddress,
 228   OUT EFI_PHYSICAL_ADDRESS  *DeviceAddress,
 229   OUT VOID                  **Mapping
 230   );
 231
 232 /**
 233   Unmap and free memory originally allocated and mapped with
 234   VirtioGpuAllocateZeroAndMapBackingStore().
 235
 236   If the memory allocated and mapped with
 237   VirtioGpuAllocateZeroAndMapBackingStore() was attached to a host-side VirtIo
 238   GPU resource with VirtioGpuResourceAttachBacking(), then the caller is
 239   responsible for detaching the backing store from the same resource, with
 240   VirtioGpuResourceDetachBacking(), before calling this function.
 241
 242   @param[in] VgpuDev        The VGPU_DEV object that represents the VirtIo GPU
 243                             device.
 244
 245   @param[in] NumberOfPages  The NumberOfPages parameter originally passed to
 246                             VirtioGpuAllocateZeroAndMapBackingStore().
 247
 248   @param[in] HostAddress    The HostAddress value originally output by
 249                             VirtioGpuAllocateZeroAndMapBackingStore().
 250
 251   @param[in] Mapping        The token that was originally output by
 252                             VirtioGpuAllocateZeroAndMapBackingStore().
 253 **/
 254 VOID
 255 VirtioGpuUnmapAndFreeBackingStore (
 256   IN VGPU_DEV  *VgpuDev,
 257   IN UINTN     NumberOfPages,
 258   IN VOID      *HostAddress,
 259   IN VOID      *Mapping
 260   );
 261
 262 /**
 263   EFI_EVENT_NOTIFY function for the VGPU_DEV.ExitBoot event. It resets the
 264   VirtIo device, causing it to release its resources and to forget its
 265   configuration.
 266
 267   This function may only be called (that is, VGPU_DEV.ExitBoot may only be
 268   signaled) after VirtioGpuInit() returns and before VirtioGpuUninit() is
 269   called.
 270
 271   @param[in] Event    Event whose notification function is being invoked.
 272
 273   @param[in] Context  Pointer to the associated VGPU_DEV object.
 274 **/
 275 VOID
 276 EFIAPI
 277 VirtioGpuExitBoot (
 278   IN EFI_EVENT  Event,
 279   IN VOID       *Context
 280   );
 281
 282 /**
 283   The following functions send requests to the VirtIo GPU device model, await
 284   the answer from the host, and return a status. They share the following
 285   interface details:
 286
 287   @param[in,out] VgpuDev  The VGPU_DEV object that represents the VirtIo GPU
 288                           device. The caller is responsible to have
 289                           successfully invoked VirtioGpuInit() on VgpuDev
 290                           previously, while VirtioGpuUninit() must not have
 291                           been called on VgpuDev.
 292
 293   @retval EFI_INVALID_PARAMETER  Invalid command-specific parameters were
 294                                  detected by this driver.
 295
 296   @retval EFI_SUCCESS            Operation successful.
 297
 298   @retval EFI_DEVICE_ERROR       The host rejected the request. The host error
 299                                  code has been logged on the DEBUG_ERROR level.
 300
 301   @return                        Codes for unexpected errors in VirtIo
 302                                  messaging.
 303
 304   For the command-specific parameters, please consult the GPU Device section of
 305   the VirtIo 1.0 specification (see references in
 306   "OvmfPkg/Include/IndustryStandard/VirtioGpu.h").
 307 **/
 308 EFI_STATUS
 309 VirtioGpuResourceCreate2d (
 310   IN OUT VGPU_DEV            *VgpuDev,
 311   IN     UINT32              ResourceId,
 312   IN     VIRTIO_GPU_FORMATS  Format,
 313   IN     UINT32              Width,
 314   IN     UINT32              Height
 315   );
 316
 317 EFI_STATUS
 318 VirtioGpuResourceUnref (
 319   IN OUT VGPU_DEV  *VgpuDev,
 320   IN     UINT32    ResourceId
 321   );
 322
 323 EFI_STATUS
 324 VirtioGpuResourceAttachBacking (
 325   IN OUT VGPU_DEV              *VgpuDev,
 326   IN     UINT32                ResourceId,
 327   IN     EFI_PHYSICAL_ADDRESS  BackingStoreDeviceAddress,
 328   IN     UINTN                 NumberOfPages
 329   );
 330
 331 EFI_STATUS
 332 VirtioGpuResourceDetachBacking (
 333   IN OUT VGPU_DEV  *VgpuDev,
 334   IN     UINT32    ResourceId
 335   );
 336
 337 EFI_STATUS
 338 VirtioGpuSetScanout (
 339   IN OUT VGPU_DEV  *VgpuDev,
 340   IN     UINT32    X,
 341   IN     UINT32    Y,
 342   IN     UINT32    Width,
 343   IN     UINT32    Height,
 344   IN     UINT32    ScanoutId,
 345   IN     UINT32    ResourceId
 346   );
 347
 348 EFI_STATUS
 349 VirtioGpuTransferToHost2d (
 350   IN OUT VGPU_DEV  *VgpuDev,
 351   IN     UINT32    X,
 352   IN     UINT32    Y,
 353   IN     UINT32    Width,
 354   IN     UINT32    Height,
 355   IN     UINT64    Offset,
 356   IN     UINT32    ResourceId
 357   );
 358
 359 EFI_STATUS
 360 VirtioGpuResourceFlush (
 361   IN OUT VGPU_DEV  *VgpuDev,
 362   IN     UINT32    X,
 363   IN     UINT32    Y,
 364   IN     UINT32    Width,
 365   IN     UINT32    Height,
 366   IN     UINT32    ResourceId
 367   );
 368
 369 /**
 370   Release guest-side and host-side resources that are related to an initialized
 371   VGPU_GOP.Gop.
 372
 373   param[in,out] VgpuGop  The VGPU_GOP object to release resources for.
 374
 375                          On input, the caller is responsible for having called
 376                          VgpuGop->Gop.SetMode() at least once successfully.
 377                          (This is equivalent to the requirement that
 378                          VgpuGop->BackingStore be non-NULL. It is also
 379                          equivalent to the requirement that VgpuGop->ResourceId
 380                          be nonzero.)
 381
 382                          On output, resources will be released, and
 383                          VgpuGop->BackingStore and VgpuGop->ResourceId will be
 384                          nulled.
 385
 386   param[in] DisableHead  Whether this head (scanout) currently references the
 387                          resource identified by VgpuGop->ResourceId. Only pass
 388                          FALSE when VgpuGop->Gop.SetMode() calls this function
 389                          while switching between modes, and set it to TRUE
 390                          every other time.
 391 **/
 392 VOID
 393 ReleaseGopResources (
 394   IN OUT VGPU_GOP  *VgpuGop,
 395   IN     BOOLEAN   DisableHead
 396   );
 397
 398 //
 399 // Template for initializing VGPU_GOP.Gop.
 400 //
 401 extern CONST EFI_GRAPHICS_OUTPUT_PROTOCOL  mGopTemplate;
 402
 403 #endif // _VIRTIO_GPU_DXE_H_