OvmfPkg/VirtioGpuDxe: map backing store to bus master device address
    
    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>
    Tested-by: Brijesh Singh <brijesh.singh@amd.com>