1 /* 2 * Texas Instruments System Control Interface Protocol 3 * 4 * Copyright (C) 2015-2016 Texas Instruments Incorporated - http://www.ti.com/ 5 * Nishanth Menon 6 * 7 * This program is free software; you can redistribute it and/or modify 8 * it under the terms of the GNU General Public License version 2 as 9 * published by the Free Software Foundation. 10 * 11 * This program is distributed "as is" WITHOUT ANY WARRANTY of any 12 * kind, whether express or implied; without even the implied warranty 13 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 */ 16 17 #ifndef __TISCI_PROTOCOL_H 18 #define __TISCI_PROTOCOL_H 19 20 /** 21 * struct ti_sci_version_info - version information structure 22 * @abi_major: Major ABI version. Change here implies risk of backward 23 * compatibility break. 24 * @abi_minor: Minor ABI version. Change here implies new feature addition, 25 * or compatible change in ABI. 26 * @firmware_revision: Firmware revision (not usually used). 27 * @firmware_description: Firmware description (not usually used). 28 */ 29 struct ti_sci_version_info { 30 u8 abi_major; 31 u8 abi_minor; 32 u16 firmware_revision; 33 char firmware_description[32]; 34 }; 35 36 struct ti_sci_handle; 37 38 /** 39 * struct ti_sci_core_ops - SoC Core Operations 40 * @reboot_device: Reboot the SoC 41 * Returns 0 for successful request(ideally should never return), 42 * else returns corresponding error value. 43 */ 44 struct ti_sci_core_ops { 45 int (*reboot_device)(const struct ti_sci_handle *handle); 46 }; 47 48 /** 49 * struct ti_sci_dev_ops - Device control operations 50 * @get_device: Command to request for device managed by TISCI 51 * Returns 0 for successful exclusive request, else returns 52 * corresponding error message. 53 * @idle_device: Command to idle a device managed by TISCI 54 * Returns 0 for successful exclusive request, else returns 55 * corresponding error message. 56 * @put_device: Command to release a device managed by TISCI 57 * Returns 0 for successful release, else returns corresponding 58 * error message. 59 * @is_valid: Check if the device ID is a valid ID. 60 * Returns 0 if the ID is valid, else returns corresponding error. 61 * @get_context_loss_count: Command to retrieve context loss counter - this 62 * increments every time the device looses context. Overflow 63 * is possible. 64 * - count: pointer to u32 which will retrieve counter 65 * Returns 0 for successful information request and count has 66 * proper data, else returns corresponding error message. 67 * @is_idle: Reports back about device idle state 68 * - req_state: Returns requested idle state 69 * Returns 0 for successful information request and req_state and 70 * current_state has proper data, else returns corresponding error 71 * message. 72 * @is_stop: Reports back about device stop state 73 * - req_state: Returns requested stop state 74 * - current_state: Returns current stop state 75 * Returns 0 for successful information request and req_state and 76 * current_state has proper data, else returns corresponding error 77 * message. 78 * @is_on: Reports back about device ON(or active) state 79 * - req_state: Returns requested ON state 80 * - current_state: Returns current ON state 81 * Returns 0 for successful information request and req_state and 82 * current_state has proper data, else returns corresponding error 83 * message. 84 * @is_transitioning: Reports back if the device is in the middle of transition 85 * of state. 86 * -current_state: Returns 'true' if currently transitioning. 87 * @set_device_resets: Command to configure resets for device managed by TISCI. 88 * -reset_state: Device specific reset bit field 89 * Returns 0 for successful request, else returns 90 * corresponding error message. 91 * @get_device_resets: Command to read state of resets for device managed 92 * by TISCI. 93 * -reset_state: pointer to u32 which will retrieve resets 94 * Returns 0 for successful request, else returns 95 * corresponding error message. 96 * 97 * NOTE: for all these functions, the following parameters are generic in 98 * nature: 99 * -handle: Pointer to TISCI handle as retrieved by *ti_sci_get_handle 100 * -id: Device Identifier 101 * 102 * Request for the device - NOTE: the client MUST maintain integrity of 103 * usage count by balancing get_device with put_device. No refcounting is 104 * managed by driver for that purpose. 105 */ 106 struct ti_sci_dev_ops { 107 int (*get_device)(const struct ti_sci_handle *handle, u32 id); 108 int (*idle_device)(const struct ti_sci_handle *handle, u32 id); 109 int (*put_device)(const struct ti_sci_handle *handle, u32 id); 110 int (*is_valid)(const struct ti_sci_handle *handle, u32 id); 111 int (*get_context_loss_count)(const struct ti_sci_handle *handle, 112 u32 id, u32 *count); 113 int (*is_idle)(const struct ti_sci_handle *handle, u32 id, 114 bool *requested_state); 115 int (*is_stop)(const struct ti_sci_handle *handle, u32 id, 116 bool *req_state, bool *current_state); 117 int (*is_on)(const struct ti_sci_handle *handle, u32 id, 118 bool *req_state, bool *current_state); 119 int (*is_transitioning)(const struct ti_sci_handle *handle, u32 id, 120 bool *current_state); 121 int (*set_device_resets)(const struct ti_sci_handle *handle, u32 id, 122 u32 reset_state); 123 int (*get_device_resets)(const struct ti_sci_handle *handle, u32 id, 124 u32 *reset_state); 125 }; 126 127 /** 128 * struct ti_sci_clk_ops - Clock control operations 129 * @get_clock: Request for activation of clock and manage by processor 130 * - needs_ssc: 'true' if Spread Spectrum clock is desired. 131 * - can_change_freq: 'true' if frequency change is desired. 132 * - enable_input_term: 'true' if input termination is desired. 133 * @idle_clock: Request for Idling a clock managed by processor 134 * @put_clock: Release the clock to be auto managed by TISCI 135 * @is_auto: Is the clock being auto managed 136 * - req_state: state indicating if the clock is auto managed 137 * @is_on: Is the clock ON 138 * - req_state: if the clock is requested to be forced ON 139 * - current_state: if the clock is currently ON 140 * @is_off: Is the clock OFF 141 * - req_state: if the clock is requested to be forced OFF 142 * - current_state: if the clock is currently Gated 143 * @set_parent: Set the clock source of a specific device clock 144 * - parent_id: Parent clock identifier to set. 145 * @get_parent: Get the current clock source of a specific device clock 146 * - parent_id: Parent clock identifier which is the parent. 147 * @get_num_parents: Get the number of parents of the current clock source 148 * - num_parents: returns the number of parent clocks. 149 * @get_best_match_freq: Find a best matching frequency for a frequency 150 * range. 151 * - match_freq: Best matching frequency in Hz. 152 * @set_freq: Set the Clock frequency 153 * @get_freq: Get the Clock frequency 154 * - current_freq: Frequency in Hz that the clock is at. 155 * 156 * NOTE: for all these functions, the following parameters are generic in 157 * nature: 158 * -handle: Pointer to TISCI handle as retrieved by *ti_sci_get_handle 159 * -did: Device identifier this request is for 160 * -cid: Clock identifier for the device for this request. 161 * Each device has it's own set of clock inputs. This indexes 162 * which clock input to modify. 163 * -min_freq: The minimum allowable frequency in Hz. This is the minimum 164 * allowable programmed frequency and does not account for clock 165 * tolerances and jitter. 166 * -target_freq: The target clock frequency in Hz. A frequency will be 167 * processed as close to this target frequency as possible. 168 * -max_freq: The maximum allowable frequency in Hz. This is the maximum 169 * allowable programmed frequency and does not account for clock 170 * tolerances and jitter. 171 * 172 * Request for the clock - NOTE: the client MUST maintain integrity of 173 * usage count by balancing get_clock with put_clock. No refcounting is 174 * managed by driver for that purpose. 175 */ 176 struct ti_sci_clk_ops { 177 int (*get_clock)(const struct ti_sci_handle *handle, u32 did, u8 cid, 178 bool needs_ssc, bool can_change_freq, 179 bool enable_input_term); 180 int (*idle_clock)(const struct ti_sci_handle *handle, u32 did, u8 cid); 181 int (*put_clock)(const struct ti_sci_handle *handle, u32 did, u8 cid); 182 int (*is_auto)(const struct ti_sci_handle *handle, u32 did, u8 cid, 183 bool *req_state); 184 int (*is_on)(const struct ti_sci_handle *handle, u32 did, u8 cid, 185 bool *req_state, bool *current_state); 186 int (*is_off)(const struct ti_sci_handle *handle, u32 did, u8 cid, 187 bool *req_state, bool *current_state); 188 int (*set_parent)(const struct ti_sci_handle *handle, u32 did, u8 cid, 189 u8 parent_id); 190 int (*get_parent)(const struct ti_sci_handle *handle, u32 did, u8 cid, 191 u8 *parent_id); 192 int (*get_num_parents)(const struct ti_sci_handle *handle, u32 did, 193 u8 cid, u8 *num_parents); 194 int (*get_best_match_freq)(const struct ti_sci_handle *handle, u32 did, 195 u8 cid, u64 min_freq, u64 target_freq, 196 u64 max_freq, u64 *match_freq); 197 int (*set_freq)(const struct ti_sci_handle *handle, u32 did, u8 cid, 198 u64 min_freq, u64 target_freq, u64 max_freq); 199 int (*get_freq)(const struct ti_sci_handle *handle, u32 did, u8 cid, 200 u64 *current_freq); 201 }; 202 203 /** 204 * struct ti_sci_ops - Function support for TI SCI 205 * @dev_ops: Device specific operations 206 * @clk_ops: Clock specific operations 207 */ 208 struct ti_sci_ops { 209 struct ti_sci_core_ops core_ops; 210 struct ti_sci_dev_ops dev_ops; 211 struct ti_sci_clk_ops clk_ops; 212 }; 213 214 /** 215 * struct ti_sci_handle - Handle returned to TI SCI clients for usage. 216 * @version: structure containing version information 217 * @ops: operations that are made available to TI SCI clients 218 */ 219 struct ti_sci_handle { 220 struct ti_sci_version_info version; 221 struct ti_sci_ops ops; 222 }; 223 224 #if IS_ENABLED(CONFIG_TI_SCI_PROTOCOL) 225 const struct ti_sci_handle *ti_sci_get_handle(struct device *dev); 226 int ti_sci_put_handle(const struct ti_sci_handle *handle); 227 const struct ti_sci_handle *devm_ti_sci_get_handle(struct device *dev); 228 229 #else /* CONFIG_TI_SCI_PROTOCOL */ 230 231 static inline const struct ti_sci_handle *ti_sci_get_handle(struct device *dev) 232 { 233 return ERR_PTR(-EINVAL); 234 } 235 236 static inline int ti_sci_put_handle(const struct ti_sci_handle *handle) 237 { 238 return -EINVAL; 239 } 240 241 static inline 242 const struct ti_sci_handle *devm_ti_sci_get_handle(struct device *dev) 243 { 244 return ERR_PTR(-EINVAL); 245 } 246 247 #endif /* CONFIG_TI_SCI_PROTOCOL */ 248 249 #endif /* __TISCI_PROTOCOL_H */ 250