Introduction

DMSC controls the power management of the device, hence is responsible for bringing the device out of reset, enforce clock and reset rules. DMSC power management functions are critical to bring device to low power modes, for example DeepSleep, and sense wake-up events to bring device back online to active state.

Files
file	sciclient_pm.h
	This file contains the definition of all the message IDs, message formats to be able to interact with the System Controller firmware for power management.

Functions
int32_t	Sciclient_pmSetModuleState (uint32_t moduleId, uint32_t state, uint32_t reqFlag, uint32_t timeout)
	Message to set the hardware block/module state 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. More...

int32_t	Sciclient_pmGetModuleState (uint32_t moduleId, uint32_t moduleState, uint32_t resetState, uint32_t *contextLossState, uint32_t timeout)
	Message to get the hardware block/Module state. This request does not require the processing entity to have control of the device via a set device state request. More...

int32_t	Sciclient_pmSetModuleRst (uint32_t moduleId, uint32_t resetBit, uint32_t timeout)
	Set the device reset state. This is used to set or release various resets of the hardware block/module. More...

int32_t	Sciclient_pmSetModuleRst_flags (uint32_t moduleId, uint32_t resetBit, uint32_t reqFlag, uint32_t timeout)
	Set the device reset state, allowing for user to set reqFlags This is used to set or release various resets of the hardware block/module. More...

int32_t	Sciclient_pmModuleClkRequest (uint32_t moduleId, uint32_t clockId, uint32_t state, uint32_t additionalFlag, uint32_t timeout)
	Message to set the clock state: 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. More...

int32_t	Sciclient_pmModuleGetClkStatus (uint32_t moduleId, uint32_t clockId, uint32_t *state, uint32_t timeout)
	Message to get the clock state to or from a hardware block. More...

int32_t	Sciclient_pmSetModuleClkParent (uint32_t moduleId, uint32_t clockId, uint32_t parent, uint32_t timeout)
	Message to Set Clock Parent: This message allows SoC specific customization for setting up a specific clock parent ID for the various clock input options for a hardware block's clock. 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. More...

int32_t	Sciclient_pmGetModuleClkParent (uint32_t moduleId, uint32_t clockId, uint32_t *parent, uint32_t timeout)
	Message to Get Clock Parent: Query the clock parent currently configured for a specific clock source of a hardware block This is typically used to confirm the current clock parent to ensure that the requisite usecase for the hardware block can be satisfied. More...

int32_t	Sciclient_pmGetModuleClkNumParent (uint32_t moduleId, uint32_t clockId, uint32_t *numParent, uint32_t timeout)
	Message to get the number of clock parents for a given module. This is typically used to get the max number of clock parent options available for a specific hardware block's clock. More...

int32_t	Sciclient_pmSetModuleClkFreq (uint32_t moduleId, uint32_t clockId, uint64_t freqHz, uint32_t additionalFlag, uint32_t timeout)
	Message to set the clock frequency. 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. More...

int32_t	Sciclient_pmSetModuleClkFreqRange (uint32_t moduleId, uint32_t clockId, uint64_t freqHz, uint64_t minFreqHz, uint64_t maxFreqHz, uint32_t additionalFlag, uint32_t timeout)
	Message to set the clock frequency. 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. More...

int32_t	Sciclient_pmQueryModuleClkFreq (uint32_t moduleId, uint32_t clockId, uint64_t reqFreqHz, uint64_t *respFreqHz, uint32_t timeout)
	Message to query the best clock frequency in the given range. 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. More...

int32_t	Sciclient_pmQueryModuleClkFreqRange (uint32_t moduleId, uint32_t clockId, uint64_t reqFreqHz, uint64_t minFreqHz, uint64_t maxFreqHz, uint64_t *respFreqHz, uint32_t timeout)
	Message to query the best clock frequency in the given range. 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. More...

int32_t	Sciclient_pmGetModuleClkFreq (uint32_t moduleId, uint32_t clockId, uint64_t *freqHz, uint32_t timeout)
	Message to Get Clock Frequency 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. More...

int32_t	Sciclient_pmDeviceReset (uint32_t timeout)
	Objective: Trigger a SoC level reset Usage: Used to trigger a system level reset. NOTE: Depending on permissions configured for the SoC, not all processing entities may be permitted to request a SoC reset. When permitted, the request once processed will not return back to caller. More...

int32_t	Sciclient_pmDomainReset (domgrp_t domGrp, uint32_t timeout)
	Objective: Trigger a domain level reset. More...

Function Documentation

◆ Sciclient_pmSetModuleState()

int32_t Sciclient_pmSetModuleState	(	uint32_t	moduleId,
		uint32_t	state,
		uint32_t	reqFlag,
		uint32_t	timeout
	)

Message to set the hardware block/module state 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.

Message: TISCI_MSG_SET_DEVICE
Request: tisci_msg_set_device_req
Response: tisci_msg_set_device_resp

Parameters

moduleId	Module for which the state should be set. Refer Sciclient_PmDeviceIds.
state	Module State requested.
reqFlag	Can be TISCI_MSG_FLAG_AOR/TISCI_MSG_FLAG_AOP ORRed with additional flag that can be set to alter the device state.
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmGetModuleState()

int32_t Sciclient_pmGetModuleState	(	uint32_t	moduleId,
		uint32_t *	moduleState,
		uint32_t *	resetState,
		uint32_t *	contextLossState,
		uint32_t	timeout
	)

Message to get the hardware block/Module state. This request does not require the processing entity to have control of the device via a set device state request.

Message: TISCI_MSG_GET_DEVICE
Request: tisci_msg_get_device_req
Response: tisci_msg_get_device_resp

Parameters

moduleId	Module for which the state should be set. Refer Sciclient_PmDeviceIds.
moduleState	Module State returned.
resetState	Programmed state of the reset lines.
contextLossState	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.
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmSetModuleRst()

int32_t Sciclient_pmSetModuleRst	(	uint32_t	moduleId,
		uint32_t	resetBit,
		uint32_t	timeout
	)

Set the device reset state. This is used to set or release various resets of the hardware block/module.

Message: TISCI_MSG_SET_DEVICE_RESETS
Request: tisci_msg_set_device_resets_req
Response: tisci_msg_set_device_resets_resp

Parameters

moduleId	Module for which the state should be set.
resetBit	Module Reset Bit to be set. 1 - Assert the reset 0 - Deassert the reset Note this convention is opposite of PSC MDCTL
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmSetModuleRst_flags()

int32_t Sciclient_pmSetModuleRst_flags	(	uint32_t	moduleId,
		uint32_t	resetBit,
		uint32_t	reqFlag,
		uint32_t	timeout
	)

Set the device reset state, allowing for user to set reqFlags This is used to set or release various resets of the hardware block/module.

Message: TISCI_MSG_SET_DEVICE_RESETS
Request: tisci_msg_set_device_resets_req
Response: tisci_msg_set_device_resets_resp

Parameters

moduleId	Module for which the state should be set.
resetBit	Module Reset Bit to be set. 1 - Assert the reset 0 - Deassert the reset Note this convention is opposite of PSC MDCTL
reqFlag	Can be TISCI_MSG_FLAG_AOR/TISCI_MSG_FLAG_AOP ORRed with additional flag that can be set to alter the device state.
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmModuleClkRequest()

int32_t Sciclient_pmModuleClkRequest	(	uint32_t	moduleId,
		uint32_t	clockId,
		uint32_t	state,
		uint32_t	additionalFlag,
		uint32_t	timeout
	)

Message to set the clock state: 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.

Message: TISCI_MSG_SET_CLOCK
Request: tisci_msg_set_clock_req
Response: tisci_msg_set_clock_resp

Parameters

moduleId	Module for which the state should be set.
clockId	Clock Id for the module.
state	Clock State requested.
additionalFlag	Certain flags can also be set to alter the clock state.
timeout	Gives a sense of how long to wait for the operation.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmModuleGetClkStatus()

int32_t Sciclient_pmModuleGetClkStatus	(	uint32_t	moduleId,
		uint32_t	clockId,
		uint32_t *	state,
		uint32_t	timeout
	)

Message to get the clock state to or from a hardware block.

Message: TISCI_MSG_GET_CLOCK
Request: tisci_msg_get_clock_req
Response: tisci_msg_get_clock_resp

Parameters

moduleId	Module for which the state should be set. Refer Sciclient_PmDeviceIds.
clockId	Clock Id for the module. Refer Sciclient_PmModuleClockIds.
state	Clock State returned.
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmSetModuleClkParent()

int32_t Sciclient_pmSetModuleClkParent	(	uint32_t	moduleId,
		uint32_t	clockId,
		uint32_t	parent,
		uint32_t	timeout
	)

Message to Set Clock Parent: This message allows SoC specific customization for setting up a specific clock parent ID for the various clock input options for a hardware block's clock. 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: TISCI_MSG_SET_CLOCK_PARENT
Request: tisci_msg_set_clock_parent_req
Response: tisci_msg_set_clock_parent_resp

Parameters

moduleId	Module for which the state should be set. Refer Sciclient_PmDeviceIds.
clockId	Clock Id for the module. Refer Sciclient_PmModuleClockIds.
parent	Parent Id for the clock.
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmGetModuleClkParent()

int32_t Sciclient_pmGetModuleClkParent	(	uint32_t	moduleId,
		uint32_t	clockId,
		uint32_t *	parent,
		uint32_t	timeout
	)

Message to Get Clock Parent: Query the clock parent currently configured for a specific clock source of a hardware block This is typically used to confirm the current clock parent to ensure that the requisite usecase for the hardware block can be satisfied.

Message: TISCI_MSG_GET_CLOCK_PARENT
Request: tisci_msg_get_clock_parent_req
Response: tisci_msg_get_clock_parent_resp

Parameters

moduleId	Module for which the state should be set. Refer Sciclient_PmDeviceIds.
clockId	Clock Id for the module. Refer Sciclient_PmModuleClockIds.
parent	Returned Parent Id for the clock.s
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmGetModuleClkNumParent()

int32_t Sciclient_pmGetModuleClkNumParent	(	uint32_t	moduleId,
		uint32_t	clockId,
		uint32_t *	numParent,
		uint32_t	timeout
	)

Message to get the number of clock parents for a given module. This is typically used to get the max number of clock parent options available for a specific hardware block's clock.

Message: TISCI_MSG_GET_NUM_CLOCK_PARENTS
Request: tisci_msg_get_num_clock_parents_req
Response: tisci_msg_get_num_clock_parents_resp

Parameters

moduleId	Module for which the state should be set. Refer Sciclient_PmDeviceIds.
clockId	Clock Id for the module. Refer Sciclient_PmModuleClockIds.
numParent	Returned number of parents.
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmSetModuleClkFreq()

int32_t Sciclient_pmSetModuleClkFreq	(	uint32_t	moduleId,
		uint32_t	clockId,
		uint64_t	freqHz,
		uint32_t	additionalFlag,
		uint32_t	timeout
	)

Message to set the clock frequency. 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.

Message: TISCI_MSG_SET_FREQ
Request: tisci_msg_set_freq_req
Response: tisci_msg_set_freq_resp

Parameters

moduleId	Module for which the state should be set. Refer Sciclient_PmDeviceIds.
clockId	Clock Id for the module. Refer Sciclient_PmModuleClockIds.
freqHz	Frequency of the clock in Hertz.
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.
additionalFlag	Additional flags for the request.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmSetModuleClkFreqRange()

int32_t Sciclient_pmSetModuleClkFreqRange	(	uint32_t	moduleId,
		uint32_t	clockId,
		uint64_t	freqHz,
		uint64_t	minFreqHz,
		uint64_t	maxFreqHz,
		uint32_t	additionalFlag,
		uint32_t	timeout
	)

Message to set the clock frequency. 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.

Message: TISCI_MSG_SET_FREQ
Request: tisci_msg_set_freq_req
Response: tisci_msg_set_freq_resp

Parameters

moduleId	Module for which the state should be set. Refer Sciclient_PmDeviceIds.
clockId	Clock Id for the module. Refer Sciclient_PmModuleClockIds.
freqHz	Frequency of the clock in Hertz.
minFreqHz	Frequency of the clock in Hertz(Min Limit).
maxFreqHz	Frequency of the clock in Hertz(Max Limit).
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.
additionalFlag	Additional flags for the request.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmQueryModuleClkFreq()

int32_t Sciclient_pmQueryModuleClkFreq	(	uint32_t	moduleId,
		uint32_t	clockId,
		uint64_t	reqFreqHz,
		uint64_t *	respFreqHz,
		uint32_t	timeout
	)

Message to query the best clock frequency in the given range. 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: TISCI_MSG_QUERY_FREQ
Request: tisci_msg_query_freq_req
Response: tisci_msg_query_freq_resp

Parameters

moduleId	Module for which the state should be set. Refer Sciclient_PmDeviceIds.
clockId	Clock Id for the module. Refer Sciclient_PmModuleClockIds.
reqFreqHz	The target clock frequency.
respFreqHz	The frequency that the hardware would set for the given parameters.
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmQueryModuleClkFreqRange()

int32_t Sciclient_pmQueryModuleClkFreqRange	(	uint32_t	moduleId,
		uint32_t	clockId,
		uint64_t	reqFreqHz,
		uint64_t	minFreqHz,
		uint64_t	maxFreqHz,
		uint64_t *	respFreqHz,
		uint32_t	timeout
	)

Message to query the best clock frequency in the given range. 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: TISCI_MSG_QUERY_FREQ
Request: tisci_msg_query_freq_req
Response: tisci_msg_query_freq_resp

Parameters

moduleId	Module for which the state should be set. Refer Sciclient_PmDeviceIds.
clockId	Clock Id for the module. Refer Sciclient_PmModuleClockIds.
reqFreqHz	The target clock frequency.
minFreqHz	The target clock frequency(Min Limit)
maxFreqHz	The target clock frequency(Max Limit)
respFreqHz	The frequency that the hardware would set for the given parameters.
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmGetModuleClkFreq()

int32_t Sciclient_pmGetModuleClkFreq	(	uint32_t	moduleId,
		uint32_t	clockId,
		uint64_t *	freqHz,
		uint32_t	timeout
	)

Message to Get Clock Frequency 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: TISCI_MSG_GET_FREQ
Request: tisci_msg_get_freq_req
Response: tisci_msg_get_freq_resp

Parameters

moduleId	Module for which the state should be set. Refer Sciclient_PmDeviceIds.
clockId	Clock Id for the module. Refer Sciclient_PmModuleClockIds.
freqHz	Frequency of the clock returned in Hertz.
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmDeviceReset()

int32_t Sciclient_pmDeviceReset ( uint32_t timeout )

Objective: Trigger a SoC level reset Usage: Used to trigger a system level reset. NOTE: Depending on permissions configured for the SoC, not all processing entities may be permitted to request a SoC reset. When permitted, the request once processed will not return back to caller.

Message: TISCI_MSG_SYS_RESET
Request: tisci_msg_sys_reset_req
Response: tisci_msg_sys_reset_resp

Parameters

timeout Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

◆ Sciclient_pmDomainReset()

int32_t Sciclient_pmDomainReset	(	domgrp_t	domGrp,
		uint32_t	timeout
	)

Objective: Trigger a domain level reset.

Parameters

domGrp	Gives the sysfw DOMGRP type. This is meant to be used in code or data structures that require distinction of domgrps.
timeout	Gives a sense of how long to wait for the operation. Refer SystemP_Timeout.

Returns: SystemP_SUCCESS on success, else failure

Introduction

Files

Functions

Function Documentation

◆ Sciclient_pmSetModuleState()

◆ Sciclient_pmGetModuleState()

◆ Sciclient_pmSetModuleRst()

◆ Sciclient_pmSetModuleRst_flags()

◆ Sciclient_pmModuleClkRequest()

◆ Sciclient_pmModuleGetClkStatus()

◆ Sciclient_pmSetModuleClkParent()

◆ Sciclient_pmGetModuleClkParent()

◆ Sciclient_pmGetModuleClkNumParent()

◆ Sciclient_pmSetModuleClkFreq()

◆ Sciclient_pmSetModuleClkFreqRange()

◆ Sciclient_pmQueryModuleClkFreq()

◆ Sciclient_pmQueryModuleClkFreqRange()

◆ Sciclient_pmGetModuleClkFreq()

◆ Sciclient_pmDeviceReset()

◆ Sciclient_pmDomainReset()