TISCI PM Clock API Documentation¶
Introduction¶
This document describes the TISCI API set for configuring and controlling the clocks within the system.
Clock configuration and control APIs¶
| TISCI Message ID | Message Name |
|---|---|
| 0x0100 | TISCI_MSG_SET_CLOCK |
| 0x0101 | TISCI_MSG_GET_CLOCK |
| 0x0102 | TISCI_MSG_SET_CLOCK_PARENT |
| 0x0103 | TISCI_MSG_GET_CLOCK_PARENT |
| 0x0104 | TISCI_MSG_GET_NUM_CLOCK_PARENTS |
| 0x010c | TISCI_MSG_SET_FREQ |
| 0x010d | TISCI_MSG_QUERY_FREQ |
| 0x010e | TISCI_MSG_GET_FREQ |
Note
Reference Chapter 5: SoC Family Specific Documentation to see clock IDs and device IDs for your SoC.
Macros Used in this Document¶
TISCI_MSG_VALUE_CLOCK_SW_STATE_UNREQ 0
The IP does not require this clock, it can be disabled, regardless of the state of the device
TISCI_MSG_VALUE_CLOCK_SW_STATE_AUTO 1
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. This is the default state.
TISCI_MSG_VALUE_CLOCK_SW_STATE_REQ 2
Configure the clock to be enabled, regardless of the state of the device.
TISCI_MSG_VALUE_CLOCK_HW_STATE_NOT_READY 0
Indicate hardware state of the clock is that it is not running.
TISCI_MSG_VALUE_CLOCK_HW_STATE_READY 1
Indicate hardware state of the clock is that it is running.
TISCI_MSG_FLAG_CLOCK_ALLOW_SSC BIT(8)
Allow this clock to be modified via spread spectrum clocking.
TISCI_MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE BIT(9)
Allow this clock’s frequency to be changed while it is running so long as it is within the min/max limits.
TISCI_MSG_FLAG_CLOCK_INPUT_TERM BIT(10)
Enable input termination, this is only applicable to clock inputs on the SoC pseudo-device, BOARD0.
TISCI_MSG_FLAG_CLOCK_SSC_ACTIVE BIT(11)
Indicate that SSC is active for this clock.
TISCI_MSG_SET_CLOCK¶
Objective¶
Setup a hardware device’s clock state
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
This requests for finer control of hardware device’s clocks. This allows for configuration for hardware blocks that require customization of the specific input clocks. NOTE: each of the clock IDs are relative to the hardware block.
TISCI Message ID¶
TISCI_MSG_SET_CLOCK (0x0100U)
Message Data Structures¶
struct tisci_msg_set_clock_req
Mark a clock as required/not required.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| device | u32 | The device ID that the clock is connected to. |
| clk | u8 | Each device has its own set of clock inputs. This indexes which clock input to modify. |
| state | u8 | The desired state of the clock, TISCI_MSG_VALUE_CLOCK_SW_STATE_REQ if the clock is currently required by the IP and TISCI_MSG_VALUE_CLOCK_SW_STATE_UNREQ if it is not. TISCI_MSG_VALUE_CLOCK_SW_STATE_AUTO enables the clock when the IP is set to enabled and disables it when the IP is set to disabled. This is the default state. |
Indicate that the selected clock is currently required/not required by the IP. Certain flags can be set in the message header for device clocks: TISCI_MSG_FLAG_CLOCK_ALLOW_SSC, TISCI_MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE, TISCI_MSG_FLAG_CLOCK_INPUT_TERM.
struct tisci_msg_set_clock_resp
Empty response for TISCI_MSG_SET_CLOCK
| 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_CLOCK¶
Objective¶
Get the state of a clock to or from a hardware block.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
This requests for additional information about the state of a clock within the system including the state it is programmed to and the actual state of the clock.
TISCI Message ID¶
TISCI_MSG_GET_CLOCK (0x0101U)
Message Data Structures¶
struct tisci_msg_get_clock_req
Get the current state of a clock
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| device | u32 | The device ID that the clock is connected to. |
| clk | u8 | Each device has its own set of clock inputs. This indexes which clock input to get. |
struct tisci_msg_get_clock_resp
Clock state response.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| programmed_state | u8 | The programmed state as set by the set message. |
| current_state | u8 | The actual state of the clock. If it is desired that a clock be on, it is usually better to send a set message with a flag indicating that an ack be sent when the message is processed rather than attempting to poll this state. |
TISCI_MSG_SET_CLOCK_PARENT¶
Objective¶
SoC specific customization for setting up a specific clock parent ID for the various clock input options for a hardware block’s clock.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
This is rarely used customization that may be required based on the usecase of the system where the reset input clock option may not suffice for the usecase attempted.
Message ID¶
TISCI_MSG_SET_CLOCK_PARENT (0x0102U)
Message Data Structures¶
struct tisci_msg_set_clock_parent_req
Set the clock parent
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| device | u32 | The device ID that the clock is connected to. |
| clk | u8 | Each device has its own set of clock inputs. This indexes which clock input to modify. |
| parent | u8 | The new clock parent is selectable by an index via this parameter. |
Many IPs have a mux external to the IP that can select among different clock sources. The clock must be disabled (TISCI_MSG_VALUE_CLOCK_SW_STATE_UNREQ) for this message to succeed. If a set frequency command is not issued before the clock is enabled again, then the execution of the enable command will attempt to set the new parent to the old parent’s frequency. If this fails, then the enable will fail. Muxes that provide clocks to multiple devices are not currently configurable via this API.
struct tisci_msg_set_clock_parent_resp
Empty response for TISCI_MSG_SET_CLOCK_PARENT
| 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_CLOCK_PARENT¶
Objective¶
Query the clock parent currently configured for a specific clock source of a hardware block
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
This is typically used to confirm the current clock parent to ensure that the requisite usecase for the hardware block can be satisfied.
Message ID¶
TISCI_MSG_GET_CLOCK_PARENT (0x0103U)
Message Data Structures¶
struct tisci_msg_get_clock_parent_req
Return the current clock parent
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| device | u32 | The device ID that the clock is connected to. |
| clk | u8 | Each device has its own set of clock inputs. This indexes which clock input to get. |
struct tisci_msg_get_clock_parent_resp
Clock parent response
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| parent | u8 | The current clock parent |
TISCI_MSG_GET_NUM_CLOCK_PARENTS¶
Objective¶
Query for the number of parent clock paths available for a specific hardware block’s clock.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
This is typically used to get the max number of clock parent options available for a specific hardware block’s clock.
Message ID¶
TISCI_MSG_GET_NUM_CLOCK_PARENTS (0x0104U)
Message Data Structures¶
struct tisci_msg_get_num_clock_parents_req
Return the number of possible parents for a clock
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| device | u32 | The device ID that the clock is connected to. |
| clk | u8 | Each device has its own set of clock inputs. This indexes which clock input to query. |
struct tisci_msg_get_num_clock_parents_resp
Num clock parents response
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| num_parents | u8 | The number of clock parents |
TISCI_MSG_SET_FREQ¶
Objective¶
Setup a clock frequency for a hardware block’s clock.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
This is typically desired when the default frequency of the hardware block’s clock is not appropriate for the usecase desired.
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.
Message ID¶
TISCI_MSG_SET_FREQ (0x010cU)
Message Data Structures¶
struct tisci_msg_set_freq_req
Set the desired frequency for a clock.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| device | u32 | The device ID that the clock is connected to. |
| min_freq_hz | u64 | 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 | u64 | The target clock frequency. The clock will be programmed at a rate as close to this target frequency as possible. |
| max_freq_hz | u64 | The maximum allowable frequency in Hz. This is the maximum allowable programmed frequency and does not account for clock tolerances and jitter. The firmware will actually accept any frequency up to but not including max + 1. |
| clk | u8 | Each device has its own set of clock inputs. This indexes which clock input to modify. |
This set the desired frequency for a clock within an allowable range. This message will fail on an enabled clock unless TISCI_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 TISCI_MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE or be disabled. Calling set frequency on a clock input to the SoC psuedo-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.
struct tisci_msg_set_freq_resp
Empty response for TISCI_MSG_SET_FREQ
| 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_QUERY_FREQ¶
Objective¶
Query to find closest match possible for a target frequency.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
This message does no real operation, instead, it requests the system control entity to respond with the best frequency that can match a frequency range provided.
NOTE: This is a snapshot view. In a multi processing system, it is very well possible that another processing entity might change the configuration after one entity has queried for best match capability. Only a SET_CLOCK_FREQ will guarantee the frequency is configured.
Message ID¶
TISCI_MSG_QUERY_FREQ (0x010dU)
Message Data Structures¶
struct tisci_msg_query_freq_req
Determine the result of a hypothetical set frequency operation.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| device | u32 | The device ID that the clock is connected to. |
| min_freq_hz | u64 | 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 | u64 | The target clock frequency. A frequency will be found as close to the target frequency as possible. |
| max_freq_hz | u64 | The maximum allowable frequency in Hz. This is the maximum allowable programmed frequency and does not account for clock tolerances and jitter. The firmware will actually accept any frequency up to but not including max + 1. |
| clk | u8 | Each device has its own set of clock inputs. This indexes which clock input to query. |
This allows the OS to determine what rate would be set given a set of parameters. A nack will be received if a frequency is not available in the given range.
struct tisci_msg_query_freq_resp
Result of a query operation
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| freq_hz | u64 | The frequency in Hz that the hardware would set for the given parameters. |
TISCI_MSG_GET_FREQ¶
Objective¶
Get the clock frequency of a specific clock which belongs to a hardware block.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
This is most used functionality and is meant for usage when the driver controlling the hardware block requires to know the input clock frequency for configuring internal dividers / multipliers as required.
Message ID¶
TISCI_MSG_GET_FREQ (0x010eU)
Message Data Structures¶
struct tisci_msg_get_freq_req
Get the current frequency of a device’s clock
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| device | u32 | The device ID that the clock is connected to. |
| clk | u8 | Each device has its own set of clock inputs. This indexes which clock input to query. |
This message will only succeed if the clock is currently enabled, otherwise it returns nack.
struct tisci_msg_get_freq_resp
Result of get frequency request
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| freq_hz | u64 | The current frequency in Hz. |