ArmPkg/Include/Protocol/ArmScmiClock2Protocol.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_CLOCK2_PROTOCOL_H_
  13 #define ARM_SCMI_CLOCK2_PROTOCOL_H_
  14
  15 #include <Protocol/ArmScmi.h>
  16 #include <Protocol/ArmScmiClockProtocol.h>
  17
  18 #define ARM_SCMI_CLOCK2_PROTOCOL_GUID { \
  19   0xb8d8caf2, 0x9e94, 0x462c, { 0xa8, 0x34, 0x6c, 0x99, 0xfc, 0x05, 0xef, 0xcf } \
  20   }
  21
  22 extern EFI_GUID gArmScmiClock2ProtocolGuid;
  23
  24 #define SCMI_CLOCK2_PROTOCOL_VERSION 1
  25
  26 typedef struct _SCMI_CLOCK2_PROTOCOL SCMI_CLOCK2_PROTOCOL;
  27
  28 // Protocol Interface functions.
  29
  30 /** Return version of the clock management protocol supported by SCP firmware.
  31
  32   @param[in]  This     A Pointer to SCMI_CLOCK2_PROTOCOL Instance.
  33
  34   @param[out] Version  Version of the supported SCMI Clock management protocol.
  35
  36   @retval EFI_SUCCESS       The version is returned.
  37   @retval EFI_DEVICE_ERROR  SCP returns an SCMI error.
  38   @retval !(EFI_SUCCESS)    Other errors.
  39 **/
  40 typedef
  41 EFI_STATUS
  42 (EFIAPI *SCMI_CLOCK2_GET_VERSION) (
  43   IN  SCMI_CLOCK2_PROTOCOL  *This,
  44   OUT UINT32                *Version
  45   );
  46
  47 /** Return total number of clock devices supported by the clock management
  48    protocol.
  49
  50   @param[in]  This         A Pointer to SCMI_CLOCK2_PROTOCOL Instance.
  51
  52   @param[out] TotalClocks  Total number of clocks supported.
  53
  54   @retval EFI_SUCCESS       Total number of clocks supported is returned.
  55   @retval EFI_DEVICE_ERROR  SCP returns an SCMI error.
  56   @retval !(EFI_SUCCESS)    Other errors.
  57 **/
  58 typedef
  59 EFI_STATUS
  60 (EFIAPI *SCMI_CLOCK2_GET_TOTAL_CLOCKS) (
  61   IN  SCMI_CLOCK2_PROTOCOL  *This,
  62   OUT UINT32                *TotalClocks
  63   );
  64
  65 /** Return attributes of a clock device.
  66
  67   @param[in]  This        A Pointer to SCMI_CLOCK2_PROTOCOL Instance.
  68   @param[in]  ClockId     Identifier for the clock device.
  69
  70   @param[out] Enabled         If TRUE, the clock device is enabled.
  71   @param[out] ClockAsciiName  A NULL terminated ASCII string with the clock
  72                               name, of up to 16 bytes.
  73
  74   @retval EFI_SUCCESS          Clock device attributes are returned.
  75   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
  76   @retval !(EFI_SUCCESS)       Other errors.
  77 **/
  78 typedef
  79 EFI_STATUS
  80 (EFIAPI *SCMI_CLOCK2_GET_CLOCK_ATTRIBUTES) (
  81   IN  SCMI_CLOCK2_PROTOCOL  *This,
  82   IN  UINT32                ClockId,
  83   OUT BOOLEAN               *Enabled,
  84   OUT CHAR8                 *ClockAsciiName
  85   );
  86
  87 /** Return list of rates supported by a given clock device.
  88
  89   @param[in] This        A pointer to SCMI_CLOCK2_PROTOCOL Instance.
  90   @param[in] ClockId     Identifier for the clock device.
  91
  92   @param[out] Format      SCMI_CLOCK_RATE_FORMAT_DISCRETE: Clock device
  93                           supports range of clock rates which are non-linear.
  94
  95                           SCMI_CLOCK_RATE_FORMAT_LINEAR: Clock device supports
  96                           range of linear clock rates from Min to Max in steps.
  97
  98   @param[out] TotalRates  Total number of rates.
  99
 100   @param[in,out] RateArraySize  Size of the RateArray.
 101
 102   @param[out] RateArray   List of clock rates.
 103
 104   @retval EFI_SUCCESS          List of clock rates are returned.
 105   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
 106   @retval EFI_BUFFER_TOO_SMALL RateArraySize is too small for the result.
 107                                It has been updated to the size needed.
 108   @retval !(EFI_SUCCESS)       Other errors.
 109 **/
 110 typedef
 111 EFI_STATUS
 112 (EFIAPI *SCMI_CLOCK2_DESCRIBE_RATES) (
 113   IN     SCMI_CLOCK2_PROTOCOL     *This,
 114   IN     UINT32                   ClockId,
 115   OUT    SCMI_CLOCK_RATE_FORMAT   *Format,
 116   OUT    UINT32                   *TotalRates,
 117   IN OUT UINT32                   *RateArraySize,
 118   OUT    SCMI_CLOCK_RATE          *RateArray
 119   );
 120
 121 /** Get clock rate.
 122
 123   @param[in]  This        A Pointer to SCMI_CLOCK2_PROTOCOL Instance.
 124   @param[in]  ClockId     Identifier for the clock device.
 125
 126   @param[out]  Rate       Clock rate.
 127
 128   @retval EFI_SUCCESS          Clock rate is returned.
 129   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
 130   @retval !(EFI_SUCCESS)       Other errors.
 131 **/
 132 typedef
 133 EFI_STATUS
 134 (EFIAPI *SCMI_CLOCK2_RATE_GET) (
 135   IN  SCMI_CLOCK2_PROTOCOL  *This,
 136   IN  UINT32                ClockId,
 137   OUT UINT64                *Rate
 138   );
 139
 140 /** Set clock rate.
 141
 142   @param[in]  This        A Pointer to SCMI_CLOCK2_PROTOCOL Instance.
 143   @param[in]  ClockId     Identifier for the clock device.
 144   @param[in]  Rate        Clock rate.
 145
 146   @retval EFI_SUCCESS          Clock rate set success.
 147   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
 148   @retval !(EFI_SUCCESS)       Other errors.
 149 **/
 150 typedef
 151 EFI_STATUS
 152 (EFIAPI *SCMI_CLOCK2_RATE_SET) (
 153   IN SCMI_CLOCK2_PROTOCOL   *This,
 154   IN UINT32                 ClockId,
 155   IN UINT64                 Rate
 156   );
 157
 158 /** Enable/Disable specified clock.
 159     Function is only available under gArmScmiClock2ProtocolGuid
 160
 161   @param[in]  This        A Pointer to SCMI_CLOCK2_PROTOCOL Instance.
 162   @param[in]  ClockId     Identifier for the clock device.
 163   @param[in]  Enable      TRUE to enable, FALSE to disable.
 164
 165   @retval EFI_SUCCESS          Clock enable/disable successful.
 166   @retval EFI_DEVICE_ERROR     SCP returns an SCMI error.
 167   @retval !(EFI_SUCCESS)       Other errors.
 168 **/
 169 typedef
 170 EFI_STATUS
 171 (EFIAPI *SCMI_CLOCK2_ENABLE) (
 172   IN SCMI_CLOCK2_PROTOCOL   *This,
 173   IN UINT32                 ClockId,
 174   IN BOOLEAN                Enable
 175   );
 176
 177 typedef struct _SCMI_CLOCK2_PROTOCOL {
 178   SCMI_CLOCK2_GET_VERSION           GetVersion;
 179   SCMI_CLOCK2_GET_TOTAL_CLOCKS      GetTotalClocks;
 180   SCMI_CLOCK2_GET_CLOCK_ATTRIBUTES  GetClockAttributes;
 181   SCMI_CLOCK2_DESCRIBE_RATES        DescribeRates;
 182   SCMI_CLOCK2_RATE_GET              RateGet;
 183   SCMI_CLOCK2_RATE_SET              RateSet;
 184
 185   // Extension to original ClockProtocol, added here so SCMI_CLOCK2_PROTOCOL
 186   // can be cast to SCMI_CLOCK_PROTOCOL
 187   UINTN                             Version; // For future expandability
 188   SCMI_CLOCK2_ENABLE                Enable;
 189 } SCMI_CLOCK2_PROTOCOL;
 190
 191 #endif /* ARM_SCMI_CLOCK2_PROTOCOL_H_ */