1 /* 2 * Copyright (c) 2017-2024, Arm Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef SCMI_H 8 #define SCMI_H 9 10 #include <stddef.h> 11 #include <stdint.h> 12 13 #include <lib/bakery_lock.h> 14 #include <lib/psci/psci.h> 15 #include <lib/spinlock.h> 16 17 /* Supported SCMI Protocol Versions */ 18 #define SCMI_AP_CORE_PROTO_VER MAKE_SCMI_VERSION(3, 0) 19 #define SCMI_PWR_DMN_PROTO_VER MAKE_SCMI_VERSION(3, 0) 20 #define SCMI_SYS_PWR_PROTO_VER MAKE_SCMI_VERSION(3, 0) 21 22 #define GET_SCMI_MAJOR_VER(ver) (((ver) >> 16) & 0xffff) 23 #define GET_SCMI_MINOR_VER(ver) ((ver) & 0xffff) 24 25 #define MAKE_SCMI_VERSION(maj, min) \ 26 ((((maj) & 0xffff) << 16) | ((min) & 0xffff)) 27 28 /* 29 * Check that the driver's version is same or higher than the reported SCMI 30 * version. We accept lower major version numbers, as all affected protocols 31 * so far stay backwards compatible. This might need to be revisited in the 32 * future. 33 */ 34 #define is_scmi_version_compatible(drv, scmi) \ 35 ((GET_SCMI_MAJOR_VER(drv) > GET_SCMI_MAJOR_VER(scmi)) || \ 36 ((GET_SCMI_MAJOR_VER(drv) == GET_SCMI_MAJOR_VER(scmi)) && \ 37 (GET_SCMI_MINOR_VER(drv) <= GET_SCMI_MINOR_VER(scmi)))) 38 39 /* SCMI Protocol identifiers */ 40 #define SCMI_BASE_PROTO_ID 0x10 41 #define SCMI_PWR_DMN_PROTO_ID 0x11 42 #define SCMI_SYS_PWR_PROTO_ID 0x12 43 /* The AP core protocol is a CSS platform-specific extension */ 44 #define SCMI_AP_CORE_PROTO_ID 0x90 45 46 /* Mandatory messages IDs for all SCMI protocols */ 47 #define SCMI_PROTO_VERSION_MSG 0x0 48 #define SCMI_PROTO_ATTR_MSG 0x1 49 #define SCMI_PROTO_MSG_ATTR_MSG 0x2 50 51 #define SCMI_PROTO_ATTR_MSG_LEN 4 52 #define SCMI_PROTO_ATTR_RESP_LEN 12 53 54 /* SCMI base protocol message IDs */ 55 #define SCMI_BASE_DISCOVER_AGENT 0x7 56 #define SCMI_BASE_DISCOVER_AGENT_MSG_LEN 8 57 #define SCMI_BASE_DISCOVER_AGENT_RESP_LEN 28 58 59 #define SCMI_BASE_RESET_AGENT_CONFIGURATION 0xB 60 #define SCMI_BASE_RESET_AGENT_CONFIGURATION_MSG_LEN 12 61 #define SCMI_BASE_RESET_AGENT_CONFIGURATION_RESP_LEN 8 62 63 /* SCMI power domain management protocol message IDs */ 64 #define SCMI_PWR_STATE_SET_MSG 0x4 65 #define SCMI_PWR_STATE_GET_MSG 0x5 66 67 /* SCMI system power management protocol message IDs */ 68 #define SCMI_SYS_PWR_STATE_SET_MSG 0x3 69 #define SCMI_SYS_PWR_STATE_GET_MSG 0x4 70 71 /* SCMI AP core protocol message IDs */ 72 #define SCMI_AP_CORE_RESET_ADDR_SET_MSG 0x3 73 #define SCMI_AP_CORE_RESET_ADDR_GET_MSG 0x4 74 75 /* Helper macros for system power management protocol commands */ 76 77 /* 78 * Macros to describe the bit-fields of the `attribute` of system power domain 79 * protocol PROTOCOL_MSG_ATTRIBUTE message. 80 */ 81 #define SYS_PWR_ATTR_WARM_RESET_SHIFT 31 82 #define SCMI_SYS_PWR_WARM_RESET_SUPPORTED (1U << SYS_PWR_ATTR_WARM_RESET_SHIFT) 83 84 #define SYS_PWR_ATTR_SUSPEND_SHIFT 30 85 #define SCMI_SYS_PWR_SUSPEND_SUPPORTED (1 << SYS_PWR_ATTR_SUSPEND_SHIFT) 86 87 /* 88 * Macros to describe the bit-fields of the `flags` parameter of system power 89 * domain protocol SYSTEM_POWER_STATE_SET message. 90 */ 91 #define SYS_PWR_SET_GRACEFUL_REQ_SHIFT 0 92 #define SCMI_SYS_PWR_GRACEFUL_REQ (1 << SYS_PWR_SET_GRACEFUL_REQ_SHIFT) 93 #define SCMI_SYS_PWR_FORCEFUL_REQ (0 << SYS_PWR_SET_GRACEFUL_REQ_SHIFT) 94 95 /* 96 * Macros to describe the `system_state` parameter of system power 97 * domain protocol SYSTEM_POWER_STATE_SET message. 98 */ 99 #define SCMI_SYS_PWR_SHUTDOWN 0x0 100 #define SCMI_SYS_PWR_COLD_RESET 0x1 101 #define SCMI_SYS_PWR_WARM_RESET 0x2 102 #define SCMI_SYS_PWR_POWER_UP 0x3 103 #define SCMI_SYS_PWR_SUSPEND 0x4 104 105 /* 106 * Macros to describe the bit-fields of the `attribute` of AP core protocol 107 * AP_CORE_RESET_ADDR set/get messages. 108 */ 109 #define SCMI_AP_CORE_LOCK_ATTR_SHIFT 0x0 110 #define SCMI_AP_CORE_LOCK_ATTR (1U << SCMI_AP_CORE_LOCK_ATTR_SHIFT) 111 112 /* SCMI Error code definitions */ 113 #define SCMI_E_QUEUED 1 114 #define SCMI_E_SUCCESS 0 115 #define SCMI_E_NOT_SUPPORTED -1 116 #define SCMI_E_INVALID_PARAM -2 117 #define SCMI_E_DENIED -3 118 #define SCMI_E_NOT_FOUND -4 119 #define SCMI_E_OUT_OF_RANGE -5 120 #define SCMI_E_BUSY -6 121 122 /* 123 * SCMI driver platform information. The details of the doorbell mechanism 124 * can be found in the SCMI specification. 125 */ 126 typedef struct scmi_channel_plat_info { 127 /* SCMI mailbox memory */ 128 uintptr_t scmi_mbx_mem; 129 /* The door bell register address */ 130 uintptr_t db_reg_addr; 131 /* The bit mask that need to be preserved when ringing doorbell */ 132 uint32_t db_preserve_mask; 133 /* The bit mask that need to be set to ring doorbell */ 134 uint32_t db_modify_mask; 135 /* The handler for ringing doorbell */ 136 void (*ring_doorbell)(struct scmi_channel_plat_info *plat_info); 137 /* cookie is unused now. But added for future enhancements. */ 138 void *cookie; 139 /* Delay in micro-seconds while polling the channel status. */ 140 uint32_t delay; 141 } scmi_channel_plat_info_t; 142 143 144 #if HW_ASSISTED_COHERENCY 145 typedef spinlock_t scmi_lock_t; 146 #else 147 typedef bakery_lock_t scmi_lock_t; 148 #endif 149 150 /* 151 * Structure to represent an SCMI channel. 152 */ 153 typedef struct scmi_channel { 154 scmi_channel_plat_info_t *info; 155 /* The lock for channel access */ 156 scmi_lock_t *lock; 157 /* Indicate whether the channel is initialized */ 158 int is_initialized; 159 } scmi_channel_t; 160 161 /* External Common API */ 162 void *scmi_init(scmi_channel_t *ch); 163 int scmi_proto_msg_attr(void *p, uint32_t proto_id, uint32_t command_id, 164 uint32_t *attr); 165 int scmi_proto_version(void *p, uint32_t proto_id, uint32_t *version); 166 167 /* 168 * Base protocol commands. Refer to the SCMI specification for more 169 * details on these commands. 170 */ 171 int scmi_base_protocol_attributes(void *p, uint32_t *num_protocols, uint32_t *num_agents); 172 int scmi_base_discover_agent(void *p, uint32_t agent_id, uint32_t *agent_id_resp, char *name); 173 int scmi_base_reset_agent_config(void *p, uint32_t agent_id, uint32_t flags); 174 175 /* 176 * Power domain protocol commands. Refer to the SCMI specification for more 177 * details on these commands. 178 */ 179 int scmi_pwr_state_set(void *p, uint32_t domain_id, uint32_t scmi_pwr_state); 180 int scmi_pwr_state_get(void *p, uint32_t domain_id, uint32_t *scmi_pwr_state); 181 182 /* 183 * System power management protocol commands. Refer SCMI specification for more 184 * details on these commands. 185 */ 186 int scmi_sys_pwr_state_set(void *p, uint32_t flags, uint32_t system_state); 187 int scmi_sys_pwr_state_get(void *p, uint32_t *system_state); 188 189 /* SCMI AP core configuration protocol commands. */ 190 int scmi_ap_core_set_reset_addr(void *p, uint64_t reset_addr, uint32_t attr); 191 int scmi_ap_core_get_reset_addr(void *p, uint64_t *reset_addr, uint32_t *attr); 192 193 /* API to get the platform specific SCMI channel information. */ 194 scmi_channel_plat_info_t *plat_css_get_scmi_info(unsigned int channel_id); 195 196 /* API to override default PSCI callbacks for platforms that support SCMI. */ 197 const plat_psci_ops_t *css_scmi_override_pm_ops(plat_psci_ops_t *ops); 198 199 #endif /* SCMI_H */ 200