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

["Albecki, Mateusz" <mateusz.albecki@intel.com>]

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. We also allow the platform to override
host controller capabilities and version which might be usefull
to manage silicon bugs or allow testing experimental features
from new version of the specification.

Cc: Hao A Wu <hao.a.wu@intel.com>
Signed-off-by: Mateusz Albecki <mateusz.albecki@intel.com>
---
 .../Include/Protocol/UfsHostControllerPlatform.h   | 130 +++++++++++++++++++++
 MdeModulePkg/MdeModulePkg.dec                      |   3 +
 2 files changed, 133 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..db7c5a5c99
--- /dev/null
+++ b/MdeModulePkg/Include/Protocol/UfsHostControllerPlatform.h
@@ -0,0 +1,130 @@
+/** @file
+  UfsHostControllerPlatformProtocol definition. This protocol is consumed by
+  generic UFS driver.
+
+  Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+  This program and the accompanying materials
+  are licensed and made available under the terms and conditions of the BSD License
+  which accompanies this distribution.  The full text of the license may be found at
+  http://opensource.org/licenses/bsd-license.php
+
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+
+**/
+
+#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 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 1471469ff9..c7c2dcf6c3 100644
--- a/MdeModulePkg/MdeModulePkg.dec
+++ b/MdeModulePkg/MdeModulePkg.dec
@@ -560,6 +560,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}}
+
   ## Include/Protocol/EsrtManagement.h
   gEsrtManagementProtocolGuid         = { 0xa340c064, 0x723c, 0x4a9c, { 0xa4, 0xdd, 0xd5, 0xb4, 0x7a, 0x26, 0xfb, 0xb0 }}
 
-- 
2.14.1.windows.1

--------------------------------------------------------------------

Intel Technology Poland sp. z o.o.
ul. Slowackiego 173 | 80-298 Gdansk | Sad Rejonowy Gdansk Polnoc | VII Wydzial Gospodarczy Krajowego Rejestru Sadowego - KRS 101882 | NIP 957-07-52-316 | Kapital zakladowy 200.000 PLN.

Ta wiadomosc wraz z zalacznikami jest przeznaczona dla okreslonego adresata i moze zawierac informacje poufne. W razie przypadkowego otrzymania tej wiadomosci, prosimy o powiadomienie nadawcy oraz trwale jej usuniecie; jakiekolwiek
przegladanie lub rozpowszechnianie jest zabronione.
This e-mail and any attachments may contain confidential material for the sole use of the intended recipient(s). If you are not the intended recipient, please contact the sender and delete all copies; any review or distribution by
others is strictly prohibited.