MdeModulePkg/Bus/Pci/NvmExpressDxe/NvmExpressBlockIo.h

   1 /** @file
   2   Header file for EFI_BLOCK_IO_PROTOCOL interface.
   3
   4 Copyright (c) 2013 - 2016, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef _EFI_NVME_BLOCKIO_H_
  10 #define _EFI_NVME_BLOCKIO_H_
  11
  12 /**
  13   Reset the Block Device.
  14
  15   @param  This                 Indicates a pointer to the calling context.
  16   @param  ExtendedVerification Driver may perform diagnostics on reset.
  17
  18   @retval EFI_SUCCESS          The device was reset.
  19   @retval EFI_DEVICE_ERROR     The device is not functioning properly and could
  20                                not be reset.
  21
  22 **/
  23 EFI_STATUS
  24 EFIAPI
  25 NvmeBlockIoReset (
  26   IN  EFI_BLOCK_IO_PROTOCOL   *This,
  27   IN  BOOLEAN                 ExtendedVerification
  28   );
  29
  30 /**
  31   Read BufferSize bytes from Lba into Buffer.
  32
  33   @param  This       Indicates a pointer to the calling context.
  34   @param  MediaId    Id of the media, changes every time the media is replaced.
  35   @param  Lba        The starting Logical Block Address to read from
  36   @param  BufferSize Size of Buffer, must be a multiple of device block size.
  37   @param  Buffer     A pointer to the destination buffer for the data. The caller is
  38                      responsible for either having implicit or explicit ownership of the buffer.
  39
  40   @retval EFI_SUCCESS           The data was read correctly from the device.
  41   @retval EFI_DEVICE_ERROR      The device reported an error while performing the read.
  42   @retval EFI_NO_MEDIA          There is no media in the device.
  43   @retval EFI_MEDIA_CHANGED     The MediaId does not matched the current device.
  44   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
  45   @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
  46                                 or the buffer is not on proper alignment.
  47
  48 **/
  49 EFI_STATUS
  50 EFIAPI
  51 NvmeBlockIoReadBlocks (
  52   IN  EFI_BLOCK_IO_PROTOCOL   *This,
  53   IN  UINT32                  MediaId,
  54   IN  EFI_LBA                 Lba,
  55   IN  UINTN                   BufferSize,
  56   OUT VOID                    *Buffer
  57   );
  58
  59 /**
  60   Write BufferSize bytes from Lba into Buffer.
  61
  62   @param  This       Indicates a pointer to the calling context.
  63   @param  MediaId    The media ID that the write request is for.
  64   @param  Lba        The starting logical block address to be written. The caller is
  65                      responsible for writing to only legitimate locations.
  66   @param  BufferSize Size of Buffer, must be a multiple of device block size.
  67   @param  Buffer     A pointer to the source buffer for the data.
  68
  69   @retval EFI_SUCCESS           The data was written correctly to the device.
  70   @retval EFI_WRITE_PROTECTED   The device can not be written to.
  71   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
  72   @retval EFI_NO_MEDIA          There is no media in the device.
  73   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
  74   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
  75   @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
  76                                 or the buffer is not on proper alignment.
  77
  78 **/
  79 EFI_STATUS
  80 EFIAPI
  81 NvmeBlockIoWriteBlocks (
  82   IN  EFI_BLOCK_IO_PROTOCOL   *This,
  83   IN  UINT32                  MediaId,
  84   IN  EFI_LBA                 Lba,
  85   IN  UINTN                   BufferSize,
  86   IN  VOID                    *Buffer
  87   );
  88
  89 /**
  90   Flush the Block Device.
  91
  92   @param  This              Indicates a pointer to the calling context.
  93
  94   @retval EFI_SUCCESS       All outstanding data was written to the device
  95   @retval EFI_DEVICE_ERROR  The device reported an error while writing back the data
  96   @retval EFI_NO_MEDIA      There is no media in the device.
  97
  98 **/
  99 EFI_STATUS
 100 EFIAPI
 101 NvmeBlockIoFlushBlocks (
 102   IN  EFI_BLOCK_IO_PROTOCOL   *This
 103   );
 104
 105 /**
 106   Reset the block device hardware.
 107
 108   @param[in]  This                 Indicates a pointer to the calling context.
 109   @param[in]  ExtendedVerification Indicates that the driver may perform a more
 110                                    exhausive verfication operation of the
 111                                    device during reset.
 112
 113   @retval EFI_SUCCESS          The device was reset.
 114   @retval EFI_DEVICE_ERROR     The device is not functioning properly and could
 115                                not be reset.
 116
 117 **/
 118 EFI_STATUS
 119 EFIAPI
 120 NvmeBlockIoResetEx (
 121   IN EFI_BLOCK_IO2_PROTOCOL  *This,
 122   IN BOOLEAN                 ExtendedVerification
 123   );
 124
 125 /**
 126   Read BufferSize bytes from Lba into Buffer.
 127
 128   This function reads the requested number of blocks from the device. All the
 129   blocks are read, or an error is returned.
 130   If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_or EFI_MEDIA_CHANGED is returned and
 131   non-blocking I/O is being used, the Event associated with this request will
 132   not be signaled.
 133
 134   @param[in]       This       Indicates a pointer to the calling context.
 135   @param[in]       MediaId    Id of the media, changes every time the media is
 136                               replaced.
 137   @param[in]       Lba        The starting Logical Block Address to read from.
 138   @param[in, out]  Token      A pointer to the token associated with the
 139                               transaction.
 140   @param[in]       BufferSize Size of Buffer, must be a multiple of device
 141                               block size.
 142   @param[out]      Buffer     A pointer to the destination buffer for the data.
 143                               The caller is responsible for either having
 144                               implicit or explicit ownership of the buffer.
 145
 146   @retval EFI_SUCCESS           The read request was queued if Token->Event is
 147                                 not NULL.The data was read correctly from the
 148                                 device if the Token->Event is NULL.
 149   @retval EFI_DEVICE_ERROR      The device reported an error while performing
 150                                 the read.
 151   @retval EFI_NO_MEDIA          There is no media in the device.
 152   @retval EFI_MEDIA_CHANGED     The MediaId is not for the current media.
 153   @retval EFI_BAD_BUFFER_SIZE   The BufferSize parameter is not a multiple of
 154                                 the intrinsic block size of the device.
 155   @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not
 156                                 valid, or the buffer is not on proper
 157                                 alignment.
 158   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a
 159                                 lack of resources.
 160
 161 **/
 162 EFI_STATUS
 163 EFIAPI
 164 NvmeBlockIoReadBlocksEx (
 165   IN     EFI_BLOCK_IO2_PROTOCOL *This,
 166   IN     UINT32                 MediaId,
 167   IN     EFI_LBA                Lba,
 168   IN OUT EFI_BLOCK_IO2_TOKEN    *Token,
 169   IN     UINTN                  BufferSize,
 170      OUT VOID                  *Buffer
 171   );
 172
 173 /**
 174   Write BufferSize bytes from Lba into Buffer.
 175
 176   This function writes the requested number of blocks to the device. All blocks
 177   are written, or an error is returned.If EFI_DEVICE_ERROR, EFI_NO_MEDIA,
 178   EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED is returned and non-blocking I/O is
 179   being used, the Event associated with this request will not be signaled.
 180
 181   @param[in]       This       Indicates a pointer to the calling context.
 182   @param[in]       MediaId    The media ID that the write request is for.
 183   @param[in]       Lba        The starting logical block address to be written.
 184                               The caller is responsible for writing to only
 185                               legitimate locations.
 186   @param[in, out]  Token      A pointer to the token associated with the
 187                               transaction.
 188   @param[in]       BufferSize Size of Buffer, must be a multiple of device
 189                               block size.
 190   @param[in]       Buffer     A pointer to the source buffer for the data.
 191
 192   @retval EFI_SUCCESS           The write request was queued if Event is not
 193                                 NULL.
 194                                 The data was written correctly to the device if
 195                                 the Event is NULL.
 196   @retval EFI_WRITE_PROTECTED   The device can not be written to.
 197   @retval EFI_NO_MEDIA          There is no media in the device.
 198   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current
 199                                 device.
 200   @retval EFI_DEVICE_ERROR      The device reported an error while performing
 201                                 the write.
 202   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size
 203                                 of the device.
 204   @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not
 205                                 valid, or the buffer is not on proper
 206                                 alignment.
 207   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a
 208                                 lack of resources.
 209
 210 **/
 211 EFI_STATUS
 212 EFIAPI
 213 NvmeBlockIoWriteBlocksEx (
 214   IN     EFI_BLOCK_IO2_PROTOCOL  *This,
 215   IN     UINT32                 MediaId,
 216   IN     EFI_LBA                Lba,
 217   IN OUT EFI_BLOCK_IO2_TOKEN    *Token,
 218   IN     UINTN                  BufferSize,
 219   IN     VOID                   *Buffer
 220   );
 221
 222 /**
 223   Flush the Block Device.
 224
 225   If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED
 226   is returned and non-blocking I/O is being used, the Event associated with
 227   this request will not be signaled.
 228
 229   @param[in]      This     Indicates a pointer to the calling context.
 230   @param[in,out]  Token    A pointer to the token associated with the
 231                            transaction.
 232
 233   @retval EFI_SUCCESS          The flush request was queued if Event is not
 234                                NULL.
 235                                All outstanding data was written correctly to
 236                                the device if the Event is NULL.
 237   @retval EFI_DEVICE_ERROR     The device reported an error while writting back
 238                                the data.
 239   @retval EFI_WRITE_PROTECTED  The device cannot be written to.
 240   @retval EFI_NO_MEDIA         There is no media in the device.
 241   @retval EFI_MEDIA_CHANGED    The MediaId is not for the current media.
 242   @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack
 243                                of resources.
 244
 245 **/
 246 EFI_STATUS
 247 EFIAPI
 248 NvmeBlockIoFlushBlocksEx (
 249   IN     EFI_BLOCK_IO2_PROTOCOL   *This,
 250   IN OUT EFI_BLOCK_IO2_TOKEN      *Token
 251   );
 252
 253 /**
 254   Send a security protocol command to a device that receives data and/or the result
 255   of one or more commands sent by SendData.
 256
 257   The ReceiveData function sends a security protocol command to the given MediaId.
 258   The security protocol command sent is defined by SecurityProtocolId and contains
 259   the security protocol specific data SecurityProtocolSpecificData. The function
 260   returns the data from the security protocol command in PayloadBuffer.
 261
 262   For devices supporting the SCSI command set, the security protocol command is sent
 263   using the SECURITY PROTOCOL IN command defined in SPC-4.
 264
 265   For devices supporting the ATA command set, the security protocol command is sent
 266   using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize
 267   is non-zero.
 268
 269   If the PayloadBufferSize is zero, the security protocol command is sent using the
 270   Trusted Non-Data command defined in ATA8-ACS.
 271
 272   If PayloadBufferSize is too small to store the available data from the security
 273   protocol command, the function shall copy PayloadBufferSize bytes into the
 274   PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL.
 275
 276   If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero,
 277   the function shall return EFI_INVALID_PARAMETER.
 278
 279   If the given MediaId does not support security protocol commands, the function shall
 280   return EFI_UNSUPPORTED. If there is no media in the device, the function returns
 281   EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device,
 282   the function returns EFI_MEDIA_CHANGED.
 283
 284   If the security protocol fails to complete within the Timeout period, the function
 285   shall return EFI_TIMEOUT.
 286
 287   If the security protocol command completes without an error, the function shall
 288   return EFI_SUCCESS. If the security protocol command completes with an error, the
 289   function shall return EFI_DEVICE_ERROR.
 290
 291   @param  This                         Indicates a pointer to the calling context.
 292   @param  MediaId                      ID of the medium to receive data from.
 293   @param  Timeout                      The timeout, in 100ns units, to use for the execution
 294                                        of the security protocol command. A Timeout value of 0
 295                                        means that this function will wait indefinitely for the
 296                                        security protocol command to execute. If Timeout is greater
 297                                        than zero, then this function will return EFI_TIMEOUT
 298                                        if the time required to execute the receive data command
 299                                        is greater than Timeout.
 300   @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
 301                                        the security protocol command to be sent.
 302   @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
 303                                        of the security protocol command to be sent.
 304   @param  PayloadBufferSize            Size in bytes of the payload data buffer.
 305   @param  PayloadBuffer                A pointer to a destination buffer to store the security
 306                                        protocol command specific payload data for the security
 307                                        protocol command. The caller is responsible for having
 308                                        either implicit or explicit ownership of the buffer.
 309   @param  PayloadTransferSize          A pointer to a buffer to store the size in bytes of the
 310                                        data written to the payload data buffer.
 311
 312   @retval EFI_SUCCESS                  The security protocol command completed successfully.
 313   @retval EFI_WARN_BUFFER_TOO_SMALL    The PayloadBufferSize was too small to store the available
 314                                        data from the device. The PayloadBuffer contains the truncated data.
 315   @retval EFI_UNSUPPORTED              The given MediaId does not support security protocol commands.
 316   @retval EFI_DEVICE_ERROR             The security protocol command completed with an error.
 317   @retval EFI_NO_MEDIA                 There is no media in the device.
 318   @retval EFI_MEDIA_CHANGED            The MediaId is not for the current media.
 319   @retval EFI_INVALID_PARAMETER        The PayloadBuffer or PayloadTransferSize is NULL and
 320                                        PayloadBufferSize is non-zero.
 321   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the security
 322                                        protocol command to execute.
 323
 324 **/
 325 EFI_STATUS
 326 EFIAPI
 327 NvmeStorageSecurityReceiveData (
 328   IN  EFI_STORAGE_SECURITY_COMMAND_PROTOCOL   *This,
 329   IN  UINT32                                  MediaId,
 330   IN  UINT64                                  Timeout,
 331   IN  UINT8                                   SecurityProtocolId,
 332   IN  UINT16                                  SecurityProtocolSpecificData,
 333   IN  UINTN                                   PayloadBufferSize,
 334   OUT VOID                                    *PayloadBuffer,
 335   OUT UINTN                                   *PayloadTransferSize
 336   );
 337
 338 /**
 339   Send a security protocol command to a device.
 340
 341   The SendData function sends a security protocol command containing the payload
 342   PayloadBuffer to the given MediaId. The security protocol command sent is
 343   defined by SecurityProtocolId and contains the security protocol specific data
 344   SecurityProtocolSpecificData. If the underlying protocol command requires a
 345   specific padding for the command payload, the SendData function shall add padding
 346   bytes to the command payload to satisfy the padding requirements.
 347
 348   For devices supporting the SCSI command set, the security protocol command is sent
 349   using the SECURITY PROTOCOL OUT command defined in SPC-4.
 350
 351   For devices supporting the ATA command set, the security protocol command is sent
 352   using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize
 353   is non-zero. If the PayloadBufferSize is zero, the security protocol command is
 354   sent using the Trusted Non-Data command defined in ATA8-ACS.
 355
 356   If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall
 357   return EFI_INVALID_PARAMETER.
 358
 359   If the given MediaId does not support security protocol commands, the function
 360   shall return EFI_UNSUPPORTED. If there is no media in the device, the function
 361   returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the
 362   device, the function returns EFI_MEDIA_CHANGED.
 363
 364   If the security protocol fails to complete within the Timeout period, the function
 365   shall return EFI_TIMEOUT.
 366
 367   If the security protocol command completes without an error, the function shall return
 368   EFI_SUCCESS. If the security protocol command completes with an error, the function
 369   shall return EFI_DEVICE_ERROR.
 370
 371   @param  This                         Indicates a pointer to the calling context.
 372   @param  MediaId                      ID of the medium to receive data from.
 373   @param  Timeout                      The timeout, in 100ns units, to use for the execution
 374                                        of the security protocol command. A Timeout value of 0
 375                                        means that this function will wait indefinitely for the
 376                                        security protocol command to execute. If Timeout is greater
 377                                        than zero, then this function will return EFI_TIMEOUT
 378                                        if the time required to execute the receive data command
 379                                        is greater than Timeout.
 380   @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
 381                                        the security protocol command to be sent.
 382   @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
 383                                        of the security protocol command to be sent.
 384   @param  PayloadBufferSize            Size in bytes of the payload data buffer.
 385   @param  PayloadBuffer                A pointer to a destination buffer to store the security
 386                                        protocol command specific payload data for the security
 387                                        protocol command.
 388
 389   @retval EFI_SUCCESS                  The security protocol command completed successfully.
 390   @retval EFI_UNSUPPORTED              The given MediaId does not support security protocol commands.
 391   @retval EFI_DEVICE_ERROR             The security protocol command completed with an error.
 392   @retval EFI_NO_MEDIA                 There is no media in the device.
 393   @retval EFI_MEDIA_CHANGED            The MediaId is not for the current media.
 394   @retval EFI_INVALID_PARAMETER        The PayloadBuffer is NULL and PayloadBufferSize is non-zero.
 395   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the security
 396                                        protocol command to execute.
 397
 398 **/
 399 EFI_STATUS
 400 EFIAPI
 401 NvmeStorageSecuritySendData (
 402   IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL    *This,
 403   IN UINT32                                   MediaId,
 404   IN UINT64                                   Timeout,
 405   IN UINT8                                    SecurityProtocolId,
 406   IN UINT16                                   SecurityProtocolSpecificData,
 407   IN UINTN                                    PayloadBufferSize,
 408   IN VOID                                     *PayloadBuffer
 409   );
 410
 411 #endif