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
46 #define VIRTIO_BLK_FROM_BLOCK_IO(BlockIoPointer) \
47 CR (BlockIoPointer, VBLK_DEV, BlockIo, VBLK_SIG)
52 Device probe function for this driver.
54 The DXE core calls this function for any given device in order to see if the
55 driver can drive the device.
57 Specs relevant in the general sense:
59 - UEFI Spec 2.3.1 + Errata C:
60 - 6.3 Protocol Handler Services -- for accessing the underlying device
61 - 10.1 EFI Driver Binding Protocol -- for exporting ourselves
63 - Driver Writer's Guide for UEFI 2.3.1 v1.01:
64 - 5.1.3.4 OpenProtocol() and CloseProtocol() -- for accessing the
66 - 9 Driver Binding Protocol -- for exporting ourselves
68 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
69 incorporating this driver (independently of
72 @param[in] DeviceHandle The device to probe.
74 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
77 @retval EFI_SUCCESS The driver supports the device being probed.
79 @retval EFI_UNSUPPORTED Based on virtio-blk discovery, we do not support
82 @return Error codes from the OpenProtocol() boot service.
88 VirtioBlkDriverBindingSupported (
89 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
90 IN EFI_HANDLE DeviceHandle
,
91 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
97 After we've pronounced support for a specific device in
98 DriverBindingSupported(), we start managing said device (passed in by the
99 Driver Exeuction Environment) with the following service.
101 See DriverBindingSupported() for specification references.
103 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
104 incorporating this driver (independently of
107 @param[in] DeviceHandle The supported device to drive.
109 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
112 @retval EFI_SUCCESS Driver instance has been created and
113 initialized for the virtio-blk device, it
114 is now accessibla via EFI_BLOCK_IO_PROTOCOL.
116 @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
118 @return Error codes from the OpenProtocol() boot
119 service, VirtioBlkInit(), or the
120 InstallProtocolInterface() boot service.
126 VirtioBlkDriverBindingStart (
127 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
128 IN EFI_HANDLE DeviceHandle
,
129 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
135 Stop driving a virtio-blk device and remove its BlockIo interface.
137 This function replays the success path of DriverBindingStart() in reverse.
138 The host side virtio-blk device is reset, so that the OS boot loader or the
139 OS may reinitialize it.
141 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
142 incorporating this driver (independently of any
145 @param[in] DeviceHandle Stop driving this device.
147 @param[in] NumberOfChildren Since this function belongs to a device driver
148 only (as opposed to a bus driver), the caller
149 environment sets NumberOfChildren to zero, and
152 @param[in] ChildHandleBuffer Ignored (corresponding to NumberOfChildren).
158 VirtioBlkDriverBindingStop (
159 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
160 IN EFI_HANDLE DeviceHandle
,
161 IN UINTN NumberOfChildren
,
162 IN EFI_HANDLE
*ChildHandleBuffer
167 // UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol
168 // Driver Writer's Guide for UEFI 2.3.1 v1.01,
169 // 24.2 Block I/O Protocol Implementations
174 IN EFI_BLOCK_IO_PROTOCOL
*This
,
175 IN BOOLEAN ExtendedVerification
181 ReadBlocks() operation for virtio-blk.
184 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
185 Protocol, EFI_BLOCK_IO_PROTOCOL.ReadBlocks().
186 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.2. ReadBlocks() and
187 ReadBlocksEx() Implementation.
189 Parameter checks and conformant return values are implemented in
190 VerifyReadWriteRequest() and SynchronousRequest().
192 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
199 VirtioBlkReadBlocks (
200 IN EFI_BLOCK_IO_PROTOCOL
*This
,
210 WriteBlocks() operation for virtio-blk.
213 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
214 Protocol, EFI_BLOCK_IO_PROTOCOL.WriteBlocks().
215 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.3 WriteBlocks() and
216 WriteBlockEx() Implementation.
218 Parameter checks and conformant return values are implemented in
219 VerifyReadWriteRequest() and SynchronousRequest().
221 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
228 VirtioBlkWriteBlocks (
229 IN EFI_BLOCK_IO_PROTOCOL
*This
,
239 FlushBlocks() operation for virtio-blk.
242 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
243 Protocol, EFI_BLOCK_IO_PROTOCOL.FlushBlocks().
244 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.4 FlushBlocks() and
245 FlushBlocksEx() Implementation.
247 If the underlying virtio-blk device doesn't support flushing (ie.
248 write-caching), then this function should not be called by higher layers,
249 according to EFI_BLOCK_IO_MEDIA characteristics set in VirtioBlkInit().
250 Should they do nonetheless, we do nothing, successfully.
256 VirtioBlkFlushBlocks (
257 IN EFI_BLOCK_IO_PROTOCOL
*This
262 // The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and
263 // EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name
264 // in English, for display on standard console devices. This is recommended for
265 // UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's
266 // Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.
268 // Device type names ("Virtio Block Device") are not formatted because the
269 // driver supports only that device type. Therefore the driver name suffices
270 // for unambiguous identification.
275 VirtioBlkGetDriverName (
276 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
278 OUT CHAR16
**DriverName
283 VirtioBlkGetDeviceName (
284 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
285 IN EFI_HANDLE DeviceHandle
,
286 IN EFI_HANDLE ChildHandle
,
288 OUT CHAR16
**ControllerName
291 #endif // _VIRTIO_BLK_DXE_H_