MdeModulePkg/Include/Ppi/NvmExpressPassThru.h

   1 /** @file
   2
   3   Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
   4   SPDX-License-Identifier: BSD-2-Clause-Patent
   5
   6 **/
   7
   8 #ifndef _EDKII_NVME_PASS_THRU_PPI_H_
   9 #define _EDKII_NVME_PASS_THRU_PPI_H_
  10
  11 #include <Protocol/DevicePath.h>
  12 #include <Protocol/NvmExpressPassthru.h>
  13
  14 ///
  15 /// Global ID for the EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI.
  16 ///
  17 #define EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI_GUID \
  18   { \
  19     0x6af31b2c, 0x3be, 0x46c1, { 0xb1, 0x2d, 0xea, 0x4a, 0x36, 0xdf, 0xa7, 0x4c } \
  20   }
  21
  22 //
  23 // Forward declaration for the EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI.
  24 //
  25 typedef struct _EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI  EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI;
  26
  27 //
  28 // Revision The revision to which the Nvme Pass Thru PPI interface adheres.
  29 //          All future revisions must be backwards compatible.
  30 //          If a future version is not back wards compatible it is not the same GUID.
  31 //
  32 #define EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI_REVISION  0x00010000
  33
  34 /**
  35   Gets the device path information of the underlying NVM Express host controller.
  36
  37   @param[in]  This                 The PPI instance pointer.
  38   @param[out] DevicePathLength     The length of the device path in bytes specified
  39                                    by DevicePath.
  40   @param[out] DevicePath           The device path of the underlying NVM Express
  41                                    host controller.
  42                                    This field re-uses EFI Device Path Protocol as
  43                                    defined by Section 10.2 EFI Device Path Protocol
  44                                    of UEFI 2.7 Specification.
  45
  46   @retval EFI_SUCCESS              The operation succeeds.
  47   @retval EFI_INVALID_PARAMETER    DevicePathLength or DevicePath is NULL.
  48   @retval EFI_OUT_OF_RESOURCES     The operation fails due to lack of resources.
  49
  50 **/
  51 typedef
  52 EFI_STATUS
  53 (EFIAPI *EDKII_PEI_NVME_PASS_THRU_GET_DEVICE_PATH) (
  54   IN  EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI   *This,
  55   OUT UINTN                                 *DevicePathLength,
  56   OUT EFI_DEVICE_PATH_PROTOCOL              **DevicePath
  57   );
  58
  59 /**
  60   Used to retrieve the next namespace ID for this NVM Express controller.
  61
  62   If on input the value pointed to by NamespaceId is 0xFFFFFFFF, then the first
  63   valid namespace ID defined on the NVM Express controller is returned in the
  64   location pointed to by NamespaceId and a status of EFI_SUCCESS is returned.
  65
  66   If on input the value pointed to by NamespaceId is an invalid namespace ID
  67   other than 0xFFFFFFFF, then EFI_INVALID_PARAMETER is returned.
  68
  69   If on input the value pointed to by NamespaceId is a valid namespace ID, then
  70   the next valid namespace ID on the NVM Express controller is returned in the
  71   location pointed to by NamespaceId, and EFI_SUCCESS is returned.
  72
  73   If the value pointed to by NamespaceId is the namespace ID of the last
  74   namespace on the NVM Express controller, then EFI_NOT_FOUND is returned.
  75
  76   @param[in]     This              The PPI instance pointer.
  77   @param[in,out] NamespaceId       On input, a pointer to a legal NamespaceId
  78                                    for an NVM Express namespace present on the
  79                                    NVM Express controller. On output, a pointer
  80                                    to the next NamespaceId of an NVM Express
  81                                    namespace on an NVM Express controller. An
  82                                    input value of 0xFFFFFFFF retrieves the
  83                                    first NamespaceId for an NVM Express
  84                                    namespace present on an NVM Express
  85                                    controller.
  86
  87   @retval EFI_SUCCESS            The Namespace ID of the next Namespace was
  88                                  returned.
  89   @retval EFI_NOT_FOUND          There are no more namespaces defined on this
  90                                  controller.
  91   @retval EFI_INVALID_PARAMETER  NamespaceId is an invalid value other than
  92                                  0xFFFFFFFF.
  93
  94 **/
  95 typedef
  96 EFI_STATUS
  97 (EFIAPI *EDKII_PEI_NVME_PASS_THRU_GET_NEXT_NAMESPACE)(
  98   IN     EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI   *This,
  99   IN OUT UINT32                                *NamespaceId
 100   );
 101
 102
 103 /**
 104   Sends an NVM Express Command Packet to an NVM Express controller or namespace. This function only
 105   supports blocking execution of the command.
 106
 107   @param[in] This                  The PPI instance pointer.
 108   @param[in] NamespaceId           Is a 32 bit Namespace ID to which the Nvm Express command packet will
 109                                    be sent.
 110                                    A Value of 0 denotes the NVM Express controller, a Value of all 0FFh in
 111                                    the namespace ID specifies that the command packet should be sent to all
 112                                    valid namespaces.
 113   @param[in,out] Packet            A pointer to the EDKII PEI NVM Express PassThru Command Packet to send
 114                                    to the NVMe namespace specified by NamespaceId.
 115
 116   @retval EFI_SUCCESS              The EDKII PEI NVM Express Command Packet was sent by the host.
 117                                    TransferLength bytes were transferred to, or from DataBuffer.
 118   @retval EFI_NOT_READY            The EDKII PEI NVM Express Command Packet could not be sent because
 119                                    the controller is not ready. The caller may retry again later.
 120   @retval EFI_DEVICE_ERROR         A device error occurred while attempting to send the EDKII PEI NVM
 121                                    Express Command Packet.
 122   @retval EFI_INVALID_PARAMETER    Namespace, or the contents of EDKII_PEI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET
 123                                    are invalid.
 124                                    The EDKII PEI NVM Express Command Packet was not sent, so no
 125                                    additional status information is available.
 126   @retval EFI_UNSUPPORTED          The command described by the EDKII PEI NVM Express Command Packet
 127                                    is not supported by the host adapter.
 128                                    The EDKII PEI NVM Express Command Packet was not sent, so no
 129                                    additional status information is available.
 130   @retval EFI_TIMEOUT              A timeout occurred while waiting for the EDKII PEI NVM Express Command
 131                                    Packet to execute.
 132
 133 **/
 134 typedef
 135 EFI_STATUS
 136 (EFIAPI *EDKII_PEI_NVME_PASS_THRU_PASSTHRU) (
 137   IN     EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI               *This,
 138   IN     UINT32                                            NamespaceId,
 139   IN OUT EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET          *Packet
 140   );
 141
 142 //
 143 // This PPI contains a set of services to send commands
 144 // to a mass storage device.
 145 //
 146 struct _EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI {
 147   UINT64                                           Revision;
 148   EFI_NVM_EXPRESS_PASS_THRU_MODE                   *Mode;
 149   EDKII_PEI_NVME_PASS_THRU_GET_DEVICE_PATH         GetDevicePath;
 150   EDKII_PEI_NVME_PASS_THRU_GET_NEXT_NAMESPACE      GetNextNameSpace;
 151   EDKII_PEI_NVME_PASS_THRU_PASSTHRU                PassThru;
 152 };
 153
 154 extern EFI_GUID gEdkiiPeiNvmExpressPassThruPpiGuid;
 155
 156 #endif