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