// SPDX-License-Identifier: BSD-3-Clause /* * Texas Instruments System Control Interface (TISCI) Protocol * * Communication protocol with TI SCI hardware * The system works in a message response protocol * See: http://processors.wiki.ti.com/index.php/TISCI for details * * Copyright (C) 2015-2016 Texas Instruments Incorporated - http://www.ti.com/ */ #ifndef __TI_SCI_H #define __TI_SCI_H /* Generic Messages */ #define TI_SCI_MSG_ENABLE_WDT 0x0000 #define TI_SCI_MSG_WAKE_RESET 0x0001 #define TI_SCI_MSG_VERSION 0x0002 #define TI_SCI_MSG_WAKE_REASON 0x0003 #define TI_SCI_MSG_GOODBYE 0x0004 #define TI_SCI_MSG_SYS_RESET 0x0005 /* Device requests */ #define TI_SCI_MSG_SET_DEVICE_STATE 0x0200 #define TI_SCI_MSG_GET_DEVICE_STATE 0x0201 #define TI_SCI_MSG_SET_DEVICE_RESETS 0x0202 /* Clock requests */ #define TI_SCI_MSG_SET_CLOCK_STATE 0x0100 #define TI_SCI_MSG_GET_CLOCK_STATE 0x0101 #define TI_SCI_MSG_SET_CLOCK_PARENT 0x0102 #define TI_SCI_MSG_GET_CLOCK_PARENT 0x0103 #define TI_SCI_MSG_GET_NUM_CLOCK_PARENTS 0x0104 #define TI_SCI_MSG_SET_CLOCK_FREQ 0x010c #define TI_SCI_MSG_QUERY_CLOCK_FREQ 0x010d #define TI_SCI_MSG_GET_CLOCK_FREQ 0x010e /* Resource Management Requests */ #define TI_SCI_MSG_GET_RESOURCE_RANGE 0x1500 /* IRQ requests */ #define TI_SCI_MSG_SET_IRQ 0x1000 #define TI_SCI_MSG_FREE_IRQ 0x1001 /** * struct ti_sci_msg_hdr - Generic Message Header for All messages and responses * @type: Type of messages: One of TI_SCI_MSG* values * @host: Host of the message * @seq: Message identifier indicating a transfer sequence * @flags: Flag for the message */ struct ti_sci_msg_hdr { u16 type; u8 host; u8 seq; #define TI_SCI_MSG_FLAG(val) (1 << (val)) #define TI_SCI_FLAG_REQ_GENERIC_NORESPONSE 0x0 #define TI_SCI_FLAG_REQ_ACK_ON_RECEIVED TI_SCI_MSG_FLAG(0) #define TI_SCI_FLAG_REQ_ACK_ON_PROCESSED TI_SCI_MSG_FLAG(1) #define TI_SCI_FLAG_RESP_GENERIC_NACK 0x0 #define TI_SCI_FLAG_RESP_GENERIC_ACK TI_SCI_MSG_FLAG(1) /* Additional Flags */ u32 flags; } __packed; /** * struct ti_sci_msg_resp_version - Response for a message * @hdr: Generic header * @firmware_description: String describing the firmware * @firmware_revision: Firmware revision * @abi_major: Major version of the ABI that firmware supports * @abi_minor: Minor version of the ABI that firmware supports * * In general, ABI version changes follow the rule that minor version increments * are backward compatible. Major revision changes in ABI may not be * backward compatible. * * Response to a generic message with message type TI_SCI_MSG_VERSION */ struct ti_sci_msg_resp_version { struct ti_sci_msg_hdr hdr; char firmware_description[32]; u16 firmware_revision; u8 abi_major; u8 abi_minor; } __packed; /** * struct ti_sci_msg_req_reboot - Reboot the SoC * @hdr: Generic Header * * Request type is TI_SCI_MSG_SYS_RESET, responded with a generic * ACK/NACK message. */ struct ti_sci_msg_req_reboot { struct ti_sci_msg_hdr hdr; } __packed; /** * struct ti_sci_msg_req_set_device_state - Set the desired state of the device * @hdr: Generic header * @id: Indicates which device to modify * @reserved: Reserved space in message, must be 0 for backward compatibility * @state: The desired state of the device. * * Certain flags can also be set to alter the device state: * + MSG_FLAG_DEVICE_WAKE_ENABLED - Configure the device to be a wake source. * The meaning of this flag will vary slightly from device to device and from * SoC to SoC but it generally allows the device to wake the SoC out of deep * suspend states. * + MSG_FLAG_DEVICE_RESET_ISO - Enable reset isolation for this device. * + MSG_FLAG_DEVICE_EXCLUSIVE - Claim this device exclusively. When passed * with STATE_RETENTION or STATE_ON, it will claim the device exclusively. * If another host already has this device set to STATE_RETENTION or STATE_ON, * the message will fail. Once successful, other hosts attempting to set * STATE_RETENTION or STATE_ON will fail. * * Request type is TI_SCI_MSG_SET_DEVICE_STATE, responded with a generic * ACK/NACK message. */ struct ti_sci_msg_req_set_device_state { /* Additional hdr->flags options */ #define MSG_FLAG_DEVICE_WAKE_ENABLED TI_SCI_MSG_FLAG(8) #define MSG_FLAG_DEVICE_RESET_ISO TI_SCI_MSG_FLAG(9) #define MSG_FLAG_DEVICE_EXCLUSIVE TI_SCI_MSG_FLAG(10) struct ti_sci_msg_hdr hdr; u32 id; u32 reserved; #define MSG_DEVICE_SW_STATE_AUTO_OFF 0 #define MSG_DEVICE_SW_STATE_RETENTION 1 #define MSG_DEVICE_SW_STATE_ON 2 u8 state; } __packed; /** * struct ti_sci_msg_req_get_device_state - Request to get device. * @hdr: Generic header * @id: Device Identifier * * Request type is TI_SCI_MSG_GET_DEVICE_STATE, responded device state * information */ struct ti_sci_msg_req_get_device_state { struct ti_sci_msg_hdr hdr; u32 id; } __packed; /** * struct ti_sci_msg_resp_get_device_state - Response to get device request. * @hdr: Generic header * @context_loss_count: Indicates how many times the device has lost context. A * driver can use this monotonic counter to determine if the device has * lost context since the last time this message was exchanged. * @resets: Programmed state of the reset lines. * @programmed_state: The state as programmed by set_device. * - Uses the MSG_DEVICE_SW_* macros * @current_state: The actual state of the hardware. * * Response to request TI_SCI_MSG_GET_DEVICE_STATE. */ struct ti_sci_msg_resp_get_device_state { struct ti_sci_msg_hdr hdr; u32 context_loss_count; u32 resets; u8 programmed_state; #define MSG_DEVICE_HW_STATE_OFF 0 #define MSG_DEVICE_HW_STATE_ON 1 #define MSG_DEVICE_HW_STATE_TRANS 2 u8 current_state; } __packed; /** * struct ti_sci_msg_req_set_device_resets - Set the desired resets * configuration of the device * @hdr: Generic header * @id: Indicates which device to modify * @resets: A bit field of resets for the device. The meaning, behavior, * and usage of the reset flags are device specific. 0 for a bit * indicates releasing the reset represented by that bit while 1 * indicates keeping it held. * * Request type is TI_SCI_MSG_SET_DEVICE_RESETS, responded with a generic * ACK/NACK message. */ struct ti_sci_msg_req_set_device_resets { struct ti_sci_msg_hdr hdr; u32 id; u32 resets; } __packed; /** * struct ti_sci_msg_req_set_clock_state - Request to setup a Clock state * @hdr: Generic Header, Certain flags can be set specific to the clocks: * MSG_FLAG_CLOCK_ALLOW_SSC: Allow this clock to be modified * via spread spectrum clocking. * MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE: Allow this clock's * frequency to be changed while it is running so long as it * is within the min/max limits. * MSG_FLAG_CLOCK_INPUT_TERM: Enable input termination, this * is only applicable to clock inputs on the SoC pseudo-device. * @dev_id: Device identifier this request is for * @clk_id: Clock identifier for the device for this request. * Each device has it's own set of clock inputs. This indexes * which clock input to modify. Set to 255 if clock ID is * greater than or equal to 255. * @request_state: Request the state for the clock to be set to. * MSG_CLOCK_SW_STATE_UNREQ: The IP does not require this clock, * it can be disabled, regardless of the state of the device * MSG_CLOCK_SW_STATE_AUTO: Allow the System Controller to * automatically manage the state of this clock. If the device * is enabled, then the clock is enabled. If the device is set * to off or retention, then the clock is internally set as not * being required by the device.(default) * MSG_CLOCK_SW_STATE_REQ: Configure the clock to be enabled, * regardless of the state of the device. * @clk_id_32: Clock identifier for the device for this request. * Only to be used if the clock ID is greater than or equal to * 255. * * Normally, all required clocks are managed by TISCI entity, this is used * only for specific control *IF* required. Auto managed state is * MSG_CLOCK_SW_STATE_AUTO, in other states, TISCI entity assume remote * will explicitly control. * * Request type is TI_SCI_MSG_SET_CLOCK_STATE, response is a generic * ACK or NACK message. */ struct ti_sci_msg_req_set_clock_state { /* Additional hdr->flags options */ #define MSG_FLAG_CLOCK_ALLOW_SSC TI_SCI_MSG_FLAG(8) #define MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE TI_SCI_MSG_FLAG(9) #define MSG_FLAG_CLOCK_INPUT_TERM TI_SCI_MSG_FLAG(10) struct ti_sci_msg_hdr hdr; u32 dev_id; u8 clk_id; #define MSG_CLOCK_SW_STATE_UNREQ 0 #define MSG_CLOCK_SW_STATE_AUTO 1 #define MSG_CLOCK_SW_STATE_REQ 2 u8 request_state; u32 clk_id_32; } __packed; /** * struct ti_sci_msg_req_get_clock_state - Request for clock state * @hdr: Generic Header * @dev_id: Device identifier this request is for * @clk_id: Clock identifier for the device for this request. * Each device has it's own set of clock inputs. This indexes * which clock input to get state of. Set to 255 if the clock * ID is greater than or equal to 255. * @clk_id_32: Clock identifier for the device for the request. * Only to be used if the clock ID is greater than or equal to * 255. * * Request type is TI_SCI_MSG_GET_CLOCK_STATE, response is state * of the clock */ struct ti_sci_msg_req_get_clock_state { struct ti_sci_msg_hdr hdr; u32 dev_id; u8 clk_id; u32 clk_id_32; } __packed; /** * struct ti_sci_msg_resp_get_clock_state - Response to get clock state * @hdr: Generic Header * @programmed_state: Any programmed state of the clock. This is one of * MSG_CLOCK_SW_STATE* values. * @current_state: Current state of the clock. This is one of: * MSG_CLOCK_HW_STATE_NOT_READY: Clock is not ready * MSG_CLOCK_HW_STATE_READY: Clock is ready * * Response to TI_SCI_MSG_GET_CLOCK_STATE. */ struct ti_sci_msg_resp_get_clock_state { struct ti_sci_msg_hdr hdr; u8 programmed_state; #define MSG_CLOCK_HW_STATE_NOT_READY 0 #define MSG_CLOCK_HW_STATE_READY 1 u8 current_state; } __packed; /** * struct ti_sci_msg_req_set_clock_parent - Set the clock parent * @hdr: Generic Header * @dev_id: Device identifier this request is for * @clk_id: Clock identifier for the device for this request. * Each device has it's own set of clock inputs. This indexes * which clock input to modify. Set to 255 if clock ID is * greater than or equal to 255. * @parent_id: The new clock parent is selectable by an index via this * parameter. Set to 255 if clock ID is greater than or * equal to 255. * @clk_id_32: Clock identifier if @clk_id field is 255. * @parent_id_32: Parent identifier if @parent_id is 255. * * Request type is TI_SCI_MSG_SET_CLOCK_PARENT, response is generic * ACK / NACK message. */ struct ti_sci_msg_req_set_clock_parent { struct ti_sci_msg_hdr hdr; u32 dev_id; u8 clk_id; u8 parent_id; u32 clk_id_32; u32 parent_id_32; } __packed; /** * struct ti_sci_msg_req_get_clock_parent - Get the clock parent * @hdr: Generic Header * @dev_id: Device identifier this request is for * @clk_id: Clock identifier for the device for this request. * Each device has it's own set of clock inputs. This indexes * which clock input to get the parent for. If this field * contains 255, the actual clock identifier is stored in * @clk_id_32. * @clk_id_32: Clock identifier if the @clk_id field contains 255. * * Request type is TI_SCI_MSG_GET_CLOCK_PARENT, response is parent information */ struct ti_sci_msg_req_get_clock_parent { struct ti_sci_msg_hdr hdr; u32 dev_id; u8 clk_id; u32 clk_id_32; } __packed; /** * struct ti_sci_msg_resp_get_clock_parent - Response with clock parent * @hdr: Generic Header * @parent_id: The current clock parent. If set to 255, the current parent * ID can be found from the @parent_id_32 field. * @parent_id_32: Current clock parent if @parent_id field is set to * 255. * * Response to TI_SCI_MSG_GET_CLOCK_PARENT. */ struct ti_sci_msg_resp_get_clock_parent { struct ti_sci_msg_hdr hdr; u8 parent_id; u32 parent_id_32; } __packed; /** * struct ti_sci_msg_req_get_clock_num_parents - Request to get clock parents * @hdr: Generic header * @dev_id: Device identifier this request is for * @clk_id: Clock identifier for the device for this request. Set to * 255 if clock ID is greater than or equal to 255. * @clk_id_32: Clock identifier if the @clk_id field contains 255. * * This request provides information about how many clock parent options * are available for a given clock to a device. This is typically used * for input clocks. * * Request type is TI_SCI_MSG_GET_NUM_CLOCK_PARENTS, response is appropriate * message, or NACK in case of inability to satisfy request. */ struct ti_sci_msg_req_get_clock_num_parents { struct ti_sci_msg_hdr hdr; u32 dev_id; u8 clk_id; u32 clk_id_32; } __packed; /** * struct ti_sci_msg_resp_get_clock_num_parents - Response for get clk parents * @hdr: Generic header * @num_parents: Number of clock parents. If set to 255, the actual * number of parents is stored into @num_parents_32 * field instead. * @num_parents_32: Number of clock parents if @num_parents field is * set to 255. * * Response to TI_SCI_MSG_GET_NUM_CLOCK_PARENTS */ struct ti_sci_msg_resp_get_clock_num_parents { struct ti_sci_msg_hdr hdr; u8 num_parents; u32 num_parents_32; } __packed; /** * struct ti_sci_msg_req_query_clock_freq - Request to query a frequency * @hdr: Generic Header * @dev_id: Device identifier this request is for * @min_freq_hz: The minimum allowable frequency in Hz. This is the minimum * allowable programmed frequency and does not account for clock * tolerances and jitter. * @target_freq_hz: The target clock frequency. A frequency will be found * as close to this target frequency as possible. * @max_freq_hz: The maximum allowable frequency in Hz. This is the maximum * allowable programmed frequency and does not account for clock * tolerances and jitter. * @clk_id: Clock identifier for the device for this request. Set to * 255 if clock identifier is greater than or equal to 255. * @clk_id_32: Clock identifier if @clk_id is set to 255. * * NOTE: Normally clock frequency management is automatically done by TISCI * entity. In case of specific requests, TISCI evaluates capability to achieve * requested frequency within provided range and responds with * result message. * * Request type is TI_SCI_MSG_QUERY_CLOCK_FREQ, response is appropriate message, * or NACK in case of inability to satisfy request. */ struct ti_sci_msg_req_query_clock_freq { struct ti_sci_msg_hdr hdr; u32 dev_id; u64 min_freq_hz; u64 target_freq_hz; u64 max_freq_hz; u8 clk_id; u32 clk_id_32; } __packed; /** * struct ti_sci_msg_resp_query_clock_freq - Response to a clock frequency query * @hdr: Generic Header * @freq_hz: Frequency that is the best match in Hz. * * Response to request type TI_SCI_MSG_QUERY_CLOCK_FREQ. NOTE: if the request * cannot be satisfied, the message will be of type NACK. */ struct ti_sci_msg_resp_query_clock_freq { struct ti_sci_msg_hdr hdr; u64 freq_hz; } __packed; /** * struct ti_sci_msg_req_set_clock_freq - Request to setup a clock frequency * @hdr: Generic Header * @dev_id: Device identifier this request is for * @min_freq_hz: The minimum allowable frequency in Hz. This is the minimum * allowable programmed frequency and does not account for clock * tolerances and jitter. * @target_freq_hz: The target clock frequency. The clock will be programmed * at a rate as close to this target frequency as possible. * @max_freq_hz: The maximum allowable frequency in Hz. This is the maximum * allowable programmed frequency and does not account for clock * tolerances and jitter. * @clk_id: Clock identifier for the device for this request. Set to * 255 if clock ID is greater than or equal to 255. * @clk_id_32: Clock identifier if @clk_id field is set to 255. * * NOTE: Normally clock frequency management is automatically done by TISCI * entity. In case of specific requests, TISCI evaluates capability to achieve * requested range and responds with success/failure message. * * This sets the desired frequency for a clock within an allowable * range. This message will fail on an enabled clock unless * MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE is set for the clock. Additionally, * if other clocks have their frequency modified due to this message, * they also must have the MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE or be disabled. * * Calling set frequency on a clock input to the SoC pseudo-device will * inform the PMMC of that clock's frequency. Setting a frequency of * zero will indicate the clock is disabled. * * Calling set frequency on clock outputs from the SoC pseudo-device will * function similarly to setting the clock frequency on a device. * * Request type is TI_SCI_MSG_SET_CLOCK_FREQ, response is a generic ACK/NACK * message. */ struct ti_sci_msg_req_set_clock_freq { struct ti_sci_msg_hdr hdr; u32 dev_id; u64 min_freq_hz; u64 target_freq_hz; u64 max_freq_hz; u8 clk_id; u32 clk_id_32; } __packed; /** * struct ti_sci_msg_req_get_clock_freq - Request to get the clock frequency * @hdr: Generic Header * @dev_id: Device identifier this request is for * @clk_id: Clock identifier for the device for this request. Set to * 255 if clock ID is greater than or equal to 255. * @clk_id_32: Clock identifier if @clk_id field is set to 255. * * NOTE: Normally clock frequency management is automatically done by TISCI * entity. In some cases, clock frequencies are configured by host. * * Request type is TI_SCI_MSG_GET_CLOCK_FREQ, responded with clock frequency * that the clock is currently at. */ struct ti_sci_msg_req_get_clock_freq { struct ti_sci_msg_hdr hdr; u32 dev_id; u8 clk_id; u32 clk_id_32; } __packed; /** * struct ti_sci_msg_resp_get_clock_freq - Response of clock frequency request * @hdr: Generic Header * @freq_hz: Frequency that the clock is currently on, in Hz. * * Response to request type TI_SCI_MSG_GET_CLOCK_FREQ. */ struct ti_sci_msg_resp_get_clock_freq { struct ti_sci_msg_hdr hdr; u64 freq_hz; } __packed; #define TI_SCI_IRQ_SECONDARY_HOST_INVALID 0xff /** * struct ti_sci_msg_req_get_resource_range - Request to get a host's assigned * range of resources. * @hdr: Generic Header * @type: Unique resource assignment type * @subtype: Resource assignment subtype within the resource type. * @secondary_host: Host processing entity to which the resources are * allocated. This is required only when the destination * host id id different from ti sci interface host id, * else TI_SCI_IRQ_SECONDARY_HOST_INVALID can be passed. * * Request type is TI_SCI_MSG_GET_RESOURCE_RANGE. Responded with requested * resource range which is of type TI_SCI_MSG_GET_RESOURCE_RANGE. */ struct ti_sci_msg_req_get_resource_range { struct ti_sci_msg_hdr hdr; #define MSG_RM_RESOURCE_TYPE_MASK GENMASK(9, 0) #define MSG_RM_RESOURCE_SUBTYPE_MASK GENMASK(5, 0) u16 type; u8 subtype; u8 secondary_host; } __packed; /** * struct ti_sci_msg_resp_get_resource_range - Response to resource get range. * @hdr: Generic Header * @range_start: Start index of the resource range. * @range_num: Number of resources in the range. * * Response to request TI_SCI_MSG_GET_RESOURCE_RANGE. */ struct ti_sci_msg_resp_get_resource_range { struct ti_sci_msg_hdr hdr; u16 range_start; u16 range_num; } __packed; /** * struct ti_sci_msg_req_manage_irq - Request to configure/release the route * between the dev and the host. * @hdr: Generic Header * @valid_params: Bit fields defining the validity of interrupt source * parameters. If a bit is not set, then corresponding * field is not valid and will not be used for route set. * Bit field definitions: * 0 - Valid bit for @dst_id * 1 - Valid bit for @dst_host_irq * 2 - Valid bit for @ia_id * 3 - Valid bit for @vint * 4 - Valid bit for @global_event * 5 - Valid bit for @vint_status_bit_index * 31 - Valid bit for @secondary_host * @src_id: IRQ source peripheral ID. * @src_index: IRQ source index within the peripheral * @dst_id: IRQ Destination ID. Based on the architecture it can be * IRQ controller or host processor ID. * @dst_host_irq: IRQ number of the destination host IRQ controller * @ia_id: Device ID of the interrupt aggregator in which the * vint resides. * @vint: Virtual interrupt number if the interrupt route * is through an interrupt aggregator. * @global_event: Global event that is to be mapped to interrupt * aggregator virtual interrupt status bit. * @vint_status_bit: Virtual interrupt status bit if the interrupt route * utilizes an interrupt aggregator status bit. * @secondary_host: Host ID of the IRQ destination computing entity. This is * required only when destination host id is different * from ti sci interface host id. * * Request type is TI_SCI_MSG_SET/RELEASE_IRQ. * Response is generic ACK / NACK message. */ struct ti_sci_msg_req_manage_irq { struct ti_sci_msg_hdr hdr; #define MSG_FLAG_DST_ID_VALID TI_SCI_MSG_FLAG(0) #define MSG_FLAG_DST_HOST_IRQ_VALID TI_SCI_MSG_FLAG(1) #define MSG_FLAG_IA_ID_VALID TI_SCI_MSG_FLAG(2) #define MSG_FLAG_VINT_VALID TI_SCI_MSG_FLAG(3) #define MSG_FLAG_GLB_EVNT_VALID TI_SCI_MSG_FLAG(4) #define MSG_FLAG_VINT_STS_BIT_VALID TI_SCI_MSG_FLAG(5) #define MSG_FLAG_SHOST_VALID TI_SCI_MSG_FLAG(31) u32 valid_params; u16 src_id; u16 src_index; u16 dst_id; u16 dst_host_irq; u16 ia_id; u16 vint; u16 global_event; u8 vint_status_bit; u8 secondary_host; } __packed; #endif /* __TI_SCI_H */