srvgrp-system-suspend.adoc

Service Group - SYSTEM_SUSPEND (SERVICEGROUP_ID: 0x0003)

This service group defines services used to request platform microcontroller to transition the system into a suspend state, also called a sleep state. The suspend state SUSPEND_TO_RAM is supported by default by the platform and if the application processor requests for SUSPEND_TO_RAM, it’s implicit for the platform microcontroller that all the application processors except the one requesting are in STOPPED state and necessary state saving in the RAM has been complete.

The following table lists the services in the SYSTEM_SUSPEND service group:

Table 1. SYSTEM_SUSPEND Services

Service ID	Service Name	Request Type
0x01	SYSSUSP_ENABLE_NOTIFICATION	NORMAL_REQUEST
0x02	SYSSUSP_GET_ATTRIBUTES	NORMAL_REQUEST
0x03	SYSSUSP_SUSPEND	NORMAL_REQUEST

Suspend Types

RPMI supports suspend types and their values as defined by SBI specification. Refer to SBI System Sleep Types in the RISC-V SBI Specification cite:[SBI] for the SUSPEND_TYPE definition.

Notifications

This service group does not support any events for notification.

Service: SYSSUSP_ENABLE_NOTIFICATION (SERVICE_ID: 0x01)

This service allows the application processor to subscribe to SYSTEM_SUSPEND service group notifications. The platform may optionally support notifications for events that may occur. The platform microcontroller can send these notification messages to the application processor if they are implemented and the application processor has subscribed to them. The supported events are described in Notifications.

Table 2. Request Data

Word	Name	Type	Description
0	EVENT_ID	uint32	The event to be subscribed for notification.
1	REQ_STATE	uint32	Requested event notification state Change or query the current state of EVENT_ID notification. 0: Disable 1: Enable 2: Return current state. Any other values of REQ_STATE field other than the defined ones are reserved for future use.

Table 3. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code Error Code Description RPMI_SUCCESS Event is subscribed successfully. RPMI_ERR_INVALID_PARAM EVENT_ID or REQ_STATE is invalid. RPMI_ERR_NOT_SUPPORTED Notification is not supported. Other errors [table_error_codes]
1	CURRENT_STATE	uint32	Current EVENT_ID notification state 0: Notification is disabled 1: Notification is enabled. In case of REQ_STATE = 0 or 1, the CURRENT_STATE will return the requested state. In case of an error, the value of CURRENT_STATE is unspecified.

Service: SYSSUSP_GET_ATTRIBUTES (SERVICE_ID: 0x02)

This service is used to discover the attributes of a suspend type. The attribute flags for a suspend type indicate whether a SUSPEND_TYPE is supported. Additionally, the flags specify whether a SUSPEND_TYPE supports a resume address.

Table 4. Request Data

Word	Name	Type	Description
0	SUSPEND_TYPE	uint32	Suspend type. See Suspend Types for more details.

Table 5. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code Error Code Description RPMI_SUCCESS Attributes returned successfully. Other errors [table_error_codes]
1	FLAGS	uint32	Attributes of the SUSPEND_TYPE Bits Description [31:2] Reserved and must be 0. [1] Resume Address Support If a SUSPEND_TYPE supports custom resume address which platform must configure for the resuming application processor. 0b1: Supported. 0b0: Not supported. [0] SUSPEND_TYPE Support 0b1: Supported 0b0: Not supported

Service: SYSSUSP_SUSPEND (SERVICE_ID: 0x03)

This service is used to request the platform microcontroller to transition the system in a suspend state. This service returns successfully when the platform microcontroller accepts the system suspend request. The application processor which called this service must then enter into a quiesced state such as WFI. The platform microcontroller will transition the system to the requested SUSPEND_STATE upon the successful transition of the application processor into the supported quiesced state. The mechanism for detecting the quiesced state of the application processor is platform specific.

The application processor must only request supported suspend types, discovered using the SYSSUSP_GET_ATTRIBUTES service.

If a suspend type does not support the custom resume address that the application processor can discover through the SYSSUSP_GET_ATTRIBUTES service then the RESUME_ADDR_LOW and RESUME_ADDR_HIGH will be ignored and the application processor will resume from the pc (program counter) after the instruction that put the application processor in the quiesced state, such as the WFI instruction.

Table 6. Request Data

Word	Name	Type	Description
0	HART_ID	uint32	Hart ID of the calling hart.
1	SUSPEND_TYPE	uint32	Suspend type. See Suspend Types for more details.
2	RESUME_ADDR_LOW	uint32	Lower 32-bit address.
3	RESUME_ADDR_HIGH	uint32	Upper 32-bit address.

Table 7. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code Error Code Description RPMI_SUCCESS Service completed successfully. Suspend request has been accepted. RPMI_ERR_INVALID_PARAM HART_ID or SUSPEND_TYPE is invalid. RPMI_ERR_INVALID_ADDR Resume address is invalid. Other errors [table_error_codes]