Skip to content
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

Merged
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
System Suspend service group improvements
Signed-off-by: Rahul Pathak <[email protected]>
pathakraul committed Aug 21, 2024
commit cb6a4d1696dde3252e2ce4e0b0f995edc51f3c69
246 changes: 179 additions & 67 deletions src/srvgrp-system-suspend.adoc
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
Copy link
Collaborator

@lftan lftan Aug 13, 2024

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.

| 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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adjust the table column width to fix the whole text in one line.

In SYSSUSP_ENABLE_NOTIFICATION table:
image

! 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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in the new pdf, font size of italic text is look bigger than other text. This can be changed?
image

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are relying on the format theme coming from the docs_resource submodule.

I think your repo has not the updated docs_resources folder. This is how it currently looks
image

Copy link
Collaborator

Choose a reason for hiding this comment

The 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
Copy link
Collaborator

Choose a reason for hiding this comment

The 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?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

here also, make it one line.

image

! `SUSPEND_TYPE` is not supported.
!===
- Other errors <<table_error_codes>>
|===