-
Notifications
You must be signed in to change notification settings - Fork 9
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
1. Improvements in Base, System Reset and System Suspend service groups #38
Changes from 1 commit
fe195fb
cb6a4d1
9c21032
a568ffe
b6063fa
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
Signed-off-by: Rahul Pathak <[email protected]>
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -9,132 +9,244 @@ ifndef::rootpath[] | |
:rootpath: ./../ | ||
endif::rootpath[] | ||
|
||
=== Service Group - *SYSTEM_SUSPEND* (servicegroup_id: 0x00003) | ||
This service group provides services to put the entire system in a low power | ||
suspend state. All harts except the hart doing system suspend need to be in | ||
the STOPPED state. | ||
=== 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. | ||
|
||
Below if the list of services in this group: | ||
[#table_syssuspend_services] | ||
.SYSTEM_SUSPEND Services | ||
[cols="1, 3, 2", width=100%, align="center", options="header"] | ||
|=== | ||
| Service ID | Service Name | Request Type | ||
| 0x01 | SYSSUSP_ENABLE_NOTIFICATION | NORMAL_REQUEST | ||
| 0x02 | SYSSUSP_GET_ATTRIBUTES | NORMAL_REQUEST | ||
| 0x03 | SYSSUSP_SUSPEND | NORMAL_REQUEST | ||
| 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 https://github.com/riscv-non-isa/riscv-sbi-doc/blob/master/src/ext-sys-suspend.adoc#table_susp_sleep_types[*SBI System Sleep Types*^] | ||
in the RISC-V SBI Specification cite:[SBI] for the `SUSPEND_TYPE` definition. | ||
|
||
[#system-suspend-notifications] | ||
==== Notifications | ||
This service group does not support any event for notification. | ||
|
||
==== Service: *SYSSUSP_ENABLE_NOTIFICATION* | ||
This service allows the AP to subscribe to SYSTEM_SUSPEND service group | ||
notification. The platform can optionally support notifications of events | ||
that may occur in the platform. PuC can send these notification messages to | ||
the AP if they are implemented and the AP has subscribed to them. Supported | ||
events are described in <<system-suspend-notifications>>. | ||
==== Service: SYSSUSP_ENABLE_NOTIFICATION (SERVICE_ID: 0x01) | ||
This service allows the application processor to subscribe to `SYSTEM_SUSPEND` | ||
service group defined events for notification. The platform can optionally | ||
support notifications of events that may occur in the platform. The platform | ||
microcontroller can send these notification messages to the application | ||
processor if they are implemented and the application processor has subscribed | ||
to them. Supported events are described in <<system-suspend-notifications>>. | ||
|
||
[#table_syssuspend_ennotification_request_data] | ||
.Request Data | ||
[cols="1, 2, 1, 7", width=100%, align="center", options="header"] | ||
|=== | ||
| Word | Name | Type | Description | ||
| 0 | EVENT_ID | uint32 | Event to be subscribed for | ||
notification. | ||
| Word | ||
| Name | ||
| Type | ||
| Description | ||
|
||
| 0 | ||
| EVENT_ID | ||
| uint32 | ||
| Event to be subscribed for notification. | ||
|=== | ||
|
||
[#table_syssuspend_ennotification_response_data] | ||
.Response Data | ||
[cols="1, 2, 1, 7a", width=100%, align="center", options="header"] | ||
|=== | ||
| Word | Name | Type | Description | ||
| 0 | STATUS | int32 | Return Status Code | ||
[cols="5,5"] | ||
| Word | ||
| Name | ||
| Type | ||
| Description | ||
|
||
| 0 | ||
| STATUS | ||
| int32 | ||
| Return Status Code | ||
|
||
[cols="6,5a", options="header"] | ||
!=== | ||
! *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. | ||
! Error Code | ||
! Description | ||
|
||
! RPMI_SUCCESS | ||
! Notifications are subscribed successfully. | ||
|
||
! RPMI_ERROR_NOT_FOUND | ||
! `EVENT_ID` is not supported or invalid. | ||
|
||
! RPMI_ERROR_NOT_SUPPORTED | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
! Notifications not supported. | ||
!=== | ||
- Other errors <<table_error_codes>> | ||
|=== | ||
|
||
==== Service: *SYSSUSP_GET_ATTRIBUTES* | ||
This service is used to discover the SYSTEM_SUSPEND attributes with a specific | ||
SUSPEND_TYPE. | ||
==== Service: SYSSUSP_GET_ATTRIBUTES (SERVICE_ID: 0x02) | ||
This service is used to discover the attributes of a `SUSPEND_TYPE`. | ||
|
||
[#table_syssuspend_getsyssuspendattrs_request_data] | ||
.Request Data | ||
[cols="1, 2, 1, 7a", width=100%, align="center", options="header"] | ||
|=== | ||
| Word | Name | Type | Description | ||
| 0 | SUSPEND_TYPE | uint32 | Suspend type value. + | ||
Refer to https://github.com/riscv-non-isa/riscv-sbi-doc/blob/master/src/ext-sys-suspend.adoc#table_susp_sleep_types[*SUSP System Sleep Types*^] | ||
in the RISC-V SBI Specification cite:[SBI] for the SUSPEND_TYPE definition. | ||
| Word | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. font size looks okay after update doc-resources |
||
| Name | ||
| Type | ||
| Description | ||
|
||
| 0 | ||
| SUSPEND_TYPE | ||
| uint32 | ||
| Suspend type + | ||
Refer <<Suspend Types, Suspend Types>> section for supported suspend types. | ||
|=== | ||
|
||
[#table_syssuspend_getsysuspendattrs_response_data] | ||
.Response Data | ||
[cols="1, 2, 1, 7a", width=100%, align="center", options="header"] | ||
|=== | ||
| Word | Name | Type | Description | ||
| 0 | STATUS | int32 | Return Status Code | ||
[cols="5,5a"] | ||
| Word | ||
| Name | ||
| Type | ||
| Description | ||
|
||
| 0 | ||
| STATUS | ||
| int32 | ||
| Return Status Code | ||
|
||
[cols="5,5a", options="header"] | ||
!=== | ||
! *Error Code* ! *Description* | ||
! RPMI_SUCCESS ! Attributes returned successfully. | ||
! Error Code | ||
! Description | ||
|
||
! RPMI_SUCCESS | ||
! Attributes returned successfully. | ||
!=== | ||
- Other errors <<table_error_codes>> | ||
| 1 | FLAGS | uint32 | Attributes of the SUSPEND_TYPE | ||
[cols="2,5a"] | ||
|
||
| 1 | ||
| FLAGS | ||
| uint32 | ||
| Attributes of the `SUSPEND_TYPE` | ||
|
||
[cols="2,5a", options="header"] | ||
!=== | ||
! *Bits* ! *Description* | ||
! [31] ! | ||
! Bits | ||
! Description | ||
|
||
! [31:2] | ||
! _Reserved, must be initialized to_ `0`. | ||
|
||
0b0: Custom resume address not supported. | ||
0b1: Custom resume address supported. | ||
! [30] ! | ||
! [1] ! Resume Address Support + | ||
If a `SUSPEND_TYPE` supports custom resume address | ||
which platform must configure for the resuming application processor. | ||
|
||
0b0: Suspend not supported | ||
0b1: Suspend supported | ||
! [29:0] ! _Reserved, must be initialized to_ `0`. | ||
0b1: Supported. | ||
0b0: Not supported. | ||
! [0] ! `SUSPEND_TYPE` Support | ||
|
||
0b1: Supported | ||
0b0: Not supported | ||
|
||
!=== | ||
|=== | ||
|
||
==== Service: *SYSSUSP_SUSPEND* | ||
This service puts the system into low power state based on the specified suspend | ||
type. It requires that all harts except the calling hart to be in the STOPPED | ||
state as defined by the Hart State Management service group. The system | ||
transitions into the low power state only after the requesting hart executes | ||
the WFI instruction. | ||
==== 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 if the platform | ||
microcontroller accepts the system suspend request. The application processor | ||
which called this service must enter into the WFI state by executing the `WFI` | ||
instruction. The platform microcontroller will transition the system to the | ||
requested `SUSPEND_STATE` upon the successful WFI state transition of the | ||
application processor. | ||
|
||
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 which the | ||
application processor can discover by the `SYSSUSP_GET_ATTRIBUTES` service | ||
then the `RESUME_ADDR_LOW` and `RESUME_ADDR_HIGH` will be ignored and the | ||
application processor in WFI state will resume from the `pc` (program counter) | ||
after the `WFI` instruction. | ||
|
||
[#table_syssuspend_syssuspend_request_data] | ||
.Request Data | ||
[cols="1, 3, 1, 7a", width=100%, align="center", options="header"] | ||
|=== | ||
| Word | Name | Type | Description | ||
| 0 | HART_ID | uint32 | Hart ID of the calling hart. | ||
| 1 | SUSPEND_TYPE | uint32 | Suspend type value. + | ||
Refer to https://github.com/riscv-non-isa/riscv-sbi-doc/blob/master/src/ext-sys-suspend.adoc#table_susp_sleep_types[*SUSP System Sleep Types*^] | ||
in the RISC-V SBI Specification cite:[SBI] for the SUSPEND_TYPE definition. | ||
| 2 | RESUME_ADDR_LOW | uint32 | Lower `32 bits` address | ||
| 3 | RESUME_ADDR_HIGH | uint32 | Upper `32 bits` address | ||
| Word | ||
| Name | ||
| Type | ||
| Description | ||
|
||
| 0 | ||
| HART_ID | ||
| uint32 | ||
| Hart ID of the calling hart. | ||
|
||
| 1 | ||
| SUSPEND_TYPE | ||
| uint32 | ||
| Suspend type. + | ||
Refer <<Suspend Types, Suspend Types>> section for supported suspend types. | ||
|
||
| 2 | ||
| RESUME_ADDR_LOW | ||
| uint32 | ||
| Lower `32 bits` address | ||
|
||
| 3 | ||
| RESUME_ADDR_HIGH | ||
| uint32 | ||
| Upper `32 bits` address | ||
|=== | ||
|
||
[#table_syssuspend_syssuspend_response_data] | ||
.Response Data | ||
[cols="1, 3, 1, 7a", width=100%, align="center", options="header"] | ||
[cols="1, 2, 1, 7a", width=100%, align="center", options="header"] | ||
|=== | ||
| Word | Name | Type | Description | ||
| 0 | STATUS | int32 | Return Status Code | ||
[cols="6,5"] | ||
| Word | ||
| Name | ||
| Type | ||
| Description | ||
|
||
| 0 | ||
| STATUS | ||
| int32 | ||
| Return Status Code | ||
|
||
[cols="6,5a", options="header"] | ||
!=== | ||
! *Error Code* ! *Description* | ||
! RPMI_ERROR_NOT_SUPPORTED ! SUSPEND_TYPE is not supported. The AP must use the | ||
SYSSUSP_GET_ATTRIBUTES service to determine if SUSPEND_TYPE is supported | ||
or not. Only supported SUSPEND_TYPE must be used with this service. | ||
! Error Code | ||
! Description | ||
|
||
! RPMI_SUCCESS | ||
! Service completed successfully. Suspend request has been accepted. | ||
|
||
! RPMI_ERROR_NOT_SUPPORTED | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. other services has RPMI_SUCCESS for success, need have this error code for all services? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
! `SUSPEND_TYPE` is not supported. | ||
!=== | ||
- Other errors <<table_error_codes>> | ||
|=== |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This table should move to before the "Suspend Types" sub-section. It is under chapter "4.3.1. Suspend Types" now.