OvmfPkg/VirtioBlkDxe/VirtioBlk.h

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