1 /* 2 * Texas Instruments System Control Interface API 3 * Based on Linux and U-Boot implementation 4 * 5 * Copyright (C) 2018-2025 Texas Instruments Incorporated - https://www.ti.com/ 6 * 7 * SPDX-License-Identifier: BSD-3-Clause 8 */ 9 10 #ifndef TI_SCI_H 11 #define TI_SCI_H 12 13 #include <stdint.h> 14 #include <stdbool.h> 15 16 /** 17 * User exported structures. 18 * 19 * The structures in ti_sci_protocol.h are used by the internal drivers. 20 * These are the structures that are exported for outside use and populated 21 * by the internal drivers. 22 * 23 * struct ti_sci_msg_version - Structure containing version info 24 * 25 * @firmware_description: String describing the firmware 26 * @firmware_revision: Firmware revision 27 * @abi_major: Major version of the ABI that firmware supports 28 * @abi_minor: Minor version of the ABI that firmware supports 29 * @sub_version: Sub-version number of the firmware 30 * @patch_version: Patch-version number of the firmware. 31 */ 32 struct ti_sci_msg_version { 33 #define FIRMWARE_DESCRIPTION_LENGTH 32 34 char firmware_description[FIRMWARE_DESCRIPTION_LENGTH]; 35 uint16_t firmware_revision; 36 uint8_t abi_major; 37 uint8_t abi_minor; 38 uint8_t sub_version; 39 uint8_t patch_version; 40 }; 41 42 /** 43 * General Message 44 * 45 * ti_sci_get_revision - Get the revision of the SCI entity 46 * @version: Structure containing the version info 47 * 48 **/ 49 int ti_sci_get_revision(struct ti_sci_msg_version *version); 50 51 /** 52 * Device control operations 53 * 54 * - ti_sci_device_get - command to request for device managed by TISCI 55 * - ti_sci_device_get_exclusive - exclusively request a device 56 * - ti_sci_device_idle - Command to idle a device managed by TISCI 57 * - ti_sci_device_idle_exclusive - exclusively idle a device 58 * - ti_sci_device_put - command to release a device managed by TISCI 59 * - ti_sci_device_put_no_wait - release a device without waiting for response 60 * - ti_sci_device_is_valid - Is the device valid 61 * - ti_sci_device_get_clcnt - Get context loss counter 62 * @count: Pointer to Context Loss counter to populate 63 * - ti_sci_device_is_idle - Check if the device is requested to be idle 64 * @r_state: true if requested to be idle 65 * - ti_sci_device_is_stop - Check if the device is requested to be stopped 66 * @r_state: true if requested to be stopped 67 * @curr_state: true if currently stopped. 68 * - ti_sci_device_is_on - Check if the device is requested to be ON 69 * @r_state: true if requested to be ON 70 * @curr_state: true if currently ON and active 71 * - ti_sci_device_is_trans - Check if the device is currently transitioning 72 * @curr_state: true if currently transitioning. 73 * - ti_sci_device_set_resets - Command to set resets for 74 * device managed by TISCI 75 * @reset_state: Device specific reset bit field 76 * - ti_sci_device_get_resets - Get reset state for device managed by TISCI 77 * @reset_state: Pointer to reset state to populate 78 * 79 * NOTE: for all these functions, the following are generic in nature: 80 * @id: Device Identifier 81 * Returns 0 for successful request, else returns corresponding error message. 82 * 83 * Request for the device - NOTE: the client MUST maintain integrity of 84 * usage count by balancing get_device with put_device. No refcounting is 85 * managed by driver for that purpose. 86 */ 87 int ti_sci_device_get(uint32_t id); 88 int ti_sci_device_get_exclusive(uint32_t id); 89 int ti_sci_device_idle(uint32_t id); 90 int ti_sci_device_idle_exclusive(uint32_t id); 91 int ti_sci_device_put(uint32_t id); 92 int ti_sci_device_put_no_wait(uint32_t id); 93 int ti_sci_device_is_valid(uint32_t id); 94 int ti_sci_device_get_clcnt(uint32_t id, uint32_t *count); 95 int ti_sci_device_is_idle(uint32_t id, bool *r_state); 96 int ti_sci_device_is_stop(uint32_t id, bool *r_state, bool *curr_state); 97 int ti_sci_device_is_on(uint32_t id, bool *r_state, bool *curr_state); 98 int ti_sci_device_is_trans(uint32_t id, bool *curr_state); 99 int ti_sci_device_set_resets(uint32_t id, uint32_t reset_state); 100 int ti_sci_device_get_resets(uint32_t id, uint32_t *reset_state); 101 102 /** 103 * Clock control operations 104 * 105 * - ti_sci_clock_get - Get control of a clock from TI SCI 106 * @needs_ssc: 'true' iff Spread Spectrum clock is desired 107 * @can_change_freq: 'true' iff frequency change is desired 108 * @enable_input_term: 'true' iff input termination is desired 109 * - ti_sci_clock_idle - Idle a clock which is in our control 110 * - ti_sci_clock_put - Release a clock from our control 111 * - ti_sci_clock_is_auto - Is the clock being auto managed 112 * @req_state: state indicating if the clock is auto managed 113 * - ti_sci_clock_is_on - Is the clock ON 114 * @req_state: state indicating if the clock is managed by us and enabled 115 * @curr_state: state indicating if the clock is ready for operation 116 * - ti_sci_clock_is_off - Is the clock OFF 117 * @req_state: state indicating if the clock is managed by us and disabled 118 * @curr_state: state indicating if the clock is NOT ready for operation 119 * - ti_sci_clock_set_parent - Set the clock source of a specific device clock 120 * @parent_id: Parent clock identifier to set 121 * - ti_sci_clock_get_parent - Get current parent clock source 122 * @parent_id: Current clock parent 123 * - ti_sci_clock_get_num_parents - Get num parents of the current clk source 124 * @num_parents: Returns he number of parents to the current clock. 125 * - ti_sci_clock_get_match_freq - Find a good match for frequency 126 * @match_freq: Frequency match in Hz response. 127 * - ti_sci_clock_set_freq - Set a frequency for clock 128 * - ti_sci_clock_get_freq - Get current frequency 129 * @freq: Currently frequency in Hz 130 * 131 * NOTE: for all these functions, the following are generic in nature: 132 * @dev_id: Device identifier this request is for 133 * @clk_id: Clock identifier for the device for this request. 134 * Each device has its own set of clock inputs. This indexes 135 * which clock input to modify. 136 * @min_freq: The minimum allowable frequency in Hz. This is the minimum 137 * allowable programmed frequency and does not account for clock 138 * tolerances and jitter. 139 * @target_freq: The target clock frequency in Hz. A frequency will be 140 * processed as close to this target frequency as possible. 141 * @max_freq: The maximum allowable frequency in Hz. This is the maximum 142 * allowable programmed frequency and does not account for clock 143 * tolerances and jitter. 144 * Returns 0 for successful request, else returns corresponding error message. 145 * 146 * Request for the clock - NOTE: the client MUST maintain integrity of 147 * usage count by balancing get_clock with put_clock. No refcounting is 148 * managed by driver for that purpose. 149 */ 150 int ti_sci_clock_get(uint32_t dev_id, uint8_t clk_id, 151 bool needs_ssc, bool can_change_freq, 152 bool enable_input_term); 153 int ti_sci_clock_idle(uint32_t dev_id, uint8_t clk_id); 154 int ti_sci_clock_put(uint32_t dev_id, uint8_t clk_id); 155 int ti_sci_clock_is_auto(uint32_t dev_id, uint8_t clk_id, 156 bool *req_state); 157 int ti_sci_clock_is_on(uint32_t dev_id, uint8_t clk_id, 158 bool *req_state, bool *curr_state); 159 int ti_sci_clock_is_off(uint32_t dev_id, uint8_t clk_id, 160 bool *req_state, bool *curr_state); 161 int ti_sci_clock_set_parent(uint32_t dev_id, uint8_t clk_id, 162 uint8_t parent_id); 163 int ti_sci_clock_get_parent(uint32_t dev_id, uint8_t clk_id, 164 uint8_t *parent_id); 165 int ti_sci_clock_get_num_parents(uint32_t dev_id, uint8_t clk_id, 166 uint8_t *num_parents); 167 int ti_sci_clock_get_match_freq(uint32_t dev_id, uint8_t clk_id, 168 uint64_t min_freq, uint64_t target_freq, 169 uint64_t max_freq, uint64_t *match_freq); 170 int ti_sci_clock_set_freq(uint32_t dev_id, uint8_t clk_id, 171 uint64_t min_freq, uint64_t target_freq, 172 uint64_t max_freq); 173 int ti_sci_clock_get_freq(uint32_t dev_id, uint8_t clk_id, uint64_t *freq); 174 175 /** 176 * Core control operations 177 * 178 * - ti_sci_core_reboot() - Command to request system reset 179 * - ti_sci_query_fw_caps() - Get the FW/SoC capabilities 180 * @fw_caps: Each bit in fw_caps indicating one FW/SOC capability 181 * 182 * Return: 0 if all went well, else returns appropriate error value. 183 */ 184 int ti_sci_core_reboot(void); 185 int ti_sci_query_fw_caps(uint64_t *fw_caps); 186 187 /** 188 * Processor control operations 189 * 190 * - ti_sci_proc_request - Command to request a physical processor control 191 * - ti_sci_proc_release - Command to release a physical processor control 192 * - ti_sci_proc_handover - Command to handover a physical processor control to 193 * a host in the processor's access control list. 194 * @host_id: Host ID to get the control of the processor 195 * - ti_sci_proc_set_boot_cfg - Command to set the processor boot configuration flags 196 * @config_flags_set: Configuration flags to be set 197 * @config_flags_clear: Configuration flags to be cleared. 198 * - ti_sci_proc_set_boot_ctrl - Command to set the processor boot control flags 199 * @control_flags_set: Control flags to be set 200 * @control_flags_clear: Control flags to be cleared 201 * - ti_sci_proc_set_boot_ctrl_no_wait - Same as above without waiting for response 202 * - ti_sci_proc_auth_boot_image - Command to authenticate and load the image 203 * and then set the processor configuration flags. 204 * @cert_addr: Memory address at which payload image certificate is located. 205 * - ti_sci_proc_get_boot_status - Command to get the processor boot status 206 * - ti_sci_proc_wait_boot_status - Command to wait for a processor boot status 207 * - ti_sci_proc_wait_boot_status_no_wait - Same as above without waiting for response 208 * 209 * NOTE: for all these functions, the following are generic in nature: 210 * @proc_id: Processor ID 211 * Returns 0 for successful request, else returns corresponding error message. 212 */ 213 int ti_sci_proc_request(uint8_t proc_id); 214 int ti_sci_proc_release(uint8_t proc_id); 215 int ti_sci_proc_handover(uint8_t proc_id, uint8_t host_id); 216 int ti_sci_proc_set_boot_cfg(uint8_t proc_id, uint64_t bootvector, 217 uint32_t config_flags_set, 218 uint32_t config_flags_clear); 219 int ti_sci_proc_set_boot_ctrl(uint8_t proc_id, uint32_t control_flags_set, 220 uint32_t control_flags_clear); 221 int ti_sci_proc_set_boot_ctrl_no_wait(uint8_t proc_id, 222 uint32_t control_flags_set, 223 uint32_t control_flags_clear); 224 int ti_sci_proc_auth_boot_image(uint8_t proc_id, uint64_t cert_addr); 225 int ti_sci_proc_get_boot_status(uint8_t proc_id, uint64_t *bv, 226 uint32_t *cfg_flags, 227 uint32_t *ctrl_flags, 228 uint32_t *sts_flags); 229 int ti_sci_proc_wait_boot_status(uint8_t proc_id, uint8_t num_wait_iterations, 230 uint8_t num_match_iterations, 231 uint8_t delay_per_iteration_us, 232 uint8_t delay_before_iterations_us, 233 uint32_t status_flags_1_set_all_wait, 234 uint32_t status_flags_1_set_any_wait, 235 uint32_t status_flags_1_clr_all_wait, 236 uint32_t status_flags_1_clr_any_wait); 237 int ti_sci_proc_wait_boot_status_no_wait(uint8_t proc_id, 238 uint8_t num_wait_iterations, 239 uint8_t num_match_iterations, 240 uint8_t delay_per_iteration_us, 241 uint8_t delay_before_iterations_us, 242 uint32_t status_flags_1_set_all_wait, 243 uint32_t status_flags_1_set_any_wait, 244 uint32_t status_flags_1_clr_all_wait, 245 uint32_t status_flags_1_clr_any_wait); 246 247 /** 248 * System Low Power Operations 249 * 250 * - ti_sci_enter_sleep - Command to initiate system transition into suspend. 251 * @proc_id: Processor ID. 252 * @mode: Low power mode to enter. 253 * @core_resume_addr: Address that core should be resumed from 254 * after low power transition. 255 * - ti_sci_lpm_get_next_sys_mode - Get next LPM system mode 256 * 257 * @next_mode: pointer to a variable that will store the next mode 258 * 259 * Return: 0 if all goes well, else appropriate error message 260 * 261 * NOTE: for all these functions, the following are generic in nature: 262 * Returns 0 for successful request, else returns corresponding error message. 263 */ 264 int ti_sci_enter_sleep(uint8_t proc_id, 265 uint8_t mode, 266 uint64_t core_resume_addr); 267 int ti_sci_lpm_get_next_sys_mode(uint8_t *next_mode); 268 269 #endif /* TI_SCI_H */ 270