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