Re: [PATCH 2/2] Improve SBI HSM extension documentation


atishp@...
 

On Sat, 2020-12-26 at 15:50 +0530, Anup Patel wrote:
We add a figure to show the HSM state machine and improve current
HSM documentation to align with the HSM state machine.

Signed-off-by: Anup Patel <anup.patel@...>
---
 Makefile            |   1 +
 riscv-sbi-hsm.ditaa |  19 ++++++++
 riscv-sbi-hsm.png   | Bin 0 -> 13518 bytes
 riscv-sbi.adoc      | 103 +++++++++++++++++++++++++++++++-----------
--
 4 files changed, 92 insertions(+), 31 deletions(-)
 create mode 100644 riscv-sbi-hsm.ditaa
 create mode 100644 riscv-sbi-hsm.png

diff --git a/Makefile b/Makefile
index f2a52d2..5216ef7 100644
--- a/Makefile
+++ b/Makefile
@@ -6,6 +6,7 @@ ASCIIDOCTOR = asciidoctor
 DITAA = ditaa
 IMAGES = riscv-sbi-intro1.png
 IMAGES += riscv-sbi-intro2.png
+IMAGES += riscv-sbi-hsm.png
 TARGETS = riscv-sbi.pdf
 TARGETS += riscv-sbi.html
 
diff --git a/riscv-sbi-hsm.ditaa b/riscv-sbi-hsm.ditaa
new file mode 100644
index 0000000..8833a5e
--- /dev/null
+++ b/riscv-sbi-hsm.ditaa
@@ -0,0 +1,19 @@
+                           +-----------------+
+                           |                 |
+            /------------->|cF78 STOPPED     |--------------\
+            |              |                 |              |
+        SEE |              +-----------------+              |
+   stopping |                                               | SBI
HART
+       HART |                                               | start
call
+            |                                               v
++-----------------------+                       +-------------------
----+
+|cCCC STOP_PENDING      |                       |cCCC
START_PENDING     |
++-----------------------+                       +-------------------
----+
+            ^                                               |
+   SBI HART |                                               | SEE
+  stop call |                                               |
starting
+            |              +-----------------+              | HART
+            |              |                 |              |
+            \--------------|c0DB STARTED     |<-------------/
+                           |                 |
+                           +-----------------+
diff --git a/riscv-sbi-hsm.png b/riscv-sbi-hsm.png
new file mode 100644
index
0000000000000000000000000000000000000000..0a1dcda07b23e04e2c2b4f396d6
d31e7099b9e91
GIT binary patch
literal 13518
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

literal 0
HcmV?d00001

diff --git a/riscv-sbi.adoc b/riscv-sbi.adoc
index 2c2cf62..4ee2621 100644
--- a/riscv-sbi.adoc
+++ b/riscv-sbi.adoc
@@ -659,9 +659,29 @@ valid for harts implementing hypervisor
extension.
 
 == Hart State Management Extension (EID #0x48534D "HSM")
 
-The Hart State Management Extension introduces a set of functions
that allow
-the supervisor to request higher privilege mode to start/stop harts
running
-in supervisor mode.
+The Hart State Management (HSM) Extension introduces a set hart
states and a
+set of functions which allow the supervisor-mode (S-mode or VS-mode)
software
+to request a hart state change.
+
+.The possible hart states are as follows:
+* **STOPPED:** The hart is not executing in S-mode and it is
probably
+  powered-down by the SBI implementation if the underlying platform
has
+  a mechanism to physically power-down harts.
Should we also specify that SBI implementation should keep it WFI state
if the platform doesn't have a physical power-down capability ?

+* **STARTED:** The hart is physically powered-up and executing in S-
mode
+  or higher privilege mode.
+* **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.
+
+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>>.
+
+.SBI HSM State Machine
+image::riscv-sbi-hsm.png[id=fig_hsm,align="center"]
 
same comment as the previous patch about figure titles.

The diagram also specifies "SBI HART start/stop call". In stead of
that, we can just mention the actual sbi hsm function names.

 === Function: HART start (FID #0)
 
@@ -672,18 +692,22 @@ struct sbiret sbi_hart_start(unsigned long
hartid,
                              unsigned long priv)
 ----
 
-Informs the SBI implementation that the supervisor would like the
given hart
-to begin execution. This call is asynchronous -- more specifically,
-`sbi_hart_start()` may return before execution has actually begin as
long as
-the SBI implementation is capable of ensuring the return code is
accurate.
+Request the SBI implementation to start executing the given hart at
specified
+address in supervisor-mode (S-mode or VS-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.
 
-*start_addr* points to a runtime-specified physical address, where a
hart can
-resume execution after its initialization/resume sequence. Before
jumping to
-*start_addr*, the hart MUST configure PMP if present and switch to
Supervisor
-mode.
+The `hartid` parameter specifies the target hart which is to be
started.
 
-*priv* is an XLEN-bit value. Upon execution from `start_addr`, `a1`
will
-contain this exact value.
+The `start_addr` parameter points to a runtime-specified physical
address,
+where the hart can start executing in supervisor-mode (S-mode or VS-
mode).
+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 jumping to `start_addr` in supervisor-mode (S-mode or VS-
mode).
+
+The `priv` parameter is a XLEN-bit value which will be set in the
`a1`
+register when the hart starts executing at `start_addr`.
 
 *Returns* one of the following possible SBI error codes through
sbiret.error.
 
@@ -694,7 +718,7 @@ contain this exact value.
                               start executing from `start_addr`.
 | SBI_ERR_INVALID_ADDRESS   | `start_addr` is not valid possibly due
to
                               following reasons: +
-                              * it is not a valid physical address.
+
+                              * It is not a valid physical address.
+
                               * The address is prohibited by PMP to
run in
                                 supervisor mode.
 | SBI_ERR_INVALID_PARAM     | `hartid` is not a valid hartid as
corresponding
@@ -703,8 +727,8 @@ contain this exact value.
 | SBI_ERR_FAILED            | The start request failed for unknown
reasons.
 |===
 
-The target hart jumps to higher privilege mode (S-mode or VS-mode)
by
-executing at `start_addr` with following values in specific
registers.
+The target hart jumps to supervisor-mode (S-mode or VS-mode) at
address
+specified by `start_addr` with following values in specific
registers.
 
 [cols=",", width=50%, align="center", options="header"]
 |===
@@ -724,13 +748,20 @@ All other registers remain in an undefined
state.
 struct sbiret sbi_hart_stop(void)
 ----
 
-Returns ownership of the calling hart back to the SBI
implementation. This
-call is not expected to return under normal conditions.
`sbi_hart_stop()`
-must be called with supervisor and user interrupts disabled.
+Request the SBI implementation to stop executing the calling hart in
+supervisor-mode (S-mode or VS-mode) and return it's ownership to the
SBI
+implementation. This call is not expected to return under normal
conditions.
+The `sbi_hart_stop()` must be called with the supervisor-mode (S-
mode or
+VS-mode) interrupts disabled.
 
-*Returns* following SBI error code through sbiret.error only if it
fails.
+The possible error codes returned in sbiret.error are shown in the
+table below:
 
-* SBI_ERR_FAILED
+[cols="1,2", width=100%, align="center", options="header"]
+|===
+| Error code     | Description
+| SBI_ERR_FAILED | Failed to stop execution of the current hart
+|===
 
 === Function: HART get status (FID #2)
 
@@ -739,23 +770,33 @@ must be called with supervisor and user
interrupts disabled.
 struct sbiret sbi_hart_get_status(unsigned long hartid)
 ----
 
-*Returns* the current status of *hartid* in sbiret.value, or an
error through
-sbiret.error. The possible status values are shown on the table
below.
+Get the current status (or HSM state) 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   | Already started
-| STOPPED               |   1   | Stopped
-| START_REQUEST_PENDING |   2   | A start request pending
-| STOP_REQUEST_PENDING  |   3   | A stop request pending
+| Name          | Value | Description
+| STARTED       |   0   | Already started
+| STOPPED       |   1   | Stopped
+| START_PENDING |   2   | A start request pending
+| STOP_PENDING  |   3   | A stop request pending
 |===
 
-Possible error code:
+The possible error codes returned in sbiret.error are shown in the
+table below:
 
-* SBI_ERR_INVALID_PARAM: The given hartid is not valid
+[cols="1,2", width=100%, align="center", options="header"]
+|===
+| Error code            | Description
+| SBI_ERR_INVALID_PARAM | The given `hartid` or `start_addr` is not
valid
+|===
 
-Since harts may transition state at any time due to any concurrent
+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
 function may not represent the actual state of the hart at the time
of
 return value verification.
--
Regards,
Atish

Join {tech-unixplatformspec@lists.riscv.org to automatically receive all group messages.