psci.h File Reference

Enumerations

Functions
errval_t	psci_version (uint16_t *major, uint16_t *minor)
	Return the version of PSCI implemented. More...
errval_t	psci_cpu_suspend (uint32_t power_state, lpaddr_t entry_point, uintptr_t context_id)
	Suspend execution on a core or higher level topology node. More...
errval_t	psci_cpu_off (void)
	Power down the calling core. More...
errval_t	psci_cpu_on (uintptr_t target_cpu, lpaddr_t entry_point, uintptr_t context_id)
	Power up a core. More...
errval_t	psci_cpu_freeze (void)
	Places the core into an IMPLEMENTATION DEFINED low-power state. More...
errval_t	psci_cpu_default_suspend (lpaddr_t entry_point_address, uintptr_t context_id)
	Will place a core into an IMPLEMENTATION DEFINED low-power state. More...
errval_t	psci_affinity_info (uintptr_t target_affinity, uint32_t lowest_affinity_level, psci_affinity_t *ret_info)
	Enable the caller to request status of an affinity instance. More...
errval_t	psci_migrate (uintptr_t target_cpu)
	Optional. This is used to ask a uniprocessor Trusted OS to migrate its context to a specific core. More...
errval_t	psci_migrate_info_type (psci_migrate_t *ret_migrate_type)
	Optional. This function allows a caller to identify the level of multicore support present in the Trusted OS. More...
errval_t	psci_migrate_info_up_cpu (uintptr_t *ret_mpdir)
	Optional. For a uniprocessor Trusted OS, this function returns the current resident core. More...
void	psci_system_off (void)
	Shutdown the system.
void	psci_system_reset (void)
	Reset the system.
errval_t	psci_system_suspend (lpaddr_t entry_point_address, uintptr_t context_id)
	Used to implement suspend to RAM. The semantics are equivalent to a CPU_SUSPEND to the deepest low-power state. More...
errval_t	psci_features (uint32_t psci_fn_id, uint32_t *ret_feature_flags)
	Query API to discover whether a specific PSCI function is implemented. More...
errval_t	psci_node_hw_state (uintptr_t target_cpu, uint32_t power_level, psci_node_hw_state_t *ret_node_hw)
	This API is intended to return the true HW state of a node in the power domain topology of the system. More...
errval_t	psci_set_suspend_mode (psci_suspend_mode_t mode)
	This API allows setting the mode used by CPU_SUSPEND to coordinate power states. More...
errval_t	psci_stat_residency (uintptr_t target_cpu, uint32_t power_state, uintptr_t *ret_residency)
	Returns the amount of time the platform has spent in the given power state since cold boot. More...
errval_t	psci_stat_count (uintptr_t target_cpu, uint32_t power_state, uintptr_t *count)
	Return the number of times the platform has used the given power state since cold boot. More...

Enumeration Type Documentation

enum psci_affinity_t

Enumerator
PSCI_AFFINITY_ON	At least one core in the instance is ON.
PSCI_AFFINITY_OFF	All cores in the affinity instance are OFF.
PSCI_AFFINITY_ON_PENDING	instance is transitioning to an ON state
PSCI_AFFINITY_INVALID	Invalid affinity state.
PSCI_AFFINITY_ON	At least one core in the instance is ON.
PSCI_AFFINITY_OFF	All cores in the affinity instance are OFF.
PSCI_AFFINITY_ON_PENDING	instance is transitioning to an ON state
PSCI_AFFINITY_INVALID	Invalid affinity state.

enum psci_errno_t

Table 7 defines the values for error codes used with PSCI functions. All errors are considered to be 32-bit signed integers. Therefore, when using the SMC64 calling convention, the upper word will be zero.

Enumerator
PSCI_ERRNO_SUCCESS	PSCI_ERRNO_SUCCESS.
PSCI_ERRNO_NOT_SUPPORTED	PSCI_ERRNO_NOT_SUPPORTED.
PSCI_ERRNO_DENIED	PSCI_ERRNO_DENIED.
PSCI_ERRNO_ALREADY_ON	PSCI_ERRNO_ALREADY_ON.
PSCI_ERRNO_ON_PENDING	PSCI_ERRNO_ON_PENDING.
PSCI_ERRNO_INTERNAL_FAILURE	PSCI_ERRNO_INTERNAL_FAILURE.
PSCI_ERRNO_NOT_PRESENT	PSCI_ERRNO_NOT_PRESENT.
PSCI_ERRNO_DISABLED	PSCI_ERRNO_DISABLED.
PSCI_ERRNO_INVALID_ADDRESS	PSCI_ERRNO_INVALID_ADDRESS.
PSCI_ERRNO_SUCCESS	PSCI_ERRNO_SUCCESS.
PSCI_ERRNO_NOT_SUPPORTED	PSCI_ERRNO_NOT_SUPPORTED.
PSCI_ERRNO_INVALID_PARAMETER	PSCI_ERRNO_INVALID_PARAMTER.
PSCI_ERRNO_DENIED	PSCI_ERRNO_DENIED.
PSCI_ERRNO_ALREADY_ON	PSCI_ERRNO_ALREADY_ON.
PSCI_ERRNO_ON_PENDING	PSCI_ERRNO_ON_PENDING.
PSCI_ERRNO_INTERNAL_FAILURE	PSCI_ERRNO_INTERNAL_FAILURE.
PSCI_ERRNO_NOT_PRESENT	PSCI_ERRNO_NOT_PRESENT.
PSCI_ERRNO_DISABLED	PSCI_ERRNO_DISABLED.
PSCI_ERRNO_INVALID_ADDRESS	PSCI_ERRNO_INVALID_ADDRESS.

enum psci_fn_t

Function Prototypes for the PSCI interface

Enumerator
PSCI_FN_CPU_SUSPEND	PSCI_FN_CPU_SUSPEND.
PSCI_FN_CPU_SUSPEND64	PSCI_FN_CPU_SUSPEND.
PSCI_FN_CPU_OFF	PSCI_FN_CPU_OFF.
PSCI_FN_CPU_ON	PSCI_FN_CPU_ON.
PSCI_FN_CPU_ON64	PSCI_FN_CPU_ON.
PSCI_FN_AFFINITY_INFO	PSCI_FN_AFFINITY_INFO.
PSCI_FN_AFFINITY_INFO64	PSCI_FN_AFFINITY_INFO.
PSCI_FN_MIGRATE	PSCI_FN_MIGRATE.
PSCI_FN_MIGRATE64	PSCI_FN_MIGRATE.
PSCI_FN_MIGRATE_INFO_TYPE	PSCI_FN_MIGRATE_INFO_TYPE.
PSCI_FN_MIGRATE_INFO_UP_CPU	PSCI_FN_MIGRATE_INFO_UP_CPU.
PSCI_FN_MIGRATE_INFO_UP_CPU64	PSCI_FN_MIGRATE_INFO_UP_CPU.
PSCI_FN_SYSTEM_OFF	PSCI_FN_SYSTEM_OFF.
PSCI_FN_SYSTEM_REST	PSCI_FN_SYSTEM_REST.
PSCI_FN_PSCI_FEATURES	PSCI_FN_PSCI_FEATURES.
PSCI_FN_CPU_FREEZE	PSCI_FN_CPU_FREEZE.
PSCI_FN_CPU_DEFAULT_SUSPEND	PSCI_FN_CPU_DEFAULT_SUSPEND.
PSCI_FN_CPU_DEFAULT_SUSPEND64	PSCI_FN_CPU_DEFAULT_SUSPEND.
PSCI_FN_NODE_HW_STATE	PSCI_FN_NODE_HW_STATE.
PSCI_FN_NODE_HW_STATE64	PSCI_FN_NODE_HW_STATE.
PSCI_FN_SYSTEM_SUPSEND	PSCI_FN_SYSTEM_SUPSEND.
PSCI_FN_SYSTEM_SUPSEND64	PSCI_FN_SYSTEM_SUPSEND.
PSCI_FN_PSCI_SET_SUSPEND_MODE	PSCI_FN_PSCI_SET_SUSPEND_MODE.
PSCI_FN_PSCI_STAT_RESIDENCY	PSCI_FN_PSCI_STAT_RESIDENCY.
PSCI_FN_PSCI_STAT_RESIDENCY64	PSCI_FN_PSCI_STAT_RESIDENCY.
PSCI_FN_PSCI_STAT_COUNT	PSCI_FN_PSCI_STAT_COUNT.
PSCI_FN_PSCI_STAT_COUNT64	PSCI_FN_PSCI_STAT_COUNT.
PSCI_FN_CPU_SUSPEND	PSCI_FN_CPU_SUSPEND.
PSCI_FN_CPU_SUSPEND64	PSCI_FN_CPU_SUSPEND.
PSCI_FN_CPU_OFF	PSCI_FN_CPU_OFF.
PSCI_FN_CPU_ON	PSCI_FN_CPU_ON.
PSCI_FN_CPU_ON64	PSCI_FN_CPU_ON.
PSCI_FN_AFFINITY_INFO	PSCI_FN_AFFINITY_INFO.
PSCI_FN_AFFINITY_INFO64	PSCI_FN_AFFINITY_INFO.
PSCI_FN_MIGRATE	PSCI_FN_MIGRATE.
PSCI_FN_MIGRATE64	PSCI_FN_MIGRATE.
PSCI_FN_MIGRATE_INFO_TYPE	PSCI_FN_MIGRATE_INFO_TYPE.
PSCI_FN_MIGRATE_INFO_UP_CPU	PSCI_FN_MIGRATE_INFO_UP_CPU.
PSCI_FN_MIGRATE_INFO_UP_CPU64	PSCI_FN_MIGRATE_INFO_UP_CPU.
PSCI_FN_SYSTEM_OFF	PSCI_FN_SYSTEM_OFF.
PSCI_FN_SYSTEM_REST	PSCI_FN_SYSTEM_REST.
PSCI_FN_PSCI_FEATURES	PSCI_FN_PSCI_FEATURES.
PSCI_FN_CPU_FREEZE	PSCI_FN_CPU_FREEZE.
PSCI_FN_CPU_DEFAULT_SUSPEND	PSCI_FN_CPU_DEFAULT_SUSPEND.
PSCI_FN_CPU_DEFAULT_SUSPEND64	PSCI_FN_CPU_DEFAULT_SUSPEND.
PSCI_FN_NODE_HW_STATE	PSCI_FN_NODE_HW_STATE.
PSCI_FN_NODE_HW_STATE64	PSCI_FN_NODE_HW_STATE.
PSCI_FN_SYSTEM_SUPSEND	PSCI_FN_SYSTEM_SUPSEND.
PSCI_FN_SYSTEM_SUPSEND64	PSCI_FN_SYSTEM_SUPSEND.
PSCI_FN_PSCI_SET_SUSPEND_MODE	PSCI_FN_PSCI_SET_SUSPEND_MODE.
PSCI_FN_PSCI_STAT_RESIDENCY	PSCI_FN_PSCI_STAT_RESIDENCY.
PSCI_FN_PSCI_STAT_RESIDENCY64	PSCI_FN_PSCI_STAT_RESIDENCY.
PSCI_FN_PSCI_STAT_COUNT	PSCI_FN_PSCI_STAT_COUNT.
PSCI_FN_PSCI_STAT_COUNT64	PSCI_FN_PSCI_STAT_COUNT.

enum psci_migrate_t

Enumerator
PSCI_MIGRATE_CAPABLE	Uniprocessor migrate capable Trusted OS.
PSCI_MIGRATE_NOT_CAPABLE	Uniprocessor not migrate capable Trusted OS.
PSCI_MIGRATE_NOT_PRESENT	Trusted OS is either not present.
PSCI_MIGRATE_INVALID	Invalid migration type.
PSCI_MIGRATE_CAPABLE	Uniprocessor migrate capable Trusted OS.
PSCI_MIGRATE_NOT_CAPABLE	Uniprocessor not migrate capable Trusted OS.
PSCI_MIGRATE_NOT_PRESENT	Trusted OS is either not present.
PSCI_MIGRATE_INVALID	Invalid migration type.

Function Documentation

errval_t psci_affinity_info	(	uintptr_t	target_affinity,
		uint32_t	lowest_affinity_level,
		psci_affinity_t *	ret_info
	)

Enable the caller to request status of an affinity instance.

Parameters

target_affinity	MPDIR of the target cpu
lowest_affinity_level	Denotes the lowest valid affinity level field
ret_info

Returns

errval_t psci_cpu_default_suspend	(	lpaddr_t	entry_point_address,
		uintptr_t	context_id
	)

Will place a core into an IMPLEMENTATION DEFINED low-power state.

Parameters

entry_point_address	Address to be executed when waking up
context_id	Context pointer to be left in x0/r0

Returns

SYS_ERR_OK on success PSCI_ERR_INVALID_ADDRESS

errval_t psci_cpu_freeze

(

void

)

Places the core into an IMPLEMENTATION DEFINED low-power state.

Returns

on success, does not return PSCI_ERR_NOT_SUPPORTED PSCI_ERR_DENIED

errval_t psci_cpu_off

(

void

)

Power down the calling core.

Returns

PSCI_ERR_DENIED on failure The call does not return on success

This call is intended for use in hotplug. A core that is powered down by CPU_OFF can only be powered up again in response to a CPU_ON.

errval_t psci_cpu_on	(	uintptr_t	target_cpu,
		lpaddr_t	entry_point,
		uintptr_t	context_id
	)

Power up a core.

Parameters

target_cpu	MPIDR of the target processors
entry_point	Address at which the core must commence execution
context_id	Value left in x0/r0 when resuming execution

Returns

SYS_ERR_OK on success PSCI_ERR_INVALID_PARAMETERS PSCI_ERR_INVALID_ADDRESS PSCI_ERR_ALREADY_ON PSCI_ERR_ON_PENDING PSCI_ERR_INTERNAL_FAILURE

This call is used to power up cores that either:

• Have not yet been booted into the calling supervisory software.
• Have been previously powered down with a CPU_OFF call.

errval_t psci_cpu_suspend	(	uint32_t	power_state,
		lpaddr_t	entry_point,
		uintptr_t	context_id
	)

Suspend execution on a core or higher level topology node.

Parameters

power_state	the power state to
entry_point	Physical address of the location to resume execution
context_id	Value left in x0/r0 when resuming execution

Returns

SYS_ERR_OK on success PSCI_ERR_INVALID_PARAMTER PSCI_ERR_INVALID_ADDRESS PSCI_ERR_DENIED

This call is intended for use in idle subsystems where the core is expected to return to execution through a wakeup event. See section 5.4.

errval_t psci_features	(	uint32_t	psci_fn_id,
		uint32_t *	ret_feature_flags
	)

Query API to discover whether a specific PSCI function is implemented.

Parameters

psci_fn_id	Function ID for a PSCI Function
ret_feature_flags	Returns a set of feature flags of the function

Returns

SYS_ERR_OK on success PSCI_ERR_NOT_SUPPORTED if the function is not supported or invalid

errval_t psci_migrate

(

uintptr_t

target_cpu

)

Optional. This is used to ask a uniprocessor Trusted OS to migrate its context to a specific core.

Parameters

target_cpu

MPDIR of the target core

Returns

SYS_ERR_OK on success PSCI_ERR_NOT_SUPPORTED PSCI_ERR_INVALID_PARAMETERS PSCI_ERR_DENIED PSCI_ERR_INTERNAL_FAILURE PSCI_ERR_NOT_PRESENT

errval_t psci_migrate_info_type

(

psci_migrate_t *

ret_migrate_type

)

Optional. This function allows a caller to identify the level of multicore support present in the Trusted OS.

Parameters

ret_migrate_type

Migration type capabilities

Returns

SYS_ERR_OK on success PSCI_ERR_NOT_SUPPORTED if the operation is not supported

errval_t psci_migrate_info_up_cpu

(

uintptr_t *

ret_mpdir

)

Optional. For a uniprocessor Trusted OS, this function returns the current resident core.

Parameters

ret_mpdir

MPIDR based value of core where the Trusted OS is resident

Returns

SYS_ERR_OK on success PSCI_ERR_NOT_SUPPORTED if not supported

errval_t psci_node_hw_state	(	uintptr_t	target_cpu,
		uint32_t	power_level,
		psci_node_hw_state_t *	ret_node_hw
	)

This API is intended to return the true HW state of a node in the power domain topology of the system.

Parameters

target_cpu	Target CPU MPDIR
power_level	Power domain level for the node
ret_node_hw	return the power node hw state

Returns

SYS_ERR_OK on success PSCI_ERR_NOT_SUPPORTED PSCI_ERR_INVALID_PARAMETERS

errval_t psci_set_suspend_mode

(

psci_suspend_mode_t

mode

)

This API allows setting the mode used by CPU_SUSPEND to coordinate power states.

Parameters

mode	Mode to put the system in

Returns

SYS_ERR_OK on success, PSCI_ERR_NOT_SUPPORTED PSCI_ERR_INVALID_PARAMETERS PSCI_ERR_DENIED

errval_t psci_stat_count	(	uintptr_t	target_cpu,
		uint32_t	power_state,
		uintptr_t *	count
	)

Return the number of times the platform has used the given power state since cold boot.

Parameters

target_cpu	target CPU MPDIR
power_state	power state to query
count	returns the count

Returns

SYS_ERR_OK

errval_t psci_stat_residency	(	uintptr_t	target_cpu,
		uint32_t	power_state,
		uintptr_t *	ret_residency
	)

Returns the amount of time the platform has spent in the given power state since cold boot.

Parameters

target_cpu	target CPU MPDIR
power_state	power state to query
ret_residency	Returns the amount of time, in microseconds, spent in state

Returns

SYS_ERR_OK

errval_t psci_system_suspend	(	lpaddr_t	entry_point_address,
		uintptr_t	context_id
	)

Used to implement suspend to RAM. The semantics are equivalent to a CPU_SUSPEND to the deepest low-power state.

Parameters

entry_point_address	physical address to be executed when returning
context_id	context id to be stored in x0/r0

Returns

does not retturn on success PSCI_ERR_NOT_SUPPORTED PSCI_ERR_INVALID_ADDRESS PSCI_ERR_ALREADY_ON

errval_t psci_version	(	uint16_t *	major,
		uint16_t *	minor
	)

Return the version of PSCI implemented.

Parameters

major	returns the major version
minor	returns the minor version

Returns

SYS_ERR_OK on success PSCI_ERR_* on failure

Return the version of PSCI implemented. See section 5.3 for more details.

Parameters

major	returns the major version
minor	returns the minor version

Returns

SYS_ERR_OK on success PSCI_ERR_* on failure