ArmPkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / ArmPkg / Include / Protocol / ArmScmiClock2Protocol.h

/** @file\r
\r
  Copyright (c) 2017-2018, Arm Limited. All rights reserved.\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
  System Control and Management Interface V1.0\r
    http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/\r
    DEN0056A_System_Control_and_Management_Interface.pdf\r
**/\r
\r
#ifndef ARM_SCMI_CLOCK2_PROTOCOL_H_\r
#define ARM_SCMI_CLOCK2_PROTOCOL_H_\r
\r
#include <Protocol/ArmScmi.h>\r
#include <Protocol/ArmScmiClockProtocol.h>\r
\r
#define ARM_SCMI_CLOCK2_PROTOCOL_GUID { \\r
  0xb8d8caf2, 0x9e94, 0x462c, { 0xa8, 0x34, 0x6c, 0x99, 0xfc, 0x05, 0xef, 0xcf } \\r
  }\r
\r
extern EFI_GUID gArmScmiClock2ProtocolGuid;\r
\r
#define SCMI_CLOCK2_PROTOCOL_VERSION 1\r
\r
typedef struct _SCMI_CLOCK2_PROTOCOL SCMI_CLOCK2_PROTOCOL;\r
\r
// Protocol Interface functions.\r
\r
/** Return version of the clock management protocol supported by SCP firmware.\r
\r
  @param[in]  This     A Pointer to SCMI_CLOCK2_PROTOCOL Instance.\r
\r
  @param[out] Version  Version of the supported SCMI Clock management protocol.\r
\r
  @retval EFI_SUCCESS       The version is returned.\r
  @retval EFI_DEVICE_ERROR  SCP returns an SCMI error.\r
  @retval !(EFI_SUCCESS)    Other errors.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *SCMI_CLOCK2_GET_VERSION) (\r
  IN  SCMI_CLOCK2_PROTOCOL  *This,\r
  OUT UINT32                *Version\r
  );\r
\r
/** Return total number of clock devices supported by the clock management\r
   protocol.\r
\r
  @param[in]  This         A Pointer to SCMI_CLOCK2_PROTOCOL Instance.\r
\r
  @param[out] TotalClocks  Total number of clocks supported.\r
\r
  @retval EFI_SUCCESS       Total number of clocks supported is returned.\r
  @retval EFI_DEVICE_ERROR  SCP returns an SCMI error.\r
  @retval !(EFI_SUCCESS)    Other errors.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *SCMI_CLOCK2_GET_TOTAL_CLOCKS) (\r
  IN  SCMI_CLOCK2_PROTOCOL  *This,\r
  OUT UINT32                *TotalClocks\r
  );\r
\r
/** Return attributes of a clock device.\r
\r
  @param[in]  This        A Pointer to SCMI_CLOCK2_PROTOCOL Instance.\r
  @param[in]  ClockId     Identifier for the clock device.\r
\r
  @param[out] Enabled         If TRUE, the clock device is enabled.\r
  @param[out] ClockAsciiName  A NULL terminated ASCII string with the clock\r
                              name, of up to 16 bytes.\r
\r
  @retval EFI_SUCCESS          Clock device attributes are returned.\r
  @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.\r
  @retval !(EFI_SUCCESS)       Other errors.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *SCMI_CLOCK2_GET_CLOCK_ATTRIBUTES) (\r
  IN  SCMI_CLOCK2_PROTOCOL  *This,\r
  IN  UINT32                ClockId,\r
  OUT BOOLEAN               *Enabled,\r
  OUT CHAR8                 *ClockAsciiName\r
  );\r
\r
/** Return list of rates supported by a given clock device.\r
\r
  @param[in] This        A pointer to SCMI_CLOCK2_PROTOCOL Instance.\r
  @param[in] ClockId     Identifier for the clock device.\r
\r
  @param[out] Format      SCMI_CLOCK_RATE_FORMAT_DISCRETE: Clock device\r
                          supports range of clock rates which are non-linear.\r
\r
                          SCMI_CLOCK_RATE_FORMAT_LINEAR: Clock device supports\r
                          range of linear clock rates from Min to Max in steps.\r
\r
  @param[out] TotalRates  Total number of rates.\r
\r
  @param[in,out] RateArraySize  Size of the RateArray.\r
\r
  @param[out] RateArray   List of clock rates.\r
\r
  @retval EFI_SUCCESS          List of clock rates are returned.\r
  @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.\r
  @retval EFI_BUFFER_TOO_SMALL RateArraySize is too small for the result.\r
                               It has been updated to the size needed.\r
  @retval !(EFI_SUCCESS)       Other errors.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *SCMI_CLOCK2_DESCRIBE_RATES) (\r
  IN     SCMI_CLOCK2_PROTOCOL     *This,\r
  IN     UINT32                   ClockId,\r
  OUT    SCMI_CLOCK_RATE_FORMAT   *Format,\r
  OUT    UINT32                   *TotalRates,\r
  IN OUT UINT32                   *RateArraySize,\r
  OUT    SCMI_CLOCK_RATE          *RateArray\r
  );\r
\r
/** Get clock rate.\r
\r
  @param[in]  This        A Pointer to SCMI_CLOCK2_PROTOCOL Instance.\r
  @param[in]  ClockId     Identifier for the clock device.\r
\r
  @param[out]  Rate       Clock rate.\r
\r
  @retval EFI_SUCCESS          Clock rate is returned.\r
  @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.\r
  @retval !(EFI_SUCCESS)       Other errors.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *SCMI_CLOCK2_RATE_GET) (\r
  IN  SCMI_CLOCK2_PROTOCOL  *This,\r
  IN  UINT32                ClockId,\r
  OUT UINT64                *Rate\r
  );\r
\r
/** Set clock rate.\r
\r
  @param[in]  This        A Pointer to SCMI_CLOCK2_PROTOCOL Instance.\r
  @param[in]  ClockId     Identifier for the clock device.\r
  @param[in]  Rate        Clock rate.\r
\r
  @retval EFI_SUCCESS          Clock rate set success.\r
  @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.\r
  @retval !(EFI_SUCCESS)       Other errors.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *SCMI_CLOCK2_RATE_SET) (\r
  IN SCMI_CLOCK2_PROTOCOL   *This,\r
  IN UINT32                 ClockId,\r
  IN UINT64                 Rate\r
  );\r
\r
/** Enable/Disable specified clock.\r
    Function is only available under gArmScmiClock2ProtocolGuid\r
\r
  @param[in]  This        A Pointer to SCMI_CLOCK2_PROTOCOL Instance.\r
  @param[in]  ClockId     Identifier for the clock device.\r
  @param[in]  Enable      TRUE to enable, FALSE to disable.\r
\r
  @retval EFI_SUCCESS          Clock enable/disable successful.\r
  @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.\r
  @retval !(EFI_SUCCESS)       Other errors.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *SCMI_CLOCK2_ENABLE) (\r
  IN SCMI_CLOCK2_PROTOCOL   *This,\r
  IN UINT32                 ClockId,\r
  IN BOOLEAN                Enable\r
  );\r
\r
typedef struct _SCMI_CLOCK2_PROTOCOL {\r
  SCMI_CLOCK2_GET_VERSION           GetVersion;\r
  SCMI_CLOCK2_GET_TOTAL_CLOCKS      GetTotalClocks;\r
  SCMI_CLOCK2_GET_CLOCK_ATTRIBUTES  GetClockAttributes;\r
  SCMI_CLOCK2_DESCRIBE_RATES        DescribeRates;\r
  SCMI_CLOCK2_RATE_GET              RateGet;\r
  SCMI_CLOCK2_RATE_SET              RateSet;\r
\r
  // Extension to original ClockProtocol, added here so SCMI_CLOCK2_PROTOCOL\r
  // can be cast to SCMI_CLOCK_PROTOCOL\r
  UINTN                             Version; // For future expandability\r
  SCMI_CLOCK2_ENABLE                Enable;\r
} SCMI_CLOCK2_PROTOCOL;\r
\r
#endif /* ARM_SCMI_CLOCK2_PROTOCOL_H_ */\r