srvgrp-hart-state-management.adoc

Service Group - HART_STATE_MANAGEMENT (servicegroup_id: 0x00004)

The Hart State Management (HSM) service group defines a set of Hart states and functionality equivalent to the RISC-V SBI HSM extension.

Below table lists the services in this group:

Table 1. Hart State Management Services

Service ID	Service Name	Request Type
0x01	ENABLE_NOTIFICATION	NORMAL_REQUEST
0x02	HART_START	NORMAL_REQUEST
0x03	HART_STOP	NORMAL_REQUEST
0x04	HART_SUSPEND	NORMAL_REQUEST
0x05	GET_HART_STATUS	NORMAL_REQUEST
0x06	GET_HART_LIST	NORMAL_REQUEST
0x07	GET_SUSPEND_TYPES	NORMAL_REQUEST
0x08	GET_SUSPEND_INFO	NORMAL_REQUEST

Hart State Management Notifications

This service group does not support any event for notification

Service: ENABLE_NOTIFICATION

This service allows AP to subscribe to system reset service group notifications. Platform can optionally support notifications of events which might occur in the platform. PuC can send these notification messages to AP if they are implemented and AP has subscribed to these. Events supported are described above in Hart State Management Notifications.

Table 2. Request Data

Word	Name	Type	Description
0	EVENT_ID	uint32	Event to be subscribed for notification.

Table 3. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Notifications are subscribed successfully. RPMI_ERROR_NOT_FOUND EVENT_ID is not supported or invalid. RPMI_ERROR_NOT_SUPPORTED Notifications not supported. Other errors [table_error_codes]

Service: HART_START

This service helps start (or power up) a hart with a specified hart-id. Successful completion of this service means that hart with specified hart-id has started execution from the provided start address. The previous state of the hart before this service was called is platform specific. It’s possible that hart was already started or hart with specified hart-id does not exist. Implementation should return proper error code in the status field accordingly.

Table 4. Request Data

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

Table 5. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Service completed successfully and hart is started. RPMI_ERROR_INVALID_PARAMETER HART_ID is invalid. Other errors [table_error_codes]

Service: HART_STOP

This service stops the calling hart. Mechanism to stop the hart is platform specific. Hart can be powered down if supported or it can be put into a deepest sleep state supported. Platform must acknowledge that hart can be stopped and return success. Application Processor must execute WFI upon successful acknowledgement. Platform then proceeds to stop the hart. Detecting the WFI state from PuC is implementation defined. Once the hart is stopped it can only be started using an explicit HART_START service call from the application processor.

Table 6. Request Data

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

Table 7. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Service completed successfully and hart is started. RPMI_ERROR_DENIED Not allowed due to current hart state which is platform specific Other errors [table_error_codes]

Service: HART_SUSPEND

This service puts the calling hart in suspended (or low power) state. Upon success, the calling hart is suspended only after it executes WFI instruction.

Table 8. Request Data

Word	Name	Type	Description
0	HART_ID	uint32	Hart ID of the calling hart.
1	SUSPEND_TYPE	uint32	Hart suspend type as defined by RISC-V SBI Extension[[TODO LINK HERE]]
2	RESUME_ADDR_LOW	uint32	Lower 32 bit of resume address. Only used for non-retentive suspend types.
3	RESUME_ADDR_HIGH	uint32	Higher 32 bit of resume address. Only used for non-retentive suspend types.

Table 9. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Service completed successfully and hart is started. RPMI_ERROR_INVALID_PARAMETER Invalid SUSPEND_TYPE. Other errors [table_error_codes]

Service: GET_HART_STATUS

This service gets the running status of a Hart.

Table 10. Request Data

Word	Name	Type	Description
0	HART_ID	uint32	Hart ID.

Table 11. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Notifications are subscribed successfully. RPMI_ERROR_INVALID_PARAMETER Invalid HART_ID. Other errors [table_error_codes]
1	HART_STATUS	uint32	Hart status values Value Description 0x0 STARTED 0x1 STOPPED 0x2 START_PENDING 0x3 STOP_PENDING 0x4 SUSPENDED 0x5 RESUME_PENDING 0x6 - 0xFFFFFFFF Reserved

Service: GET_HART_LIST

This service gets the list of harts with a specified Hart ID start index

Table 12. Request Data

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

Table 13. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Notifications are subscribed successfully. RPMI_ERROR_INVALID_PARAMETER Invalid START_INDEX. Other errors [table_error_codes]
1	REMAINING	uint32	Number of remaining items in the list pending to be returned.
2	RETURNED	uint32	Total number of items returned so far.
3	HART_ID[0]	uint32	HART_ID
4	HART_ID[1]	uint32	HART_ID
5	HART_ID[N - 1]	uint32	HART_ID

Service: GET_SUSPEND_TYPES

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

Table 14. Request Data

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

Table 15. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Notifications are subscribed successfully. RPMI_ERROR_INVALID_PARAMETER Invalid START_INDEX. Other errors [table_error_codes]
1	REMAINING	uint32	Number of remaining items in the list pending to be returned.
2	RETURNED	uint32	Total number of items returned so far.
3	SUSPEND_TYPE[0]	uint32	Suspend Type
4	SUSPEND_TYPE[1]	uint32	Suspend Type
5	SUSPEND_TYPE[N - 1]	uint32	Suspend Type

Service: GET_SUSPEND_INFO

Get attributes of a suspend type.

Table 16. Request Data

Word	Name	Type	Description
0	SUSPEND_TYPE	uint32	Suspend type.

Table 17. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Notifications are subscribed successfully. RPMI_ERROR_INVALID_PARAMETER Invalid SUSPEND_TYPE. Other errors [table_error_codes]
1	FLAGS	uint32	Bits Description [31] 0b0: Counter does not stop if this bit is cleared. 0b1: Local timer stops when the hart is suspended if this bit is set. [30:0] Reserved, must be initialized to 0.
2	ENTRY_LATENCY_US	uint32	Entry latency in microseconds.
3	EXIT_LATENCY_US	uint32	Exit latency in microseconds.
4	WAKEUP_LATENCY_US	uint32	Wakeup latency in microseconds.
5	MIN_RESIDENCY_US	uint32	Minimum residency latency in microseconds.