1 /** @file 2 3 Internal definitions for the virtio-blk driver, which produces Block I/O 4 Protocol instances for virtio-blk devices. 5 6 Copyright (C) 2012, Red Hat, Inc. 7 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 12 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. 15 16 **/ 17 18 #ifndef _VIRTIO_BLK_DXE_H_ 19 #define _VIRTIO_BLK_DXE_H_ 20 21 #include <Protocol/BlockIo.h> 22 #include <Protocol/ComponentName.h> 23 #include <Protocol/DriverBinding.h> 24 25 #include <IndustryStandard/Virtio.h> 26 27 28 #define VBLK_SIG SIGNATURE_32 ('V', 'B', 'L', 'K') 29 30 typedef struct { 31 // 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 34 // track them. 35 // 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 } VBLK_DEV; 45 46 #define VIRTIO_BLK_FROM_BLOCK_IO(BlockIoPointer) \ 47 CR (BlockIoPointer, VBLK_DEV, BlockIo, VBLK_SIG) 48 49 50 /** 51 52 Device probe function for this driver. 53 54 The DXE core calls this function for any given device in order to see if the 55 driver can drive the device. 56 57 Specs relevant in the general sense: 58 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 62 63 - Driver Writer's Guide for UEFI 2.3.1 v1.01: 64 - 5.1.3.4 OpenProtocol() and CloseProtocol() -- for accessing the 65 underlying device 66 - 9 Driver Binding Protocol -- for exporting ourselves 67 68 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object 69 incorporating this driver (independently of 70 any device). 71 72 @param[in] DeviceHandle The device to probe. 73 74 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored. 75 76 77 @retval EFI_SUCCESS The driver supports the device being probed. 78 79 @retval EFI_UNSUPPORTED Based on virtio-blk discovery, we do not support 80 the device. 81 82 @return Error codes from the OpenProtocol() boot service. 83 84 **/ 85 86 EFI_STATUS 87 EFIAPI 88 VirtioBlkDriverBindingSupported ( 89 IN EFI_DRIVER_BINDING_PROTOCOL *This, 90 IN EFI_HANDLE DeviceHandle, 91 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 92 ); 93 94 95 /** 96 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. 100 101 See DriverBindingSupported() for specification references. 102 103 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object 104 incorporating this driver (independently of 105 any device). 106 107 @param[in] DeviceHandle The supported device to drive. 108 109 @param[in] RemainingDevicePath Relevant only for bus drivers, ignored. 110 111 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. 115 116 @retval EFI_OUT_OF_RESOURCES Memory allocation failed. 117 118 @return Error codes from the OpenProtocol() boot 119 service, VirtioBlkInit(), or the 120 InstallProtocolInterface() boot service. 121 122 **/ 123 124 EFI_STATUS 125 EFIAPI 126 VirtioBlkDriverBindingStart ( 127 IN EFI_DRIVER_BINDING_PROTOCOL *This, 128 IN EFI_HANDLE DeviceHandle, 129 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 130 ); 131 132 133 /** 134 135 Stop driving a virtio-blk device and remove its BlockIo interface. 136 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. 140 141 @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object 142 incorporating this driver (independently of any 143 device). 144 145 @param[in] DeviceHandle Stop driving this device. 146 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 150 we ignore it. 151 152 @param[in] ChildHandleBuffer Ignored (corresponding to NumberOfChildren). 153 154 **/ 155 156 EFI_STATUS 157 EFIAPI 158 VirtioBlkDriverBindingStop ( 159 IN EFI_DRIVER_BINDING_PROTOCOL *This, 160 IN EFI_HANDLE DeviceHandle, 161 IN UINTN NumberOfChildren, 162 IN EFI_HANDLE *ChildHandleBuffer 163 ); 164 165 166 // 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 170 // 171 EFI_STATUS 172 EFIAPI 173 VirtioBlkReset ( 174 IN EFI_BLOCK_IO_PROTOCOL *This, 175 IN BOOLEAN ExtendedVerification 176 ); 177 178 179 /** 180 181 ReadBlocks() operation for virtio-blk. 182 183 See 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. 188 189 Parameter checks and conformant return values are implemented in 190 VerifyReadWriteRequest() and SynchronousRequest(). 191 192 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case, 193 successfully. 194 195 **/ 196 197 EFI_STATUS 198 EFIAPI 199 VirtioBlkReadBlocks ( 200 IN EFI_BLOCK_IO_PROTOCOL *This, 201 IN UINT32 MediaId, 202 IN EFI_LBA Lba, 203 IN UINTN BufferSize, 204 OUT VOID *Buffer 205 ); 206 207 208 /** 209 210 WriteBlocks() operation for virtio-blk. 211 212 See 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. 217 218 Parameter checks and conformant return values are implemented in 219 VerifyReadWriteRequest() and SynchronousRequest(). 220 221 A zero BufferSize doesn't seem to be prohibited, so do nothing in that case, 222 successfully. 223 224 **/ 225 226 EFI_STATUS 227 EFIAPI 228 VirtioBlkWriteBlocks ( 229 IN EFI_BLOCK_IO_PROTOCOL *This, 230 IN UINT32 MediaId, 231 IN EFI_LBA Lba, 232 IN UINTN BufferSize, 233 IN VOID *Buffer 234 ); 235 236 237 /** 238 239 FlushBlocks() operation for virtio-blk. 240 241 See 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. 246 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. 251 252 **/ 253 254 EFI_STATUS 255 EFIAPI 256 VirtioBlkFlushBlocks ( 257 IN EFI_BLOCK_IO_PROTOCOL *This 258 ); 259 260 261 // 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. 267 // 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. 271 // 272 273 EFI_STATUS 274 EFIAPI 275 VirtioBlkGetDriverName ( 276 IN EFI_COMPONENT_NAME_PROTOCOL *This, 277 IN CHAR8 *Language, 278 OUT CHAR16 **DriverName 279 ); 280 281 EFI_STATUS 282 EFIAPI 283 VirtioBlkGetDeviceName ( 284 IN EFI_COMPONENT_NAME_PROTOCOL *This, 285 IN EFI_HANDLE DeviceHandle, 286 IN EFI_HANDLE ChildHandle, 287 IN CHAR8 *Language, 288 OUT CHAR16 **ControllerName 289 ); 290 291 #endif // _VIRTIO_BLK_DXE_H_ 292