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