MdeModulePkg/Bus/Pci/NvmExpressDxe/NvmExpressBlockIo.h

   1 /** @file
   2   Header file for EFI_BLOCK_IO_PROTOCOL interface.
   3
   4 Copyright (c) 2013 - 2015, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _EFI_NVME_BLOCKIO_H_
  16 #define _EFI_NVME_BLOCKIO_H_
  17
  18 /**
  19   Reset the Block Device.
  20
  21   @param  This                 Indicates a pointer to the calling context.
  22   @param  ExtendedVerification Driver may perform diagnostics on reset.
  23
  24   @retval EFI_SUCCESS          The device was reset.
  25   @retval EFI_DEVICE_ERROR     The device is not functioning properly and could
  26                                not be reset.
  27
  28 **/
  29 EFI_STATUS
  30 EFIAPI
  31 NvmeBlockIoReset (
  32   IN  EFI_BLOCK_IO_PROTOCOL   *This,
  33   IN  BOOLEAN                 ExtendedVerification
  34   );
  35
  36 /**
  37   Read BufferSize bytes from Lba into Buffer.
  38
  39   @param  This       Indicates a pointer to the calling context.
  40   @param  MediaId    Id of the media, changes every time the media is replaced.
  41   @param  Lba        The starting Logical Block Address to read from
  42   @param  BufferSize Size of Buffer, must be a multiple of device block size.
  43   @param  Buffer     A pointer to the destination buffer for the data. The caller is
  44                      responsible for either having implicit or explicit ownership of the buffer.
  45
  46   @retval EFI_SUCCESS           The data was read correctly from the device.
  47   @retval EFI_DEVICE_ERROR      The device reported an error while performing the read.
  48   @retval EFI_NO_MEDIA          There is no media in the device.
  49   @retval EFI_MEDIA_CHANGED     The MediaId does not matched the current device.
  50   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
  51   @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
  52                                 or the buffer is not on proper alignment.
  53
  54 **/
  55 EFI_STATUS
  56 EFIAPI
  57 NvmeBlockIoReadBlocks (
  58   IN  EFI_BLOCK_IO_PROTOCOL   *This,
  59   IN  UINT32                  MediaId,
  60   IN  EFI_LBA                 Lba,
  61   IN  UINTN                   BufferSize,
  62   OUT VOID                    *Buffer
  63   );
  64
  65 /**
  66   Write BufferSize bytes from Lba into Buffer.
  67
  68   @param  This       Indicates a pointer to the calling context.
  69   @param  MediaId    The media ID that the write request is for.
  70   @param  Lba        The starting logical block address to be written. The caller is
  71                      responsible for writing to only legitimate locations.
  72   @param  BufferSize Size of Buffer, must be a multiple of device block size.
  73   @param  Buffer     A pointer to the source buffer for the data.
  74
  75   @retval EFI_SUCCESS           The data was written correctly to the device.
  76   @retval EFI_WRITE_PROTECTED   The device can not be written to.
  77   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
  78   @retval EFI_NO_MEDIA          There is no media in the device.
  79   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
  80   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
  81   @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
  82                                 or the buffer is not on proper alignment.
  83
  84 **/
  85 EFI_STATUS
  86 EFIAPI
  87 NvmeBlockIoWriteBlocks (
  88   IN  EFI_BLOCK_IO_PROTOCOL   *This,
  89   IN  UINT32                  MediaId,
  90   IN  EFI_LBA                 Lba,
  91   IN  UINTN                   BufferSize,
  92   IN  VOID                    *Buffer
  93   );
  94
  95 /**
  96   Flush the Block Device.
  97
  98   @param  This              Indicates a pointer to the calling context.
  99
 100   @retval EFI_SUCCESS       All outstanding data was written to the device
 101   @retval EFI_DEVICE_ERROR  The device reported an error while writing back the data
 102   @retval EFI_NO_MEDIA      There is no media in the device.
 103
 104 **/
 105 EFI_STATUS
 106 EFIAPI
 107 NvmeBlockIoFlushBlocks (
 108   IN  EFI_BLOCK_IO_PROTOCOL   *This
 109   );
 110
 111 /**
 112   Send a security protocol command to a device that receives data and/or the result
 113   of one or more commands sent by SendData.
 114
 115   The ReceiveData function sends a security protocol command to the given MediaId.
 116   The security protocol command sent is defined by SecurityProtocolId and contains
 117   the security protocol specific data SecurityProtocolSpecificData. The function
 118   returns the data from the security protocol command in PayloadBuffer.
 119
 120   For devices supporting the SCSI command set, the security protocol command is sent
 121   using the SECURITY PROTOCOL IN command defined in SPC-4.
 122
 123   For devices supporting the ATA command set, the security protocol command is sent
 124   using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize
 125   is non-zero.
 126
 127   If the PayloadBufferSize is zero, the security protocol command is sent using the
 128   Trusted Non-Data command defined in ATA8-ACS.
 129
 130   If PayloadBufferSize is too small to store the available data from the security
 131   protocol command, the function shall copy PayloadBufferSize bytes into the
 132   PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL.
 133
 134   If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero,
 135   the function shall return EFI_INVALID_PARAMETER.
 136
 137   If the given MediaId does not support security protocol commands, the function shall
 138   return EFI_UNSUPPORTED. If there is no media in the device, the function returns
 139   EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device,
 140   the function returns EFI_MEDIA_CHANGED.
 141
 142   If the security protocol fails to complete within the Timeout period, the function
 143   shall return EFI_TIMEOUT.
 144
 145   If the security protocol command completes without an error, the function shall
 146   return EFI_SUCCESS. If the security protocol command completes with an error, the
 147   function shall return EFI_DEVICE_ERROR.
 148
 149   @param  This                         Indicates a pointer to the calling context.
 150   @param  MediaId                      ID of the medium to receive data from.
 151   @param  Timeout                      The timeout, in 100ns units, to use for the execution
 152                                        of the security protocol command. A Timeout value of 0
 153                                        means that this function will wait indefinitely for the
 154                                        security protocol command to execute. If Timeout is greater
 155                                        than zero, then this function will return EFI_TIMEOUT
 156                                        if the time required to execute the receive data command
 157                                        is greater than Timeout.
 158   @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
 159                                        the security protocol command to be sent.
 160   @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
 161                                        of the security protocol command to be sent.
 162   @param  PayloadBufferSize            Size in bytes of the payload data buffer.
 163   @param  PayloadBuffer                A pointer to a destination buffer to store the security
 164                                        protocol command specific payload data for the security
 165                                        protocol command. The caller is responsible for having
 166                                        either implicit or explicit ownership of the buffer.
 167   @param  PayloadTransferSize          A pointer to a buffer to store the size in bytes of the
 168                                        data written to the payload data buffer.
 169
 170   @retval EFI_SUCCESS                  The security protocol command completed successfully.
 171   @retval EFI_WARN_BUFFER_TOO_SMALL    The PayloadBufferSize was too small to store the available
 172                                        data from the device. The PayloadBuffer contains the truncated data.
 173   @retval EFI_UNSUPPORTED              The given MediaId does not support security protocol commands.
 174   @retval EFI_DEVICE_ERROR             The security protocol command completed with an error.
 175   @retval EFI_NO_MEDIA                 There is no media in the device.
 176   @retval EFI_MEDIA_CHANGED            The MediaId is not for the current media.
 177   @retval EFI_INVALID_PARAMETER        The PayloadBuffer or PayloadTransferSize is NULL and
 178                                        PayloadBufferSize is non-zero.
 179   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the security
 180                                        protocol command to execute.
 181
 182 **/
 183 EFI_STATUS
 184 EFIAPI
 185 NvmeStorageSecurityReceiveData (
 186   IN  EFI_STORAGE_SECURITY_COMMAND_PROTOCOL   *This,
 187   IN  UINT32                                  MediaId,
 188   IN  UINT64                                  Timeout,
 189   IN  UINT8                                   SecurityProtocolId,
 190   IN  UINT16                                  SecurityProtocolSpecificData,
 191   IN  UINTN                                   PayloadBufferSize,
 192   OUT VOID                                    *PayloadBuffer,
 193   OUT UINTN                                   *PayloadTransferSize
 194   );
 195
 196 /**
 197   Send a security protocol command to a device.
 198
 199   The SendData function sends a security protocol command containing the payload
 200   PayloadBuffer to the given MediaId. The security protocol command sent is
 201   defined by SecurityProtocolId and contains the security protocol specific data
 202   SecurityProtocolSpecificData. If the underlying protocol command requires a
 203   specific padding for the command payload, the SendData function shall add padding
 204   bytes to the command payload to satisfy the padding requirements.
 205
 206   For devices supporting the SCSI command set, the security protocol command is sent
 207   using the SECURITY PROTOCOL OUT command defined in SPC-4.
 208
 209   For devices supporting the ATA command set, the security protocol command is sent
 210   using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize
 211   is non-zero. If the PayloadBufferSize is zero, the security protocol command is
 212   sent using the Trusted Non-Data command defined in ATA8-ACS.
 213
 214   If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall
 215   return EFI_INVALID_PARAMETER.
 216
 217   If the given MediaId does not support security protocol commands, the function
 218   shall return EFI_UNSUPPORTED. If there is no media in the device, the function
 219   returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the
 220   device, the function returns EFI_MEDIA_CHANGED.
 221
 222   If the security protocol fails to complete within the Timeout period, the function
 223   shall return EFI_TIMEOUT.
 224
 225   If the security protocol command completes without an error, the function shall return
 226   EFI_SUCCESS. If the security protocol command completes with an error, the function
 227   shall return EFI_DEVICE_ERROR.
 228
 229   @param  This                         Indicates a pointer to the calling context.
 230   @param  MediaId                      ID of the medium to receive data from.
 231   @param  Timeout                      The timeout, in 100ns units, to use for the execution
 232                                        of the security protocol command. A Timeout value of 0
 233                                        means that this function will wait indefinitely for the
 234                                        security protocol command to execute. If Timeout is greater
 235                                        than zero, then this function will return EFI_TIMEOUT
 236                                        if the time required to execute the receive data command
 237                                        is greater than Timeout.
 238   @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
 239                                        the security protocol command to be sent.
 240   @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
 241                                        of the security protocol command to be sent.
 242   @param  PayloadBufferSize            Size in bytes of the payload data buffer.
 243   @param  PayloadBuffer                A pointer to a destination buffer to store the security
 244                                        protocol command specific payload data for the security
 245                                        protocol command.
 246
 247   @retval EFI_SUCCESS                  The security protocol command completed successfully.
 248   @retval EFI_UNSUPPORTED              The given MediaId does not support security protocol commands.
 249   @retval EFI_DEVICE_ERROR             The security protocol command completed with an error.
 250   @retval EFI_NO_MEDIA                 There is no media in the device.
 251   @retval EFI_MEDIA_CHANGED            The MediaId is not for the current media.
 252   @retval EFI_INVALID_PARAMETER        The PayloadBuffer is NULL and PayloadBufferSize is non-zero.
 253   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the security
 254                                        protocol command to execute.
 255
 256 **/
 257 EFI_STATUS
 258 EFIAPI
 259 NvmeStorageSecuritySendData (
 260   IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL    *This,
 261   IN UINT32                                   MediaId,
 262   IN UINT64                                   Timeout,
 263   IN UINT8                                    SecurityProtocolId,
 264   IN UINT16                                   SecurityProtocolSpecificData,
 265   IN UINTN                                    PayloadBufferSize,
 266   IN VOID                                     *PayloadBuffer
 267   );
 268
 269 #endif