ArmPkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / ArmPkg / Include / Protocol / ArmScmiClockProtocol.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_CLOCK_PROTOCOL_H_\r
#define ARM_SCMI_CLOCK_PROTOCOL_H_\r
\r
#include <Protocol/ArmScmi.h>\r
\r
#define ARM_SCMI_CLOCK_PROTOCOL_GUID { \\r
  0x91ce67a8, 0xe0aa, 0x4012, {0xb9, 0x9f, 0xb6, 0xfc, 0xf3, 0x4, 0x8e, 0xaa} \\r
  }\r
\r
extern EFI_GUID gArmScmiClockProtocolGuid;\r
\r
// Message Type for clock management protocol.\r
typedef enum {\r
  SCMI_MESSAGE_ID_CLOCK_ATTRIBUTES     = 0x3,\r
  SCMI_MESSAGE_ID_CLOCK_DESCRIBE_RATES = 0x4,\r
  SCMI_MESSAGE_ID_CLOCK_RATE_SET       = 0x5,\r
  SCMI_MESSAGE_ID_CLOCK_RATE_GET       = 0x6,\r
  SCMI_MESSAGE_ID_CLOCK_CONFIG_SET     = 0x7\r
} SCMI_MESSAGE_ID_CLOCK;\r
\r
typedef enum {\r
  SCMI_CLOCK_RATE_FORMAT_DISCRETE, // Non-linear range.\r
  SCMI_CLOCK_RATE_FORMAT_LINEAR    // Linear range.\r
} SCMI_CLOCK_RATE_FORMAT;\r
\r
// Clock management protocol version.\r
#define SCMI_CLOCK_PROTOCOL_VERSION 0x10000\r
\r
#define SCMI_CLOCK_PROTOCOL_PENDING_ASYNC_RATES_MASK      0xFFU\r
#define SCMI_CLOCK_PROTOCOL_PENDING_ASYNC_RATES_SHIFT     16\r
#define SCMI_CLOCK_PROTOCOL_NUM_CLOCKS_MASK               0xFFFFU\r
\r
/** Total number of pending asynchronous clock rates changes\r
  supported by the SCP, Attr Bits[23:16]\r
*/\r
#define SCMI_CLOCK_PROTOCOL_MAX_ASYNC_CLK_RATES(Attr) (                       \\r
                  (Attr >> SCMI_CLOCK_PROTOCOL_PENDING_ASYNC_RATES_SHIFT) &&  \\r
                   SCMI_CLOCK_PROTOCOL_PENDING_ASYNC_RATES_MASK)\r
\r
// Total of clock devices supported by the SCP, Attr Bits[15:0]\r
#define SCMI_CLOCK_PROTOCOL_TOTAL_CLKS(Attr) (Attr & SCMI_CLOCK_PROTOCOL_NUM_CLOCKS_MASK)\r
\r
#pragma pack(1)\r
\r
/* Depending on the format (linear/non-linear) supported by a clock device\r
   either Rate or Min/Max/Step triplet is valid.\r
*/\r
typedef struct {\r
  union {\r
  UINT64 Min;\r
  UINT64 Rate;\r
  };\r
  UINT64 Max;\r
  UINT64 Step;\r
} SCMI_CLOCK_RATE;\r
\r
#pragma pack()\r
\r
typedef struct _SCMI_CLOCK_PROTOCOL SCMI_CLOCK_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_CLOCK_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_CLOCK_GET_VERSION) (\r
  IN  SCMI_CLOCK_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_CLOCK_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_CLOCK_GET_TOTAL_CLOCKS) (\r
  IN  SCMI_CLOCK_PROTOCOL  *This,\r
  OUT UINT32               *TotalClocks\r
  );\r
\r
/** Return attributes of a clock device.\r
\r
  @param[in]  This        A Pointer to SCMI_CLOCK_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_CLOCK_GET_CLOCK_ATTRIBUTES) (\r
  IN  SCMI_CLOCK_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_CLOCK_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_CLOCK_DESCRIBE_RATES) (\r
  IN     SCMI_CLOCK_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_CLOCK_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_CLOCK_RATE_GET) (\r
  IN  SCMI_CLOCK_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_CLOCK_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_CLOCK_RATE_SET) (\r
  IN SCMI_CLOCK_PROTOCOL  *This,\r
  IN UINT32               ClockId,\r
  IN UINT64               Rate\r
  );\r
\r
typedef struct _SCMI_CLOCK_PROTOCOL {\r
  SCMI_CLOCK_GET_VERSION GetVersion;\r
  SCMI_CLOCK_GET_TOTAL_CLOCKS GetTotalClocks;\r
  SCMI_CLOCK_GET_CLOCK_ATTRIBUTES GetClockAttributes;\r
  SCMI_CLOCK_DESCRIBE_RATES DescribeRates;\r
  SCMI_CLOCK_RATE_GET RateGet;\r
  SCMI_CLOCK_RATE_SET RateSet;\r
} SCMI_CLOCK_PROTOCOL;\r
\r
#endif /* ARM_SCMI_CLOCK_PROTOCOL_H_ */\r
\r