| 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 | SPDX-License-Identifier: BSD-2-Clause-Patent
|
|---|
| 9 |
|
|---|
| 10 | **/
|
|---|
| 11 |
|
|---|
| 12 | #ifndef _VIRTIO_BLK_DXE_H_
|
|---|
| 13 | #define _VIRTIO_BLK_DXE_H_
|
|---|
| 14 |
|
|---|
| 15 | #include <Protocol/BlockIo.h>
|
|---|
| 16 | #include <Protocol/ComponentName.h>
|
|---|
| 17 | #include <Protocol/DriverBinding.h>
|
|---|
| 18 |
|
|---|
| 19 | #include <IndustryStandard/Virtio.h>
|
|---|
| 20 |
|
|---|
| 21 | #define VBLK_SIG SIGNATURE_32 ('V', 'B', 'L', 'K')
|
|---|
| 22 |
|
|---|
| 23 | typedef struct {
|
|---|
| 24 | //
|
|---|
| 25 | // Parts of this structure are initialized / torn down in various functions
|
|---|
| 26 | // at various call depths. The table to the right should make it easier to
|
|---|
| 27 | // track them.
|
|---|
| 28 | //
|
|---|
| 29 | // field init function init dpth
|
|---|
| 30 | // --------------------- ------------------ ---------
|
|---|
| 31 | UINT32 Signature; // DriverBindingStart 0
|
|---|
| 32 | VIRTIO_DEVICE_PROTOCOL *VirtIo; // DriverBindingStart 0
|
|---|
| 33 | EFI_EVENT ExitBoot; // DriverBindingStart 0
|
|---|
| 34 | VRING Ring; // VirtioRingInit 2
|
|---|
| 35 | EFI_BLOCK_IO_PROTOCOL BlockIo; // VirtioBlkInit 1
|
|---|
| 36 | EFI_BLOCK_IO_MEDIA BlockIoMedia; // VirtioBlkInit 1
|
|---|
| 37 | VOID *RingMap; // VirtioRingMap 2
|
|---|
| 38 | } VBLK_DEV;
|
|---|
| 39 |
|
|---|
| 40 | #define VIRTIO_BLK_FROM_BLOCK_IO(BlockIoPointer) \
|
|---|
| 41 | CR (BlockIoPointer, VBLK_DEV, BlockIo, VBLK_SIG)
|
|---|
| 42 |
|
|---|
| 43 | /**
|
|---|
| 44 |
|
|---|
| 45 | Device probe function for this driver.
|
|---|
| 46 |
|
|---|
| 47 | The DXE core calls this function for any given device in order to see if the
|
|---|
| 48 | driver can drive the device.
|
|---|
| 49 |
|
|---|
| 50 | Specs relevant in the general sense:
|
|---|
| 51 |
|
|---|
| 52 | - UEFI Spec 2.3.1 + Errata C:
|
|---|
| 53 | - 6.3 Protocol Handler Services -- for accessing the underlying device
|
|---|
| 54 | - 10.1 EFI Driver Binding Protocol -- for exporting ourselves
|
|---|
| 55 |
|
|---|
| 56 | - Driver Writer's Guide for UEFI 2.3.1 v1.01:
|
|---|
| 57 | - 5.1.3.4 OpenProtocol() and CloseProtocol() -- for accessing the
|
|---|
| 58 | underlying device
|
|---|
| 59 | - 9 Driver Binding Protocol -- for exporting ourselves
|
|---|
| 60 |
|
|---|
| 61 | @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
|
|---|
| 62 | incorporating this driver (independently of
|
|---|
| 63 | any device).
|
|---|
| 64 |
|
|---|
| 65 | @param[in] DeviceHandle The device to probe.
|
|---|
| 66 |
|
|---|
| 67 | @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
|
|---|
| 68 |
|
|---|
| 69 |
|
|---|
| 70 | @retval EFI_SUCCESS The driver supports the device being probed.
|
|---|
| 71 |
|
|---|
| 72 | @retval EFI_UNSUPPORTED Based on virtio-blk discovery, we do not support
|
|---|
| 73 | the device.
|
|---|
| 74 |
|
|---|
| 75 | @return Error codes from the OpenProtocol() boot service.
|
|---|
| 76 |
|
|---|
| 77 | **/
|
|---|
| 78 |
|
|---|
| 79 | EFI_STATUS
|
|---|
| 80 | EFIAPI
|
|---|
| 81 | VirtioBlkDriverBindingSupported (
|
|---|
| 82 | IN EFI_DRIVER_BINDING_PROTOCOL *This,
|
|---|
| 83 | IN EFI_HANDLE DeviceHandle,
|
|---|
| 84 | IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
|
|---|
| 85 | );
|
|---|
| 86 |
|
|---|
| 87 | /**
|
|---|
| 88 |
|
|---|
| 89 | After we've pronounced support for a specific device in
|
|---|
| 90 | DriverBindingSupported(), we start managing said device (passed in by the
|
|---|
| 91 | Driver Execution Environment) with the following service.
|
|---|
| 92 |
|
|---|
| 93 | See DriverBindingSupported() for specification references.
|
|---|
| 94 |
|
|---|
| 95 | @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
|
|---|
| 96 | incorporating this driver (independently of
|
|---|
| 97 | any device).
|
|---|
| 98 |
|
|---|
| 99 | @param[in] DeviceHandle The supported device to drive.
|
|---|
| 100 |
|
|---|
| 101 | @param[in] RemainingDevicePath Relevant only for bus drivers, ignored.
|
|---|
| 102 |
|
|---|
| 103 |
|
|---|
| 104 | @retval EFI_SUCCESS Driver instance has been created and
|
|---|
| 105 | initialized for the virtio-blk device, it
|
|---|
| 106 | is now accessible via EFI_BLOCK_IO_PROTOCOL.
|
|---|
| 107 |
|
|---|
| 108 | @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
|
|---|
| 109 |
|
|---|
| 110 | @return Error codes from the OpenProtocol() boot
|
|---|
| 111 | service, VirtioBlkInit(), or the
|
|---|
| 112 | InstallProtocolInterface() boot service.
|
|---|
| 113 |
|
|---|
| 114 | **/
|
|---|
| 115 |
|
|---|
| 116 | EFI_STATUS
|
|---|
| 117 | EFIAPI
|
|---|
| 118 | VirtioBlkDriverBindingStart (
|
|---|
| 119 | IN EFI_DRIVER_BINDING_PROTOCOL *This,
|
|---|
| 120 | IN EFI_HANDLE DeviceHandle,
|
|---|
| 121 | IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
|
|---|
| 122 | );
|
|---|
| 123 |
|
|---|
| 124 | /**
|
|---|
| 125 |
|
|---|
| 126 | Stop driving a virtio-blk device and remove its BlockIo interface.
|
|---|
| 127 |
|
|---|
| 128 | This function replays the success path of DriverBindingStart() in reverse.
|
|---|
| 129 | The host side virtio-blk device is reset, so that the OS boot loader or the
|
|---|
| 130 | OS may reinitialize it.
|
|---|
| 131 |
|
|---|
| 132 | @param[in] This The EFI_DRIVER_BINDING_PROTOCOL object
|
|---|
| 133 | incorporating this driver (independently of any
|
|---|
| 134 | device).
|
|---|
| 135 |
|
|---|
| 136 | @param[in] DeviceHandle Stop driving this device.
|
|---|
| 137 |
|
|---|
| 138 | @param[in] NumberOfChildren Since this function belongs to a device driver
|
|---|
| 139 | only (as opposed to a bus driver), the caller
|
|---|
| 140 | environment sets NumberOfChildren to zero, and
|
|---|
| 141 | we ignore it.
|
|---|
| 142 |
|
|---|
| 143 | @param[in] ChildHandleBuffer Ignored (corresponding to NumberOfChildren).
|
|---|
| 144 |
|
|---|
| 145 | **/
|
|---|
| 146 |
|
|---|
| 147 | EFI_STATUS
|
|---|
| 148 | EFIAPI
|
|---|
| 149 | VirtioBlkDriverBindingStop (
|
|---|
| 150 | IN EFI_DRIVER_BINDING_PROTOCOL *This,
|
|---|
| 151 | IN EFI_HANDLE DeviceHandle,
|
|---|
| 152 | IN UINTN NumberOfChildren,
|
|---|
| 153 | IN EFI_HANDLE *ChildHandleBuffer
|
|---|
| 154 | );
|
|---|
| 155 |
|
|---|
| 156 | //
|
|---|
| 157 | // UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol
|
|---|
| 158 | // Driver Writer's Guide for UEFI 2.3.1 v1.01,
|
|---|
| 159 | // 24.2 Block I/O Protocol Implementations
|
|---|
| 160 | //
|
|---|
| 161 | EFI_STATUS
|
|---|
| 162 | EFIAPI
|
|---|
| 163 | VirtioBlkReset (
|
|---|
| 164 | IN EFI_BLOCK_IO_PROTOCOL *This,
|
|---|
| 165 | IN BOOLEAN ExtendedVerification
|
|---|
| 166 | );
|
|---|
| 167 |
|
|---|
| 168 | /**
|
|---|
| 169 |
|
|---|
| 170 | ReadBlocks() operation for virtio-blk.
|
|---|
| 171 |
|
|---|
| 172 | See
|
|---|
| 173 | - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
|
|---|
| 174 | Protocol, EFI_BLOCK_IO_PROTOCOL.ReadBlocks().
|
|---|
| 175 | - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.2. ReadBlocks() and
|
|---|
| 176 | ReadBlocksEx() Implementation.
|
|---|
| 177 |
|
|---|
| 178 | Parameter checks and conformant return values are implemented in
|
|---|
| 179 | VerifyReadWriteRequest() and SynchronousRequest().
|
|---|
| 180 |
|
|---|
| 181 | A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
|
|---|
| 182 | successfully.
|
|---|
| 183 |
|
|---|
| 184 | **/
|
|---|
| 185 |
|
|---|
| 186 | EFI_STATUS
|
|---|
| 187 | EFIAPI
|
|---|
| 188 | VirtioBlkReadBlocks (
|
|---|
| 189 | IN EFI_BLOCK_IO_PROTOCOL *This,
|
|---|
| 190 | IN UINT32 MediaId,
|
|---|
| 191 | IN EFI_LBA Lba,
|
|---|
| 192 | IN UINTN BufferSize,
|
|---|
| 193 | OUT VOID *Buffer
|
|---|
| 194 | );
|
|---|
| 195 |
|
|---|
| 196 | /**
|
|---|
| 197 |
|
|---|
| 198 | WriteBlocks() operation for virtio-blk.
|
|---|
| 199 |
|
|---|
| 200 | See
|
|---|
| 201 | - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
|
|---|
| 202 | Protocol, EFI_BLOCK_IO_PROTOCOL.WriteBlocks().
|
|---|
| 203 | - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.3 WriteBlocks() and
|
|---|
| 204 | WriteBlockEx() Implementation.
|
|---|
| 205 |
|
|---|
| 206 | Parameter checks and conformant return values are implemented in
|
|---|
| 207 | VerifyReadWriteRequest() and SynchronousRequest().
|
|---|
| 208 |
|
|---|
| 209 | A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,
|
|---|
| 210 | successfully.
|
|---|
| 211 |
|
|---|
| 212 | **/
|
|---|
| 213 |
|
|---|
| 214 | EFI_STATUS
|
|---|
| 215 | EFIAPI
|
|---|
| 216 | VirtioBlkWriteBlocks (
|
|---|
| 217 | IN EFI_BLOCK_IO_PROTOCOL *This,
|
|---|
| 218 | IN UINT32 MediaId,
|
|---|
| 219 | IN EFI_LBA Lba,
|
|---|
| 220 | IN UINTN BufferSize,
|
|---|
| 221 | IN VOID *Buffer
|
|---|
| 222 | );
|
|---|
| 223 |
|
|---|
| 224 | /**
|
|---|
| 225 |
|
|---|
| 226 | FlushBlocks() operation for virtio-blk.
|
|---|
| 227 |
|
|---|
| 228 | See
|
|---|
| 229 | - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O
|
|---|
| 230 | Protocol, EFI_BLOCK_IO_PROTOCOL.FlushBlocks().
|
|---|
| 231 | - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.4 FlushBlocks() and
|
|---|
| 232 | FlushBlocksEx() Implementation.
|
|---|
| 233 |
|
|---|
| 234 | If the underlying virtio-blk device doesn't support flushing (ie.
|
|---|
| 235 | write-caching), then this function should not be called by higher layers,
|
|---|
| 236 | according to EFI_BLOCK_IO_MEDIA characteristics set in VirtioBlkInit().
|
|---|
| 237 | Should they do nonetheless, we do nothing, successfully.
|
|---|
| 238 |
|
|---|
| 239 | **/
|
|---|
| 240 |
|
|---|
| 241 | EFI_STATUS
|
|---|
| 242 | EFIAPI
|
|---|
| 243 | VirtioBlkFlushBlocks (
|
|---|
| 244 | IN EFI_BLOCK_IO_PROTOCOL *This
|
|---|
| 245 | );
|
|---|
| 246 |
|
|---|
| 247 | //
|
|---|
| 248 | // The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and
|
|---|
| 249 | // EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name
|
|---|
| 250 | // in English, for display on standard console devices. This is recommended for
|
|---|
| 251 | // UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's
|
|---|
| 252 | // Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.
|
|---|
| 253 | //
|
|---|
| 254 | // Device type names ("Virtio Block Device") are not formatted because the
|
|---|
| 255 | // driver supports only that device type. Therefore the driver name suffices
|
|---|
| 256 | // for unambiguous identification.
|
|---|
| 257 | //
|
|---|
| 258 |
|
|---|
| 259 | EFI_STATUS
|
|---|
| 260 | EFIAPI
|
|---|
| 261 | VirtioBlkGetDriverName (
|
|---|
| 262 | IN EFI_COMPONENT_NAME_PROTOCOL *This,
|
|---|
| 263 | IN CHAR8 *Language,
|
|---|
| 264 | OUT CHAR16 **DriverName
|
|---|
| 265 | );
|
|---|
| 266 |
|
|---|
| 267 | EFI_STATUS
|
|---|
| 268 | EFIAPI
|
|---|
| 269 | VirtioBlkGetDeviceName (
|
|---|
| 270 | IN EFI_COMPONENT_NAME_PROTOCOL *This,
|
|---|
| 271 | IN EFI_HANDLE DeviceHandle,
|
|---|
| 272 | IN EFI_HANDLE ChildHandle,
|
|---|
| 273 | IN CHAR8 *Language,
|
|---|
| 274 | OUT CHAR16 **ControllerName
|
|---|
| 275 | );
|
|---|
| 276 |
|
|---|
| 277 | #endif // _VIRTIO_BLK_DXE_H_
|
|---|
