ArmPkg/Drivers/ArmScmiDxe/ScmiPrivate.h

   1 /** @file
   2
   3   Copyright (c) 2017-2021, Arm Limited. All rights reserved.<BR>
   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 SCMI_PRIVATE_H_
  13 #define SCMI_PRIVATE_H_
  14
  15 // SCMI protocol IDs.
  16 typedef enum {
  17   ScmiProtocolIdBase        = 0x10,
  18   ScmiProtocolIdPowerDomain = 0x11,
  19   ScmiProtocolIdSystemPower = 0x12,
  20   ScmiProtocolIdPerformance = 0x13,
  21   ScmiProtocolIdClock       = 0x14,
  22   ScmiProtocolIdSensor      = 0x15
  23 } SCMI_PROTOCOL_ID;
  24
  25 // SCMI message types.
  26 typedef enum {
  27   ScmiMessageTypeCommand         = 0,
  28   ScmiMessageTypeDelayedResponse = 2, // Skipping 1 is deliberate.
  29   ScmiMessageTypeNotification    = 3
  30 } SCMI_MESSAGE_TYPE;
  31
  32 // SCMI response error codes.
  33 typedef enum {
  34   ScmiSuccess           =  0,
  35   ScmiNotSupported      = -1,
  36   ScmiInvalidParameters = -2,
  37   ScmiDenied            = -3,
  38   ScmiNotFound          = -4,
  39   ScmiOutOfRange        = -5,
  40   ScmiBusy              = -6,
  41   ScmiCommsError        = -7,
  42   ScmiGenericError      = -8,
  43   ScmiHardwareError     = -9,
  44   ScmiProtocolError     = -10
  45 } SCMI_STATUS;
  46
  47 // SCMI message IDs common to all protocols.
  48 typedef enum {
  49   ScmiMessageIdProtocolVersion           = 0x0,
  50   ScmiMessageIdProtocolAttributes        = 0x1,
  51   ScmiMessageIdProtocolMessageAttributes = 0x2
  52 } SCMI_MESSAGE_ID;
  53
  54 // Not defined in SCMI specification but will help to identify a message.
  55 typedef struct {
  56   SCMI_PROTOCOL_ID    ProtocolId;
  57   UINT32              MessageId;
  58 } SCMI_COMMAND;
  59
  60 #pragma pack(1)
  61
  62 // Response to a SCMI command.
  63 typedef struct {
  64   INT32     Status;
  65   UINT32    ReturnValues[];
  66 } SCMI_MESSAGE_RESPONSE;
  67
  68 // Message header. MsgId[7:0], MsgType[9:8], ProtocolId[17:10]
  69 #define MESSAGE_TYPE_SHIFT  8
  70 #define PROTOCOL_ID_SHIFT   10
  71 #define SCMI_MESSAGE_HEADER(MsgId, MsgType, ProtocolId)  (           \
  72                             MsgType << MESSAGE_TYPE_SHIFT   |        \
  73                             ProtocolId << PROTOCOL_ID_SHIFT |        \
  74                             MsgId                                    \
  75                             )
  76 // SCMI message header.
  77 typedef struct {
  78   UINT32    MessageHeader;
  79 } SCMI_MESSAGE_HEADER;
  80
  81 #pragma pack()
  82
  83 /** Return a pointer to the message payload.
  84
  85   @param[out] Payload         Holds pointer to the message payload.
  86
  87   @retval EFI_SUCCESS         Payload holds a valid message payload pointer.
  88   @retval EFI_TIMEOUT         Time out error if MTL channel is busy.
  89   @retval EFI_UNSUPPORTED     If MTL channel is unsupported.
  90 **/
  91 EFI_STATUS
  92 ScmiCommandGetPayload (
  93   OUT UINT32  **Payload
  94   );
  95
  96 /** Execute a SCMI command and receive a response.
  97
  98   This function uses a MTL channel to transfer message to SCP
  99   and waits for a response.
 100
 101   @param[in]   Command      Pointer to the SCMI command (Protocol ID
 102                             and Message ID)
 103
 104   @param[in,out] PayloadLength   SCMI command message length.
 105
 106   @param[out] OPTIONAL  ReturnValues   Pointer to SCMI response.
 107
 108   @retval OUT EFI_SUCCESS       Command sent and message received successfully.
 109   @retval OUT EFI_UNSUPPORTED   Channel not supported.
 110   @retval OUT EFI_TIMEOUT       Timeout on the channel.
 111   @retval OUT EFI_DEVICE_ERROR  Channel not ready.
 112   @retval OUT EFI_DEVICE_ERROR  Message Header corrupted.
 113   @retval OUT EFI_DEVICE_ERROR  SCMI error.
 114 **/
 115 EFI_STATUS
 116 ScmiCommandExecute (
 117   IN     SCMI_COMMAND  *Command,
 118   IN OUT UINT32        *PayloadLength,
 119   OUT    UINT32        **ReturnValues OPTIONAL
 120   );
 121
 122 /** Return protocol version from SCP for a given protocol ID.
 123
 124   @param[in]  Protocol ID    Protocol ID.
 125   @param[out] Version        Pointer to version of the protocol.
 126
 127   @retval EFI_SUCCESS       Version holds a valid version received
 128                              from the SCP.
 129   @retval EFI_DEVICE_ERROR  SCMI error.
 130   @retval !(EFI_SUCCESS)    Other errors.
 131 **/
 132 EFI_STATUS
 133 ScmiGetProtocolVersion (
 134   IN  SCMI_PROTOCOL_ID  ProtocolId,
 135   OUT UINT32            *Version
 136   );
 137
 138 /** Return protocol attributes from SCP for a given protocol ID.
 139
 140   @param[in]  Protocol ID    Protocol ID.
 141   @param[out] ReturnValues   Pointer to attributes of the protocol.
 142
 143   @retval EFI_SUCCESS       ReturnValues points to protocol attributes.
 144   @retval EFI_DEVICE_ERROR  SCMI error.
 145   @retval !(EFI_SUCCESS)    Other errors.
 146 **/
 147 EFI_STATUS
 148 ScmiGetProtocolAttributes (
 149   IN  SCMI_PROTOCOL_ID  ProtocolId,
 150   OUT UINT32            **ReturnValues
 151   );
 152
 153 /** Return protocol message attributes from SCP for a given protocol ID.
 154
 155   @param[in]  Protocol ID    Protocol ID.
 156
 157   @param[out] Attributes     Pointer to attributes of the protocol.
 158
 159   @retval EFI_SUCCESS       ReturnValues points to protocol message attributes.
 160   @retval EFI_DEVICE_ERROR  SCMI error.
 161   @retval !(EFI_SUCCESS)    Other errors.
 162 **/
 163 EFI_STATUS
 164 ScmiGetProtocolMessageAttributes (
 165   IN  SCMI_PROTOCOL_ID  ProtocolId,
 166   OUT UINT32            **ReturnValues
 167   );
 168
 169 #endif /* SCMI_PRIVATE_H_ */