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