1 // SPDX-License-Identifier: BSD-3-Clause 2 /* 3 * Texas Instruments System Control Interface (TISCI) Protocol 4 * 5 * Communication protocol with TI SCI hardware 6 * The system works in a message response protocol 7 * See: http://processors.wiki.ti.com/index.php/TISCI for details 8 * 9 * Copyright (C) 2015-2016 Texas Instruments Incorporated - http://www.ti.com/ 10 */ 11 12 #ifndef __TI_SCI_H 13 #define __TI_SCI_H 14 15 /* Generic Messages */ 16 #define TI_SCI_MSG_ENABLE_WDT 0x0000 17 #define TI_SCI_MSG_WAKE_RESET 0x0001 18 #define TI_SCI_MSG_VERSION 0x0002 19 #define TI_SCI_MSG_WAKE_REASON 0x0003 20 #define TI_SCI_MSG_GOODBYE 0x0004 21 #define TI_SCI_MSG_SYS_RESET 0x0005 22 23 /* Device requests */ 24 #define TI_SCI_MSG_SET_DEVICE_STATE 0x0200 25 #define TI_SCI_MSG_GET_DEVICE_STATE 0x0201 26 #define TI_SCI_MSG_SET_DEVICE_RESETS 0x0202 27 28 /* Clock requests */ 29 #define TI_SCI_MSG_SET_CLOCK_STATE 0x0100 30 #define TI_SCI_MSG_GET_CLOCK_STATE 0x0101 31 #define TI_SCI_MSG_SET_CLOCK_PARENT 0x0102 32 #define TI_SCI_MSG_GET_CLOCK_PARENT 0x0103 33 #define TI_SCI_MSG_GET_NUM_CLOCK_PARENTS 0x0104 34 #define TI_SCI_MSG_SET_CLOCK_FREQ 0x010c 35 #define TI_SCI_MSG_QUERY_CLOCK_FREQ 0x010d 36 #define TI_SCI_MSG_GET_CLOCK_FREQ 0x010e 37 38 /** 39 * struct ti_sci_msg_hdr - Generic Message Header for All messages and responses 40 * @type: Type of messages: One of TI_SCI_MSG* values 41 * @host: Host of the message 42 * @seq: Message identifier indicating a transfer sequence 43 * @flags: Flag for the message 44 */ 45 struct ti_sci_msg_hdr { 46 u16 type; 47 u8 host; 48 u8 seq; 49 #define TI_SCI_MSG_FLAG(val) (1 << (val)) 50 #define TI_SCI_FLAG_REQ_GENERIC_NORESPONSE 0x0 51 #define TI_SCI_FLAG_REQ_ACK_ON_RECEIVED TI_SCI_MSG_FLAG(0) 52 #define TI_SCI_FLAG_REQ_ACK_ON_PROCESSED TI_SCI_MSG_FLAG(1) 53 #define TI_SCI_FLAG_RESP_GENERIC_NACK 0x0 54 #define TI_SCI_FLAG_RESP_GENERIC_ACK TI_SCI_MSG_FLAG(1) 55 /* Additional Flags */ 56 u32 flags; 57 } __packed; 58 59 /** 60 * struct ti_sci_msg_resp_version - Response for a message 61 * @hdr: Generic header 62 * @firmware_description: String describing the firmware 63 * @firmware_revision: Firmware revision 64 * @abi_major: Major version of the ABI that firmware supports 65 * @abi_minor: Minor version of the ABI that firmware supports 66 * 67 * In general, ABI version changes follow the rule that minor version increments 68 * are backward compatible. Major revision changes in ABI may not be 69 * backward compatible. 70 * 71 * Response to a generic message with message type TI_SCI_MSG_VERSION 72 */ 73 struct ti_sci_msg_resp_version { 74 struct ti_sci_msg_hdr hdr; 75 char firmware_description[32]; 76 u16 firmware_revision; 77 u8 abi_major; 78 u8 abi_minor; 79 } __packed; 80 81 /** 82 * struct ti_sci_msg_req_reboot - Reboot the SoC 83 * @hdr: Generic Header 84 * 85 * Request type is TI_SCI_MSG_SYS_RESET, responded with a generic 86 * ACK/NACK message. 87 */ 88 struct ti_sci_msg_req_reboot { 89 struct ti_sci_msg_hdr hdr; 90 } __packed; 91 92 /** 93 * struct ti_sci_msg_req_set_device_state - Set the desired state of the device 94 * @hdr: Generic header 95 * @id: Indicates which device to modify 96 * @reserved: Reserved space in message, must be 0 for backward compatibility 97 * @state: The desired state of the device. 98 * 99 * Certain flags can also be set to alter the device state: 100 * + MSG_FLAG_DEVICE_WAKE_ENABLED - Configure the device to be a wake source. 101 * The meaning of this flag will vary slightly from device to device and from 102 * SoC to SoC but it generally allows the device to wake the SoC out of deep 103 * suspend states. 104 * + MSG_FLAG_DEVICE_RESET_ISO - Enable reset isolation for this device. 105 * + MSG_FLAG_DEVICE_EXCLUSIVE - Claim this device exclusively. When passed 106 * with STATE_RETENTION or STATE_ON, it will claim the device exclusively. 107 * If another host already has this device set to STATE_RETENTION or STATE_ON, 108 * the message will fail. Once successful, other hosts attempting to set 109 * STATE_RETENTION or STATE_ON will fail. 110 * 111 * Request type is TI_SCI_MSG_SET_DEVICE_STATE, responded with a generic 112 * ACK/NACK message. 113 */ 114 struct ti_sci_msg_req_set_device_state { 115 /* Additional hdr->flags options */ 116 #define MSG_FLAG_DEVICE_WAKE_ENABLED TI_SCI_MSG_FLAG(8) 117 #define MSG_FLAG_DEVICE_RESET_ISO TI_SCI_MSG_FLAG(9) 118 #define MSG_FLAG_DEVICE_EXCLUSIVE TI_SCI_MSG_FLAG(10) 119 struct ti_sci_msg_hdr hdr; 120 u32 id; 121 u32 reserved; 122 123 #define MSG_DEVICE_SW_STATE_AUTO_OFF 0 124 #define MSG_DEVICE_SW_STATE_RETENTION 1 125 #define MSG_DEVICE_SW_STATE_ON 2 126 u8 state; 127 } __packed; 128 129 /** 130 * struct ti_sci_msg_req_get_device_state - Request to get device. 131 * @hdr: Generic header 132 * @id: Device Identifier 133 * 134 * Request type is TI_SCI_MSG_GET_DEVICE_STATE, responded device state 135 * information 136 */ 137 struct ti_sci_msg_req_get_device_state { 138 struct ti_sci_msg_hdr hdr; 139 u32 id; 140 } __packed; 141 142 /** 143 * struct ti_sci_msg_resp_get_device_state - Response to get device request. 144 * @hdr: Generic header 145 * @context_loss_count: Indicates how many times the device has lost context. A 146 * driver can use this monotonic counter to determine if the device has 147 * lost context since the last time this message was exchanged. 148 * @resets: Programmed state of the reset lines. 149 * @programmed_state: The state as programmed by set_device. 150 * - Uses the MSG_DEVICE_SW_* macros 151 * @current_state: The actual state of the hardware. 152 * 153 * Response to request TI_SCI_MSG_GET_DEVICE_STATE. 154 */ 155 struct ti_sci_msg_resp_get_device_state { 156 struct ti_sci_msg_hdr hdr; 157 u32 context_loss_count; 158 u32 resets; 159 u8 programmed_state; 160 #define MSG_DEVICE_HW_STATE_OFF 0 161 #define MSG_DEVICE_HW_STATE_ON 1 162 #define MSG_DEVICE_HW_STATE_TRANS 2 163 u8 current_state; 164 } __packed; 165 166 /** 167 * struct ti_sci_msg_req_set_device_resets - Set the desired resets 168 * configuration of the device 169 * @hdr: Generic header 170 * @id: Indicates which device to modify 171 * @resets: A bit field of resets for the device. The meaning, behavior, 172 * and usage of the reset flags are device specific. 0 for a bit 173 * indicates releasing the reset represented by that bit while 1 174 * indicates keeping it held. 175 * 176 * Request type is TI_SCI_MSG_SET_DEVICE_RESETS, responded with a generic 177 * ACK/NACK message. 178 */ 179 struct ti_sci_msg_req_set_device_resets { 180 struct ti_sci_msg_hdr hdr; 181 u32 id; 182 u32 resets; 183 } __packed; 184 185 /** 186 * struct ti_sci_msg_req_set_clock_state - Request to setup a Clock state 187 * @hdr: Generic Header, Certain flags can be set specific to the clocks: 188 * MSG_FLAG_CLOCK_ALLOW_SSC: Allow this clock to be modified 189 * via spread spectrum clocking. 190 * MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE: Allow this clock's 191 * frequency to be changed while it is running so long as it 192 * is within the min/max limits. 193 * MSG_FLAG_CLOCK_INPUT_TERM: Enable input termination, this 194 * is only applicable to clock inputs on the SoC pseudo-device. 195 * @dev_id: Device identifier this request is for 196 * @clk_id: Clock identifier for the device for this request. 197 * Each device has it's own set of clock inputs. This indexes 198 * which clock input to modify. 199 * @request_state: Request the state for the clock to be set to. 200 * MSG_CLOCK_SW_STATE_UNREQ: The IP does not require this clock, 201 * it can be disabled, regardless of the state of the device 202 * MSG_CLOCK_SW_STATE_AUTO: Allow the System Controller to 203 * automatically manage the state of this clock. If the device 204 * is enabled, then the clock is enabled. If the device is set 205 * to off or retention, then the clock is internally set as not 206 * being required by the device.(default) 207 * MSG_CLOCK_SW_STATE_REQ: Configure the clock to be enabled, 208 * regardless of the state of the device. 209 * 210 * Normally, all required clocks are managed by TISCI entity, this is used 211 * only for specific control *IF* required. Auto managed state is 212 * MSG_CLOCK_SW_STATE_AUTO, in other states, TISCI entity assume remote 213 * will explicitly control. 214 * 215 * Request type is TI_SCI_MSG_SET_CLOCK_STATE, response is a generic 216 * ACK or NACK message. 217 */ 218 struct ti_sci_msg_req_set_clock_state { 219 /* Additional hdr->flags options */ 220 #define MSG_FLAG_CLOCK_ALLOW_SSC TI_SCI_MSG_FLAG(8) 221 #define MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE TI_SCI_MSG_FLAG(9) 222 #define MSG_FLAG_CLOCK_INPUT_TERM TI_SCI_MSG_FLAG(10) 223 struct ti_sci_msg_hdr hdr; 224 u32 dev_id; 225 u8 clk_id; 226 #define MSG_CLOCK_SW_STATE_UNREQ 0 227 #define MSG_CLOCK_SW_STATE_AUTO 1 228 #define MSG_CLOCK_SW_STATE_REQ 2 229 u8 request_state; 230 } __packed; 231 232 /** 233 * struct ti_sci_msg_req_get_clock_state - Request for clock state 234 * @hdr: Generic Header 235 * @dev_id: Device identifier this request is for 236 * @clk_id: Clock identifier for the device for this request. 237 * Each device has it's own set of clock inputs. This indexes 238 * which clock input to get state of. 239 * 240 * Request type is TI_SCI_MSG_GET_CLOCK_STATE, response is state 241 * of the clock 242 */ 243 struct ti_sci_msg_req_get_clock_state { 244 struct ti_sci_msg_hdr hdr; 245 u32 dev_id; 246 u8 clk_id; 247 } __packed; 248 249 /** 250 * struct ti_sci_msg_resp_get_clock_state - Response to get clock state 251 * @hdr: Generic Header 252 * @programmed_state: Any programmed state of the clock. This is one of 253 * MSG_CLOCK_SW_STATE* values. 254 * @current_state: Current state of the clock. This is one of: 255 * MSG_CLOCK_HW_STATE_NOT_READY: Clock is not ready 256 * MSG_CLOCK_HW_STATE_READY: Clock is ready 257 * 258 * Response to TI_SCI_MSG_GET_CLOCK_STATE. 259 */ 260 struct ti_sci_msg_resp_get_clock_state { 261 struct ti_sci_msg_hdr hdr; 262 u8 programmed_state; 263 #define MSG_CLOCK_HW_STATE_NOT_READY 0 264 #define MSG_CLOCK_HW_STATE_READY 1 265 u8 current_state; 266 } __packed; 267 268 /** 269 * struct ti_sci_msg_req_set_clock_parent - Set the clock parent 270 * @hdr: Generic Header 271 * @dev_id: Device identifier this request is for 272 * @clk_id: Clock identifier for the device for this request. 273 * Each device has it's own set of clock inputs. This indexes 274 * which clock input to modify. 275 * @parent_id: The new clock parent is selectable by an index via this 276 * parameter. 277 * 278 * Request type is TI_SCI_MSG_SET_CLOCK_PARENT, response is generic 279 * ACK / NACK message. 280 */ 281 struct ti_sci_msg_req_set_clock_parent { 282 struct ti_sci_msg_hdr hdr; 283 u32 dev_id; 284 u8 clk_id; 285 u8 parent_id; 286 } __packed; 287 288 /** 289 * struct ti_sci_msg_req_get_clock_parent - Get the clock parent 290 * @hdr: Generic Header 291 * @dev_id: Device identifier this request is for 292 * @clk_id: Clock identifier for the device for this request. 293 * Each device has it's own set of clock inputs. This indexes 294 * which clock input to get the parent for. 295 * 296 * Request type is TI_SCI_MSG_GET_CLOCK_PARENT, response is parent information 297 */ 298 struct ti_sci_msg_req_get_clock_parent { 299 struct ti_sci_msg_hdr hdr; 300 u32 dev_id; 301 u8 clk_id; 302 } __packed; 303 304 /** 305 * struct ti_sci_msg_resp_get_clock_parent - Response with clock parent 306 * @hdr: Generic Header 307 * @parent_id: The current clock parent 308 * 309 * Response to TI_SCI_MSG_GET_CLOCK_PARENT. 310 */ 311 struct ti_sci_msg_resp_get_clock_parent { 312 struct ti_sci_msg_hdr hdr; 313 u8 parent_id; 314 } __packed; 315 316 /** 317 * struct ti_sci_msg_req_get_clock_num_parents - Request to get clock parents 318 * @hdr: Generic header 319 * @dev_id: Device identifier this request is for 320 * @clk_id: Clock identifier for the device for this request. 321 * 322 * This request provides information about how many clock parent options 323 * are available for a given clock to a device. This is typically used 324 * for input clocks. 325 * 326 * Request type is TI_SCI_MSG_GET_NUM_CLOCK_PARENTS, response is appropriate 327 * message, or NACK in case of inability to satisfy request. 328 */ 329 struct ti_sci_msg_req_get_clock_num_parents { 330 struct ti_sci_msg_hdr hdr; 331 u32 dev_id; 332 u8 clk_id; 333 } __packed; 334 335 /** 336 * struct ti_sci_msg_resp_get_clock_num_parents - Response for get clk parents 337 * @hdr: Generic header 338 * @num_parents: Number of clock parents 339 * 340 * Response to TI_SCI_MSG_GET_NUM_CLOCK_PARENTS 341 */ 342 struct ti_sci_msg_resp_get_clock_num_parents { 343 struct ti_sci_msg_hdr hdr; 344 u8 num_parents; 345 } __packed; 346 347 /** 348 * struct ti_sci_msg_req_query_clock_freq - Request to query a frequency 349 * @hdr: Generic Header 350 * @dev_id: Device identifier this request is for 351 * @min_freq_hz: The minimum allowable frequency in Hz. This is the minimum 352 * allowable programmed frequency and does not account for clock 353 * tolerances and jitter. 354 * @target_freq_hz: The target clock frequency. A frequency will be found 355 * as close to this target frequency as possible. 356 * @max_freq_hz: The maximum allowable frequency in Hz. This is the maximum 357 * allowable programmed frequency and does not account for clock 358 * tolerances and jitter. 359 * @clk_id: Clock identifier for the device for this request. 360 * 361 * NOTE: Normally clock frequency management is automatically done by TISCI 362 * entity. In case of specific requests, TISCI evaluates capability to achieve 363 * requested frequency within provided range and responds with 364 * result message. 365 * 366 * Request type is TI_SCI_MSG_QUERY_CLOCK_FREQ, response is appropriate message, 367 * or NACK in case of inability to satisfy request. 368 */ 369 struct ti_sci_msg_req_query_clock_freq { 370 struct ti_sci_msg_hdr hdr; 371 u32 dev_id; 372 u64 min_freq_hz; 373 u64 target_freq_hz; 374 u64 max_freq_hz; 375 u8 clk_id; 376 } __packed; 377 378 /** 379 * struct ti_sci_msg_resp_query_clock_freq - Response to a clock frequency query 380 * @hdr: Generic Header 381 * @freq_hz: Frequency that is the best match in Hz. 382 * 383 * Response to request type TI_SCI_MSG_QUERY_CLOCK_FREQ. NOTE: if the request 384 * cannot be satisfied, the message will be of type NACK. 385 */ 386 struct ti_sci_msg_resp_query_clock_freq { 387 struct ti_sci_msg_hdr hdr; 388 u64 freq_hz; 389 } __packed; 390 391 /** 392 * struct ti_sci_msg_req_set_clock_freq - Request to setup a clock frequency 393 * @hdr: Generic Header 394 * @dev_id: Device identifier this request is for 395 * @min_freq_hz: The minimum allowable frequency in Hz. This is the minimum 396 * allowable programmed frequency and does not account for clock 397 * tolerances and jitter. 398 * @target_freq_hz: The target clock frequency. The clock will be programmed 399 * at a rate as close to this target frequency as possible. 400 * @max_freq_hz: The maximum allowable frequency in Hz. This is the maximum 401 * allowable programmed frequency and does not account for clock 402 * tolerances and jitter. 403 * @clk_id: Clock identifier for the device for this request. 404 * 405 * NOTE: Normally clock frequency management is automatically done by TISCI 406 * entity. In case of specific requests, TISCI evaluates capability to achieve 407 * requested range and responds with success/failure message. 408 * 409 * This sets the desired frequency for a clock within an allowable 410 * range. This message will fail on an enabled clock unless 411 * MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE is set for the clock. Additionally, 412 * if other clocks have their frequency modified due to this message, 413 * they also must have the MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE or be disabled. 414 * 415 * Calling set frequency on a clock input to the SoC pseudo-device will 416 * inform the PMMC of that clock's frequency. Setting a frequency of 417 * zero will indicate the clock is disabled. 418 * 419 * Calling set frequency on clock outputs from the SoC pseudo-device will 420 * function similarly to setting the clock frequency on a device. 421 * 422 * Request type is TI_SCI_MSG_SET_CLOCK_FREQ, response is a generic ACK/NACK 423 * message. 424 */ 425 struct ti_sci_msg_req_set_clock_freq { 426 struct ti_sci_msg_hdr hdr; 427 u32 dev_id; 428 u64 min_freq_hz; 429 u64 target_freq_hz; 430 u64 max_freq_hz; 431 u8 clk_id; 432 } __packed; 433 434 /** 435 * struct ti_sci_msg_req_get_clock_freq - Request to get the clock frequency 436 * @hdr: Generic Header 437 * @dev_id: Device identifier this request is for 438 * @clk_id: Clock identifier for the device for this request. 439 * 440 * NOTE: Normally clock frequency management is automatically done by TISCI 441 * entity. In some cases, clock frequencies are configured by host. 442 * 443 * Request type is TI_SCI_MSG_GET_CLOCK_FREQ, responded with clock frequency 444 * that the clock is currently at. 445 */ 446 struct ti_sci_msg_req_get_clock_freq { 447 struct ti_sci_msg_hdr hdr; 448 u32 dev_id; 449 u8 clk_id; 450 } __packed; 451 452 /** 453 * struct ti_sci_msg_resp_get_clock_freq - Response of clock frequency request 454 * @hdr: Generic Header 455 * @freq_hz: Frequency that the clock is currently on, in Hz. 456 * 457 * Response to request type TI_SCI_MSG_GET_CLOCK_FREQ. 458 */ 459 struct ti_sci_msg_resp_get_clock_freq { 460 struct ti_sci_msg_hdr hdr; 461 u64 freq_hz; 462 } __packed; 463 464 #endif /* __TI_SCI_H */ 465