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 VRING Ring
; // VirtioRingInit 2
41 EFI_BLOCK_IO_PROTOCOL BlockIo
; // VirtioBlkInit 1
42 EFI_BLOCK_IO_MEDIA BlockIoMedia
; // VirtioBlkInit 1
45 #define VIRTIO_BLK_FROM_BLOCK_IO(BlockIoPointer) \
46 CR (BlockIoPointer, VBLK_DEV, BlockIo, VBLK_SIG)
51 Device probe function for this driver.
53 The DXE core calls this function for any given device in order to see if the
54 driver can drive the device.
56 Specs relevant in the general sense:
58 - UEFI Spec 2.3.1 + Errata C:
59 - 6.3 Protocol Handler Services -- for accessing the underlying device
60 - 10.1 EFI Driver Binding Protocol -- for exporting ourselves
62 - Driver Writer's Guide for UEFI 2.3.1 v1.01:
63 - 5.1.3.4 OpenProtocol() and CloseProtocol() -- for accessing the
65 - 9 Driver Binding Protocol -- for exporting ourselves
67 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
68 incorporating this driver (independently of
71 @param[in] DeviceHandle The device to probe.
73 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
76 @retval EFI_SUCCESS The driver supports the device being probed.
78 @retval EFI_UNSUPPORTED Based on virtio-blk discovery, we do not support
81 @return Error codes from the OpenProtocol() boot service.
87 VirtioBlkDriverBindingSupported (
88 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
89 IN EFI_HANDLE DeviceHandle
,
90 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
96 After we've pronounced support for a specific device in
97 DriverBindingSupported(), we start managing said device (passed in by the
98 Driver Exeuction Environment) with the following service.
100 See DriverBindingSupported() for specification references.
102 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
103 incorporating this driver (independently of
106 @param[in] DeviceHandle The supported device to drive.
108 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
111 @retval EFI_SUCCESS Driver instance has been created and
112 initialized for the virtio-blk device, it
113 is now accessibla via EFI_BLOCK_IO_PROTOCOL.
115 @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
117 @return Error codes from the OpenProtocol() boot
118 service, VirtioBlkInit(), or the
119 InstallProtocolInterface() boot service.
125 VirtioBlkDriverBindingStart (
126 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
127 IN EFI_HANDLE DeviceHandle
,
128 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
134 Stop driving a virtio-blk device and remove its BlockIo interface.
136 This function replays the success path of DriverBindingStart() in reverse.
137 The host side virtio-blk device is reset, so that the OS boot loader or the
138 OS may reinitialize it.
140 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
141 incorporating this driver (independently of any
144 @param[in] DeviceHandle Stop driving this device.
146 @param[in] NumberOfChildren Since this function belongs to a device driver
147 only (as opposed to a bus driver), the caller
148 environment sets NumberOfChildren to zero, and
151 @param[in] ChildHandleBuffer Ignored (corresponding to NumberOfChildren).
157 VirtioBlkDriverBindingStop (
158 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
159 IN EFI_HANDLE DeviceHandle
,
160 IN UINTN NumberOfChildren
,
161 IN EFI_HANDLE
*ChildHandleBuffer
166 // UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol
167 // Driver Writer's Guide for UEFI 2.3.1 v1.01,
168 // 24.2 Block I/O Protocol Implementations
173 IN EFI_BLOCK_IO_PROTOCOL
*This
,
174 IN BOOLEAN ExtendedVerification
180 ReadBlocks() operation for virtio-blk.
183 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
184 Protocol, EFI_BLOCK_IO_PROTOCOL.ReadBlocks().
185 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.2. ReadBlocks() and
186 ReadBlocksEx() Implementation.
188 Parameter checks and conformant return values are implemented in
189 VerifyReadWriteRequest() and SynchronousRequest().
191 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
198 VirtioBlkReadBlocks (
199 IN EFI_BLOCK_IO_PROTOCOL
*This
,
209 WriteBlocks() operation for virtio-blk.
212 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
213 Protocol, EFI_BLOCK_IO_PROTOCOL.WriteBlocks().
214 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.3 WriteBlocks() and
215 WriteBlockEx() Implementation.
217 Parameter checks and conformant return values are implemented in
218 VerifyReadWriteRequest() and SynchronousRequest().
220 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
227 VirtioBlkWriteBlocks (
228 IN EFI_BLOCK_IO_PROTOCOL
*This
,
238 FlushBlocks() operation for virtio-blk.
241 - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
242 Protocol, EFI_BLOCK_IO_PROTOCOL.FlushBlocks().
243 - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.4 FlushBlocks() and
244 FlushBlocksEx() Implementation.
246 If the underlying virtio-blk device doesn't support flushing (ie.
247 write-caching), then this function should not be called by higher layers,
248 according to EFI_BLOCK_IO_MEDIA characteristics set in VirtioBlkInit().
249 Should they do nonetheless, we do nothing, successfully.
255 VirtioBlkFlushBlocks (
256 IN EFI_BLOCK_IO_PROTOCOL
*This
261 // The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and
262 // EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name
263 // in English, for display on standard console devices. This is recommended for
264 // UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's
265 // Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.
267 // Device type names ("Virtio Block Device") are not formatted because the
268 // driver supports only that device type. Therefore the driver name suffices
269 // for unambiguous identification.
274 VirtioBlkGetDriverName (
275 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
277 OUT CHAR16
**DriverName
282 VirtioBlkGetDeviceName (
283 IN EFI_COMPONENT_NAME_PROTOCOL
*This
,
284 IN EFI_HANDLE DeviceHandle
,
285 IN EFI_HANDLE ChildHandle
,
287 OUT CHAR16
**ControllerName
290 #endif // _VIRTIO_BLK_DXE_H_