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 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.