OvmfPkg: Apply uncrustify changes

[mirror_edk2.git] / OvmfPkg / VirtioBlkDxe / VirtioBlk.h

/** @file\r
\r
  Internal definitions for the virtio-blk driver, which produces Block I/O\r
  Protocol instances for virtio-blk devices.\r
\r
  Copyright (C) 2012, Red Hat, Inc.\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _VIRTIO_BLK_DXE_H_\r
#define _VIRTIO_BLK_DXE_H_\r
\r
#include <Protocol/BlockIo.h>\r
#include <Protocol/ComponentName.h>\r
#include <Protocol/DriverBinding.h>\r
\r
#include <IndustryStandard/Virtio.h>\r
\r
#define VBLK_SIG  SIGNATURE_32 ('V', 'B', 'L', 'K')\r
\r
typedef struct {\r
  //\r
  // Parts of this structure are initialized / torn down in various functions\r
  // at various call depths. The table to the right should make it easier to\r
  // track them.\r
  //\r
  //                     field                    init function       init dpth\r
  //                     ---------------------    ------------------  ---------\r
  UINT32                    Signature;         // DriverBindingStart  0\r
  VIRTIO_DEVICE_PROTOCOL    *VirtIo;           // DriverBindingStart  0\r
  EFI_EVENT                 ExitBoot;          // DriverBindingStart  0\r
  VRING                     Ring;              // VirtioRingInit      2\r
  EFI_BLOCK_IO_PROTOCOL     BlockIo;           // VirtioBlkInit       1\r
  EFI_BLOCK_IO_MEDIA        BlockIoMedia;      // VirtioBlkInit       1\r
  VOID                      *RingMap;          // VirtioRingMap       2\r
} VBLK_DEV;\r
\r
#define VIRTIO_BLK_FROM_BLOCK_IO(BlockIoPointer) \\r
        CR (BlockIoPointer, VBLK_DEV, BlockIo, VBLK_SIG)\r
\r
/**\r
\r
  Device probe function for this driver.\r
\r
  The DXE core calls this function for any given device in order to see if the\r
  driver can drive the device.\r
\r
  Specs relevant in the general sense:\r
\r
  - UEFI Spec 2.3.1 + Errata C:\r
    - 6.3 Protocol Handler Services -- for accessing the underlying device\r
    - 10.1 EFI Driver Binding Protocol -- for exporting ourselves\r
\r
  - Driver Writer's Guide for UEFI 2.3.1 v1.01:\r
    - 5.1.3.4 OpenProtocol() and CloseProtocol() -- for accessing the\r
      underlying device\r
    - 9 Driver Binding Protocol -- for exporting ourselves\r
\r
  @param[in]  This                The EFI_DRIVER_BINDING_PROTOCOL object\r
                                  incorporating this driver (independently of\r
                                  any device).\r
\r
  @param[in] DeviceHandle         The device to probe.\r
\r
  @param[in] RemainingDevicePath  Relevant only for bus drivers, ignored.\r
\r
\r
  @retval EFI_SUCCESS      The driver supports the device being probed.\r
\r
  @retval EFI_UNSUPPORTED  Based on virtio-blk discovery, we do not support\r
                           the device.\r
\r
  @return                  Error codes from the OpenProtocol() boot service.\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkDriverBindingSupported (\r
  IN EFI_DRIVER_BINDING_PROTOCOL  *This,\r
  IN EFI_HANDLE                   DeviceHandle,\r
  IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
  );\r
\r
/**\r
\r
  After we've pronounced support for a specific device in\r
  DriverBindingSupported(), we start managing said device (passed in by the\r
  Driver Execution Environment) with the following service.\r
\r
  See DriverBindingSupported() for specification references.\r
\r
  @param[in]  This                The EFI_DRIVER_BINDING_PROTOCOL object\r
                                  incorporating this driver (independently of\r
                                  any device).\r
\r
  @param[in] DeviceHandle         The supported device to drive.\r
\r
  @param[in] RemainingDevicePath  Relevant only for bus drivers, ignored.\r
\r
\r
  @retval EFI_SUCCESS           Driver instance has been created and\r
                                initialized  for the virtio-blk device, it\r
                                is now accessible via EFI_BLOCK_IO_PROTOCOL.\r
\r
  @retval EFI_OUT_OF_RESOURCES  Memory allocation failed.\r
\r
  @return                       Error codes from the OpenProtocol() boot\r
                                service, VirtioBlkInit(), or the\r
                                InstallProtocolInterface() boot service.\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkDriverBindingStart (\r
  IN EFI_DRIVER_BINDING_PROTOCOL  *This,\r
  IN EFI_HANDLE                   DeviceHandle,\r
  IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
  );\r
\r
/**\r
\r
  Stop driving a virtio-blk device and remove its BlockIo interface.\r
\r
  This function replays the success path of DriverBindingStart() in reverse.\r
  The host side virtio-blk device is reset, so that the OS boot loader or the\r
  OS may reinitialize it.\r
\r
  @param[in] This               The EFI_DRIVER_BINDING_PROTOCOL object\r
                                incorporating this driver (independently of any\r
                                device).\r
\r
  @param[in] DeviceHandle       Stop driving this device.\r
\r
  @param[in] NumberOfChildren   Since this function belongs to a device driver\r
                                only (as opposed to a bus driver), the caller\r
                                environment sets NumberOfChildren to zero, and\r
                                we ignore it.\r
\r
  @param[in] ChildHandleBuffer  Ignored (corresponding to NumberOfChildren).\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkDriverBindingStop (\r
  IN EFI_DRIVER_BINDING_PROTOCOL  *This,\r
  IN EFI_HANDLE                   DeviceHandle,\r
  IN UINTN                        NumberOfChildren,\r
  IN EFI_HANDLE                   *ChildHandleBuffer\r
  );\r
\r
//\r
// UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol\r
// Driver Writer's Guide for UEFI 2.3.1 v1.01,\r
//   24.2 Block I/O Protocol Implementations\r
//\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkReset (\r
  IN EFI_BLOCK_IO_PROTOCOL  *This,\r
  IN BOOLEAN                ExtendedVerification\r
  );\r
\r
/**\r
\r
  ReadBlocks() operation for virtio-blk.\r
\r
  See\r
  - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O\r
    Protocol, EFI_BLOCK_IO_PROTOCOL.ReadBlocks().\r
  - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.2. ReadBlocks() and\r
    ReadBlocksEx() Implementation.\r
\r
  Parameter checks and conformant return values are implemented in\r
  VerifyReadWriteRequest() and SynchronousRequest().\r
\r
  A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,\r
  successfully.\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkReadBlocks (\r
  IN  EFI_BLOCK_IO_PROTOCOL  *This,\r
  IN  UINT32                 MediaId,\r
  IN  EFI_LBA                Lba,\r
  IN  UINTN                  BufferSize,\r
  OUT VOID                   *Buffer\r
  );\r
\r
/**\r
\r
  WriteBlocks() operation for virtio-blk.\r
\r
  See\r
  - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O\r
    Protocol, EFI_BLOCK_IO_PROTOCOL.WriteBlocks().\r
  - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.3 WriteBlocks() and\r
    WriteBlockEx() Implementation.\r
\r
  Parameter checks and conformant return values are implemented in\r
  VerifyReadWriteRequest() and SynchronousRequest().\r
\r
  A zero BufferSize doesn't seem to be prohibited, so do nothing in that case,\r
  successfully.\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkWriteBlocks (\r
  IN EFI_BLOCK_IO_PROTOCOL  *This,\r
  IN UINT32                 MediaId,\r
  IN EFI_LBA                Lba,\r
  IN UINTN                  BufferSize,\r
  IN VOID                   *Buffer\r
  );\r
\r
/**\r
\r
  FlushBlocks() operation for virtio-blk.\r
\r
  See\r
  - UEFI Spec 2.3.1 + Errata C, 12.8 EFI Block I/O Protocol, 12.8 EFI Block I/O\r
    Protocol, EFI_BLOCK_IO_PROTOCOL.FlushBlocks().\r
  - Driver Writer's Guide for UEFI 2.3.1 v1.01, 24.2.4 FlushBlocks() and\r
    FlushBlocksEx() Implementation.\r
\r
  If the underlying virtio-blk device doesn't support flushing (ie.\r
  write-caching), then this function should not be called by higher layers,\r
  according to EFI_BLOCK_IO_MEDIA characteristics set in VirtioBlkInit().\r
  Should they do nonetheless, we do nothing, successfully.\r
\r
**/\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkFlushBlocks (\r
  IN EFI_BLOCK_IO_PROTOCOL  *This\r
  );\r
\r
//\r
// The purpose of the following scaffolding (EFI_COMPONENT_NAME_PROTOCOL and\r
// EFI_COMPONENT_NAME2_PROTOCOL implementation) is to format the driver's name\r
// in English, for display on standard console devices. This is recommended for\r
// UEFI drivers that follow the UEFI Driver Model. Refer to the Driver Writer's\r
// Guide for UEFI 2.3.1 v1.01, 11 UEFI Driver and Controller Names.\r
//\r
// Device type names ("Virtio Block Device") are not formatted because the\r
// driver supports only that device type. Therefore the driver name suffices\r
// for unambiguous identification.\r
//\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkGetDriverName (\r
  IN  EFI_COMPONENT_NAME_PROTOCOL  *This,\r
  IN  CHAR8                        *Language,\r
  OUT CHAR16                       **DriverName\r
  );\r
\r
EFI_STATUS\r
EFIAPI\r
VirtioBlkGetDeviceName (\r
  IN  EFI_COMPONENT_NAME_PROTOCOL  *This,\r
  IN  EFI_HANDLE                   DeviceHandle,\r
  IN  EFI_HANDLE                   ChildHandle,\r
  IN  CHAR8                        *Language,\r
  OUT CHAR16                       **ControllerName\r
  );\r
\r
#endif // _VIRTIO_BLK_DXE_H_\r