[mirror_edk2.git] / OvmfPkg / VirtioGpuDxe / VirtioGpu.h

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