srvgrp-hart-state-management.adoc

Service Group - HART_STATE_MANAGEMENT (SERVICEGROUP_ID: 0x0004)

This service group defines services to control and manage the application processor (hart) power states. Hart power states include power on, power off, suspend modes, etc. A hart is identified by a 32-bit identifier called HART_ID.

In a platform, depending on the sharing of power controls and common resources, the harts can be grouped in a hierarchical topology to form cores, clusters, nodes, etc. In such cases the power state change for a hart can affect the entire hierarchical group in which the hart is located, requiring coordination for the power state change. RPMI supports the coordination mechanisms and hart power states defined by the RISC-V SBI Specification cite:[SBI].

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

Table 1. HART_STATE_MANAGEMENT Services

Service ID	Service Name	Request Type
0x01	HSM_ENABLE_NOTIFICATION	NORMAL_REQUEST
0x02	HSM_GET_HART_STATUS	NORMAL_REQUEST
0x03	HSM_GET_HART_LIST	NORMAL_REQUEST
0x04	HSM_GET_SUSPEND_TYPES	NORMAL_REQUEST
0x05	HSM_GET_SUSPEND_INFO	NORMAL_REQUEST
0x06	HSM_HART_START	NORMAL_REQUEST
0x07	HSM_HART_STOP	NORMAL_REQUEST
0x08	HSM_HART_SUSPEND	NORMAL_REQUEST

Hart States

Hart HSM states and the HSM state machine supported by the RPMI are defined in the RISC-V SBI Specification cite:[SBI]. Refer to HSM States.

From a hart perspective a start state means hart has started execution of instructions and stop state means that hart is not executing the instructions. The platform can implement the stop state either by powering down the hart or just putting the hart in a platform supported low-power state.

Hart Suspend Types

The RPMI supports the hart suspend types encoding as defined in RISC-V SBI Specification cite:[SBI]. Refer to HSM Suspend Types. The values for the platform supported suspend types are discovered through a service defined in this service group.

Notifications

This service group does not support any events for notification.

Service: HSM_ENABLE_NOTIFICATION (SERVICE_ID: 0x01)

This service allows the application processor to subscribe to HART_STATE_MANAGEMENT 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: HSM_GET_HART_STATUS (SERVICE_ID: 0x02)

This service returns the current HSM state of a hart. If a hart is in an invalid state that is not a defined HSM state, an error code will be set in the STATUS field.

Table 4. Request Data

Word	Name	Type	Description
0	HART_ID	uint32	Hart ID

Table 5. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code Error Code Description RPMI_SUCCESS Service completed successfully. RPMI_ERR_INVALID_PARAM HART_ID is invalid. RPMI_ERR_INVALID_STATE Hart is in invalid state. Other errors [table_error_codes]
1	HART_STATE	uint32	Hart state. See Hart States for more details.

Service: HSM_GET_HART_LIST (SERVICE_ID: 0x03)

This service retrieves the list of Hart IDs managed by this service group.

If the number of words required for all available Hart IDs exceeds the number of words that can be returned in one acknowledgement message then the platform microcontroller will set the REMAINING and RETURNED fields accordingly and only return the Hart IDs which can be accommodated. The application processor may need to call this service again with the appropriate START_INDEX until the REMAINING field returns 0.

Table 6. Request Data

Word	Name	Type	Description
0	START_INDEX	uint32	Start index of the Hart ID.

Table 7. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code Error Code Description RPMI_SUCCESS Service completed successfully. RPMI_ERR_INVALID_PARAM START_INDEX is invalid. Other errors [table_error_codes]
1	REMAINING	uint32	Remaining number of Hart IDs to be returned.
2	RETURNED	uint32	Number of Hart IDs returned in this request.
3	HART_ID[N]	uint32	Hart IDs

Service: HSM_GET_SUSPEND_TYPES (SERVICE_ID: 0x04)

This service gets the list of all supported suspend types for a hart. The suspend types in the list must be ordered based on increasing power savings.

If the number of words required for all available suspend types exceeds the number of words that can be returned in one acknowledgement message then the platform microcontroller will set the REMAINING and RETURNED fields accordingly and only return the suspend types which can be accommodated. The application processor may need to call this service again with the appropriate START_INDEX until the REMAINING field returns 0.

The attributes and details of each suspend type can be discovered using the HSM_GET_SUSPEND_INFO service.

Table 8. Request Data

Word	Name	Type	Description
0	START_INDEX	uint32	Start index of the Hart ID. 0 for the first call, subsequent calls will use the next index of the remaining items.

Table 9. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code Error Code Description RPMI_SUCCESS Service completed successfully. RPMI_ERR_INVALID_PARAM START_INDEX is invalid. Other errors [table_error_codes]
1	REMAINING	uint32	Remaining number of suspend types to be returned.
2	RETURNED	uint32	Number of suspend types returned in this request.
3	SUSPEND_TYPE[N]	uint32	Suspend types. See Hart Suspend Types for more details.

Service: HSM_GET_SUSPEND_INFO (SERVICE_ID: 0x05)

This service is used to get the attributes of a suspend type.

Table 10. Request Data

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

Table 11. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code Error Code Description RPMI_SUCCESS Service completed successfully. RPMI_ERR_INVALID_PARAM SUSPEND_TYPE is invalid. Other errors [table_error_codes]
1	FLAGS	uint32	Bits Description [31: 1] Reserved, must be initialized to 0. [0] Local timer running status 0b1: Local timer stops when the hart is suspended. 0b0: Local timer does not stop when hart is suspended.
2	ENTRY_LATENCY	uint32	Entry latency in microseconds.
3	EXIT_LATENCY	uint32	Exit latency in microseconds.
4	WAKEUP_LATENCY	uint32	Wakeup latency in microseconds.
5	MIN_RESIDENCY	uint32	Minimum residency time in microseconds.

Service: HSM_HART_START (SERVICE_ID: 0x06)

This service is used to start the execution on a hart identified by HART_ID. This service requires a start address which is the physical address from which the target hart will start execution. Successful completion of this service means that the hart has started execution from the specified start address.

Table 12. Request Data

Word	Name	Type	Description
0	HART_ID	uint32	Hart ID of the target hart to be started.
1	START_ADDR_LOW	uint32	Lower 32-bit of the start address.
2	START_ADDR_HIGH	uint32	Upper 32-bit of the start address.

Table 13. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code Error Code Description RPMI_SUCCESS Service completed successfully and hart has started. RPMI_ERR_INVALID_PARAM HART_ID or start address is invalid. RPMI_ERR_ALREADY Hart is already in transition to start state or has already started. RPMI_ERR_DENIED Hart is not in stopped state. RPMI_ERR_HW_FAULT Failed due to hardware fault. Other errors [table_error_codes]

Service: HSM_HART_STOP (SERVICE_ID: 0x07)

This service stops the execution on the calling hart. The mechanism for stopping the hart is platform specific. The hart can be powered down, if supported, or put into the deepest available sleep state.

This service returns successful if the platform microcontroller has successfully acknowledged that the target hart can be stopped. The hart upon successful acknowledgement can perform the final context saving if required and must enter into a quiesced state such as WFI which can be detected and allow the platform microcontroller to proceed to stop the hart. The mechanism to detect the hart quiesced state by the platform microcontroller is platform specific.

Once the hart is stopped, it can only be restarted by explicitly invoking the HSM_HART_START service call explicitly by any other hart.

Table 14. Request Data

Word	Name	Type	Description
0	HART_ID	uint32	Hart ID of the calling hart.

Table 15. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code Error Code Description RPMI_SUCCESS Service completed successfully and hart is stopped. RPMI_ERR_ALREADY Hart is already in transition to stop state or has already stopped. RPMI_ERR_DENIED Hart is not in start state. RPMI_ERR_HW_FAULT Failed due to hardware failure. Other errors [table_error_codes]

Service: HSM_HART_SUSPEND (SERVICE_ID: 0x08)

This service is used to put a hart in a low power suspend state supported by the platform. Each suspend type is a 32-bit value which is discovered through the HSM_GET_SUSPEND_TYPES service.

This service returns successful if the platform microcontroller has successfully acknowledged that the target hart can be put into the requested SUSPEND_TYPE state. The target hart after the successful acknowledgement must enter into a quiesced state such as WFI which can be detected and allow the platform microcontroller complete the suspend state transition. The mechanism to detect the hart quiesced state by the platform microcontroller is platform specific.

For non-retentive suspend state the hart will resume its execution from the provided resume address.

Table 16. Request Data

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

Table 17. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code Error Code Description RPMI_SUCCESS Service completed successfully. RPMI_ERR_INVALID_PARAM HART_ID or SUSPEND_TYPE is invalid. Other errors [table_error_codes]