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