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