]> git.proxmox.com Git - mirror_edk2.git/blame - OvmfPkg/VirtioBlkDxe/VirtioBlk.h
OvmfPkg: move VirtioBlkDxe/Virtio.h to Include/IndustryStandard/Virtio.h
[mirror_edk2.git] / OvmfPkg / VirtioBlkDxe / VirtioBlk.h
CommitLineData
fd51d759 1/** @file\r
2\r
3 Internal definitions for the virtio-blk driver, which produces Block I/O\r
4 Protocol instances for virtio-blk devices.\r
5\r
6 Copyright (C) 2012, Red Hat, Inc.\r
7\r
8 This program and the accompanying materials are licensed and made available\r
9 under the terms and conditions of the BSD License which accompanies this\r
10 distribution. The full text of the license may be found at\r
11 http://opensource.org/licenses/bsd-license.php\r
12\r
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT\r
14 WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
15\r
16**/\r
17\r
936e3a5d 18#ifndef _VIRTIO_BLK_DXE_H_\r
19#define _VIRTIO_BLK_DXE_H_\r
20\r
fd51d759 21#include <Protocol/BlockIo.h>\r
22#include <Protocol/ComponentName.h>\r
23#include <Protocol/DriverBinding.h>\r
24#include <Protocol/PciIo.h>\r
25\r
045b46e9 26#include <IndustryStandard/Virtio.h>\r
fd51d759 27\r
28\r
29#define VBLK_SIG SIGNATURE_32 ('V', 'B', 'L', 'K')\r
30\r
31typedef struct {\r
32 //\r
33 // Parts of this structure are initialized / torn down in various functions\r
34 // at various call depths. The table to the right should make it easier to\r
35 // track them.\r
36 //\r
37 // field init function init dpth\r
38 // ---------------------- ------------------ ---------\r
39 UINT32 Signature; // DriverBindingStart 0\r
40 EFI_PCI_IO_PROTOCOL *PciIo; // DriverBindingStart 0\r
41 UINT64 OriginalPciAttributes; // DriverBindingStart 0\r
42 VRING Ring; // VirtioRingInit 2\r
43 EFI_BLOCK_IO_PROTOCOL BlockIo; // VirtioBlkInit 1\r
44 EFI_BLOCK_IO_MEDIA BlockIoMedia; // VirtioBlkInit 1\r
45} VBLK_DEV;\r
46\r
47#define VIRTIO_BLK_FROM_BLOCK_IO(BlockIoPointer) \\r
48 CR (BlockIoPointer, VBLK_DEV, BlockIo, VBLK_SIG)\r
49\r
50\r
51/**\r
52\r
53 Device probe function for this driver.\r
54\r
55 The DXE core calls this function for any given device in order to see if the\r
56 driver can drive the device.\r
57\r
58 Specs relevant in the general sense:\r
59\r
60 - UEFI Spec 2.3.1 + Errata C:\r
61 - 6.3 Protocol Handler Services -- for accessing the underlying device\r
62 - 10.1 EFI Driver Binding Protocol -- for exporting ourselves\r
63\r
64 - Driver Writer's Guide for UEFI 2.3.1 v1.01:\r
65 - 5.1.3.4 OpenProtocol() and CloseProtocol() -- for accessing the\r
66 underlying device\r
67 - 9 Driver Binding Protocol -- for exporting ourselves\r
68\r
69 Specs relevant in the specific sense:\r
70 - UEFI Spec 2.3.1 + Errata C, 13.4 EFI PCI I/O Protocol\r
71 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 18 PCI Driver Design\r
72 Guidelines, 18.3 PCI drivers.\r
73\r
74 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object\r
75 incorporating this driver (independently of\r
76 any device).\r
77\r
78 @param[in] DeviceHandle The device to probe.\r
79\r
80 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.\r
81\r
82\r
83 @retval EFI_SUCCESS The driver supports the device being probed.\r
84\r
85 @retval EFI_UNSUPPORTED Based on virtio-blk PCI discovery, we do not support\r
86 the device.\r
87\r
88 @return Error codes from the OpenProtocol() boot service or\r
89 the PciIo protocol.\r
90\r
91**/\r
92\r
93EFI_STATUS\r
94EFIAPI\r
95VirtioBlkDriverBindingSupported (\r
96 IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
97 IN EFI_HANDLE DeviceHandle,\r
98 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
99 );\r
100\r
101\r
102/**\r
103\r
104 After we've pronounced support for a specific device in\r
105 DriverBindingSupported(), we start managing said device (passed in by the\r
106 Driver Exeuction Environment) with the following service.\r
107\r
108 See DriverBindingSupported() for specification references.\r
109\r
110 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object\r
111 incorporating this driver (independently of\r
112 any device).\r
113\r
114 @param[in] DeviceHandle The supported device to drive.\r
115\r
116 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.\r
117\r
118\r
119 @retval EFI_SUCCESS Driver instance has been created and\r
120 initialized for the virtio-blk PCI device, it\r
121 is now accessibla via EFI_BLOCK_IO_PROTOCOL.\r
122\r
123 @retval EFI_OUT_OF_RESOURCES Memory allocation failed.\r
124\r
125 @return Error codes from the OpenProtocol() boot\r
126 service, the PciIo protocol, VirtioBlkInit(),\r
127 or the InstallProtocolInterface() boot service.\r
128\r
129**/\r
130\r
131EFI_STATUS\r
132EFIAPI\r
133VirtioBlkDriverBindingStart (\r
134 IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
135 IN EFI_HANDLE DeviceHandle,\r
136 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
137 );\r
138\r
139\r
140/**\r
141\r
142 Stop driving a virtio-blk device and remove its BlockIo interface.\r
143\r
144 This function replays the success path of DriverBindingStart() in reverse.\r
145 The host side virtio-blk device is reset, so that the OS boot loader or the\r
146 OS may reinitialize it.\r
147\r
148 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object\r
149 incorporating this driver (independently of any\r
150 device).\r
151\r
152 @param[in] DeviceHandle Stop driving this device.\r
153\r
154 @param[in] NumberOfChildren Since this function belongs to a device driver\r
155 only (as opposed to a bus driver), the caller\r
156 environment sets NumberOfChildren to zero, and\r
157 we ignore it.\r
158\r
159 @param[in] ChildHandleBuffer Ignored (corresponding to NumberOfChildren).\r
160\r
161**/\r
162\r
163EFI_STATUS\r
164EFIAPI\r
165VirtioBlkDriverBindingStop (\r
166 IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
167 IN EFI_HANDLE DeviceHandle,\r
168 IN UINTN NumberOfChildren,\r
169 IN EFI_HANDLE *ChildHandleBuffer\r
170 );\r
171\r
172\r
173//\r
174// UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol\r
175// Driver Writer's Guide for UEFI 2.3.1 v1.01,\r
176// 24.2 Block I/O Protocol Implementations\r
177//\r
178EFI_STATUS\r
179EFIAPI\r
180VirtioBlkReset (\r
181 IN EFI_BLOCK_IO_PROTOCOL *This,\r
182 IN BOOLEAN ExtendedVerification\r
183 );\r
184\r
185\r
186/**\r
187\r
188 ReadBlocks() operation for virtio-blk.\r
189\r
190 See\r
191 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O\r
192 Protocol, EFI_BLOCK_IO_PROTOCOL.ReadBlocks().\r
193 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.2. ReadBlocks() and\r
194 ReadBlocksEx() Implementation.\r
195\r
196 Parameter checks and conformant return values are implemented in\r
197 VerifyReadWriteRequest() and SynchronousRequest().\r
198\r
199 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,\r
200 successfully.\r
201\r
202**/\r
203\r
204EFI_STATUS\r
205EFIAPI\r
206VirtioBlkReadBlocks (\r
207 IN EFI_BLOCK_IO_PROTOCOL *This,\r
208 IN UINT32 MediaId,\r
209 IN EFI_LBA Lba,\r
210 IN UINTN BufferSize,\r
211 OUT VOID *Buffer\r
212 );\r
213\r
214\r
215/**\r
216\r
217 WriteBlocks() operation for virtio-blk.\r
218\r
219 See\r
220 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O\r
221 Protocol, EFI_BLOCK_IO_PROTOCOL.WriteBlocks().\r
222 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.3 WriteBlocks() and\r
223 WriteBlockEx() Implementation.\r
224\r
225 Parameter checks and conformant return values are implemented in\r
226 VerifyReadWriteRequest() and SynchronousRequest().\r
227\r
228 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,\r
229 successfully.\r
230\r
231**/\r
232\r
233EFI_STATUS\r
234EFIAPI\r
235VirtioBlkWriteBlocks (\r
236 IN EFI_BLOCK_IO_PROTOCOL *This,\r
237 IN UINT32 MediaId,\r
238 IN EFI_LBA Lba,\r
239 IN UINTN BufferSize,\r
240 IN VOID *Buffer\r
241 );\r
242\r
243\r
244/**\r
245\r
246 FlushBlocks() operation for virtio-blk.\r
247\r
248 See\r
249 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O\r
250 Protocol, EFI_BLOCK_IO_PROTOCOL.FlushBlocks().\r
251 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.4 FlushBlocks() and\r
252 FlushBlocksEx() Implementation.\r
253\r
254 If the underlying virtio-blk device doesn't support flushing (ie.\r
255 write-caching), then this function should not be called by higher layers,\r
256 according to EFI_BLOCK_IO_MEDIA characteristics set in VirtioBlkInit().\r
257 Should they do nonetheless, we do nothing, successfully.\r
258\r
259**/\r
260\r
261EFI_STATUS\r
262EFIAPI\r
263VirtioBlkFlushBlocks (\r
264 IN EFI_BLOCK_IO_PROTOCOL *This\r
265 );\r
266\r
267\r
268//\r
269// The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and\r
270// EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name\r
271// in English, for display on standard console devices. This is recommended for\r
272// UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's\r
273// Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.\r
274//\r
275// Device type names ("Virtio Block Device") are not formatted because the\r
276// driver supports only that device type. Therefore the driver name suffices\r
277// for unambiguous identification.\r
278//\r
279\r
280EFI_STATUS\r
281EFIAPI\r
282VirtioBlkGetDriverName (\r
283 IN EFI_COMPONENT_NAME_PROTOCOL *This,\r
284 IN CHAR8 *Language,\r
285 OUT CHAR16 **DriverName\r
286 );\r
287\r
288EFI_STATUS\r
289EFIAPI\r
290VirtioBlkGetDeviceName (\r
291 IN EFI_COMPONENT_NAME_PROTOCOL *This,\r
292 IN EFI_HANDLE DeviceHandle,\r
293 IN EFI_HANDLE ChildHandle,\r
294 IN CHAR8 *Language,\r
295 OUT CHAR16 **ControllerName\r
296 );\r
936e3a5d 297\r
298#endif // _VIRTIO_BLK_DXE_H_\r