ArmPkg/Drivers/ArmScmiDxe/ScmiPrivate.h

   1 /** @file
   2
   3   Copyright (c) 2017-2018, Arm Limited. All rights reserved.
   4
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   System Control and Management Interface V1.0
  14     http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/
  15     DEN0056A_System_Control_and_Management_Interface.pdf
  16 **/
  17 #ifndef SCMI_PRIVATE_H_
  18 #define SCMI_PRIVATE_H_
  19
  20 // SCMI protocol IDs.
  21 typedef enum {
  22   SCMI_PROTOCOL_ID_BASE         = 0x10,
  23   SCMI_PROTOCOL_ID_POWER_DOMAIN = 0x11,
  24   SCMI_PROTOCOL_ID_SYSTEM_POWER = 0x12,
  25   SCMI_PROTOCOL_ID_PERFORMANCE  = 0x13,
  26   SCMI_PROTOCOL_ID_CLOCK        = 0x14,
  27   SCMI_PROTOCOL_ID_SENSOR       = 0x15
  28 } SCMI_PROTOCOL_ID;
  29
  30 // SCMI message types.
  31 typedef enum {
  32   SCMI_MESSAGE_TYPE_COMMAND          = 0,
  33   SCMI_MESSAGE_TYPE_DELAYED_RESPONSE = 2, // Skipping 1 is deliberate.
  34   SCMI_MESSAGE_TYPE_NOTIFICATION     = 3
  35 } SCMI_MESSAGE_TYPE;
  36
  37 // SCMI response error codes.
  38 typedef enum {
  39   SCMI_SUCCESS            =  0,
  40   SCMI_NOT_SUPPORTED      = -1,
  41   SCMI_INVALID_PARAMETERS = -2,
  42   SCMI_DENIED             = -3,
  43   SCMI_NOT_FOUND          = -4,
  44   SCMI_OUT_OF_RANGE       = -5,
  45   SCMI_BUSY               = -6,
  46   SCMI_COMMS_ERROR        = -7,
  47   SCMI_GENERIC_ERROR      = -8,
  48   SCMI_HARDWARE_ERROR     = -9,
  49   SCMI_PROTOCOL_ERROR     = -10
  50 } SCMI_STATUS;
  51
  52 // SCMI message IDs common to all protocols.
  53 typedef enum {
  54   SCMI_MESSAGE_ID_PROTOCOL_VERSION            = 0x0,
  55   SCMI_MESSAGE_ID_PROTOCOL_ATTRIBUTES         = 0x1,
  56   SCMI_MESSAGE_ID_PROTOCOL_MESSAGE_ATTRIBUTES = 0x2
  57 } SCMI_MESSAGE_ID;
  58
  59 // Not defined in SCMI specification but will help to identify a message.
  60 typedef struct {
  61   SCMI_PROTOCOL_ID ProtocolId;
  62   UINT32 MessageId;
  63 } SCMI_COMMAND;
  64
  65 #pragma pack(1)
  66
  67 // Response to a SCMI command.
  68 typedef struct {
  69   INT32 Status;
  70   UINT32 ReturnValues[];
  71 } SCMI_MESSAGE_RESPONSE;
  72
  73 // Message header. MsgId[7:0], MsgType[9:8], ProtocolId[17:10]
  74 #define MESSAGE_TYPE_SHIFT       8
  75 #define PROTOCOL_ID_SHIFT       10
  76 #define SCMI_MESSAGE_HEADER(MsgId, MsgType, ProtocolId)  (           \
  77                             MsgType << MESSAGE_TYPE_SHIFT   |        \
  78                             ProtocolId << PROTOCOL_ID_SHIFT |        \
  79                             MsgId                                    \
  80                             )
  81 // SCMI message header.
  82 typedef struct {
  83   UINT32 MessageHeader;
  84 } SCMI_MESSAGE_HEADER;
  85
  86 #pragma pack()
  87
  88 /** Return a pointer to the message payload.
  89
  90   @param[out] Payload         Holds pointer to the message payload.
  91
  92   @retval EFI_SUCCESS         Payload holds a valid message payload pointer.
  93   @retval EFI_TIMEOUT         Time out error if MTL channel is busy.
  94   @retval EFI_UNSUPPORTED     If MTL channel is unsupported.
  95 **/
  96 EFI_STATUS
  97 ScmiCommandGetPayload (
  98   OUT UINT32** Payload
  99   );
 100
 101 /** Execute a SCMI command and receive a response.
 102
 103   This function uses a MTL channel to transfer message to SCP
 104   and waits for a response.
 105
 106   @param[in]   Command      Pointer to the SCMI command (Protocol ID
 107                             and Message ID)
 108
 109   @param[in,out] PayloadLength   SCMI command message length.
 110
 111   @param[out] OPTIONAL  ReturnValues   Pointer to SCMI response.
 112
 113   @retval OUT EFI_SUCCESS       Command sent and message received successfully.
 114   @retval OUT EFI_UNSUPPORTED   Channel not supported.
 115   @retval OUT EFI_TIMEOUT       Timeout on the channel.
 116   @retval OUT EFI_DEVICE_ERROR  Channel not ready.
 117   @retval OUT EFI_DEVICE_ERROR  Message Header corrupted.
 118   @retval OUT EFI_DEVICE_ERROR  SCMI error.
 119 **/
 120 EFI_STATUS
 121 ScmiCommandExecute (
 122   IN     SCMI_COMMAND  *Command,
 123   IN OUT UINT32        *PayloadLength,
 124   OUT    UINT32       **ReturnValues OPTIONAL
 125   );
 126
 127 /** Return protocol version from SCP for a given protocol ID.
 128
 129   @param[in]  Protocol ID    Protocol ID.
 130   @param[out] Version        Pointer to version of the protocol.
 131
 132   @retval EFI_SUCCESS       Version holds a valid version received
 133                              from the SCP.
 134   @retval EFI_DEVICE_ERROR  SCMI error.
 135   @retval !(EFI_SUCCESS)    Other errors.
 136 **/
 137 EFI_STATUS
 138 ScmiGetProtocolVersion (
 139   IN  SCMI_PROTOCOL_ID  ProtocolId,
 140   OUT UINT32            *Version
 141   );
 142
 143 /** Return protocol attributes from SCP for a given protocol ID.
 144
 145   @param[in]  Protocol ID    Protocol ID.
 146   @param[out] ReturnValues   Pointer to attributes of the protocol.
 147
 148   @retval EFI_SUCCESS       ReturnValues points to protocol attributes.
 149   @retval EFI_DEVICE_ERROR  SCMI error.
 150   @retval !(EFI_SUCCESS)    Other errors.
 151 **/
 152 EFI_STATUS
 153 ScmiGetProtocolAttributes (
 154   IN  SCMI_PROTOCOL_ID  ProtocolId,
 155   OUT UINT32            **ReturnValues
 156   );
 157
 158 /** Return protocol message attributes from SCP for a given protocol ID.
 159
 160   @param[in]  Protocol ID    Protocol ID.
 161
 162   @param[out] Attributes     Pointer to attributes of the protocol.
 163
 164   @retval EFI_SUCCESS       ReturnValues points to protocol message attributes.
 165   @retval EFI_DEVICE_ERROR  SCMI error.
 166   @retval !(EFI_SUCCESS)    Other errors.
 167 **/
 168 EFI_STATUS
 169 ScmiGetProtocolMessageAttributes (
 170   IN  SCMI_PROTOCOL_ID  ProtocolId,
 171   OUT UINT32            **ReturnValues
 172   );
 173
 174 #endif /* SCMI_PRIVATE_H_ */