ArmPkg/Include/Protocol/ArmScmiClockProtocol.h

   1 /** @file
   2
   3   Copyright (c) 2017-2018, Arm Limited. All rights reserved.
   4
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7   System Control and Management Interface V1.0
   8     http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/
   9     DEN0056A_System_Control_and_Management_Interface.pdf
  10 **/
  11
  12 #ifndef ARM_SCMI_CLOCK_PROTOCOL_H_
  13 #define ARM_SCMI_CLOCK_PROTOCOL_H_
  14
  15 #include <Protocol/ArmScmi.h>
  16
  17 #define ARM_SCMI_CLOCK_PROTOCOL_GUID { \
  18   0x91ce67a8, 0xe0aa, 0x4012, {0xb9, 0x9f, 0xb6, 0xfc, 0xf3, 0x4, 0x8e, 0xaa} \
  19   }
  20
  21 extern EFI_GUID gArmScmiClockProtocolGuid;
  22
  23 // Message Type for clock management protocol.
  24 typedef enum {
  25   SCMI_MESSAGE_ID_CLOCK_ATTRIBUTES     = 0x3,
  26   SCMI_MESSAGE_ID_CLOCK_DESCRIBE_RATES = 0x4,
  27   SCMI_MESSAGE_ID_CLOCK_RATE_SET       = 0x5,
  28   SCMI_MESSAGE_ID_CLOCK_RATE_GET       = 0x6,
  29   SCMI_MESSAGE_ID_CLOCK_CONFIG_SET     = 0x7
  30 } SCMI_MESSAGE_ID_CLOCK;
  31
  32 typedef enum {
  33   SCMI_CLOCK_RATE_FORMAT_DISCRETE, // Non-linear range.
  34   SCMI_CLOCK_RATE_FORMAT_LINEAR    // Linear range.
  35 } SCMI_CLOCK_RATE_FORMAT;
  36
  37 // Clock management protocol version.
  38 #define SCMI_CLOCK_PROTOCOL_VERSION 0x10000
  39
  40 #define SCMI_CLOCK_PROTOCOL_PENDING_ASYNC_RATES_MASK      0xFFU
  41 #define SCMI_CLOCK_PROTOCOL_PENDING_ASYNC_RATES_SHIFT     16
  42 #define SCMI_CLOCK_PROTOCOL_NUM_CLOCKS_MASK               0xFFFFU
  43
  44 /** Total number of pending asynchronous clock rates changes
  45   supported by the SCP, Attr Bits[23:16]
  46 */
  47 #define SCMI_CLOCK_PROTOCOL_MAX_ASYNC_CLK_RATES(Attr) (                       \
  48                   (Attr >> SCMI_CLOCK_PROTOCOL_PENDING_ASYNC_RATES_SHIFT) &&  \
  49                    SCMI_CLOCK_PROTOCOL_PENDING_ASYNC_RATES_MASK)
  50
  51 // Total of clock devices supported by the SCP, Attr Bits[15:0]
  52 #define SCMI_CLOCK_PROTOCOL_TOTAL_CLKS(Attr) (Attr & SCMI_CLOCK_PROTOCOL_NUM_CLOCKS_MASK)
  53
  54 #pragma pack(1)
  55
  56 /* Depending on the format (linear/non-linear) supported by a clock device
  57    either Rate or Min/Max/Step triplet is valid.
  58 */
  59 typedef struct {
  60   union {
  61   UINT64 Min;
  62   UINT64 Rate;
  63   };
  64   UINT64 Max;
  65   UINT64 Step;
  66 } SCMI_CLOCK_RATE;
  67
  68 #pragma pack()
  69
  70 typedef struct _SCMI_CLOCK_PROTOCOL SCMI_CLOCK_PROTOCOL;
  71
  72 // Protocol Interface functions.
  73
  74 /** Return version of the clock management protocol supported by SCP firmware.
  75
  76   @param[in]  This     A Pointer to SCMI_CLOCK_PROTOCOL Instance.
  77
  78   @param[out] Version  Version of the supported SCMI Clock management protocol.
  79
  80   @retval EFI_SUCCESS       The version is returned.
  81   @retval EFI_DEVICE_ERROR  SCP returns an SCMI error.
  82   @retval !(EFI_SUCCESS)    Other errors.
  83 **/
  84 typedef
  85 EFI_STATUS
  86 (EFIAPI *SCMI_CLOCK_GET_VERSION) (
  87   IN  SCMI_CLOCK_PROTOCOL  *This,
  88   OUT UINT32               *Version
  89   );
  90
  91 /** Return total number of clock devices supported by the clock management
  92    protocol.
  93
  94   @param[in]  This         A Pointer to SCMI_CLOCK_PROTOCOL Instance.
  95
  96   @param[out] TotalClocks  Total number of clocks supported.
  97
  98   @retval EFI_SUCCESS       Total number of clocks supported is returned.
  99   @retval EFI_DEVICE_ERROR  SCP returns an SCMI error.
 100   @retval !(EFI_SUCCESS)    Other errors.
 101 **/
 102 typedef
 103 EFI_STATUS
 104 (EFIAPI *SCMI_CLOCK_GET_TOTAL_CLOCKS) (
 105   IN  SCMI_CLOCK_PROTOCOL  *This,
 106   OUT UINT32               *TotalClocks
 107   );
 108
 109 /** Return attributes of a clock device.
 110
 111   @param[in]  This        A Pointer to SCMI_CLOCK_PROTOCOL Instance.
 112   @param[in]  ClockId     Identifier for the clock device.
 113
 114   @param[out] Enabled         If TRUE, the clock device is enabled.
 115   @param[out] ClockAsciiName  A NULL terminated ASCII string with the clock
 116                               name, of up to 16 bytes.
 117
 118   @retval EFI_SUCCESS          Clock device attributes are returned.
 119   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
 120   @retval !(EFI_SUCCESS)       Other errors.
 121 **/
 122 typedef
 123 EFI_STATUS
 124 (EFIAPI *SCMI_CLOCK_GET_CLOCK_ATTRIBUTES) (
 125   IN  SCMI_CLOCK_PROTOCOL  *This,
 126   IN  UINT32               ClockId,
 127   OUT BOOLEAN              *Enabled,
 128   OUT CHAR8                *ClockAsciiName
 129   );
 130
 131 /** Return list of rates supported by a given clock device.
 132
 133   @param[in] This        A pointer to SCMI_CLOCK_PROTOCOL Instance.
 134   @param[in] ClockId     Identifier for the clock device.
 135
 136   @param[out] Format      SCMI_CLOCK_RATE_FORMAT_DISCRETE: Clock device
 137                           supports range of clock rates which are non-linear.
 138
 139                           SCMI_CLOCK_RATE_FORMAT_LINEAR: Clock device supports
 140                           range of linear clock rates from Min to Max in steps.
 141
 142   @param[out] TotalRates  Total number of rates.
 143
 144   @param[in,out] RateArraySize  Size of the RateArray.
 145
 146   @param[out] RateArray   List of clock rates.
 147
 148   @retval EFI_SUCCESS          List of clock rates are returned.
 149   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
 150   @retval EFI_BUFFER_TOO_SMALL RateArraySize is too small for the result.
 151                                It has been updated to the size needed.
 152   @retval !(EFI_SUCCESS)       Other errors.
 153 **/
 154 typedef
 155 EFI_STATUS
 156 (EFIAPI *SCMI_CLOCK_DESCRIBE_RATES) (
 157   IN     SCMI_CLOCK_PROTOCOL     *This,
 158   IN     UINT32                   ClockId,
 159   OUT    SCMI_CLOCK_RATE_FORMAT  *Format,
 160   OUT    UINT32                  *TotalRates,
 161   IN OUT UINT32                  *RateArraySize,
 162   OUT    SCMI_CLOCK_RATE         *RateArray
 163   );
 164
 165 /** Get clock rate.
 166
 167   @param[in]  This        A Pointer to SCMI_CLOCK_PROTOCOL Instance.
 168   @param[in]  ClockId     Identifier for the clock device.
 169
 170   @param[out]  Rate       Clock rate.
 171
 172   @retval EFI_SUCCESS          Clock rate is returned.
 173   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
 174   @retval !(EFI_SUCCESS)       Other errors.
 175 **/
 176 typedef
 177 EFI_STATUS
 178 (EFIAPI *SCMI_CLOCK_RATE_GET) (
 179   IN  SCMI_CLOCK_PROTOCOL  *This,
 180   IN  UINT32               ClockId,
 181   OUT UINT64               *Rate
 182   );
 183
 184 /** Set clock rate.
 185
 186   @param[in]  This        A Pointer to SCMI_CLOCK_PROTOCOL Instance.
 187   @param[in]  ClockId     Identifier for the clock device.
 188   @param[in]  Rate        Clock rate.
 189
 190   @retval EFI_SUCCESS          Clock rate set success.
 191   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
 192   @retval !(EFI_SUCCESS)       Other errors.
 193 **/
 194 typedef
 195 EFI_STATUS
 196 (EFIAPI *SCMI_CLOCK_RATE_SET) (
 197   IN SCMI_CLOCK_PROTOCOL  *This,
 198   IN UINT32               ClockId,
 199   IN UINT64               Rate
 200   );
 201
 202 typedef struct _SCMI_CLOCK_PROTOCOL {
 203   SCMI_CLOCK_GET_VERSION GetVersion;
 204   SCMI_CLOCK_GET_TOTAL_CLOCKS GetTotalClocks;
 205   SCMI_CLOCK_GET_CLOCK_ATTRIBUTES GetClockAttributes;
 206   SCMI_CLOCK_DESCRIBE_RATES DescribeRates;
 207   SCMI_CLOCK_RATE_GET RateGet;
 208   SCMI_CLOCK_RATE_SET RateSet;
 209 } SCMI_CLOCK_PROTOCOL;
 210
 211 #endif /* ARM_SCMI_CLOCK_PROTOCOL_H_ */
 212