The HSM suspend function will bring new HSM states and more tables.

This patch improves HSM documentation so that adding new HSM states
is straight forward and we can cross-reference tables from HSM function
documentation.

Signed-off-by: Anup Patel <anup.patel@...>
---
riscv-sbi-theme.yml | 3 +
riscv-sbi.adoc | 132 +++++++++++++++++++++++++-------------------
2 files changed, 79 insertions(+), 56 deletions(-)

diff --git a/riscv-sbi-theme.yml b/riscv-sbi-theme.yml
index c9a03b9..ce00e22 100644
--- a/riscv-sbi-theme.yml
+++ b/riscv-sbi-theme.yml
@@ -3,3 +3,6 @@ image:
align: center
caption:
align: center
+table:
+ caption:
+ side: bottom
diff --git a/riscv-sbi.adoc b/riscv-sbi.adoc
index d7401fa..a4c3be3 100644
--- a/riscv-sbi.adoc
+++ b/riscv-sbi.adoc
@@ -668,27 +668,46 @@ The Hart State Management (HSM) Extension introduces a set hart states and a
set of functions which allow the supervisor-mode software to request a hart
state change.

-The possible hart states are as follows:
-
-* **STOPPED:** The hart is not executing in supervisor-mode or any lower
- privilege mode. It is probably powered-down by the SBI implementation
- if the underlying platform has a mechanism to physically power-down harts.
-* **STARTED:** The hart is physically powered-up and executing normally.
-* **START_PENDING:** Some other hart has requested to start (or power-up)
- the hart from the **STOPPED** state and the SBI implementation is still
- working to get the hart in the **STARTED** state.
-* **STOP_PENDING:** The hart has requested to stop (or power-down) itself
- from the **STARTED** state and the SBI implementation is still working
- to get the hart in the **STOPPED** state.
+The <<table_hsm_states>> shown below describes all possible **HSM states**
+along with a unique **HSM state id** for each state:
+
+[#table_hsm_states]
+.HSM Hart States
+[cols="1,2,4", width=100%, align="center", options="header"]
+|===
+| State ID | State Name | Description
+| 0 | STARTED | The hart is physically powered-up and executing
+ normally.
+| 1 | STOPPED | The hart is not executing in supervisor-mode
+ or any lower privilege mode. It is probably
+ powered-down by the SBI implementation if the
+ underlying platform has a mechanism to
+ physically power-down harts.
+| 2 | START_PENDING | Some other hart has requested to start (or
+ power-up) the hart from the **STOPPED** state
+ and the SBI implementation is still working to
+ get the hart in the **STARTED** state.
+| 3 | STOP_PENDING | The hart has requested to stop (or power-down)
+ itself from the **STARTED** state and the SBI
+ implementation is still working to get the hart
+ in the **STOPPED** state.
+|===

At any point in time, a hart should be in one of the above mentioned hart
states. The hart state transitions by the SBI implementation should follow
-the state machine shown below in the figure <<fig_hsm>>.
+the state machine shown below in the <<figure_hsm>>.

-[#fig_hsm]
+[#figure_hsm]
.SBI HSM State Machine
image::riscv-sbi-hsm.png[]

+A platform can have multiple harts grouped into a cluster with separate power
+and clock. The HSM states are only hart level states and does not imply any
+thing about the cluster level states. The SBI implementation can incorporate
+a plaform specific cluster level state transitions but SBI implementation
+must ensure that there is no impact on hart level state transition latency
+due to implicit cluster level state transitions.
+
=== Function: HART start (FID #0)

[source, C]
@@ -698,13 +717,29 @@ struct sbiret sbi_hart_start(unsigned long hartid,
unsigned long opaque)
----

-Request the SBI implementation to start executing the given hart at specified
-address in supervisor-mode. This call is asynchronous -- more specifically,
-the `sbi_hart_start()` may return before target hart starts executing as long
-as the SBI implemenation is capable of ensuring the return code is accurate.
-It is recommended that if the SBI implementation is a platform runtime
-firmware executing in machine-mode (M-mode) then it MUST configure PMP and
-other the M-mode state before executing in supervisor-mode.
+Request the SBI implementation to start executing the target hart in
+supervisor-mode at address specified by `start_addr` parameter with
+specific registers values described in the <<table_hsm_hart_start_regs>>
+below.
+
+[#table_hsm_hart_start_regs]
+.HSM Hart Start Register State
+[cols=",", width=80%, align="center", options="header"]
+|===
+|Register Name | Register Value
+|satp | 0
+|sstatus.SIE | 0
+|a0 | hartid
+|a1 | `opaque` parameter
+2+|All other registers remain in an undefined state.
+|===
+
+This call is asynchronous -- more specifically, the `sbi_hart_start()` may
+return before target hart starts executing as long as the SBI implemenation
+is capable of ensuring the return code is accurate. It is recommended that
+if the SBI implementation is a platform runtime firmware executing in
+machine-mode (M-mode) then it MUST configure PMP and other the M-mode
+state before executing in supervisor-mode.

The `hartid` parameter specifies the target hart which is to be started.

@@ -715,8 +750,10 @@ The `opaque` parameter is a XLEN-bit value which will be set in the `a1`
register when the hart starts executing at `start_addr`.

The possible error codes returned in `sbiret.error` are shown in the
-table below:
+<<table_hsm_hart_start_errors>> below.

+[#table_hsm_hart_start_errors]
+.HSM Hart Start Errors
[cols="1,2", width=100%, align="center", options="header"]
|===
| Error code | Description
@@ -733,20 +770,6 @@ table below:
| SBI_ERR_FAILED | The start request failed for unknown reasons.
|===

-The target hart jumps to supervisor-mode at address specified by `start_addr`
-with following values in specific registers.
-
-[cols=",", width=50%, align="center", options="header"]
-|===
-|Register Name | Register Value
-|satp | 0
-|sstatus.SIE | 0
-|a0 | hartid
-|a1 | opaque
-|===
-
-All other registers remain in an undefined state.
-
=== Function: HART stop (FID #1)

[source, C]
@@ -761,8 +784,10 @@ This call is not expected to return under normal conditions. The
disabled.

The possible error codes returned in `sbiret.error` are shown in the
-table below:
+<<table_hsm_hart_stop_errors>> below.

+[#table_hsm_hart_stop_errors]
+.HSM Hart Stop Errors
[cols="1,2", width=100%, align="center", options="header"]
|===
| Error code | Description
@@ -776,26 +801,19 @@ table below:
struct sbiret sbi_hart_get_status(unsigned long hartid)
----

-Get the current status (or HSM state) of the given hart in `sbiret.value`,
+Get the current status (or HSM state id) of the given hart in `sbiret.value`,
or an error through `sbiret.error`.

The `hartid` parameter specifies the target hart which is to be started.

-The possible status values returned in `sbiret.value` are shown in the
-table below:
-
-[cols="2,1,2", width=80%, align="center", options="header"]
-|===
-| Name | Value | Description
-| STARTED | 0 | Hart Started
-| STOPPED | 1 | Hart Stopped
-| START_PENDING | 2 | Hart start request pending
-| STOP_PENDING | 3 | Hart stop request pending
-|===
+The possible status (or HSM state id) values returned in `sbiret.value`
+are described in <<table_hsm_states>>.

The possible error codes returned in `sbiret.error` are shown in the
-table below:
+<<table_hsm_hart_get_status_errors>> below.

+[#table_hsm_hart_get_status_errors]
+.HSM Hart Get Status Errors
[cols="1,2", width=100%, align="center", options="header"]
|===
| Error code | Description
@@ -803,18 +821,20 @@ table below:
|===

The harts may transition HSM states at any time due to any concurrent
-`sbi_hart_start` or `sbi_hart_stop` calls, the return value from this
+`sbi_hart_start()` or `sbi_hart_stop()` calls, the return value from this
function may not represent the actual state of the hart at the time of
return value verification.

=== Function Listing

-[cols="3,1,1", width=70%, align="center", options="header"]
+[#table_hsm_function_list]
+.HSM Function List
+[cols="3,2,1,2", width=80%, align="center", options="header"]
|===
-| Function Name | FID | EID
-| sbi_hart_start | 0 | 0x48534D
-| sbi_hart_stop | 1 | 0x48534D
-| sbi_hart_get_status | 2 | 0x48534D
+| Function Name | SBI Version | FID | EID
+| sbi_hart_start | 0.2 | 0 | 0x48534D
+| sbi_hart_stop | 0.2 | 1 | 0x48534D
+| sbi_hart_get_status | 0.2 | 2 | 0x48534D
|===

== System Reset Extension (EID #0x53525354 "SRST")
--
2.25.1