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 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   Reset the block device hardware.
 113
 114   @param[in]  This                 Indicates a pointer to the calling context.
 115   @param[in]  ExtendedVerification Indicates that the driver may perform a more
 116                                    exhausive verfication operation of the
 117                                    device during reset.
 118
 119   @retval EFI_SUCCESS          The device was reset.
 120   @retval EFI_DEVICE_ERROR     The device is not functioning properly and could
 121                                not be reset.
 122
 123 **/
 124 EFI_STATUS
 125 EFIAPI
 126 NvmeBlockIoResetEx (
 127   IN EFI_BLOCK_IO2_PROTOCOL  *This,
 128   IN BOOLEAN                 ExtendedVerification
 129   );
 130
 131 /**
 132   Read BufferSize bytes from Lba into Buffer.
 133
 134   This function reads the requested number of blocks from the device. All the
 135   blocks are read, or an error is returned.
 136   If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_or EFI_MEDIA_CHANGED is returned and
 137   non-blocking I/O is being used, the Event associated with this request will
 138   not be signaled.
 139
 140   @param[in]       This       Indicates a pointer to the calling context.
 141   @param[in]       MediaId    Id of the media, changes every time the media is
 142                               replaced.
 143   @param[in]       Lba        The starting Logical Block Address to read from.
 144   @param[in, out]  Token      A pointer to the token associated with the
 145                               transaction.
 146   @param[in]       BufferSize Size of Buffer, must be a multiple of device
 147                               block size.
 148   @param[out]      Buffer     A pointer to the destination buffer for the data.
 149                               The caller is responsible for either having
 150                               implicit or explicit ownership of the buffer.
 151
 152   @retval EFI_SUCCESS           The read request was queued if Token->Event is
 153                                 not NULL.The data was read correctly from the
 154                                 device if the Token->Event is NULL.
 155   @retval EFI_DEVICE_ERROR      The device reported an error while performing
 156                                 the read.
 157   @retval EFI_NO_MEDIA          There is no media in the device.
 158   @retval EFI_MEDIA_CHANGED     The MediaId is not for the current media.
 159   @retval EFI_BAD_BUFFER_SIZE   The BufferSize parameter is not a multiple of
 160                                 the intrinsic block size of the device.
 161   @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not
 162                                 valid, or the buffer is not on proper
 163                                 alignment.
 164   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a
 165                                 lack of resources.
 166
 167 **/
 168 EFI_STATUS
 169 EFIAPI
 170 NvmeBlockIoReadBlocksEx (
 171   IN     EFI_BLOCK_IO2_PROTOCOL *This,
 172   IN     UINT32                 MediaId,
 173   IN     EFI_LBA                Lba,
 174   IN OUT EFI_BLOCK_IO2_TOKEN    *Token,
 175   IN     UINTN                  BufferSize,
 176      OUT VOID                  *Buffer
 177   );
 178
 179 /**
 180   Write BufferSize bytes from Lba into Buffer.
 181
 182   This function writes the requested number of blocks to the device. All blocks
 183   are written, or an error is returned.If EFI_DEVICE_ERROR, EFI_NO_MEDIA,
 184   EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED is returned and non-blocking I/O is
 185   being used, the Event associated with this request will not be signaled.
 186
 187   @param[in]       This       Indicates a pointer to the calling context.
 188   @param[in]       MediaId    The media ID that the write request is for.
 189   @param[in]       Lba        The starting logical block address to be written.
 190                               The caller is responsible for writing to only
 191                               legitimate locations.
 192   @param[in, out]  Token      A pointer to the token associated with the
 193                               transaction.
 194   @param[in]       BufferSize Size of Buffer, must be a multiple of device
 195                               block size.
 196   @param[in]       Buffer     A pointer to the source buffer for the data.
 197
 198   @retval EFI_SUCCESS           The write request was queued if Event is not
 199                                 NULL.
 200                                 The data was written correctly to the device if
 201                                 the Event is NULL.
 202   @retval EFI_WRITE_PROTECTED   The device can not be written to.
 203   @retval EFI_NO_MEDIA          There is no media in the device.
 204   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current
 205                                 device.
 206   @retval EFI_DEVICE_ERROR      The device reported an error while performing
 207                                 the write.
 208   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size
 209                                 of the device.
 210   @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not
 211                                 valid, or the buffer is not on proper
 212                                 alignment.
 213   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a
 214                                 lack of resources.
 215
 216 **/
 217 EFI_STATUS
 218 EFIAPI
 219 NvmeBlockIoWriteBlocksEx (
 220   IN     EFI_BLOCK_IO2_PROTOCOL  *This,
 221   IN     UINT32                 MediaId,
 222   IN     EFI_LBA                Lba,
 223   IN OUT EFI_BLOCK_IO2_TOKEN    *Token,
 224   IN     UINTN                  BufferSize,
 225   IN     VOID                   *Buffer
 226   );
 227
 228 /**
 229   Flush the Block Device.
 230
 231   If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED
 232   is returned and non-blocking I/O is being used, the Event associated with
 233   this request will not be signaled.
 234
 235   @param[in]      This     Indicates a pointer to the calling context.
 236   @param[in,out]  Token    A pointer to the token associated with the
 237                            transaction.
 238
 239   @retval EFI_SUCCESS          The flush request was queued if Event is not
 240                                NULL.
 241                                All outstanding data was written correctly to
 242                                the device if the Event is NULL.
 243   @retval EFI_DEVICE_ERROR     The device reported an error while writting back
 244                                the data.
 245   @retval EFI_WRITE_PROTECTED  The device cannot be written to.
 246   @retval EFI_NO_MEDIA         There is no media in the device.
 247   @retval EFI_MEDIA_CHANGED    The MediaId is not for the current media.
 248   @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack
 249                                of resources.
 250
 251 **/
 252 EFI_STATUS
 253 EFIAPI
 254 NvmeBlockIoFlushBlocksEx (
 255   IN     EFI_BLOCK_IO2_PROTOCOL   *This,
 256   IN OUT EFI_BLOCK_IO2_TOKEN      *Token
 257   );
 258
 259 /**
 260   Send a security protocol command to a device that receives data and/or the result
 261   of one or more commands sent by SendData.
 262
 263   The ReceiveData function sends a security protocol command to the given MediaId.
 264   The security protocol command sent is defined by SecurityProtocolId and contains
 265   the security protocol specific data SecurityProtocolSpecificData. The function
 266   returns the data from the security protocol command in PayloadBuffer.
 267
 268   For devices supporting the SCSI command set, the security protocol command is sent
 269   using the SECURITY PROTOCOL IN command defined in SPC-4.
 270
 271   For devices supporting the ATA command set, the security protocol command is sent
 272   using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize
 273   is non-zero.
 274
 275   If the PayloadBufferSize is zero, the security protocol command is sent using the
 276   Trusted Non-Data command defined in ATA8-ACS.
 277
 278   If PayloadBufferSize is too small to store the available data from the security
 279   protocol command, the function shall copy PayloadBufferSize bytes into the
 280   PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL.
 281
 282   If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero,
 283   the function shall return EFI_INVALID_PARAMETER.
 284
 285   If the given MediaId does not support security protocol commands, the function shall
 286   return EFI_UNSUPPORTED. If there is no media in the device, the function returns
 287   EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device,
 288   the function returns EFI_MEDIA_CHANGED.
 289
 290   If the security protocol fails to complete within the Timeout period, the function
 291   shall return EFI_TIMEOUT.
 292
 293   If the security protocol command completes without an error, the function shall
 294   return EFI_SUCCESS. If the security protocol command completes with an error, the
 295   function shall return EFI_DEVICE_ERROR.
 296
 297   @param  This                         Indicates a pointer to the calling context.
 298   @param  MediaId                      ID of the medium to receive data from.
 299   @param  Timeout                      The timeout, in 100ns units, to use for the execution
 300                                        of the security protocol command. A Timeout value of 0
 301                                        means that this function will wait indefinitely for the
 302                                        security protocol command to execute. If Timeout is greater
 303                                        than zero, then this function will return EFI_TIMEOUT
 304                                        if the time required to execute the receive data command
 305                                        is greater than Timeout.
 306   @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
 307                                        the security protocol command to be sent.
 308   @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
 309                                        of the security protocol command to be sent.
 310   @param  PayloadBufferSize            Size in bytes of the payload data buffer.
 311   @param  PayloadBuffer                A pointer to a destination buffer to store the security
 312                                        protocol command specific payload data for the security
 313                                        protocol command. The caller is responsible for having
 314                                        either implicit or explicit ownership of the buffer.
 315   @param  PayloadTransferSize          A pointer to a buffer to store the size in bytes of the
 316                                        data written to the payload data buffer.
 317
 318   @retval EFI_SUCCESS                  The security protocol command completed successfully.
 319   @retval EFI_WARN_BUFFER_TOO_SMALL    The PayloadBufferSize was too small to store the available
 320                                        data from the device. The PayloadBuffer contains the truncated data.
 321   @retval EFI_UNSUPPORTED              The given MediaId does not support security protocol commands.
 322   @retval EFI_DEVICE_ERROR             The security protocol command completed with an error.
 323   @retval EFI_NO_MEDIA                 There is no media in the device.
 324   @retval EFI_MEDIA_CHANGED            The MediaId is not for the current media.
 325   @retval EFI_INVALID_PARAMETER        The PayloadBuffer or PayloadTransferSize is NULL and
 326                                        PayloadBufferSize is non-zero.
 327   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the security
 328                                        protocol command to execute.
 329
 330 **/
 331 EFI_STATUS
 332 EFIAPI
 333 NvmeStorageSecurityReceiveData (
 334   IN  EFI_STORAGE_SECURITY_COMMAND_PROTOCOL   *This,
 335   IN  UINT32                                  MediaId,
 336   IN  UINT64                                  Timeout,
 337   IN  UINT8                                   SecurityProtocolId,
 338   IN  UINT16                                  SecurityProtocolSpecificData,
 339   IN  UINTN                                   PayloadBufferSize,
 340   OUT VOID                                    *PayloadBuffer,
 341   OUT UINTN                                   *PayloadTransferSize
 342   );
 343
 344 /**
 345   Send a security protocol command to a device.
 346
 347   The SendData function sends a security protocol command containing the payload
 348   PayloadBuffer to the given MediaId. The security protocol command sent is
 349   defined by SecurityProtocolId and contains the security protocol specific data
 350   SecurityProtocolSpecificData. If the underlying protocol command requires a
 351   specific padding for the command payload, the SendData function shall add padding
 352   bytes to the command payload to satisfy the padding requirements.
 353
 354   For devices supporting the SCSI command set, the security protocol command is sent
 355   using the SECURITY PROTOCOL OUT command defined in SPC-4.
 356
 357   For devices supporting the ATA command set, the security protocol command is sent
 358   using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize
 359   is non-zero. If the PayloadBufferSize is zero, the security protocol command is
 360   sent using the Trusted Non-Data command defined in ATA8-ACS.
 361
 362   If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall
 363   return EFI_INVALID_PARAMETER.
 364
 365   If the given MediaId does not support security protocol commands, the function
 366   shall return EFI_UNSUPPORTED. If there is no media in the device, the function
 367   returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the
 368   device, the function returns EFI_MEDIA_CHANGED.
 369
 370   If the security protocol fails to complete within the Timeout period, the function
 371   shall return EFI_TIMEOUT.
 372
 373   If the security protocol command completes without an error, the function shall return
 374   EFI_SUCCESS. If the security protocol command completes with an error, the function
 375   shall return EFI_DEVICE_ERROR.
 376
 377   @param  This                         Indicates a pointer to the calling context.
 378   @param  MediaId                      ID of the medium to receive data from.
 379   @param  Timeout                      The timeout, in 100ns units, to use for the execution
 380                                        of the security protocol command. A Timeout value of 0
 381                                        means that this function will wait indefinitely for the
 382                                        security protocol command to execute. If Timeout is greater
 383                                        than zero, then this function will return EFI_TIMEOUT
 384                                        if the time required to execute the receive data command
 385                                        is greater than Timeout.
 386   @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
 387                                        the security protocol command to be sent.
 388   @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
 389                                        of the security protocol command to be sent.
 390   @param  PayloadBufferSize            Size in bytes of the payload data buffer.
 391   @param  PayloadBuffer                A pointer to a destination buffer to store the security
 392                                        protocol command specific payload data for the security
 393                                        protocol command.
 394
 395   @retval EFI_SUCCESS                  The security protocol command completed successfully.
 396   @retval EFI_UNSUPPORTED              The given MediaId does not support security protocol commands.
 397   @retval EFI_DEVICE_ERROR             The security protocol command completed with an error.
 398   @retval EFI_NO_MEDIA                 There is no media in the device.
 399   @retval EFI_MEDIA_CHANGED            The MediaId is not for the current media.
 400   @retval EFI_INVALID_PARAMETER        The PayloadBuffer is NULL and PayloadBufferSize is non-zero.
 401   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the security
 402                                        protocol command to execute.
 403
 404 **/
 405 EFI_STATUS
 406 EFIAPI
 407 NvmeStorageSecuritySendData (
 408   IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL    *This,
 409   IN UINT32                                   MediaId,
 410   IN UINT64                                   Timeout,
 411   IN UINT8                                    SecurityProtocolId,
 412   IN UINT16                                   SecurityProtocolSpecificData,
 413   IN UINTN                                    PayloadBufferSize,
 414   IN VOID                                     *PayloadBuffer
 415   );
 416
 417 #endif