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>
24 #include <Protocol/PciIo.h>
26 #include <IndustryStandard/Virtio.h>
29 #define VBLK_SIG SIGNATURE_32 ('V', 'B', 'L', 'K')
33 // Parts of this structure are initialized / torn down in various functions
34 // at various call depths. The table to the right should make it easier to
37 // field init function init dpth
38 // ---------------------- ------------------ ---------
39 UINT32 Signature
; // DriverBindingStart 0
40 EFI_PCI_IO_PROTOCOL
*PciIo
; // DriverBindingStart 0
41 UINT64 OriginalPciAttributes
; // DriverBindingStart 0
42 VRING Ring
; // VirtioRingInit 2
43 EFI_BLOCK_IO_PROTOCOL BlockIo
; // VirtioBlkInit 1
44 EFI_BLOCK_IO_MEDIA BlockIoMedia
; // VirtioBlkInit 1
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 Specs relevant in the specific sense:
70 - UEFI Spec 2.3.1 + Errata C, 13.4 EFI PCI I/O Protocol
71 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 18 PCI Driver Design
72 Guidelines, 18.3 PCI drivers.
74 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
75 incorporating this driver (independently of
78 @param[in] DeviceHandle The device to probe.
80 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
83 @retval EFI_SUCCESS The driver supports the device being probed.
85 @retval EFI_UNSUPPORTED Based on virtio-blk PCI discovery, we do not support
88 @return Error codes from the OpenProtocol() boot service or
95 VirtioBlkDriverBindingSupported (
96 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
97 IN EFI_HANDLE DeviceHandle
,
98 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
104 After we've pronounced support for a specific device in
105 DriverBindingSupported(), we start managing said device (passed in by the
106 Driver Exeuction Environment) with the following service.
108 See DriverBindingSupported() for specification references.
110 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
111 incorporating this driver (independently of
114 @param[in] DeviceHandle The supported device to drive.
116 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
119 @retval EFI_SUCCESS Driver instance has been created and
120 initialized for the virtio-blk PCI device, it
121 is now accessibla via EFI_BLOCK_IO_PROTOCOL.
123 @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
125 @return Error codes from the OpenProtocol() boot
126 service, the PciIo protocol, VirtioBlkInit(),
127 or the InstallProtocolInterface() boot service.
133 VirtioBlkDriverBindingStart (
134 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
135 IN EFI_HANDLE DeviceHandle
,
136 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
142 Stop driving a virtio-blk device and remove its BlockIo interface.
144 This function replays the success path of DriverBindingStart() in reverse.
145 The host side virtio-blk device is reset, so that the OS boot loader or the
146 OS may reinitialize it.
148 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
149 incorporating this driver (independently of any
152 @param[in] DeviceHandle Stop driving this device.
154 @param[in] NumberOfChildren Since this function belongs to a device driver
155 only (as opposed to a bus driver), the caller
156 environment sets NumberOfChildren to zero, and
159 @param[in] ChildHandleBuffer Ignored (corresponding to NumberOfChildren).
165 VirtioBlkDriverBindingStop (
166 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
167 IN EFI_HANDLE DeviceHandle
,
168 IN UINTN NumberOfChildren
,
169 IN EFI_HANDLE
*ChildHandleBuffer
174 // UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol
175 // Driver Writer's Guide for UEFI 2.3.1 v1.01,
176 // 24.2 Block I/O Protocol Implementations
181 IN EFI_BLOCK_IO_PROTOCOL
*This
,
182 IN BOOLEAN ExtendedVerification
188 ReadBlocks() operation for virtio-blk.
191 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
192 Protocol, EFI_BLOCK_IO_PROTOCOL.ReadBlocks().
193 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.2. ReadBlocks() and
194 ReadBlocksEx() Implementation.
196 Parameter checks and conformant return values are implemented in
197 VerifyReadWriteRequest() and SynchronousRequest().
199 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
206 VirtioBlkReadBlocks (
207 IN EFI_BLOCK_IO_PROTOCOL
*This
,
217 WriteBlocks() operation for virtio-blk.
220 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
221 Protocol, EFI_BLOCK_IO_PROTOCOL.WriteBlocks().
222 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.3 WriteBlocks() and
223 WriteBlockEx() Implementation.
225 Parameter checks and conformant return values are implemented in
226 VerifyReadWriteRequest() and SynchronousRequest().
228 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
235 VirtioBlkWriteBlocks (
236 IN EFI_BLOCK_IO_PROTOCOL
*This
,
246 FlushBlocks() operation for virtio-blk.
249 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
250 Protocol, EFI_BLOCK_IO_PROTOCOL.FlushBlocks().
251 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.4 FlushBlocks() and
252 FlushBlocksEx() Implementation.
254 If the underlying virtio-blk device doesn't support flushing (ie.
255 write-caching), then this function should not be called by higher layers,
256 according to EFI_BLOCK_IO_MEDIA characteristics set in VirtioBlkInit().
257 Should they do nonetheless, we do nothing, successfully.
263 VirtioBlkFlushBlocks (
264 IN EFI_BLOCK_IO_PROTOCOL
*This
269 // The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and
270 // EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name
271 // in English, for display on standard console devices. This is recommended for
272 // UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's
273 // Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.
275 // Device type names ("Virtio Block Device") are not formatted because the
276 // driver supports only that device type. Therefore the driver name suffices
277 // for unambiguous identification.
282 VirtioBlkGetDriverName (
283 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
285 OUT CHAR16
**DriverName
290 VirtioBlkGetDeviceName (
291 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
292 IN EFI_HANDLE DeviceHandle
,
293 IN EFI_HANDLE ChildHandle
,
295 OUT CHAR16
**ControllerName
298 #endif // _VIRTIO_BLK_DXE_H_