MdeModulePkg/Bus/Sd/EmmcDxe/EmmcBlockIo.h

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