TISCI PM Device API Documentation¶
Introduction¶
This document describes the TISCI API set for configuring and controlling the devices within the system.
Device configuration and control APIs¶
| TISCI Message ID | Message Name |
|---|---|
| 0x0200 | TISCI_MSG_SET_DEVICE |
| 0x0201 | TISCI_MSG_GET_DEVICE |
| 0x0202 | TISCI_MSG_SET_DEVICE_RESETS |
Note
Reference Chapter 5: SoC Family Specific Documentation to see device IDs for your SoC.
Macros Used in this Document¶
TISCI_MSG_FLAG_DEVICE_WAKE_ENABLED BIT(8)
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 low power states.
TISCI_MSG_FLAG_DEVICE_RESET_ISO BIT(9)
Enable reset isolation for this device.
TISCI_MSG_FLAG_DEVICE_EXCLUSIVE BIT(10)
Claim a 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.
TISCI_MSG_VALUE_DEVICE_SW_STATE_AUTO_OFF 0
Used by TISCI_MSG_SET_DEVICE to turn device off when possible. This must be used in conjunction with SoC dependencies to identify the overall power domain state being achieved.
TISCI_MSG_VALUE_DEVICE_SW_STATE_RETENTION 1
Used by TISCI_MSG_SET_DEVICE to disable device but keep in retention.
TISCI_MSG_VALUE_DEVICE_SW_STATE_ON 2
Used by TISCI_MSG_SET_DEVICE to turn device on for usage.
TISCI_MSG_VALUE_DEVICE_HW_STATE_OFF 0
TISCI_MSG_GET_DEVICE sets this as current state to indicate device is off.
TISCI_MSG_VALUE_DEVICE_HW_STATE_ON 1
TISCI_MSG_GET_DEVICE sets this as current state to indicate device is on.
TISCI_MSG_VALUE_DEVICE_HW_STATE_TRANS 2
TISCI_MSG_GET_DEVICE sets this as current state to indicate device is transitioning between states. When a device stays in this state it is typically due to the fact that some resource that the device is dependent on (example IRQs) are pending preventing completion of hardware handshake. Please refer to Technical Reference Manual for additional information.
TISCI_MSG_SET_DEVICE¶
Objective¶
Request for a device state to be set.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
This is used to request or release a device. For example: When the device is requested for operation, state is set to MSG_DEVICE_SW_STATE_ON. When the usage of the device is complete and released, the same request with state set as MSG_DEVICE_SW_STATE_AUTO_OFF is invoked. Based on exclusive access request, multiple processing entities can share a specific hardware block, however, this must be carefully used keeping the full system view in mind.
TISCI Message ID¶
TISCI_MSG_SET_DEVICE (0x0200U)
Message Data Structures¶
struct tisci_msg_set_device_req
Set the desired state of the device.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| id | u32 | Indicates which device to modify |
| reserved | u32 | Field is ignored |
| state | u8 | The desired state of the device. |
Certain flags can also be set to alter the device state: TISCI_MSG_FLAG_DEVICE_WAKE_ENABLED, TISCI_MSG_FLAG_DEVICE_RESET_ISO, TISCI_MSG_FLAG_DEVICE_EXCLUSIVE
struct tisci_msg_set_device_resp
Empty response for TISCI_MSG_SET_DEVICE
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header to provide ACK/NAK flags to the host. |
Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation.
TISCI_MSG_GET_DEVICE¶
Objective¶
Retrieve the hardware block state.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
This requests information regarding the state of a device including the device’s programmed state, current state, number of resets, and the number of times a device lost context.
TISCI Message ID¶
TISCI_MSG_GET_DEVICE (0x0201U)
Message Data Structures¶
struct tisci_msg_get_device_req
Request to get device based on id.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header. |
| id | u32 | Indicates which device to modify |
struct tisci_msg_get_device_resp
Response to get device request.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header. |
| context_loss_count | u32 | 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 | u32 | Programmed state of the reset lines. |
| programmed_state | u8 | The state as programmed by set_device. |
| current_state | u8 | The actual state of the hardware. |
TISCI_MSG_SET_DEVICE_RESETS¶
Objective¶
Set the state of device reset state.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
This is used to set or release various resets of the hardware block. This is typically used for hardware blocks which require special handling prior to specific resets being released. Typical example is when starting up a processing entity like ICSS/DSP, the device must be requested with resets asserted, required firmware loaded and the required resets released in appropriate order for operation of the device.
The reset state is passed as a 32-bit wide bitfield with any set bit indicating an asserted reset, and any cleared bit indicated a de-asserted reset. The individual bits can have device specific meanings. Some bits are standardized across all devices:
| Bit Position | Meaning |
|---|---|
| 0 | Power State Controller (PSC) local reset (LRST) |
| 1 | PSC module reset (MRST) |
Note that not all devices implement the above reset types. PSC local reset will always assert the local reset regardless of module state. PSC module reset will assert the module reset. Depending on the state of the module the state chosen will follow the below table:
| Device Enabled | Device Retention | Module Reset | Module State |
|---|---|---|---|
| No | No | Don’t Care | SwRstDisabled (may power off) |
| No | Yes | No | Disabled |
| No | Yes | Yes | SwRstDisabled (powered-on) |
| Yes | Don’t Care | No | Enabled |
| Yes | Don’t Care | Yes | SyncReset |
TISCI Message ID¶
TISCI_MSG_SET_DEVICE_RESETS (0x0202U)
Message Data Structures¶
struct tisci_msg_set_device_resets_req
Set the desired state of the resets of a device.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header. |
| id | u32 | Indicates which device to modify |
| resets | u32 | A bit field of resets for the device. The meaning, behavior, and usage of the reset flags are device specific. Altough the flags can be set independently of device state, the firmware will control when resets are actually set to insure compliance with the SoC specific reset requirements. |
struct tisci_msg_set_device_resets_resp
Empty response for TISCI_MSG_SET_DEVICE_RESETS
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header to provide ACK/NAK flags to the host. |
Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation.