ArmPkg/Include/Protocol/ArmScmiClockProtocol.h

   1 /** @file
   2
   3   Copyright (c) 2017-2021, 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   ScmiMessageIdClockAttributes    = 0x3,
  26   ScmiMessageIdClockDescribeRates = 0x4,
  27   ScmiMessageIdClockRateSet       = 0x5,
  28   ScmiMessageIdClockRateGet       = 0x6,
  29   ScmiMessageIdClockConfigSet     = 0x7
  30 } SCMI_MESSAGE_ID_CLOCK;
  31
  32 typedef enum {
  33   ScmiClockRateFormatDiscrete, // Non-linear range.
  34   ScmiClockRateFormatLinear    // 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   UINT64    Min;
  61   UINT64    Max;
  62   UINT64    Step;
  63 } SCMI_CLOCK_RATE_CONTINUOUS;
  64
  65 typedef struct {
  66   UINT64    Rate;
  67 } SCMI_CLOCK_RATE_DISCRETE;
  68
  69 typedef union {
  70   SCMI_CLOCK_RATE_CONTINUOUS    ContinuousRate;
  71   SCMI_CLOCK_RATE_DISCRETE      DiscreteRate;
  72 } SCMI_CLOCK_RATE;
  73
  74 #pragma pack()
  75
  76 typedef struct _SCMI_CLOCK_PROTOCOL SCMI_CLOCK_PROTOCOL;
  77
  78 // Protocol Interface functions.
  79
  80 /** Return version of the clock management protocol supported by SCP firmware.
  81
  82   @param[in]  This     A Pointer to SCMI_CLOCK_PROTOCOL Instance.
  83
  84   @param[out] Version  Version of the supported SCMI Clock management protocol.
  85
  86   @retval EFI_SUCCESS       The version is returned.
  87   @retval EFI_DEVICE_ERROR  SCP returns an SCMI error.
  88   @retval !(EFI_SUCCESS)    Other errors.
  89 **/
  90 typedef
  91 EFI_STATUS
  92 (EFIAPI *SCMI_CLOCK_GET_VERSION)(
  93   IN  SCMI_CLOCK_PROTOCOL  *This,
  94   OUT UINT32               *Version
  95   );
  96
  97 /** Return total number of clock devices supported by the clock management
  98    protocol.
  99
 100   @param[in]  This         A Pointer to SCMI_CLOCK_PROTOCOL Instance.
 101
 102   @param[out] TotalClocks  Total number of clocks supported.
 103
 104   @retval EFI_SUCCESS       Total number of clocks supported is returned.
 105   @retval EFI_DEVICE_ERROR  SCP returns an SCMI error.
 106   @retval !(EFI_SUCCESS)    Other errors.
 107 **/
 108 typedef
 109 EFI_STATUS
 110 (EFIAPI *SCMI_CLOCK_GET_TOTAL_CLOCKS)(
 111   IN  SCMI_CLOCK_PROTOCOL  *This,
 112   OUT UINT32               *TotalClocks
 113   );
 114
 115 /** Return attributes of a clock device.
 116
 117   @param[in]  This        A Pointer to SCMI_CLOCK_PROTOCOL Instance.
 118   @param[in]  ClockId     Identifier for the clock device.
 119
 120   @param[out] Enabled         If TRUE, the clock device is enabled.
 121   @param[out] ClockAsciiName  A NULL terminated ASCII string with the clock
 122                               name, of up to 16 bytes.
 123
 124   @retval EFI_SUCCESS          Clock device attributes are returned.
 125   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
 126   @retval !(EFI_SUCCESS)       Other errors.
 127 **/
 128 typedef
 129 EFI_STATUS
 130 (EFIAPI *SCMI_CLOCK_GET_CLOCK_ATTRIBUTES)(
 131   IN  SCMI_CLOCK_PROTOCOL  *This,
 132   IN  UINT32               ClockId,
 133   OUT BOOLEAN              *Enabled,
 134   OUT CHAR8                *ClockAsciiName
 135   );
 136
 137 /** Return list of rates supported by a given clock device.
 138
 139   @param[in] This        A pointer to SCMI_CLOCK_PROTOCOL Instance.
 140   @param[in] ClockId     Identifier for the clock device.
 141
 142   @param[out] Format      ScmiClockRateFormatDiscrete: Clock device
 143                           supports range of clock rates which are non-linear.
 144
 145                           ScmiClockRateFormatLinear: Clock device supports
 146                           range of linear clock rates from Min to Max in steps.
 147
 148   @param[out] TotalRates  Total number of rates.
 149
 150   @param[in,out] RateArraySize  Size of the RateArray.
 151
 152   @param[out] RateArray   List of clock rates.
 153
 154   @retval EFI_SUCCESS          List of clock rates are returned.
 155   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
 156   @retval EFI_BUFFER_TOO_SMALL RateArraySize is too small for the result.
 157                                It has been updated to the size needed.
 158   @retval !(EFI_SUCCESS)       Other errors.
 159 **/
 160 typedef
 161 EFI_STATUS
 162 (EFIAPI *SCMI_CLOCK_DESCRIBE_RATES)(
 163   IN     SCMI_CLOCK_PROTOCOL     *This,
 164   IN     UINT32                   ClockId,
 165   OUT    SCMI_CLOCK_RATE_FORMAT  *Format,
 166   OUT    UINT32                  *TotalRates,
 167   IN OUT UINT32                  *RateArraySize,
 168   OUT    SCMI_CLOCK_RATE         *RateArray
 169   );
 170
 171 /** Get clock rate.
 172
 173   @param[in]  This        A Pointer to SCMI_CLOCK_PROTOCOL Instance.
 174   @param[in]  ClockId     Identifier for the clock device.
 175
 176   @param[out]  Rate       Clock rate.
 177
 178   @retval EFI_SUCCESS          Clock rate is returned.
 179   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
 180   @retval !(EFI_SUCCESS)       Other errors.
 181 **/
 182 typedef
 183 EFI_STATUS
 184 (EFIAPI *SCMI_CLOCK_RATE_GET)(
 185   IN  SCMI_CLOCK_PROTOCOL  *This,
 186   IN  UINT32               ClockId,
 187   OUT UINT64               *Rate
 188   );
 189
 190 /** Set clock rate.
 191
 192   @param[in]  This        A Pointer to SCMI_CLOCK_PROTOCOL Instance.
 193   @param[in]  ClockId     Identifier for the clock device.
 194   @param[in]  Rate        Clock rate.
 195
 196   @retval EFI_SUCCESS          Clock rate set success.
 197   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
 198   @retval !(EFI_SUCCESS)       Other errors.
 199 **/
 200 typedef
 201 EFI_STATUS
 202 (EFIAPI *SCMI_CLOCK_RATE_SET)(
 203   IN SCMI_CLOCK_PROTOCOL  *This,
 204   IN UINT32               ClockId,
 205   IN UINT64               Rate
 206   );
 207
 208 typedef struct _SCMI_CLOCK_PROTOCOL {
 209   SCMI_CLOCK_GET_VERSION             GetVersion;
 210   SCMI_CLOCK_GET_TOTAL_CLOCKS        GetTotalClocks;
 211   SCMI_CLOCK_GET_CLOCK_ATTRIBUTES    GetClockAttributes;
 212   SCMI_CLOCK_DESCRIBE_RATES          DescribeRates;
 213   SCMI_CLOCK_RATE_GET                RateGet;
 214   SCMI_CLOCK_RATE_SET                RateSet;
 215 } SCMI_CLOCK_PROTOCOL;
 216
 217 #endif /* ARM_SCMI_CLOCK_PROTOCOL_H_ */