Re: [PATCH 1/4] MdeModulePkg: Add definition of the EDKII_UFS_HC_PLATFORM_PROTOCOL

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

> -----Original Message-----
> From: Albecki, Mateusz
> Sent: Thursday, August 08, 2019 12:51 AM
> To: devel@edk2.groups.io
> Cc: Albecki, Mateusz; Wu, Hao A
> Subject: [PATCH 1/4] MdeModulePkg: Add definition of the
> EDKII_UFS_HC_PLATFORM_PROTOCOL
> 
> https://bugzilla.tianocore.org/show_bug.cgi?id=1343
> 
> EDKII_UFS_HC_PLATFORM_PROTOCOL will allow the platform to inject
> platform specific logic into standard UFS flows. Right now we
> support callbacks pre and post host controller enable and pre
> and post link startup. Provided callbacks allow the platform
> driver to inject UIC programming after HCE is set which is
> a standard initialization step covered by UFS specification as
> well as cover some additional use cases during other calllbacks.
> For instance platform driver may switch to fast mode after link
> startup.
> 
> We also allow the platform to override host controller capabilities
> and version which might be usefull to manage silicon bugs or
> allow testign experimental features from new versions of the
> specification.


I will handle the below typos when pushing this patch:
usefull -> useful
testign -> testing


> 
> Cc: Hao A Wu <hao.a.wu@intel.com>
> Signed-off-by: Mateusz Albecki <mateusz.albecki@intel.com>
> ---
>  .../Include/Protocol/UfsHostControllerPlatform.h   | 124
> +++++++++++++++++++++
>  MdeModulePkg/MdeModulePkg.dec                      |   3 +
>  2 files changed, 127 insertions(+)
>  create mode 100644
> MdeModulePkg/Include/Protocol/UfsHostControllerPlatform.h
> 
> diff --git a/MdeModulePkg/Include/Protocol/UfsHostControllerPlatform.h
> b/MdeModulePkg/Include/Protocol/UfsHostControllerPlatform.h
> new file mode 100644
> index 0000000000..0f6732a1f8
> --- /dev/null
> +++ b/MdeModulePkg/Include/Protocol/UfsHostControllerPlatform.h
> @@ -0,0 +1,124 @@
> +/** @file
> +  EDKII_UFS_HC_PLATFORM_PROTOCOL definition.
> +
> +Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
> +SPDX-License-Identifier: BSD-2-Clause-Patent
> +
> +**/
> +
> +#ifndef __EDKII_UFS_HC_PLATFORM_PROTOCOL_H__
> +#define __EDKII_UFS_HC_PLATFORM_PROTOCOL_H__
> +
> +#include <Protocol/UfsHostController.h>
> +
> +#define EDKII_UFS_HC_PLATFORM_PROTOCOL_VERSION 1
> +
> +extern EFI_GUID  gEdkiiUfsHcPlatformProtocolGuid;
> +
> +typedef struct _EDKII_UFS_HC_PLATFORM_PROTOCOL
> EDKII_UFS_HC_PLATFORM_PROTOCOL;
> +
> +typedef struct _EDKII_UFS_HC_DRIVER_INTERFACE
> EDKII_UFS_HC_DRIVER_INTERFACE;
> +
> +typedef struct {
> +  UINT32 Opcode;
> +  UINT32 Arg1;
> +  UINT32 Arg2;
> +  UINT32 Arg3;
> +} EDKII_UIC_COMMAND;
> +
> +/**
> +  Execute UIC command
> +
> +  @param[in]      This        Pointer to driver interface produced by the UFS
> controller.
> +  @param[in, out] UicCommand  Descriptor of the command that will be
> executed.
> +
> +  @retval EFI_SUCCESS            Command executed successfully.
> +  @retval EFI_INVALID_PARAMETER  This or UicCommand is NULL.
> +  @retval Others                 Command failed to execute.
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EDKII_UFS_EXEC_UIC_COMMAND) (
> +  IN      EDKII_UFS_HC_DRIVER_INTERFACE  *This,
> +  IN OUT  EDKII_UIC_COMMAND              *UicCommand
> +);
> +
> +struct _EDKII_UFS_HC_DRIVER_INTERFACE {
> +  ///
> +  /// Protocol to accesss host controller MMIO and PCI registers.
> +  ///
> +  EDKII_UFS_HOST_CONTROLLER_PROTOCOL  *UfsHcProtocol;
> +  ///
> +  /// Function implementing UIC command execution.
> +  ///
> +  EDKII_UFS_EXEC_UIC_COMMAND          UfsExecUicCommand;
> +};
> +
> +typedef struct {
> +  UINT32 Capabilities;
> +  UINT32 Version;
> +} EDKII_UFS_HC_INFO;
> +
> +/**
> +  Allows platform protocol to override host controller information
> +
> +  @param[in]      ControllerHandle  Handle of the UFS controller.
> +  @param[in, out] HcInfo            Pointer EDKII_UFS_HC_INFO associated with
> host controller.
> +
> +  @retval EFI_SUCCESS            Function completed successfully.
> +  @retval EFI_INVALID_PARAMETER  HcInfo is NULL.
> +  @retval Others                 Function failed to complete.
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EDKII_UFS_HC_PLATFORM_OVERRIDE_HC_INFO) (
> +  IN     EFI_HANDLE         ControllerHandle,
> +  IN OUT EDKII_UFS_HC_INFO  *HcInfo
> +);
> +
> +typedef enum {
> +  EdkiiUfsHcPreHce,
> +  EdkiiUfsHcPostHce,
> +  EdkiiUfsHcPreLinkStartup,
> +  EdkiiUfsHcPostLinkStartup
> +} EDKII_UFS_HC_PLATFORM_CALLBACK_PHASE;
> +
> +/**
> +  Callback function for platform driver.
> +
> +  @param[in]      ControllerHandle  Handle of the UFS controller.
> +  @param[in]      CallbackPhase     Specifies when the platform protocol is
> called
> +  @param[in, out] CallbackData      Data specific to the callback phase.
> +                                    For PreHce and PostHce -
> EDKII_UFS_HC_DRIVER_INTERFACE.
> +                                    For PreLinkStartup and PostLinkStartup -
> EDKII_UFS_HC_DRIVER_INTERFACE.
> +
> +  @retval EFI_SUCCESS            Override function completed successfully.
> +  @retval EFI_INVALID_PARAMETER  CallbackPhase is invalid or CallbackData
> is NULL when phase expects valid data.
> +  @retval Others                 Function failed to complete.
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EDKII_UFS_HC_PLATFORM_CALLBACK) (
> +  IN     EFI_HANDLE                            ControllerHandle,
> +  IN     EDKII_UFS_HC_PLATFORM_CALLBACK_PHASE  CallbackPhase,
> +  IN OUT VOID                                  *CallbackData
> +);
> +
> +struct _EDKII_UFS_HC_PLATFORM_PROTOCOL {
> +  ///
> +  /// Version of the protocol.
> +  ///
> +  UINT32                                  Version;
> +  ///
> +  /// Allows platform driver to override host controller information.
> +  ///
> +  EDKII_UFS_HC_PLATFORM_OVERRIDE_HC_INFO  OverrideHcInfo;
> +  ///
> +  /// Allows platform driver to implement platform specific flows
> +  /// for host controller.
> +  ///
> +  EDKII_UFS_HC_PLATFORM_CALLBACK          Callback;
> +};
> +
> +#endif
> +
> diff --git a/MdeModulePkg/MdeModulePkg.dec
> b/MdeModulePkg/MdeModulePkg.dec
> index c4139753d3..b663453c8b 100644
> --- a/MdeModulePkg/MdeModulePkg.dec
> +++ b/MdeModulePkg/MdeModulePkg.dec
> @@ -558,6 +558,9 @@
>    ## Include/Protocol/UfsHostController.h
>    gEdkiiUfsHostControllerProtocolGuid = { 0xebc01af5, 0x7a9, 0x489e, { 0xb7,
> 0xce, 0xdc, 0x8, 0x9e, 0x45, 0x9b, 0x2f } }
> 
> +  ## Include/Protocol/UfsHostControllerPlatform.h
> +  gEdkiiUfsHcPlatformProtocolGuid = { 0x3d18ba13, 0xd9b1, 0x4dd4, {0xb9,
> 0x16, 0xd3, 0x07, 0x96, 0x53, 0x9e, 0xd8}}
> +


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

Best Regards,
Hao Wu


>    ## Include/Protocol/EsrtManagement.h
>    gEsrtManagementProtocolGuid         = { 0xa340c064, 0x723c, 0x4a9c, { 0xa4,
> 0xdd, 0xd5, 0xb4, 0x7a, 0x26, 0xfb, 0xb0 }}
> 
> --
> 2.14.1.windows.1