1 /** @file
2 
3   Virtio GPU Device specific type and macro definitions.
4 
5   At the time of this writing, the Virtio 1.0 specification has not
6   incorporated the GPU device yet. The following work-in-progress specification
7   is used as basis for the implementation:
8 
9   - https://lists.oasis-open.org/archives/virtio-dev/201605/msg00002.html
10   - https://www.kraxel.org/virtio/
11 
12   This header file is minimal, and only defines the types and macros that are
13   necessary for the OvmfPkg implementation.
14 
15   Copyright (C) 2016, Red Hat, Inc.
16 
17   SPDX-License-Identifier: BSD-2-Clause-Patent
18 
19 **/
20 
21 #ifndef _VIRTIO_GPU_H_
22 #define _VIRTIO_GPU_H_
23 
24 #include <IndustryStandard/Virtio.h>
25 
26 //
27 // Queue number for sending control commands.
28 //
29 #define VIRTIO_GPU_CONTROL_QUEUE 0
30 
31 //
32 // Command and response types.
33 //
34 typedef enum {
35   //
36   // Commands related to mode setup:
37   //
38   // - create/release a host-side 2D resource,
39   //
40   VirtioGpuCmdResourceCreate2d      = 0x0101,
41   VirtioGpuCmdResourceUnref         = 0x0102,
42   //
43   // - attach/detach guest RAM to/from a host-side 2D resource,
44   //
45   VirtioGpuCmdResourceAttachBacking = 0x0106,
46   VirtioGpuCmdResourceDetachBacking = 0x0107,
47   //
48   // - assign/unassign a host-side 2D resource to/from a scanout ("head").
49   //
50   VirtioGpuCmdSetScanout            = 0x0103,
51 
52   //
53   // Commands related to drawing:
54   //
55   // - transfer a guest RAM update to the host-side 2D resource (does not imply
56   //   host display refresh),
57   //
58   VirtioGpuCmdTransferToHost2d      = 0x0105,
59   //
60   // - trigger a host display refresh from the 2D resource.
61   //
62   VirtioGpuCmdResourceFlush         = 0x0104,
63 
64   //
65   // Success code for all of the above commands.
66   //
67   VirtioGpuRespOkNodata             = 0x1100,
68 } VIRTIO_GPU_CONTROL_TYPE;
69 
70 //
71 // Common request/response header.
72 //
73 #define VIRTIO_GPU_FLAG_FENCE BIT0
74 
75 #pragma pack (1)
76 typedef struct {
77   //
78   // The guest sets Type to VirtioGpuCmd* in the requests. The host sets Type
79   // to VirtioGpuResp* in the responses.
80   //
81   UINT32 Type;
82 
83   //
84   // Fencing forces the host to complete the command before producing a
85   // response.
86   //
87   UINT32 Flags;
88   UINT64 FenceId;
89 
90   //
91   // Unused.
92   //
93   UINT32 CtxId;
94   UINT32 Padding;
95 } VIRTIO_GPU_CONTROL_HEADER;
96 #pragma pack ()
97 
98 //
99 // Rectangle structure used by several operations.
100 //
101 #pragma pack (1)
102 typedef struct {
103   UINT32 X;
104   UINT32 Y;
105   UINT32 Width;
106   UINT32 Height;
107 } VIRTIO_GPU_RECTANGLE;
108 #pragma pack ()
109 
110 //
111 // Request structure for VirtioGpuCmdResourceCreate2d.
112 //
113 typedef enum {
114   //
115   // 32-bit depth, BGRX component order, X component ignored.
116   //
117   VirtioGpuFormatB8G8R8X8Unorm = 2,
118 } VIRTIO_GPU_FORMATS;
119 
120 #pragma pack (1)
121 typedef struct {
122   VIRTIO_GPU_CONTROL_HEADER Header;
123   UINT32                    ResourceId; // note: 0 is invalid
124   UINT32                    Format;     // from VIRTIO_GPU_FORMATS
125   UINT32                    Width;
126   UINT32                    Height;
127 } VIRTIO_GPU_RESOURCE_CREATE_2D;
128 #pragma pack ()
129 
130 //
131 // Request structure for VirtioGpuCmdResourceUnref.
132 //
133 #pragma pack (1)
134 typedef struct {
135   VIRTIO_GPU_CONTROL_HEADER Header;
136   UINT32                    ResourceId;
137   UINT32                    Padding;
138 } VIRTIO_GPU_RESOURCE_UNREF;
139 #pragma pack ()
140 
141 //
142 // Request structure for VirtioGpuCmdResourceAttachBacking.
143 //
144 // The spec allows for a scatter-gather list, but for simplicity we hard-code a
145 // single guest buffer.
146 //
147 #pragma pack (1)
148 typedef struct {
149   UINT64 Addr;
150   UINT32 Length;
151   UINT32 Padding;
152 } VIRTIO_GPU_MEM_ENTRY;
153 
154 typedef struct {
155   VIRTIO_GPU_CONTROL_HEADER Header;
156   UINT32                    ResourceId;
157   UINT32                    NrEntries;  // number of entries: constant 1
158   VIRTIO_GPU_MEM_ENTRY      Entry;
159 } VIRTIO_GPU_RESOURCE_ATTACH_BACKING;
160 #pragma pack ()
161 
162 //
163 // Request structure for VirtioGpuCmdResourceDetachBacking.
164 //
165 #pragma pack (1)
166 typedef struct {
167   VIRTIO_GPU_CONTROL_HEADER Header;
168   UINT32                    ResourceId;
169   UINT32                    Padding;
170 } VIRTIO_GPU_RESOURCE_DETACH_BACKING;
171 #pragma pack ()
172 
173 //
174 // Request structure for VirtioGpuCmdSetScanout.
175 //
176 #pragma pack (1)
177 typedef struct {
178   VIRTIO_GPU_CONTROL_HEADER Header;
179   VIRTIO_GPU_RECTANGLE      Rectangle;
180   UINT32                    ScanoutId;
181   UINT32                    ResourceId;
182 } VIRTIO_GPU_SET_SCANOUT;
183 #pragma pack ()
184 
185 //
186 // Request structure for VirtioGpuCmdTransferToHost2d.
187 //
188 #pragma pack (1)
189 typedef struct {
190   VIRTIO_GPU_CONTROL_HEADER Header;
191   VIRTIO_GPU_RECTANGLE      Rectangle;
192   UINT64                    Offset;
193   UINT32                    ResourceId;
194   UINT32                    Padding;
195 }  VIRTIO_GPU_CMD_TRANSFER_TO_HOST_2D;
196 #pragma pack ()
197 
198 //
199 // Request structure for VirtioGpuCmdResourceFlush.
200 //
201 #pragma pack (1)
202 typedef struct {
203   VIRTIO_GPU_CONTROL_HEADER Header;
204   VIRTIO_GPU_RECTANGLE      Rectangle;
205   UINT32                    ResourceId;
206   UINT32                    Padding;
207 } VIRTIO_GPU_RESOURCE_FLUSH;
208 #pragma pack ()
209 
210 #endif // _VIRTIO_GPU_H_
211