MdeModulePkg/Bus/Pci/NvmExpressDxe/NvmExpressBlockIo.c

   1 /** @file
   2   NvmExpressDxe driver is used to manage non-volatile memory subsystem which follows
   3   NVM Express specification.
   4
   5   Copyright (c) 2013 - 2016, Intel Corporation. All rights reserved.<BR>
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php.
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #include "NvmExpress.h"
  17
  18 /**
  19   Read some sectors from the device.
  20
  21   @param  Device                 The pointer to the NVME_DEVICE_PRIVATE_DATA data structure.
  22   @param  Buffer                 The buffer used to store the data read from the device.
  23   @param  Lba                    The start block number.
  24   @param  Blocks                 Total block number to be read.
  25
  26   @retval EFI_SUCCESS            Datum are read from the device.
  27   @retval Others                 Fail to read all the datum.
  28
  29 **/
  30 EFI_STATUS
  31 ReadSectors (
  32   IN NVME_DEVICE_PRIVATE_DATA           *Device,
  33   IN UINT64                             Buffer,
  34   IN UINT64                             Lba,
  35   IN UINT32                             Blocks
  36   )
  37 {
  38   NVME_CONTROLLER_PRIVATE_DATA             *Private;
  39   UINT32                                   Bytes;
  40   EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET CommandPacket;
  41   EFI_NVM_EXPRESS_COMMAND                  Command;
  42   EFI_NVM_EXPRESS_COMPLETION               Completion;
  43   EFI_STATUS                               Status;
  44   UINT32                                   BlockSize;
  45
  46   Private    = Device->Controller;
  47   BlockSize  = Device->Media.BlockSize;
  48   Bytes      = Blocks * BlockSize;
  49
  50   ZeroMem (&CommandPacket, sizeof(EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET));
  51   ZeroMem (&Command, sizeof(EFI_NVM_EXPRESS_COMMAND));
  52   ZeroMem (&Completion, sizeof(EFI_NVM_EXPRESS_COMPLETION));
  53
  54   CommandPacket.NvmeCmd        = &Command;
  55   CommandPacket.NvmeCompletion = &Completion;
  56
  57   CommandPacket.NvmeCmd->Cdw0.Opcode = NVME_IO_READ_OPC;
  58   CommandPacket.NvmeCmd->Nsid        = Device->NamespaceId;
  59   CommandPacket.TransferBuffer       = (VOID *)(UINTN)Buffer;
  60
  61   CommandPacket.TransferLength = Bytes;
  62   CommandPacket.CommandTimeout = NVME_GENERIC_TIMEOUT;
  63   CommandPacket.QueueType      = NVME_IO_QUEUE;
  64
  65   CommandPacket.NvmeCmd->Cdw10 = (UINT32)Lba;
  66   CommandPacket.NvmeCmd->Cdw11 = (UINT32)RShiftU64(Lba, 32);
  67   CommandPacket.NvmeCmd->Cdw12 = (Blocks - 1) & 0xFFFF;
  68
  69   CommandPacket.NvmeCmd->Flags = CDW10_VALID | CDW11_VALID | CDW12_VALID;
  70
  71   Status = Private->Passthru.PassThru (
  72                                &Private->Passthru,
  73                                Device->NamespaceId,
  74                                &CommandPacket,
  75                                NULL
  76                                );
  77
  78   return Status;
  79 }
  80
  81 /**
  82   Write some sectors to the device.
  83
  84   @param  Device                 The pointer to the NVME_DEVICE_PRIVATE_DATA data structure.
  85   @param  Buffer                 The buffer to be written into the device.
  86   @param  Lba                    The start block number.
  87   @param  Blocks                 Total block number to be written.
  88
  89   @retval EFI_SUCCESS            Datum are written into the buffer.
  90   @retval Others                 Fail to write all the datum.
  91
  92 **/
  93 EFI_STATUS
  94 WriteSectors (
  95   IN NVME_DEVICE_PRIVATE_DATA      *Device,
  96   IN UINT64                        Buffer,
  97   IN UINT64                        Lba,
  98   IN UINT32                        Blocks
  99   )
 100 {
 101   NVME_CONTROLLER_PRIVATE_DATA             *Private;
 102   EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET CommandPacket;
 103   EFI_NVM_EXPRESS_COMMAND                  Command;
 104   EFI_NVM_EXPRESS_COMPLETION               Completion;
 105   EFI_STATUS                               Status;
 106   UINT32                                   Bytes;
 107   UINT32                                   BlockSize;
 108
 109   Private    = Device->Controller;
 110   BlockSize  = Device->Media.BlockSize;
 111   Bytes      = Blocks * BlockSize;
 112
 113   ZeroMem (&CommandPacket, sizeof(EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET));
 114   ZeroMem (&Command, sizeof(EFI_NVM_EXPRESS_COMMAND));
 115   ZeroMem (&Completion, sizeof(EFI_NVM_EXPRESS_COMPLETION));
 116
 117   CommandPacket.NvmeCmd        = &Command;
 118   CommandPacket.NvmeCompletion = &Completion;
 119
 120   CommandPacket.NvmeCmd->Cdw0.Opcode = NVME_IO_WRITE_OPC;
 121   CommandPacket.NvmeCmd->Nsid  = Device->NamespaceId;
 122   CommandPacket.TransferBuffer = (VOID *)(UINTN)Buffer;
 123
 124   CommandPacket.TransferLength = Bytes;
 125   CommandPacket.CommandTimeout = NVME_GENERIC_TIMEOUT;
 126   CommandPacket.QueueType      = NVME_IO_QUEUE;
 127
 128   CommandPacket.NvmeCmd->Cdw10 = (UINT32)Lba;
 129   CommandPacket.NvmeCmd->Cdw11 = (UINT32)RShiftU64(Lba, 32);
 130   //
 131   // Set Force Unit Access bit (bit 30) to use write-through behaviour
 132   //
 133   CommandPacket.NvmeCmd->Cdw12 = ((Blocks - 1) & 0xFFFF) | BIT30;
 134
 135   CommandPacket.MetadataBuffer = NULL;
 136   CommandPacket.MetadataLength = 0;
 137
 138   CommandPacket.NvmeCmd->Flags = CDW10_VALID | CDW11_VALID | CDW12_VALID;
 139
 140   Status = Private->Passthru.PassThru (
 141                                &Private->Passthru,
 142                                Device->NamespaceId,
 143                                &CommandPacket,
 144                                NULL
 145                                );
 146
 147   return Status;
 148 }
 149
 150 /**
 151   Read some blocks from the device.
 152
 153   @param  Device                 The pointer to the NVME_DEVICE_PRIVATE_DATA data structure.
 154   @param  Buffer                 The buffer used to store the data read from the device.
 155   @param  Lba                    The start block number.
 156   @param  Blocks                 Total block number to be read.
 157
 158   @retval EFI_SUCCESS            Datum are read from the device.
 159   @retval Others                 Fail to read all the datum.
 160
 161 **/
 162 EFI_STATUS
 163 NvmeRead (
 164   IN     NVME_DEVICE_PRIVATE_DATA       *Device,
 165      OUT VOID                           *Buffer,
 166   IN     UINT64                         Lba,
 167   IN     UINTN                          Blocks
 168   )
 169 {
 170   EFI_STATUS                       Status;
 171   UINT32                           BlockSize;
 172   NVME_CONTROLLER_PRIVATE_DATA     *Private;
 173   UINT32                           MaxTransferBlocks;
 174   UINTN                            OrginalBlocks;
 175
 176   Status        = EFI_SUCCESS;
 177   Private       = Device->Controller;
 178   BlockSize     = Device->Media.BlockSize;
 179   OrginalBlocks = Blocks;
 180
 181   if (Private->ControllerData->Mdts != 0) {
 182     MaxTransferBlocks = (1 << (Private->ControllerData->Mdts)) * (1 << (Private->Cap.Mpsmin + 12)) / BlockSize;
 183   } else {
 184     MaxTransferBlocks = 1024;
 185   }
 186
 187   while (Blocks > 0) {
 188     if (Blocks > MaxTransferBlocks) {
 189       Status = ReadSectors (Device, (UINT64)(UINTN)Buffer, Lba, MaxTransferBlocks);
 190
 191       Blocks -= MaxTransferBlocks;
 192       Buffer  = (VOID *)(UINTN)((UINT64)(UINTN)Buffer + MaxTransferBlocks * BlockSize);
 193       Lba    += MaxTransferBlocks;
 194     } else {
 195       Status = ReadSectors (Device, (UINT64)(UINTN)Buffer, Lba, (UINT32)Blocks);
 196       Blocks = 0;
 197     }
 198
 199     if (EFI_ERROR(Status)) {
 200       break;
 201     }
 202   }
 203
 204   DEBUG ((EFI_D_VERBOSE, "%a: Lba = 0x%08Lx, Original = 0x%08Lx, "
 205     "Remaining = 0x%08Lx, BlockSize = 0x%x, Status = %r\n", __FUNCTION__, Lba,
 206     (UINT64)OrginalBlocks, (UINT64)Blocks, BlockSize, Status));
 207
 208   return Status;
 209 }
 210
 211 /**
 212   Write some blocks to the device.
 213
 214   @param  Device                 The pointer to the NVME_DEVICE_PRIVATE_DATA data structure.
 215   @param  Buffer                 The buffer to be written into the device.
 216   @param  Lba                    The start block number.
 217   @param  Blocks                 Total block number to be written.
 218
 219   @retval EFI_SUCCESS            Datum are written into the buffer.
 220   @retval Others                 Fail to write all the datum.
 221
 222 **/
 223 EFI_STATUS
 224 NvmeWrite (
 225   IN NVME_DEVICE_PRIVATE_DATA           *Device,
 226   IN VOID                               *Buffer,
 227   IN UINT64                             Lba,
 228   IN UINTN                              Blocks
 229   )
 230 {
 231   EFI_STATUS                       Status;
 232   UINT32                           BlockSize;
 233   NVME_CONTROLLER_PRIVATE_DATA     *Private;
 234   UINT32                           MaxTransferBlocks;
 235   UINTN                            OrginalBlocks;
 236
 237   Status        = EFI_SUCCESS;
 238   Private       = Device->Controller;
 239   BlockSize     = Device->Media.BlockSize;
 240   OrginalBlocks = Blocks;
 241
 242   if (Private->ControllerData->Mdts != 0) {
 243     MaxTransferBlocks = (1 << (Private->ControllerData->Mdts)) * (1 << (Private->Cap.Mpsmin + 12)) / BlockSize;
 244   } else {
 245     MaxTransferBlocks = 1024;
 246   }
 247
 248   while (Blocks > 0) {
 249     if (Blocks > MaxTransferBlocks) {
 250       Status = WriteSectors (Device, (UINT64)(UINTN)Buffer, Lba, MaxTransferBlocks);
 251
 252       Blocks -= MaxTransferBlocks;
 253       Buffer  = (VOID *)(UINTN)((UINT64)(UINTN)Buffer + MaxTransferBlocks * BlockSize);
 254       Lba    += MaxTransferBlocks;
 255     } else {
 256       Status = WriteSectors (Device, (UINT64)(UINTN)Buffer, Lba, (UINT32)Blocks);
 257       Blocks = 0;
 258     }
 259
 260     if (EFI_ERROR(Status)) {
 261       break;
 262     }
 263   }
 264
 265   DEBUG ((EFI_D_VERBOSE, "%a: Lba = 0x%08Lx, Original = 0x%08Lx, "
 266     "Remaining = 0x%08Lx, BlockSize = 0x%x, Status = %r\n", __FUNCTION__, Lba,
 267     (UINT64)OrginalBlocks, (UINT64)Blocks, BlockSize, Status));
 268
 269   return Status;
 270 }
 271
 272 /**
 273   Flushes all modified data to the device.
 274
 275   @param  Device                 The pointer to the NVME_DEVICE_PRIVATE_DATA data structure.
 276
 277   @retval EFI_SUCCESS            Datum are written into the buffer.
 278   @retval Others                 Fail to write all the datum.
 279
 280 **/
 281 EFI_STATUS
 282 NvmeFlush (
 283   IN NVME_DEVICE_PRIVATE_DATA      *Device
 284   )
 285 {
 286   NVME_CONTROLLER_PRIVATE_DATA             *Private;
 287   EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET CommandPacket;
 288   EFI_NVM_EXPRESS_COMMAND                  Command;
 289   EFI_NVM_EXPRESS_COMPLETION               Completion;
 290   EFI_STATUS                               Status;
 291
 292   Private = Device->Controller;
 293
 294   ZeroMem (&CommandPacket, sizeof(EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET));
 295   ZeroMem (&Command, sizeof(EFI_NVM_EXPRESS_COMMAND));
 296   ZeroMem (&Completion, sizeof(EFI_NVM_EXPRESS_COMPLETION));
 297
 298   CommandPacket.NvmeCmd        = &Command;
 299   CommandPacket.NvmeCompletion = &Completion;
 300
 301   CommandPacket.NvmeCmd->Cdw0.Opcode = NVME_IO_FLUSH_OPC;
 302   CommandPacket.NvmeCmd->Nsid  = Device->NamespaceId;
 303   CommandPacket.CommandTimeout = NVME_GENERIC_TIMEOUT;
 304   CommandPacket.QueueType      = NVME_IO_QUEUE;
 305
 306   Status = Private->Passthru.PassThru (
 307                                &Private->Passthru,
 308                                Device->NamespaceId,
 309                                &CommandPacket,
 310                                NULL
 311                                );
 312
 313   return Status;
 314 }
 315
 316
 317 /**
 318   Reset the Block Device.
 319
 320   @param  This                 Indicates a pointer to the calling context.
 321   @param  ExtendedVerification Driver may perform diagnostics on reset.
 322
 323   @retval EFI_SUCCESS          The device was reset.
 324   @retval EFI_DEVICE_ERROR     The device is not functioning properly and could
 325                                not be reset.
 326
 327 **/
 328 EFI_STATUS
 329 EFIAPI
 330 NvmeBlockIoReset (
 331   IN  EFI_BLOCK_IO_PROTOCOL   *This,
 332   IN  BOOLEAN                 ExtendedVerification
 333   )
 334 {
 335   EFI_TPL                         OldTpl;
 336   NVME_CONTROLLER_PRIVATE_DATA    *Private;
 337   NVME_DEVICE_PRIVATE_DATA        *Device;
 338   EFI_STATUS                      Status;
 339
 340   if (This == NULL) {
 341     return EFI_INVALID_PARAMETER;
 342   }
 343
 344   //
 345   // For Nvm Express subsystem, reset block device means reset controller.
 346   //
 347   OldTpl  = gBS->RaiseTPL (TPL_CALLBACK);
 348
 349   Device  = NVME_DEVICE_PRIVATE_DATA_FROM_BLOCK_IO (This);
 350
 351   Private = Device->Controller;
 352
 353   Status  = NvmeControllerInit (Private);
 354
 355   if (EFI_ERROR (Status)) {
 356     Status = EFI_DEVICE_ERROR;
 357   }
 358
 359   gBS->RestoreTPL (OldTpl);
 360
 361   return Status;
 362 }
 363
 364 /**
 365   Read BufferSize bytes from Lba into Buffer.
 366
 367   @param  This       Indicates a pointer to the calling context.
 368   @param  MediaId    Id of the media, changes every time the media is replaced.
 369   @param  Lba        The starting Logical Block Address to read from.
 370   @param  BufferSize Size of Buffer, must be a multiple of device block size.
 371   @param  Buffer     A pointer to the destination buffer for the data. The caller is
 372                      responsible for either having implicit or explicit ownership of the buffer.
 373
 374   @retval EFI_SUCCESS           The data was read correctly from the device.
 375   @retval EFI_DEVICE_ERROR      The device reported an error while performing the read.
 376   @retval EFI_NO_MEDIA          There is no media in the device.
 377   @retval EFI_MEDIA_CHANGED     The MediaId does not matched the current device.
 378   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
 379   @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
 380                                 or the buffer is not on proper alignment.
 381
 382 **/
 383 EFI_STATUS
 384 EFIAPI
 385 NvmeBlockIoReadBlocks (
 386   IN  EFI_BLOCK_IO_PROTOCOL   *This,
 387   IN  UINT32                  MediaId,
 388   IN  EFI_LBA                 Lba,
 389   IN  UINTN                   BufferSize,
 390   OUT VOID                    *Buffer
 391   )
 392 {
 393   NVME_DEVICE_PRIVATE_DATA          *Device;
 394   EFI_STATUS                        Status;
 395   EFI_BLOCK_IO_MEDIA                *Media;
 396   UINTN                             BlockSize;
 397   UINTN                             NumberOfBlocks;
 398   UINTN                             IoAlign;
 399   EFI_TPL                           OldTpl;
 400
 401   //
 402   // Check parameters.
 403   //
 404   if (This == NULL) {
 405     return EFI_INVALID_PARAMETER;
 406   }
 407
 408   Media = This->Media;
 409
 410   if (MediaId != Media->MediaId) {
 411     return EFI_MEDIA_CHANGED;
 412   }
 413
 414   if (Buffer == NULL) {
 415     return EFI_INVALID_PARAMETER;
 416   }
 417
 418   if (BufferSize == 0) {
 419     return EFI_SUCCESS;
 420   }
 421
 422   BlockSize = Media->BlockSize;
 423   if ((BufferSize % BlockSize) != 0) {
 424     return EFI_BAD_BUFFER_SIZE;
 425   }
 426
 427   NumberOfBlocks  = BufferSize / BlockSize;
 428   if ((Lba + NumberOfBlocks - 1) > Media->LastBlock) {
 429     return EFI_INVALID_PARAMETER;
 430   }
 431
 432   IoAlign = Media->IoAlign;
 433   if (IoAlign > 0 && (((UINTN) Buffer & (IoAlign - 1)) != 0)) {
 434     return EFI_INVALID_PARAMETER;
 435   }
 436
 437   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 438
 439   Device = NVME_DEVICE_PRIVATE_DATA_FROM_BLOCK_IO (This);
 440
 441   Status = NvmeRead (Device, Buffer, Lba, NumberOfBlocks);
 442
 443   gBS->RestoreTPL (OldTpl);
 444   return Status;
 445 }
 446
 447 /**
 448   Write BufferSize bytes from Lba into Buffer.
 449
 450   @param  This       Indicates a pointer to the calling context.
 451   @param  MediaId    The media ID that the write request is for.
 452   @param  Lba        The starting logical block address to be written. The caller is
 453                      responsible for writing to only legitimate locations.
 454   @param  BufferSize Size of Buffer, must be a multiple of device block size.
 455   @param  Buffer     A pointer to the source buffer for the data.
 456
 457   @retval EFI_SUCCESS           The data was written correctly to the device.
 458   @retval EFI_WRITE_PROTECTED   The device can not be written to.
 459   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
 460   @retval EFI_NO_MEDIA          There is no media in the device.
 461   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
 462   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
 463   @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
 464                                 or the buffer is not on proper alignment.
 465
 466 **/
 467 EFI_STATUS
 468 EFIAPI
 469 NvmeBlockIoWriteBlocks (
 470   IN  EFI_BLOCK_IO_PROTOCOL   *This,
 471   IN  UINT32                  MediaId,
 472   IN  EFI_LBA                 Lba,
 473   IN  UINTN                   BufferSize,
 474   IN  VOID                    *Buffer
 475   )
 476 {
 477   NVME_DEVICE_PRIVATE_DATA          *Device;
 478   EFI_STATUS                        Status;
 479   EFI_BLOCK_IO_MEDIA                *Media;
 480   UINTN                             BlockSize;
 481   UINTN                             NumberOfBlocks;
 482   UINTN                             IoAlign;
 483   EFI_TPL                           OldTpl;
 484
 485   //
 486   // Check parameters.
 487   //
 488   if (This == NULL) {
 489     return EFI_INVALID_PARAMETER;
 490   }
 491
 492   Media = This->Media;
 493
 494   if (MediaId != Media->MediaId) {
 495     return EFI_MEDIA_CHANGED;
 496   }
 497
 498   if (Buffer == NULL) {
 499     return EFI_INVALID_PARAMETER;
 500   }
 501
 502   if (BufferSize == 0) {
 503     return EFI_SUCCESS;
 504   }
 505
 506   BlockSize = Media->BlockSize;
 507   if ((BufferSize % BlockSize) != 0) {
 508     return EFI_BAD_BUFFER_SIZE;
 509   }
 510
 511   NumberOfBlocks  = BufferSize / BlockSize;
 512   if ((Lba + NumberOfBlocks - 1) > Media->LastBlock) {
 513     return EFI_INVALID_PARAMETER;
 514   }
 515
 516   IoAlign = Media->IoAlign;
 517   if (IoAlign > 0 && (((UINTN) Buffer & (IoAlign - 1)) != 0)) {
 518     return EFI_INVALID_PARAMETER;
 519   }
 520
 521   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 522
 523   Device = NVME_DEVICE_PRIVATE_DATA_FROM_BLOCK_IO (This);
 524
 525   Status = NvmeWrite (Device, Buffer, Lba, NumberOfBlocks);
 526
 527   gBS->RestoreTPL (OldTpl);
 528
 529   return Status;
 530 }
 531
 532 /**
 533   Flush the Block Device.
 534
 535   @param  This              Indicates a pointer to the calling context.
 536
 537   @retval EFI_SUCCESS       All outstanding data was written to the device.
 538   @retval EFI_DEVICE_ERROR  The device reported an error while writing back the data.
 539   @retval EFI_NO_MEDIA      There is no media in the device.
 540
 541 **/
 542 EFI_STATUS
 543 EFIAPI
 544 NvmeBlockIoFlushBlocks (
 545   IN  EFI_BLOCK_IO_PROTOCOL   *This
 546   )
 547 {
 548   NVME_DEVICE_PRIVATE_DATA          *Device;
 549   EFI_STATUS                        Status;
 550   EFI_TPL                           OldTpl;
 551
 552   //
 553   // Check parameters.
 554   //
 555   if (This == NULL) {
 556     return EFI_INVALID_PARAMETER;
 557   }
 558
 559   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 560
 561   Device = NVME_DEVICE_PRIVATE_DATA_FROM_BLOCK_IO (This);
 562
 563   Status = NvmeFlush (Device);
 564
 565   gBS->RestoreTPL (OldTpl);
 566
 567   return Status;
 568 }
 569
 570 /**
 571   Trust transfer data from/to NVMe device.
 572
 573   This function performs one NVMe transaction to do a trust transfer from/to NVMe device.
 574
 575   @param  Private                      The pointer to the NVME_CONTROLLER_PRIVATE_DATA data structure.
 576   @param  Buffer                       The pointer to the current transaction buffer.
 577   @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
 578                                        the security protocol command to be sent.
 579   @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
 580                                        of the security protocol command to be sent.
 581   @param  TransferLength               The block number or sector count of the transfer.
 582   @param  IsTrustSend                  Indicates whether it is a trust send operation or not.
 583   @param  Timeout                      The timeout, in 100ns units, to use for the execution
 584                                        of the security protocol command. A Timeout value of 0
 585                                        means that this function will wait indefinitely for the
 586                                        security protocol command to execute. If Timeout is greater
 587                                        than zero, then this function will return EFI_TIMEOUT
 588                                        if the time required to execute the receive data command
 589                                        is greater than Timeout.
 590   @param  TransferLengthOut            A pointer to a buffer to store the size in bytes of the data
 591                                        written to the buffer. Ignore it when IsTrustSend is TRUE.
 592
 593   @retval EFI_SUCCESS       The data transfer is complete successfully.
 594   @return others            Some error occurs when transferring data.
 595
 596 **/
 597 EFI_STATUS
 598 TrustTransferNvmeDevice (
 599   IN OUT NVME_CONTROLLER_PRIVATE_DATA      *Private,
 600   IN OUT VOID                              *Buffer,
 601   IN UINT8                                 SecurityProtocolId,
 602   IN UINT16                                SecurityProtocolSpecificData,
 603   IN UINTN                                 TransferLength,
 604   IN BOOLEAN                               IsTrustSend,
 605   IN UINT64                                Timeout,
 606   OUT UINTN                                *TransferLengthOut
 607   )
 608 {
 609   EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET CommandPacket;
 610   EFI_NVM_EXPRESS_COMMAND                  Command;
 611   EFI_NVM_EXPRESS_COMPLETION               Completion;
 612   EFI_STATUS                               Status;
 613   UINT16                                   SpecificData;
 614
 615   ZeroMem (&CommandPacket, sizeof (EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET));
 616   ZeroMem (&Command, sizeof (EFI_NVM_EXPRESS_COMMAND));
 617   ZeroMem (&Completion, sizeof (EFI_NVM_EXPRESS_COMPLETION));
 618
 619   CommandPacket.NvmeCmd        = &Command;
 620   CommandPacket.NvmeCompletion = &Completion;
 621
 622   //
 623   // Change Endianness of SecurityProtocolSpecificData
 624   //
 625   SpecificData = (((SecurityProtocolSpecificData << 8) & 0xFF00) | (SecurityProtocolSpecificData >> 8));
 626
 627   if (IsTrustSend) {
 628     Command.Cdw0.Opcode          = NVME_ADMIN_SECURITY_SEND_CMD;
 629     CommandPacket.TransferBuffer = Buffer;
 630     CommandPacket.TransferLength = (UINT32)TransferLength;
 631     CommandPacket.NvmeCmd->Cdw10 = (UINT32)((SecurityProtocolId << 24) | (SpecificData << 8));
 632     CommandPacket.NvmeCmd->Cdw11 = (UINT32)TransferLength;
 633   } else {
 634     Command.Cdw0.Opcode          = NVME_ADMIN_SECURITY_RECEIVE_CMD;
 635     CommandPacket.TransferBuffer = Buffer;
 636     CommandPacket.TransferLength = (UINT32)TransferLength;
 637     CommandPacket.NvmeCmd->Cdw10 = (UINT32)((SecurityProtocolId << 24) | (SpecificData << 8));
 638     CommandPacket.NvmeCmd->Cdw11 = (UINT32)TransferLength;
 639   }
 640
 641   CommandPacket.NvmeCmd->Flags = CDW10_VALID | CDW11_VALID;
 642   CommandPacket.NvmeCmd->Nsid  = NVME_CONTROLLER_ID;
 643   CommandPacket.CommandTimeout = Timeout;
 644   CommandPacket.QueueType      = NVME_ADMIN_QUEUE;
 645
 646   Status = Private->Passthru.PassThru (
 647                                &Private->Passthru,
 648                                NVME_CONTROLLER_ID,
 649                                &CommandPacket,
 650                                NULL
 651                                );
 652
 653   if (!IsTrustSend) {
 654     if (EFI_ERROR (Status))  {
 655       *TransferLengthOut = 0;
 656     } else {
 657       *TransferLengthOut = (UINTN) TransferLength;
 658     }
 659   }
 660
 661   return Status;
 662 }
 663
 664 /**
 665   Send a security protocol command to a device that receives data and/or the result
 666   of one or more commands sent by SendData.
 667
 668   The ReceiveData function sends a security protocol command to the given MediaId.
 669   The security protocol command sent is defined by SecurityProtocolId and contains
 670   the security protocol specific data SecurityProtocolSpecificData. The function
 671   returns the data from the security protocol command in PayloadBuffer.
 672
 673   For devices supporting the SCSI command set, the security protocol command is sent
 674   using the SECURITY PROTOCOL IN command defined in SPC-4.
 675
 676   For devices supporting the ATA command set, the security protocol command is sent
 677   using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize
 678   is non-zero.
 679
 680   If the PayloadBufferSize is zero, the security protocol command is sent using the
 681   Trusted Non-Data command defined in ATA8-ACS.
 682
 683   If PayloadBufferSize is too small to store the available data from the security
 684   protocol command, the function shall copy PayloadBufferSize bytes into the
 685   PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL.
 686
 687   If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero,
 688   the function shall return EFI_INVALID_PARAMETER.
 689
 690   If the given MediaId does not support security protocol commands, the function shall
 691   return EFI_UNSUPPORTED. If there is no media in the device, the function returns
 692   EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device,
 693   the function returns EFI_MEDIA_CHANGED.
 694
 695   If the security protocol fails to complete within the Timeout period, the function
 696   shall return EFI_TIMEOUT.
 697
 698   If the security protocol command completes without an error, the function shall
 699   return EFI_SUCCESS. If the security protocol command completes with an error, the
 700   function shall return EFI_DEVICE_ERROR.
 701
 702   @param  This                         Indicates a pointer to the calling context.
 703   @param  MediaId                      ID of the medium to receive data from.
 704   @param  Timeout                      The timeout, in 100ns units, to use for the execution
 705                                        of the security protocol command. A Timeout value of 0
 706                                        means that this function will wait indefinitely for the
 707                                        security protocol command to execute. If Timeout is greater
 708                                        than zero, then this function will return EFI_TIMEOUT
 709                                        if the time required to execute the receive data command
 710                                        is greater than Timeout.
 711   @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
 712                                        the security protocol command to be sent.
 713   @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
 714                                        of the security protocol command to be sent.
 715   @param  PayloadBufferSize            Size in bytes of the payload data buffer.
 716   @param  PayloadBuffer                A pointer to a destination buffer to store the security
 717                                        protocol command specific payload data for the security
 718                                        protocol command. The caller is responsible for having
 719                                        either implicit or explicit ownership of the buffer.
 720   @param  PayloadTransferSize          A pointer to a buffer to store the size in bytes of the
 721                                        data written to the payload data buffer.
 722
 723   @retval EFI_SUCCESS                  The security protocol command completed successfully.
 724   @retval EFI_WARN_BUFFER_TOO_SMALL    The PayloadBufferSize was too small to store the available
 725                                        data from the device. The PayloadBuffer contains the truncated data.
 726   @retval EFI_UNSUPPORTED              The given MediaId does not support security protocol commands.
 727   @retval EFI_DEVICE_ERROR             The security protocol command completed with an error.
 728   @retval EFI_NO_MEDIA                 There is no media in the device.
 729   @retval EFI_MEDIA_CHANGED            The MediaId is not for the current media.
 730   @retval EFI_INVALID_PARAMETER        The PayloadBuffer or PayloadTransferSize is NULL and
 731                                        PayloadBufferSize is non-zero.
 732   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the security
 733                                        protocol command to execute.
 734
 735 **/
 736 EFI_STATUS
 737 EFIAPI
 738 NvmeStorageSecurityReceiveData (
 739   IN  EFI_STORAGE_SECURITY_COMMAND_PROTOCOL    *This,
 740   IN  UINT32                                   MediaId,
 741   IN  UINT64                                   Timeout,
 742   IN  UINT8                                    SecurityProtocolId,
 743   IN  UINT16                                   SecurityProtocolSpecificData,
 744   IN  UINTN                                    PayloadBufferSize,
 745   OUT VOID                                     *PayloadBuffer,
 746   OUT UINTN                                    *PayloadTransferSize
 747   )
 748 {
 749   EFI_STATUS                       Status;
 750   NVME_DEVICE_PRIVATE_DATA         *Device;
 751
 752   Status  = EFI_SUCCESS;
 753
 754   if ((PayloadBuffer == NULL) || (PayloadTransferSize == NULL) || (PayloadBufferSize == 0)) {
 755     return EFI_INVALID_PARAMETER;
 756   }
 757
 758   Device = NVME_DEVICE_PRIVATE_DATA_FROM_STORAGE_SECURITY (This);
 759
 760   if (MediaId != Device->BlockIo.Media->MediaId) {
 761     return EFI_MEDIA_CHANGED;
 762   }
 763
 764   if (!Device->BlockIo.Media->MediaPresent) {
 765     return EFI_NO_MEDIA;
 766   }
 767
 768   Status = TrustTransferNvmeDevice (
 769              Device->Controller,
 770              PayloadBuffer,
 771              SecurityProtocolId,
 772              SecurityProtocolSpecificData,
 773              PayloadBufferSize,
 774              FALSE,
 775              Timeout,
 776              PayloadTransferSize
 777              );
 778
 779   return Status;
 780 }
 781
 782 /**
 783   Send a security protocol command to a device.
 784
 785   The SendData function sends a security protocol command containing the payload
 786   PayloadBuffer to the given MediaId. The security protocol command sent is
 787   defined by SecurityProtocolId and contains the security protocol specific data
 788   SecurityProtocolSpecificData. If the underlying protocol command requires a
 789   specific padding for the command payload, the SendData function shall add padding
 790   bytes to the command payload to satisfy the padding requirements.
 791
 792   For devices supporting the SCSI command set, the security protocol command is sent
 793   using the SECURITY PROTOCOL OUT command defined in SPC-4.
 794
 795   For devices supporting the ATA command set, the security protocol command is sent
 796   using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize
 797   is non-zero. If the PayloadBufferSize is zero, the security protocol command is
 798   sent using the Trusted Non-Data command defined in ATA8-ACS.
 799
 800   If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall
 801   return EFI_INVALID_PARAMETER.
 802
 803   If the given MediaId does not support security protocol commands, the function
 804   shall return EFI_UNSUPPORTED. If there is no media in the device, the function
 805   returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the
 806   device, the function returns EFI_MEDIA_CHANGED.
 807
 808   If the security protocol fails to complete within the Timeout period, the function
 809   shall return EFI_TIMEOUT.
 810
 811   If the security protocol command completes without an error, the function shall return
 812   EFI_SUCCESS. If the security protocol command completes with an error, the function
 813   shall return EFI_DEVICE_ERROR.
 814
 815   @param  This                         Indicates a pointer to the calling context.
 816   @param  MediaId                      ID of the medium to receive data from.
 817   @param  Timeout                      The timeout, in 100ns units, to use for the execution
 818                                        of the security protocol command. A Timeout value of 0
 819                                        means that this function will wait indefinitely for the
 820                                        security protocol command to execute. If Timeout is greater
 821                                        than zero, then this function will return EFI_TIMEOUT
 822                                        if the time required to execute the send data command
 823                                        is greater than Timeout.
 824   @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
 825                                        the security protocol command to be sent.
 826   @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
 827                                        of the security protocol command to be sent.
 828   @param  PayloadBufferSize            Size in bytes of the payload data buffer.
 829   @param  PayloadBuffer                A pointer to a destination buffer to store the security
 830                                        protocol command specific payload data for the security
 831                                        protocol command.
 832
 833   @retval EFI_SUCCESS                  The security protocol command completed successfully.
 834   @retval EFI_UNSUPPORTED              The given MediaId does not support security protocol commands.
 835   @retval EFI_DEVICE_ERROR             The security protocol command completed with an error.
 836   @retval EFI_NO_MEDIA                 There is no media in the device.
 837   @retval EFI_MEDIA_CHANGED            The MediaId is not for the current media.
 838   @retval EFI_INVALID_PARAMETER        The PayloadBuffer is NULL and PayloadBufferSize is non-zero.
 839   @retval EFI_TIMEOUT                  A timeout occurred while waiting for the security
 840                                        protocol command to execute.
 841
 842 **/
 843 EFI_STATUS
 844 EFIAPI
 845 NvmeStorageSecuritySendData (
 846   IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL    *This,
 847   IN UINT32                                   MediaId,
 848   IN UINT64                                   Timeout,
 849   IN UINT8                                    SecurityProtocolId,
 850   IN UINT16                                   SecurityProtocolSpecificData,
 851   IN UINTN                                    PayloadBufferSize,
 852   IN VOID                                     *PayloadBuffer
 853   )
 854 {
 855   EFI_STATUS                       Status;
 856   NVME_DEVICE_PRIVATE_DATA         *Device;
 857
 858   Status  = EFI_SUCCESS;
 859
 860   if ((PayloadBuffer == NULL) && (PayloadBufferSize != 0)) {
 861     return EFI_INVALID_PARAMETER;
 862   }
 863
 864   Device = NVME_DEVICE_PRIVATE_DATA_FROM_STORAGE_SECURITY (This);
 865
 866   if (MediaId != Device->BlockIo.Media->MediaId) {
 867     return EFI_MEDIA_CHANGED;
 868   }
 869
 870   if (!Device->BlockIo.Media->MediaPresent) {
 871     return EFI_NO_MEDIA;
 872   }
 873
 874   Status = TrustTransferNvmeDevice (
 875              Device->Controller,
 876              PayloadBuffer,
 877              SecurityProtocolId,
 878              SecurityProtocolSpecificData,
 879              PayloadBufferSize,
 880              TRUE,
 881              Timeout,
 882              NULL
 883              );
 884
 885   return Status;
 886 }
 887
 888
 889
 890