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 This program and the accompanying materials are licensed and made available
9 under the terms and conditions of the BSD License which accompanies this
10 distribution. The full text of the license may be found at
11 http://opensource.org/licenses/bsd-license.php
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
14 WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18 #ifndef _VIRTIO_BLK_DXE_H_
19 #define _VIRTIO_BLK_DXE_H_
21 #include <Protocol/BlockIo.h>
22 #include <Protocol/ComponentName.h>
23 #include <Protocol/DriverBinding.h>
25 #include <IndustryStandard/Virtio.h>
28 #define VBLK_SIG SIGNATURE_32 ('V', 'B', 'L', 'K')
32 // Parts of this structure are initialized / torn down in various functions
33 // at various call depths. The table to the right should make it easier to
36 // field init function init dpth
37 // --------------------- ------------------ ---------
38 UINT32 Signature
; // DriverBindingStart 0
39 VIRTIO_DEVICE_PROTOCOL
*VirtIo
; // DriverBindingStart 0
40 EFI_EVENT ExitBoot
; // DriverBindingStart 0
41 VRING Ring
; // VirtioRingInit 2
42 EFI_BLOCK_IO_PROTOCOL BlockIo
; // VirtioBlkInit 1
43 EFI_BLOCK_IO_MEDIA BlockIoMedia
; // VirtioBlkInit 1
44 VOID
*RingMap
; // VirtioRingMap 2
47 #define VIRTIO_BLK_FROM_BLOCK_IO(BlockIoPointer) \
48 CR (BlockIoPointer, VBLK_DEV, BlockIo, VBLK_SIG)
53 Device probe function for this driver.
55 The DXE core calls this function for any given device in order to see if the
56 driver can drive the device.
58 Specs relevant in the general sense:
60 - UEFI Spec 2.3.1 + Errata C:
61 - 6.3 Protocol Handler Services -- for accessing the underlying device
62 - 10.1 EFI Driver Binding Protocol -- for exporting ourselves
64 - Driver Writer's Guide for UEFI 2.3.1 v1.01:
65 - 5.1.3.4 OpenProtocol() and CloseProtocol() -- for accessing the
67 - 9 Driver Binding Protocol -- for exporting ourselves
69 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
70 incorporating this driver (independently of
73 @param[in] DeviceHandle The device to probe.
75 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
78 @retval EFI_SUCCESS The driver supports the device being probed.
80 @retval EFI_UNSUPPORTED Based on virtio-blk discovery, we do not support
83 @return Error codes from the OpenProtocol() boot service.
89 VirtioBlkDriverBindingSupported (
90 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
91 IN EFI_HANDLE DeviceHandle
,
92 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
98 After we've pronounced support for a specific device in
99 DriverBindingSupported(), we start managing said device (passed in by the
100 Driver Execution Environment) with the following service.
102 See DriverBindingSupported() for specification references.
104 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
105 incorporating this driver (independently of
108 @param[in] DeviceHandle The supported device to drive.
110 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
113 @retval EFI_SUCCESS Driver instance has been created and
114 initialized for the virtio-blk device, it
115 is now accessible via EFI_BLOCK_IO_PROTOCOL.
117 @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
119 @return Error codes from the OpenProtocol() boot
120 service, VirtioBlkInit(), or the
121 InstallProtocolInterface() boot service.
127 VirtioBlkDriverBindingStart (
128 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
129 IN EFI_HANDLE DeviceHandle
,
130 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
136 Stop driving a virtio-blk device and remove its BlockIo interface.
138 This function replays the success path of DriverBindingStart() in reverse.
139 The host side virtio-blk device is reset, so that the OS boot loader or the
140 OS may reinitialize it.
142 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
143 incorporating this driver (independently of any
146 @param[in] DeviceHandle Stop driving this device.
148 @param[in] NumberOfChildren Since this function belongs to a device driver
149 only (as opposed to a bus driver), the caller
150 environment sets NumberOfChildren to zero, and
153 @param[in] ChildHandleBuffer Ignored (corresponding to NumberOfChildren).
159 VirtioBlkDriverBindingStop (
160 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
161 IN EFI_HANDLE DeviceHandle
,
162 IN UINTN NumberOfChildren
,
163 IN EFI_HANDLE
*ChildHandleBuffer
168 // UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol
169 // Driver Writer's Guide for UEFI 2.3.1 v1.01,
170 // 24.2 Block I/O Protocol Implementations
175 IN EFI_BLOCK_IO_PROTOCOL
*This
,
176 IN BOOLEAN ExtendedVerification
182 ReadBlocks() operation for virtio-blk.
185 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
186 Protocol, EFI_BLOCK_IO_PROTOCOL.ReadBlocks().
187 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.2. ReadBlocks() and
188 ReadBlocksEx() Implementation.
190 Parameter checks and conformant return values are implemented in
191 VerifyReadWriteRequest() and SynchronousRequest().
193 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
200 VirtioBlkReadBlocks (
201 IN EFI_BLOCK_IO_PROTOCOL
*This
,
211 WriteBlocks() operation for virtio-blk.
214 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
215 Protocol, EFI_BLOCK_IO_PROTOCOL.WriteBlocks().
216 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.3 WriteBlocks() and
217 WriteBlockEx() Implementation.
219 Parameter checks and conformant return values are implemented in
220 VerifyReadWriteRequest() and SynchronousRequest().
222 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
229 VirtioBlkWriteBlocks (
230 IN EFI_BLOCK_IO_PROTOCOL
*This
,
240 FlushBlocks() operation for virtio-blk.
243 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
244 Protocol, EFI_BLOCK_IO_PROTOCOL.FlushBlocks().
245 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.4 FlushBlocks() and
246 FlushBlocksEx() Implementation.
248 If the underlying virtio-blk device doesn't support flushing (ie.
249 write-caching), then this function should not be called by higher layers,
250 according to EFI_BLOCK_IO_MEDIA characteristics set in VirtioBlkInit().
251 Should they do nonetheless, we do nothing, successfully.
257 VirtioBlkFlushBlocks (
258 IN EFI_BLOCK_IO_PROTOCOL
*This
263 // The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and
264 // EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name
265 // in English, for display on standard console devices. This is recommended for
266 // UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's
267 // Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.
269 // Device type names ("Virtio Block Device") are not formatted because the
270 // driver supports only that device type. Therefore the driver name suffices
271 // for unambiguous identification.
276 VirtioBlkGetDriverName (
277 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
279 OUT CHAR16
**DriverName
284 VirtioBlkGetDeviceName (
285 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
286 IN EFI_HANDLE DeviceHandle
,
287 IN EFI_HANDLE ChildHandle
,
289 OUT CHAR16
**ControllerName
292 #endif // _VIRTIO_BLK_DXE_H_