3 Internal definitions for the virtio-blk driver, which produces Block I/O
4 Protocol instances for virtio-blk devices.
6 Copyright (C) 2012, Red Hat, Inc.
8 SPDX-License-Identifier: BSD-2-Clause-Patent
12 #ifndef _VIRTIO_BLK_DXE_H_
13 #define _VIRTIO_BLK_DXE_H_
15 #include <Protocol/BlockIo.h>
16 #include <Protocol/ComponentName.h>
17 #include <Protocol/DriverBinding.h>
19 #include <IndustryStandard/Virtio.h>
21 #define VBLK_SIG SIGNATURE_32 ('V', 'B', 'L', 'K')
25 // Parts of this structure are initialized / torn down in various functions
26 // at various call depths. The table to the right should make it easier to
29 // field init function init dpth
30 // --------------------- ------------------ ---------
31 UINT32 Signature
; // DriverBindingStart 0
32 VIRTIO_DEVICE_PROTOCOL
*VirtIo
; // DriverBindingStart 0
33 EFI_EVENT ExitBoot
; // DriverBindingStart 0
34 VRING Ring
; // VirtioRingInit 2
35 EFI_BLOCK_IO_PROTOCOL BlockIo
; // VirtioBlkInit 1
36 EFI_BLOCK_IO_MEDIA BlockIoMedia
; // VirtioBlkInit 1
37 VOID
*RingMap
; // VirtioRingMap 2
40 #define VIRTIO_BLK_FROM_BLOCK_IO(BlockIoPointer) \
41 CR (BlockIoPointer, VBLK_DEV, BlockIo, VBLK_SIG)
45 Device probe function for this driver.
47 The DXE core calls this function for any given device in order to see if the
48 driver can drive the device.
50 Specs relevant in the general sense:
52 - UEFI Spec 2.3.1 + Errata C:
53 - 6.3 Protocol Handler Services -- for accessing the underlying device
54 - 10.1 EFI Driver Binding Protocol -- for exporting ourselves
56 - Driver Writer's Guide for UEFI 2.3.1 v1.01:
57 - 5.1.3.4 OpenProtocol() and CloseProtocol() -- for accessing the
59 - 9 Driver Binding Protocol -- for exporting ourselves
61 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
62 incorporating this driver (independently of
65 @param[in] DeviceHandle The device to probe.
67 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
70 @retval EFI_SUCCESS The driver supports the device being probed.
72 @retval EFI_UNSUPPORTED Based on virtio-blk discovery, we do not support
75 @return Error codes from the OpenProtocol() boot service.
81 VirtioBlkDriverBindingSupported (
82 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
83 IN EFI_HANDLE DeviceHandle
,
84 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
89 After we've pronounced support for a specific device in
90 DriverBindingSupported(), we start managing said device (passed in by the
91 Driver Execution Environment) with the following service.
93 See DriverBindingSupported() for specification references.
95 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
96 incorporating this driver (independently of
99 @param[in] DeviceHandle The supported device to drive.
101 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
104 @retval EFI_SUCCESS Driver instance has been created and
105 initialized for the virtio-blk device, it
106 is now accessible via EFI_BLOCK_IO_PROTOCOL.
108 @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
110 @return Error codes from the OpenProtocol() boot
111 service, VirtioBlkInit(), or the
112 InstallProtocolInterface() boot service.
118 VirtioBlkDriverBindingStart (
119 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
120 IN EFI_HANDLE DeviceHandle
,
121 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
126 Stop driving a virtio-blk device and remove its BlockIo interface.
128 This function replays the success path of DriverBindingStart() in reverse.
129 The host side virtio-blk device is reset, so that the OS boot loader or the
130 OS may reinitialize it.
132 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
133 incorporating this driver (independently of any
136 @param[in] DeviceHandle Stop driving this device.
138 @param[in] NumberOfChildren Since this function belongs to a device driver
139 only (as opposed to a bus driver), the caller
140 environment sets NumberOfChildren to zero, and
143 @param[in] ChildHandleBuffer Ignored (corresponding to NumberOfChildren).
149 VirtioBlkDriverBindingStop (
150 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
151 IN EFI_HANDLE DeviceHandle
,
152 IN UINTN NumberOfChildren
,
153 IN EFI_HANDLE
*ChildHandleBuffer
157 // UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol
158 // Driver Writer's Guide for UEFI 2.3.1 v1.01,
159 // 24.2 Block I/O Protocol Implementations
164 IN EFI_BLOCK_IO_PROTOCOL
*This
,
165 IN BOOLEAN ExtendedVerification
170 ReadBlocks() operation for virtio-blk.
173 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
174 Protocol, EFI_BLOCK_IO_PROTOCOL.ReadBlocks().
175 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.2. ReadBlocks() and
176 ReadBlocksEx() Implementation.
178 Parameter checks and conformant return values are implemented in
179 VerifyReadWriteRequest() and SynchronousRequest().
181 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
188 VirtioBlkReadBlocks (
189 IN EFI_BLOCK_IO_PROTOCOL
*This
,
198 WriteBlocks() operation for virtio-blk.
201 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
202 Protocol, EFI_BLOCK_IO_PROTOCOL.WriteBlocks().
203 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.3 WriteBlocks() and
204 WriteBlockEx() Implementation.
206 Parameter checks and conformant return values are implemented in
207 VerifyReadWriteRequest() and SynchronousRequest().
209 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
216 VirtioBlkWriteBlocks (
217 IN EFI_BLOCK_IO_PROTOCOL
*This
,
226 FlushBlocks() operation for virtio-blk.
229 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
230 Protocol, EFI_BLOCK_IO_PROTOCOL.FlushBlocks().
231 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.4 FlushBlocks() and
232 FlushBlocksEx() Implementation.
234 If the underlying virtio-blk device doesn't support flushing (ie.
235 write-caching), then this function should not be called by higher layers,
236 according to EFI_BLOCK_IO_MEDIA characteristics set in VirtioBlkInit().
237 Should they do nonetheless, we do nothing, successfully.
243 VirtioBlkFlushBlocks (
244 IN EFI_BLOCK_IO_PROTOCOL
*This
248 // The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and
249 // EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name
250 // in English, for display on standard console devices. This is recommended for
251 // UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's
252 // Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.
254 // Device type names ("Virtio Block Device") are not formatted because the
255 // driver supports only that device type. Therefore the driver name suffices
256 // for unambiguous identification.
261 VirtioBlkGetDriverName (
262 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
264 OUT CHAR16
**DriverName
269 VirtioBlkGetDeviceName (
270 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
271 IN EFI_HANDLE DeviceHandle
,
272 IN EFI_HANDLE ChildHandle
,
274 OUT CHAR16
**ControllerName
277 #endif // _VIRTIO_BLK_DXE_H_