[PATCH 5/6] OvmfPkg/VirtioGpuDxe: map backing store to bus master device address

[Laszlo Ersek <lersek@redhat.com>]

VirtioGpuDxe is a UEFI Bus driver (not a Device driver). This is because a
UEFI graphics driver is expected to produce its GraphicsOutput protocol
instance(s) on new child handle(s) of the video controller handle, one
child handle (plus GOP) per video output (or, one child handle plus GOP
per combination of multiple video outputs).

In VirtioGpuDxe, we support a single VirtIo GPU head (scanout), namely
head#0. This means that, with regard to a specific VirtIo GPU device, the
driver may be in one of three states, at any time:

[1] VirtioGpuDxe has not bound the device at all,

[2] VirtioGpuDxe has bound the device, but not produced the sole child
    handle for head#0,

[3] VirtioGpuDxe has bound the device, and produced the sole child handle
    for head#0, with a GOP instance on the child handle.

(Which state the driver is in wrt. a given VirtIo GPU device depends on
the VirtioGpuDriverBindingStart() / VirtioGpuDriverBindingStop()
invocations issued by the ConnectController() / DisconnectController()
boot services. In turn those come from BDS or e.g. the UEFI shell.)

The concept of "current video mode" is technically tied to the GOP (i.e.,
the child handle, state [3] only), not the VirtIo GPU controller handle.
This is why we manage the storage that backs the current video mode in our
EFI_GRAPHICS_OUTPUT_PROTOCOL.SetMode() member implementation.

GopSetMode() is first called *internally*, when we enter state [3] (that
is, when we produce the child handle + GOP on it):

  VirtioGpuDriverBindingStart() [DriverBinding.c]
    InitVgpuGop()               [DriverBinding.c]
      VgpuGop->Gop.SetMode()    [Gop.c]

When this happens, we allocate the backing store *without* having a
preexistent backing store (due to no preexistent video mode and GOP).
Skipping VirtIo GPU details not relevant for this patch, we just note that
the backing store is exposed *permanently* to the VirtIo GPU device, with
the RESOURCE_ATTACH_BACKING command.

When external clients call the EFI_GRAPHICS_OUTPUT_PROTOCOL.Blt() member
function -- called GopBlt() in this driver --, in state [3], the function
operates on the backing store, and sends only small messages to the VirtIo
GPU device.

When external clients call GopSetMode() for switching between video modes
-- in state [3] --, then

- a new backing store is allocated and exposed to the device (attached to
  a new host-side VirtIo GPU resource),

- head#0 is flipped to the new backing store,

- on success, the ReleaseGopResources() function both detaches the
  previous backing store from the VirtIo GPU device, an releases it. The
  new backing store address and size are saved in our GOP object. (In
  other words, we "commit" to the new video mode.)

When the DisconnectController() boot service asks us to leave state [3] --
we can leave it directly only for state [2] --, then the
ReleaseGopResources() function is called on a different path:

  VirtioGpuDriverBindingStop() [DriverBinding.c]
    UninitVgpuGop()            [DriverBinding.c]
      ReleaseGopResources()    [Gop.c]

In this case, the backing store being released is still in use (we're not
leaving it for a new mode -- head#0 has not been flipped "away" from it),
so in ReleaseGopResources() we disable head#0 first.

(The ReleaseGopResources() function is called the same way on the error
path in InitVgpuGop(), if the first -- internal -- VgpuGop->Gop.SetMode()
call succeeds, but the rest of InitVgpuGop() fails.)

Based on the above, for IOMMU-compatibility,

- in GopSetMode(), don't just allocate, but also map the backing store of
  the nascent video mode to a device address, for bus master common buffer
  operation,

- (the VirtioGpuAllocateZeroAndMapBackingStore() helper function
  introduced in the last patch takes care of zeroing internally,)

- pass the device address to the VirtIo GPU device in the
  RESOURCE_ATTACH_BACKING command,

- if GopSetMode() succeeds, save the mapping token,

- if GopSetMode() fails, don't just free but also unmap the still-born
  backing store,

- in ReleaseGopResources(), don't just free but also unmap the backing
  store -- which is the previous backing store if we're mode-switching,
  and the current backing store if we're leaving state [3].

Finally, ExitBootServices() may be called when the driver is in either
state [1], [2] or [3], wrt. a given VirtIo GPU device. (Of course we are
only notified in states [2] and [3].) If we get the notification in state
[3], then the current video mode's backing store has to be unmapped, but
not released. (We must not change the UEFI memory map.)

Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Cc: Brijesh Singh <brijesh.singh@amd.com>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Cc: Tom Lendacky <thomas.lendacky@amd.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
---
 OvmfPkg/VirtioGpuDxe/VirtioGpu.h |  7 +++
 OvmfPkg/VirtioGpuDxe/Commands.c  | 21 ++++++++
 OvmfPkg/VirtioGpuDxe/Gop.c       | 55 +++++++++++++-------
 3 files changed, 64 insertions(+), 19 deletions(-)

diff --git a/OvmfPkg/VirtioGpuDxe/VirtioGpu.h b/OvmfPkg/VirtioGpuDxe/VirtioGpu.h
index 65b1bd6088b8..73893ccb56eb 100644
--- a/OvmfPkg/VirtioGpuDxe/VirtioGpu.h
+++ b/OvmfPkg/VirtioGpuDxe/VirtioGpu.h
@@ -94,80 +94,87 @@ typedef struct {
 struct VGPU_GOP_STRUCT {
   UINT64                               Signature;
 
   //
   // ParentBus points to the parent VGPU_DEV object. Never NULL.
   //
   VGPU_DEV                             *ParentBus;
 
   //
   // GopName carries a customized name for
   // EFI_COMPONENT_NAME2_PROTOCOL.GetControllerName(). It is expressed in table
   // form because it can theoretically support several languages. Never NULL.
   //
   EFI_UNICODE_STRING_TABLE             *GopName;
 
   //
   // GopHandle is the UEFI child handle that carries the device path ending
   // with the ACPI ADR node, and the Graphics Output Protocol. Never NULL.
   //
   EFI_HANDLE                           GopHandle;
 
   //
   // The GopDevicePath field is the device path installed on GopHandle,
   // ending with an ACPI ADR node. Never NULL.
   //
   EFI_DEVICE_PATH_PROTOCOL             *GopDevicePath;
 
   //
   // The Gop field is installed on the child handle as Graphics Output Protocol
   // interface.
   //
   EFI_GRAPHICS_OUTPUT_PROTOCOL         Gop;
 
   //
   // Referenced by Gop.Mode, GopMode provides a summary about the supported
   // graphics modes, and the current mode.
   //
   EFI_GRAPHICS_OUTPUT_PROTOCOL_MODE    GopMode;
 
   //
   // Referenced by GopMode.Info, GopModeInfo provides detailed information
   // about the current mode.
   //
   EFI_GRAPHICS_OUTPUT_MODE_INFORMATION GopModeInfo;
 
   //
   // Identifier of the 2D host resource that is in use by this head (scanout)
   // of the VirtIo GPU device. Zero until the first successful -- internal --
   // Gop.SetMode() call, never zero afterwards.
   //
   UINT32                               ResourceId;
 
   //
   // A number of whole pages providing the backing store for the 2D host
   // resource identified by ResourceId above. NULL until the first successful
   // -- internal -- Gop.SetMode() call, never NULL afterwards.
   //
   UINT32                               *BackingStore;
   UINTN                                NumberOfPages;
+
+  //
+  // Token associated with BackingStore's mapping for bus master common
+  // buffer operation. BackingStoreMap is valid if, and only if,
+  // BackingStore is non-NULL.
+  //
+  VOID                                 *BackingStoreMap;
 };
 
 //
 // VirtIo GPU initialization, and commands (primitives) for the GPU device.
 //
 /**
   Configure the VirtIo GPU device that underlies VgpuDev.
 
   @param[in,out] VgpuDev  The VGPU_DEV object to set up VirtIo messaging for.
                           On input, the caller is responsible for having
                           initialized VgpuDev->VirtIo. On output, VgpuDev->Ring
                           has been initialized, and synchronous VirtIo GPU
                           commands (primitives) can be submitted to the device.
 
   @retval EFI_SUCCESS      VirtIo GPU configuration successful.
 
   @retval EFI_UNSUPPORTED  The host-side configuration of the VirtIo GPU is not
                            supported by this driver.
 
   @retval                  Error codes from underlying functions.
 **/
diff --git a/OvmfPkg/VirtioGpuDxe/Commands.c b/OvmfPkg/VirtioGpuDxe/Commands.c
index 595a3717d926..db5bdbca4bee 100644
--- a/OvmfPkg/VirtioGpuDxe/Commands.c
+++ b/OvmfPkg/VirtioGpuDxe/Commands.c
@@ -349,55 +349,76 @@ EFIAPI
 VirtioGpuExitBoot (
   IN EFI_EVENT Event,
   IN VOID      *Context
   )
 {
   VGPU_DEV *VgpuDev;
 
   VgpuDev = Context;
   VgpuDev->VirtIo->SetDeviceStatus (VgpuDev->VirtIo, 0);
+
+  //
+  // If VirtioGpuDriverBindingStart() and VirtioGpuDriverBindingStop() have
+  // been called thus far in such a sequence that right now our (sole) child
+  // handle exists -- with the GOP on it standing for head (scanout) #0 --,
+  // then we have to unmap the current video mode's backing store.
+  //
+  if (VgpuDev->Child != NULL) {
+    //
+    // The current video mode is guaranteed to have a valid and mapped backing
+    // store, due to the first Gop.SetMode() call, made internally in
+    // InitVgpuGop().
+    //
+    ASSERT (VgpuDev->Child->BackingStore != NULL);
+
+    VgpuDev->VirtIo->UnmapSharedBuffer (
+                       VgpuDev->VirtIo,
+                       VgpuDev->Child->BackingStoreMap
+                       );
+  }
+
   VgpuDev->VirtIo->UnmapSharedBuffer (VgpuDev->VirtIo, VgpuDev->RingMap);
 }
 
 /**
   Internal utility function that sends a request to the VirtIo GPU device
   model, awaits the answer from the host, and returns a status.
 
   @param[in,out] VgpuDev  The VGPU_DEV object that represents the VirtIo GPU
                           device. The caller is responsible to have
                           successfully invoked VirtioGpuInit() on VgpuDev
                           previously, while VirtioGpuUninit() must not have
                           been called on VgpuDev.
 
   @param[in] RequestType  The type of the request. The caller is responsible
                           for providing a VirtioGpuCmd* RequestType which, on
                           success, elicits a VirtioGpuRespOkNodata response
                           from the host.
 
   @param[in] Fence        Whether to enable fencing for this request. Fencing
                           forces the host to complete the command before
                           producing a response. If Fence is TRUE, then
                           VgpuDev->FenceId is consumed, and incremented.
 
   @param[in,out] Header   Pointer to the caller-allocated request object. The
                           request must start with VIRTIO_GPU_CONTROL_HEADER.
                           This function overwrites all fields of Header before
                           submitting the request to the host:
 
                           - it sets Type from RequestType,
 
                           - it sets Flags and FenceId based on Fence,
 
                           - it zeroes CtxId and Padding.
 
   @param[in] RequestSize  Size of the entire caller-allocated request object,
                           including the leading VIRTIO_GPU_CONTROL_HEADER.
 
   @retval EFI_SUCCESS            Operation successful.
 
   @retval EFI_DEVICE_ERROR       The host rejected the request. The host error
                                  code has been logged on the EFI_D_ERROR level.
 
   @return                        Codes for unexpected errors in VirtIo
                                  messaging, or request/response
                                  mapping/unmapping.
 **/
diff --git a/OvmfPkg/VirtioGpuDxe/Gop.c b/OvmfPkg/VirtioGpuDxe/Gop.c
index 507e1a770d10..936e181e8a87 100644
--- a/OvmfPkg/VirtioGpuDxe/Gop.c
+++ b/OvmfPkg/VirtioGpuDxe/Gop.c
@@ -45,95 +45,101 @@ VOID
 ReleaseGopResources (
   IN OUT VGPU_GOP *VgpuGop,
   IN     BOOLEAN  DisableHead
   )
 {
   EFI_STATUS Status;
 
   ASSERT (VgpuGop->ResourceId != 0);
   ASSERT (VgpuGop->BackingStore != NULL);
 
   //
   // If any of the following host-side destruction steps fail, we can't get out
   // of an inconsistent state, so we'll hang. In general errors in object
   // destruction can hardly be recovered from.
   //
   if (DisableHead) {
     //
     // Dissociate head (scanout) #0 from the currently used 2D host resource,
     // by setting ResourceId=0 for it.
     //
     Status = VirtioGpuSetScanout (
                VgpuGop->ParentBus, // VgpuDev
                0, 0, 0, 0,         // X, Y, Width, Height
                0,                  // ScanoutId
                0                   // ResourceId
                );
     //
     // HACK BEGINS HERE
     //
     // According to the GPU Device section of the VirtIo specification, the
     // above operation is valid:
     //
     // "The driver can use resource_id = 0 to disable a scanout."
     //
     // However, in practice QEMU does not allow us to disable head (scanout) #0
     // -- it rejects the command with response code 0x1202
     // (VIRTIO_GPU_RESP_ERR_INVALID_SCANOUT_ID). Looking at the QEMU source
     // code, function virtio_gpu_set_scanout() in "hw/display/virtio-gpu.c",
     // this appears fully intentional, despite not being documented in the
     // spec.
     //
     // Surprisingly, ignoring the error here, and proceeding to release
     // host-side resources that presumably underlie head (scanout) #0, work
     // without any problems -- the driver survives repeated "disconnect" /
     // "connect -r" commands in the UEFI shell.
     //
     // So, for now, let's just suppress the error.
     //
     Status = EFI_SUCCESS;
     //
     // HACK ENDS HERE
     //
 
     ASSERT_EFI_ERROR (Status);
     if (EFI_ERROR (Status)) {
       CpuDeadLoop ();
     }
   }
 
   //
   // Detach backing pages from the currently used 2D host resource.
   //
   Status = VirtioGpuResourceDetachBacking (
              VgpuGop->ParentBus, // VgpuDev
              VgpuGop->ResourceId // ResourceId
              );
   ASSERT_EFI_ERROR (Status);
   if (EFI_ERROR (Status)) {
     CpuDeadLoop ();
   }
 
   //
-  // Release backing pages.
+  // Unmap and release backing pages.
   //
-  FreePages (VgpuGop->BackingStore, VgpuGop->NumberOfPages);
+  VirtioGpuUnmapAndFreeBackingStore (
+    VgpuGop->ParentBus,      // VgpuDev
+    VgpuGop->NumberOfPages,  // NumberOfPages
+    VgpuGop->BackingStore,   // HostAddress
+    VgpuGop->BackingStoreMap // Mapping
+    );
   VgpuGop->BackingStore  = NULL;
   VgpuGop->NumberOfPages = 0;
+  VgpuGop->BackingStoreMap = NULL;
 
   //
   // Destroy the currently used 2D host resource.
   //
   Status = VirtioGpuResourceUnref (
              VgpuGop->ParentBus, // VgpuDev
              VgpuGop->ResourceId // ResourceId
              );
   ASSERT_EFI_ERROR (Status);
   if (EFI_ERROR (Status)) {
     CpuDeadLoop ();
   }
   VgpuGop->ResourceId = 0;
 }
 
 //
 // The resolutions supported by this driver.
 //
@@ -228,176 +234,182 @@ EFIAPI
 GopSetMode (
   IN  EFI_GRAPHICS_OUTPUT_PROTOCOL *This,
   IN  UINT32                       ModeNumber
   )
 {
-  VGPU_GOP   *VgpuGop;
-  UINT32     NewResourceId;
-  UINTN      NewNumberOfBytes;
-  UINTN      NewNumberOfPages;
-  VOID       *NewBackingStore;
+  VGPU_GOP             *VgpuGop;
+  UINT32               NewResourceId;
+  UINTN                NewNumberOfBytes;
+  UINTN                NewNumberOfPages;
+  VOID                 *NewBackingStore;
+  EFI_PHYSICAL_ADDRESS NewBackingStoreDeviceAddress;
+  VOID                 *NewBackingStoreMap;
+
   EFI_STATUS Status;
   EFI_STATUS Status2;
 
   if (ModeNumber >= ARRAY_SIZE (mGopResolutions)) {
     return EFI_UNSUPPORTED;
   }
 
   VgpuGop = VGPU_GOP_FROM_GOP (This);
 
   //
   // Distinguish the first (internal) call from the other (protocol consumer)
   // calls.
   //
   if (VgpuGop->ResourceId == 0) {
     //
     // Set up the Gop -> GopMode -> GopModeInfo pointer chain, and the other
     // (nonzero) constant fields.
     //
     // No direct framebuffer access is supported, only Blt() is.
     //
     VgpuGop->Gop.Mode = &VgpuGop->GopMode;
 
     VgpuGop->GopMode.MaxMode         = (UINT32)(ARRAY_SIZE (mGopResolutions));
     VgpuGop->GopMode.Info            = &VgpuGop->GopModeInfo;
     VgpuGop->GopMode.SizeOfInfo      = sizeof VgpuGop->GopModeInfo;
 
     VgpuGop->GopModeInfo.PixelFormat = PixelBltOnly;
 
     //
     // This is the first time we create a host side resource.
     //
     NewResourceId = 1;
   } else {
     //
     // We already have an active host side resource. Create the new one without
     // interfering with the current one, so that we can cleanly bail out on
     // error, without disturbing the current graphics mode.
     //
     // The formula below will alternate between IDs 1 and 2.
     //
     NewResourceId = 3 - VgpuGop->ResourceId;
   }
 
   //
   // Create the 2D host resource.
   //
   Status = VirtioGpuResourceCreate2d (
              VgpuGop->ParentBus,                // VgpuDev
              NewResourceId,                     // ResourceId
              VirtioGpuFormatB8G8R8X8Unorm,      // Format
              mGopResolutions[ModeNumber].Width, // Width
              mGopResolutions[ModeNumber].Height // Height
              );
   if (EFI_ERROR (Status)) {
     return Status;
   }
 
   //
-  // Allocate guest backing store.
+  // Allocate, zero and map guest backing store, for bus master common buffer
+  // operation.
   //
   NewNumberOfBytes = mGopResolutions[ModeNumber].Width *
                      mGopResolutions[ModeNumber].Height * sizeof (UINT32);
   NewNumberOfPages = EFI_SIZE_TO_PAGES (NewNumberOfBytes);
-  NewBackingStore = AllocatePages (NewNumberOfPages);
-  if (NewBackingStore == NULL) {
-    Status = EFI_OUT_OF_RESOURCES;
+  Status = VirtioGpuAllocateZeroAndMapBackingStore (
+             VgpuGop->ParentBus,            // VgpuDev
+             NewNumberOfPages,              // NumberOfPages
+             &NewBackingStore,              // HostAddress
+             &NewBackingStoreDeviceAddress, // DeviceAddress
+             &NewBackingStoreMap            // Mapping
+             );
+  if (EFI_ERROR (Status)) {
     goto DestroyHostResource;
   }
-  //
-  // Fill visible part of backing store with black.
-  //
-  ZeroMem (NewBackingStore, NewNumberOfBytes);
 
   //
   // Attach backing store to the host resource.
   //
   Status = VirtioGpuResourceAttachBacking (
              VgpuGop->ParentBus,           // VgpuDev
              NewResourceId,                // ResourceId
-             (UINTN)NewBackingStore,       // BackingStoreDeviceAddress
+             NewBackingStoreDeviceAddress, // BackingStoreDeviceAddress
              NewNumberOfPages              // NumberOfPages
              );
   if (EFI_ERROR (Status)) {
-    goto FreeBackingStore;
+    goto UnmapAndFreeBackingStore;
   }
 
   //
   // Point head (scanout) #0 to the host resource.
   //
   Status = VirtioGpuSetScanout (
              VgpuGop->ParentBus,                 // VgpuDev
              0,                                  // X
              0,                                  // Y
              mGopResolutions[ModeNumber].Width,  // Width
              mGopResolutions[ModeNumber].Height, // Height
              0,                                  // ScanoutId
              NewResourceId                       // ResourceId
              );
   if (EFI_ERROR (Status)) {
     goto DetachBackingStore;
   }
 
   //
   // If this is not the first (i.e., internal) call, then we have to (a) flush
   // the new resource to head (scanout) #0, after having flipped the latter to
   // the former above, plus (b) release the old resources.
   //
   if (VgpuGop->ResourceId != 0) {
     Status = VirtioGpuResourceFlush (
                VgpuGop->ParentBus,                 // VgpuDev
                0,                                  // X
                0,                                  // Y
                mGopResolutions[ModeNumber].Width,  // Width
                mGopResolutions[ModeNumber].Height, // Height
                NewResourceId                       // ResourceId
                );
     if (EFI_ERROR (Status)) {
       //
       // Flip head (scanout) #0 back to the current resource. If this fails, we
       // cannot continue, as this error occurs on the error path and is
       // therefore non-recoverable.
       //
       Status2 = VirtioGpuSetScanout (
                   VgpuGop->ParentBus,                       // VgpuDev
                   0,                                        // X
                   0,                                        // Y
                   mGopResolutions[This->Mode->Mode].Width,  // Width
                   mGopResolutions[This->Mode->Mode].Height, // Height
                   0,                                        // ScanoutId
                   VgpuGop->ResourceId                       // ResourceId
                   );
       ASSERT_EFI_ERROR (Status2);
       if (EFI_ERROR (Status2)) {
         CpuDeadLoop ();
       }
       goto DetachBackingStore;
     }
 
     //
     // Flush successful; release the old resources (without disabling head
     // (scanout) #0).
     //
     ReleaseGopResources (VgpuGop, FALSE /* DisableHead */);
   }
 
   //
   // This is either the first (internal) call when we have no old resources
   // yet, or we've changed the mode successfully and released the old
   // resources.
   //
   ASSERT (VgpuGop->ResourceId == 0);
   ASSERT (VgpuGop->BackingStore == NULL);
 
   VgpuGop->ResourceId = NewResourceId;
   VgpuGop->BackingStore = NewBackingStore;
   VgpuGop->NumberOfPages = NewNumberOfPages;
+  VgpuGop->BackingStoreMap = NewBackingStoreMap;
 
   //
   // Populate Mode and ModeInfo (mutable fields only).
   //
   VgpuGop->GopMode.Mode = ModeNumber;
   VgpuGop->GopModeInfo.HorizontalResolution =
                                              mGopResolutions[ModeNumber].Width;
   VgpuGop->GopModeInfo.VerticalResolution = mGopResolutions[ModeNumber].Height;
   VgpuGop->GopModeInfo.PixelsPerScanLine = mGopResolutions[ModeNumber].Width;
   return EFI_SUCCESS;
@@ -409,8 +421,13 @@ DetachBackingStore:
     CpuDeadLoop ();
   }
 
-FreeBackingStore:
-  FreePages (NewBackingStore, NewNumberOfPages);
+UnmapAndFreeBackingStore:
+  VirtioGpuUnmapAndFreeBackingStore (
+    VgpuGop->ParentBus, // VgpuDev
+    NewNumberOfPages,   // NumberOfPages
+    NewBackingStore,    // HostAddress
+    NewBackingStoreMap  // Mapping
+    );
 
 DestroyHostResource:
   Status2 = VirtioGpuResourceUnref (VgpuGop->ParentBus, NewResourceId);
-- 
2.14.1.3.gb7cf6e02401b