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