OvmfPkg/VirtioGpuDxe: introduce with Component Name 2 and Driver Binding

This patch adds the skeleton of the driver: it implements the Component
Name 2 Protocol and the Driver  Binding Protocol, in accordance with the
generic and GOP-specific requirements set forth in the UEFI spec and the
Driver Writers' Guide.

The basic idea is that VGPU_DEV abstracts the virtio GPU device, while the
single VGPU_GOP that we intend to support at this point stands for "head"
(aka "scanout") #0.

For now, the Virtio Device Protocol is only used for driver binding; no
actual virtio operations are done yet. Similarly, we use a "dummy" GOP
GUID and protocol structure (a plain UINT8 object) for now, so that
GOP-consuming drivers don't look at what we produce just yet.

The driver is a bit different from the other virtio device drivers written
thus far:

- It implements the GetControllerName() member of the Component Name 2
  Protocol. (Formatting helpful names is recommended by UEFI.) As a "best
  effort", we format the PCI BDF into the name (a PCI backend is not
  guaranteed by VIRTIO_DEVICE_PROTOCOL). It should provide a more friendly
  experience in the shell and elsewhere.

- This driver seeks to support all RemainingDevicePath cases:
  - NULL: produce all (= one) child handles (= VGPU_GOP heads) at once,
  - End of Device Path Node: produce no child handles,
  - specific ACPI ADR Node: check if it's supportable, and produce it
    (only one specific child controller is supported).
  This is one of the reasons for separating VGPU_GOP from VGPU_DEV.

The driver is a hybrid driver: it produces both child handles (one, to be
exact), but also installs a structure (VGPU_DEV) directly on the VirtIo
controller handle, using gEfiCallerIdGuid as protocol GUID. This is a
trick I've seen elsewhere in edk2 (for example, TerminalDxe), and it is
necessary for the following reason:

In EFI_COMPONENT_NAME2_PROTOCOL.GetControllerName(), we must be able to
"cast down" a VirtIo ControllerHandle to our own private data structure
(VGPU_DEV). That's only possible if we install the structure directly on
the VirtIo ControllerHandle (thereby rendering the driver a hybrid
driver), because a child controller with our GOP implementation on it may
not exist / be passed in there.

Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Ref: https://tianocore.acgmultimedia.com/show_bug.cgi?id=66
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
Reviewed-by: Jordan Justen <jordan.l.justen@intel.com>

1 files changed, 106 insertions, 0 deletions

diff --git a/OvmfPkg/VirtioGpuDxe/VirtioGpu.h b/OvmfPkg/VirtioGpuDxe/VirtioGpu.h
new file mode 100644
index 0000000000..ca5805df84
--- /dev/null
+++ b/OvmfPkg/VirtioGpuDxe/VirtioGpu.h
@@ -0,0 +1,106 @@
+/** @file

+

+  Internal type and macro definitions for the Virtio GPU hybrid driver.

+

+  Copyright (C) 2016, Red Hat, Inc.

+

+  This program and the accompanying materials are licensed and made available

+  under the terms and conditions of the BSD License which accompanies this

+  distribution. The full text of the license may be found at

+  http://opensource.org/licenses/bsd-license.php

+

+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT

+  WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

+

+**/

+

+#ifndef _VIRTIO_GPU_DXE_H_

+#define _VIRTIO_GPU_DXE_H_

+

+#include <Library/DebugLib.h>

+#include <Library/UefiLib.h>

+#include <Protocol/VirtioDevice.h>

+

+//

+// Forward declaration of VGPU_GOP.

+//

+typedef struct VGPU_GOP_STRUCT VGPU_GOP;

+

+//

+// The abstraction that directly corresponds to a Virtio GPU device.

+//

+// This structure will be installed on the handle that has the VirtIo Device

+// Protocol interface, with GUID gEfiCallerIdGuid. A similar trick is employed

+// in TerminalDxe, and it is necessary so that we can look up VGPU_DEV just

+// from the VirtIo Device Protocol handle in the Component Name 2 Protocol

+// implementation.

+//

+typedef struct {

+  //

+  // VirtIo represents access to the Virtio GPU device. Never NULL.

+  //

+  VIRTIO_DEVICE_PROTOCOL   *VirtIo;

+

+  //

+  // BusName 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 *BusName;

+

+  //

+  // The Child field references the GOP wrapper structure. If this pointer is

+  // NULL, then the hybrid driver has bound (i.e., started) the

+  // VIRTIO_DEVICE_PROTOCOL controller without producing the child GOP

+  // controller (that is, after Start() was called with RemainingDevicePath

+  // pointing to and End of Device Path node). Child can be created and

+  // destroyed, even repeatedly, independently of VGPU_DEV.

+  //

+  // In practice, this field represents the single head (scanout) that we

+  // support.

+  //

+  VGPU_GOP                 *Child;

+} VGPU_DEV;

+

+//

+// The Graphics Output Protocol wrapper structure.

+//

+#define VGPU_GOP_SIG SIGNATURE_64 ('V', 'G', 'P', 'U', '_', 'G', 'O', 'P')

+

+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.

+  //

+  // For now it is just a placeholder.

+  //

+  UINT8                                Gop;

+};

+

+#endif // _VIRTIO_GPU_DXE_H_