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 #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_