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