Re: [PATCH] MdeModulePkg: Add definitions for NVM Express Passthru PPI

["Wu, Hao A" <hao.a.wu@intel.com>]

> -----Original Message-----
> From: Chu, Maggie
> Sent: Monday, June 17, 2019 10:11 AM
> To: devel@edk2.groups.io
> Cc: Wu, Hao A; Wang, Jian J; Ni, Ray; Zeng, Star
> Subject: [PATCH] MdeModulePkg: Add definitions for NVM Express Passthru
> PPI
> 
> https://bugzilla.tianocore.org/show_bug.cgi?id=1879
> This commit will add the definitions of Nvm Express PassThru PPI.
> This PPI will provide services that allow NVM commands to be sent
> to NVM Express devices during PEI phase.
> 
> More specifically, the PPI will provide services to:
> 
> * Sends an NVM Express Command Packet to an NVM Express controller
>   or namespace (by service 'PassThru');
> * Get the list of the attached namespaces on a controller
>   (by services 'GetNextNameSpace');
> * Get the identification information (DevicePath) of the underlying
>   NVM Express host controller (by service 'GetDevicePath').
> 
> Signed-off-by: Maggie Chu <maggie.chu@intel.com>
> Cc: Hao A Wu <hao.a.wu@intel.com>
> Cc: Jian J Wang <jian.j.wang@intel.com>
> Cc: Ray Ni <ray.ni@intel.com>
> Cc: Star Zeng <star.zeng@intel.com>
> ---
>  MdeModulePkg/Include/Ppi/NvmExpressPassThru.h | 156
> ++++++++++++++++++++++++++
>  MdeModulePkg/MdeModulePkg.dec                 |   3 +
>  2 files changed, 159 insertions(+)
>  create mode 100644 MdeModulePkg/Include/Ppi/NvmExpressPassThru.h
> 
> diff --git a/MdeModulePkg/Include/Ppi/NvmExpressPassThru.h
> b/MdeModulePkg/Include/Ppi/NvmExpressPassThru.h
> new file mode 100644
> index 0000000000..cb5b3b3b18
> --- /dev/null
> +++ b/MdeModulePkg/Include/Ppi/NvmExpressPassThru.h
> @@ -0,0 +1,156 @@
> +/** @file
> +
> +  Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
> +  SPDX-License-Identifier: BSD-2-Clause-Patent
> +
> +**/
> +
> +#ifndef _EDKII_NVME_PASS_THRU_PPI_H_
> +#define _EDKII_NVME_PASS_THRU_PPI_H_
> +
> +#include <Protocol/DevicePath.h>
> +#include <Protocol/NvmExpressPassthru.h>
> +
> +///
> +/// Global ID for the EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI.
> +///
> +#define EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI_GUID \
> +  { \
> +    0x6af31b2c, 0x3be, 0x46c1, { 0xb1, 0x2d, 0xea, 0x4a, 0x36, 0xdf, 0xa7,
> 0x4c } \
> +  }
> +
> +//
> +// Forward declaration for the EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI.
> +//
> +typedef struct _EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI
> EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI;
> +
> +//
> +// Revision The revision to which the Nvme Pass Thru PPI interface adheres.
> +//          All future revisions must be backwards compatible.
> +//          If a future version is not back wards compatible it is not the same
> GUID.
> +//
> +#define EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI_REVISION  0x00010000
> +
> +/**
> +  Gets the device path information of the underlying NVM Express host
> controller.
> +
> +  @param[in]  This                 The PPI instance pointer.
> +  @param[out] DevicePathLength     The length of the device path in bytes
> specified
> +                                   by DevicePath.
> +  @param[out] DevicePath           The device path of the underlying NVM
> Express
> +                                   host controller.
> +                                   This field re-uses EFI Device Path Protocol as
> +                                   defined by Section 10.2 EFI Device Path Protocol
> +                                   of UEFI 2.7 Specification.
> +
> +  @retval EFI_SUCCESS              The operation succeeds.
> +  @retval EFI_INVALID_PARAMETER    DevicePathLength or DevicePath is
> NULL.
> +  @retval EFI_OUT_OF_RESOURCES     The operation fails due to lack of
> resources.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EDKII_PEI_NVME_PASS_THRU_GET_DEVICE_PATH) (
> +  IN  EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI   *This,
> +  OUT UINTN                                 *DevicePathLength,
> +  OUT EFI_DEVICE_PATH_PROTOCOL              **DevicePath
> +  );
> +
> +/**
> +  Used to retrieve the next namespace ID for this NVM Express controller.
> +
> +  If on input the value pointed to by NamespaceId is 0xFFFFFFFF, then the
> first
> +  valid namespace ID defined on the NVM Express controller is returned in
> the
> +  location pointed to by NamespaceId and a status of EFI_SUCCESS is
> returned.
> +
> +  If on input the value pointed to by NamespaceId is an invalid namespace
> ID
> +  other than 0xFFFFFFFF, then EFI_INVALID_PARAMETER is returned.
> +
> +  If on input the value pointed to by NamespaceId is a valid namespace ID,
> then
> +  the next valid namespace ID on the NVM Express controller is returned in
> the
> +  location pointed to by NamespaceId, and EFI_SUCCESS is returned.
> +
> +  If the value pointed to by NamespaceId is the namespace ID of the last
> +  namespace on the NVM Express controller, then EFI_NOT_FOUND is
> returned.
> +
> +  @param[in]     This              The PPI instance pointer.
> +  @param[in,out] NamespaceId       On input, a pointer to a legal
> NamespaceId
> +                                   for an NVM Express namespace present on the
> +                                   NVM Express controller. On output, a pointer
> +                                   to the next NamespaceId of an NVM Express
> +                                   namespace on an NVM Express controller. An
> +                                   input value of 0xFFFFFFFF retrieves the
> +                                   first NamespaceId for an NVM Express
> +                                   namespace present on an NVM Express
> +                                   controller.
> +
> +  @retval EFI_SUCCESS            The Namespace ID of the next Namespace was
> +                                 returned.
> +  @retval EFI_NOT_FOUND          There are no more namespaces defined on
> this
> +                                 controller.
> +  @retval EFI_INVALID_PARAMETER  NamespaceId is an invalid value other
> than
> +                                 0xFFFFFFFF.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EDKII_PEI_NVME_PASS_THRU_GET_NEXT_NAMESPACE)(
> +  IN     EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI   *This,
> +  IN OUT UINT32                                *NamespaceId
> +  );
> +
> +
> +/**
> +  Sends an NVM Express Command Packet to an NVM Express controller or
> namespace. This function only
> +  supports blocking execution of the command.
> +
> +  @param[in] This                  The PPI instance pointer.
> +  @param[in] NamespaceId           Is a 32 bit Namespace ID to which the Nvm
> Express command packet will
> +                                   be sent.
> +                                   A Value of 0 denotes the NVM Express controller, a Value
> of all 0FFh in
> +                                   the namespace ID specifies that the command packet
> should be sent to all
> +                                   valid namespaces.
> +  @param[in,out] Packet            A pointer to the EDKII PEI NVM Express
> PassThru Command Packet to send
> +                                   to the NVMe namespace specified by NamespaceId.
> +
> +  @retval EFI_SUCCESS              The EDKII PEI NVM Express Command Packet
> was sent by the host.
> +                                   TransferLength bytes were transferred to, or from
> DataBuffer.
> +  @retval EFI_NOT_READY            The EDKII PEI NVM Express Command
> Packet could not be sent because
> +                                   the controller is not ready. The caller may retry again later.
> +  @retval EFI_DEVICE_ERROR         A device error occurred while attempting
> to send the EDKII PEI NVM
> +                                   Express Command Packet.
> +  @retval EFI_INVALID_PARAMETER    Namespace, or the contents of
> EDKII_PEI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET
> +                                   are invalid.
> +                                   The EDKII PEI NVM Express Command Packet was not sent,
> so no
> +                                   additional status information is available.
> +  @retval EFI_UNSUPPORTED          The command described by the EDKII PEI
> NVM Express Command Packet
> +                                   is not supported by the host adapter.
> +                                   The EDKII PEI NVM Express Command Packet was not sent,
> so no
> +                                   additional status information is available.
> +  @retval EFI_TIMEOUT              A timeout occurred while waiting for the
> EDKII PEI NVM Express Command
> +                                   Packet to execute.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EDKII_PEI_NVME_PASS_THRU_PASSTHRU) (
> +  IN     EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI               *This,
> +  IN     UINT32                                            NamespaceId,
> +  IN OUT EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET          *Packet
> +  );
> +
> +//
> +// This PPI contains a set of services to send commands
> +// to a mass storage device.
> +//
> +struct _EDKII_PEI_NVM_EXPRESS_PASS_THRU_PPI {
> +  UINT64                                           Revision;
> +  EFI_NVM_EXPRESS_PASS_THRU_MODE                   *Mode;
> +  EDKII_PEI_NVME_PASS_THRU_GET_DEVICE_PATH         GetDevicePath;
> +  EDKII_PEI_NVME_PASS_THRU_GET_NEXT_NAMESPACE
> GetNextNameSpace;
> +  EDKII_PEI_NVME_PASS_THRU_PASSTHRU                PassThru;
> +};
> +
> +extern EFI_GUID gEdkiiPeiNvmExpressPassThruPpiGuid;
> +
> +#endif
> diff --git a/MdeModulePkg/MdeModulePkg.dec
> b/MdeModulePkg/MdeModulePkg.dec
> index 6cba729982..8ade6bac0e 100644
> --- a/MdeModulePkg/MdeModulePkg.dec
> +++ b/MdeModulePkg/MdeModulePkg.dec
> @@ -466,6 +466,9 @@
>    ## Include/Ppi/Debug.h
>    gEdkiiDebugPpiGuid                        = { 0x999e699c, 0xb013, 0x475e, { 0xb1,
> 0x7b, 0xf3, 0xa8, 0xae, 0x5c, 0x48, 0x75 } }
> 
> +  ## Include/Ppi/NvmExpressPassThru.h
> +  gEdkiiPeiNvmExpressPassThruPpiGuid    = { 0x6af31b2c, 0x3be, 0x46c1,
> { 0xb1, 0x2d, 0xea, 0x4a, 0x36, 0xdf, 0xa7, 0x4c } }
> +


Reviewed-by: Hao A Wu <hao.a.wu@intel.com>

Best Regards,
Hao Wu


>  [Protocols]
>    ## Load File protocol provides capability to load and unload EFI image into
> memory and execute it.
>    #  Include/Protocol/LoadPe32Image.h
> --
> 2.16.2.windows.1