/** @file
  EDKII_UFS_HC_PLATFORM_PROTOCOL definition.

Copyright (c) 2019 - 2022, 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  2

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;

typedef enum {
  EdkiiUfsCardRefClkFreq19p2Mhz,
  EdkiiUfsCardRefClkFreq26Mhz,
  EdkiiUfsCardRefClkFreq38p4Mhz,
  EdkiiUfsCardRefClkFreqObsolete
} EDKII_UFS_CARD_REF_CLK_FREQ_ATTRIBUTE;

/**
  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;
  ///
  /// Reference Clock Frequency Ufs Card Attribute that need to be set in this Ufs Host Environment.
  ///
  EDKII_UFS_CARD_REF_CLK_FREQ_ATTRIBUTE     RefClkFreq;
};

#endif