Andrew F. Davis | a513b2a | 2018-05-04 19:06:09 +0000 | [diff] [blame] | 1 | /* |
| 2 | * Texas Instruments System Control Interface API |
| 3 | * Based on Linux and U-Boot implementation |
| 4 | * |
Manorit Chawdhry | 7660cb5 | 2024-01-29 12:40:54 +0530 | [diff] [blame] | 5 | * Copyright (C) 2018-2024 Texas Instruments Incorporated - https://www.ti.com/ |
Andrew F. Davis | a513b2a | 2018-05-04 19:06:09 +0000 | [diff] [blame] | 6 | * |
| 7 | * SPDX-License-Identifier: BSD-3-Clause |
| 8 | */ |
| 9 | |
Antonio Nino Diaz | 5eb8837 | 2018-11-08 10:20:19 +0000 | [diff] [blame] | 10 | #ifndef TI_SCI_H |
| 11 | #define TI_SCI_H |
Andrew F. Davis | a513b2a | 2018-05-04 19:06:09 +0000 | [diff] [blame] | 12 | |
Andrew F. Davis | 4f2a055 | 2018-05-04 19:06:10 +0000 | [diff] [blame] | 13 | #include <stdint.h> |
| 14 | #include <stdbool.h> |
| 15 | |
| 16 | /** |
Manorit Chawdhry | 7660cb5 | 2024-01-29 12:40:54 +0530 | [diff] [blame] | 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 | /** |
Andrew F. Davis | 4f2a055 | 2018-05-04 19:06:10 +0000 | [diff] [blame] | 52 | * Device control operations |
| 53 | * |
Andrew F. Davis | 4f2a055 | 2018-05-04 19:06:10 +0000 | [diff] [blame] | 54 | * - ti_sci_device_get - command to request for device managed by TISCI |
Andrew F. Davis | fbe6c06 | 2019-02-11 12:58:32 -0600 | [diff] [blame] | 55 | * - ti_sci_device_get_exclusive - exclusively request a device |
Andrew F. Davis | 4f2a055 | 2018-05-04 19:06:10 +0000 | [diff] [blame] | 56 | * - ti_sci_device_idle - Command to idle a device managed by TISCI |
Andrew F. Davis | fbe6c06 | 2019-02-11 12:58:32 -0600 | [diff] [blame] | 57 | * - ti_sci_device_idle_exclusive - exclusively idle a device |
Andrew F. Davis | 4f2a055 | 2018-05-04 19:06:10 +0000 | [diff] [blame] | 58 | * - ti_sci_device_put - command to release a device managed by TISCI |
Andrew F. Davis | a29578d | 2019-02-11 14:18:53 -0600 | [diff] [blame] | 59 | * - ti_sci_device_put_no_wait - release a device without waiting for response |
Andrew F. Davis | 4f2a055 | 2018-05-04 19:06:10 +0000 | [diff] [blame] | 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 | */ |
Andrew F. Davis | 4f2a055 | 2018-05-04 19:06:10 +0000 | [diff] [blame] | 87 | int ti_sci_device_get(uint32_t id); |
Andrew F. Davis | fbe6c06 | 2019-02-11 12:58:32 -0600 | [diff] [blame] | 88 | int ti_sci_device_get_exclusive(uint32_t id); |
Andrew F. Davis | 4f2a055 | 2018-05-04 19:06:10 +0000 | [diff] [blame] | 89 | int ti_sci_device_idle(uint32_t id); |
Andrew F. Davis | fbe6c06 | 2019-02-11 12:58:32 -0600 | [diff] [blame] | 90 | int ti_sci_device_idle_exclusive(uint32_t id); |
Andrew F. Davis | 4f2a055 | 2018-05-04 19:06:10 +0000 | [diff] [blame] | 91 | int ti_sci_device_put(uint32_t id); |
Andrew F. Davis | a29578d | 2019-02-11 14:18:53 -0600 | [diff] [blame] | 92 | int ti_sci_device_put_no_wait(uint32_t id); |
Andrew F. Davis | 4f2a055 | 2018-05-04 19:06:10 +0000 | [diff] [blame] | 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 | |
Andrew F. Davis | a513b2a | 2018-05-04 19:06:09 +0000 | [diff] [blame] | 102 | /** |
Andrew F. Davis | dc08adf | 2018-05-04 19:06:11 +0000 | [diff] [blame] | 103 | * Clock control operations |
| 104 | * |
Andrew F. Davis | dc08adf | 2018-05-04 19:06:11 +0000 | [diff] [blame] | 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 | */ |
Andrew F. Davis | dc08adf | 2018-05-04 19:06:11 +0000 | [diff] [blame] | 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 | /** |
Andrew F. Davis | 0d44930 | 2018-05-04 19:06:12 +0000 | [diff] [blame] | 176 | * Core control operations |
| 177 | * |
| 178 | * - ti_sci_core_reboot() - Command to request system reset |
Andrew Davis | 10d67f9 | 2023-06-26 12:49:17 -0500 | [diff] [blame] | 179 | * - ti_sci_query_fw_caps() - Get the FW/SoC capabilities |
| 180 | * @fw_caps: Each bit in fw_caps indicating one FW/SOC capability |
Andrew F. Davis | 0d44930 | 2018-05-04 19:06:12 +0000 | [diff] [blame] | 181 | * |
| 182 | * Return: 0 if all went well, else returns appropriate error value. |
| 183 | */ |
| 184 | int ti_sci_core_reboot(void); |
Andrew Davis | 10d67f9 | 2023-06-26 12:49:17 -0500 | [diff] [blame] | 185 | int ti_sci_query_fw_caps(uint64_t *fw_caps); |
Andrew F. Davis | 0d44930 | 2018-05-04 19:06:12 +0000 | [diff] [blame] | 186 | |
| 187 | /** |
Andrew F. Davis | d92fdfb | 2018-05-04 19:06:13 +0000 | [diff] [blame] | 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 |
Andrew F. Davis | a29578d | 2019-02-11 14:18:53 -0600 | [diff] [blame] | 201 | * - ti_sci_proc_set_boot_ctrl_no_wait - Same as above without waiting for response |
Andrew F. Davis | d92fdfb | 2018-05-04 19:06:13 +0000 | [diff] [blame] | 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 |
Andrew F. Davis | b62cc1e | 2018-12-18 13:21:12 -0600 | [diff] [blame] | 206 | * - ti_sci_proc_wait_boot_status - Command to wait for a processor boot status |
Andrew F. Davis | a29578d | 2019-02-11 14:18:53 -0600 | [diff] [blame] | 207 | * - ti_sci_proc_wait_boot_status_no_wait - Same as above without waiting for response |
Andrew F. Davis | d92fdfb | 2018-05-04 19:06:13 +0000 | [diff] [blame] | 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); |
Andrew F. Davis | a29578d | 2019-02-11 14:18:53 -0600 | [diff] [blame] | 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); |
Andrew F. Davis | d92fdfb | 2018-05-04 19:06:13 +0000 | [diff] [blame] | 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); |
Andrew F. Davis | b62cc1e | 2018-12-18 13:21:12 -0600 | [diff] [blame] | 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); |
Andrew F. Davis | a29578d | 2019-02-11 14:18:53 -0600 | [diff] [blame] | 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); |
Andrew F. Davis | d92fdfb | 2018-05-04 19:06:13 +0000 | [diff] [blame] | 246 | |
| 247 | /** |
Dave Gerlach | 7a94ce8 | 2021-11-30 15:35:08 -0600 | [diff] [blame] | 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 | * |
| 256 | * NOTE: for all these functions, the following are generic in nature: |
| 257 | * Returns 0 for successful request, else returns corresponding error message. |
| 258 | */ |
| 259 | int ti_sci_enter_sleep(uint8_t proc_id, |
| 260 | uint8_t mode, |
| 261 | uint64_t core_resume_addr); |
| 262 | |
Antonio Nino Diaz | 5eb8837 | 2018-11-08 10:20:19 +0000 | [diff] [blame] | 263 | #endif /* TI_SCI_H */ |