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