On Thu, 2020-10-22 at 19:35 -0400, Sean Anderson wrote:

Terms like should et. al. are commonly understood to introduce a
requirement, but it is sometimes unclear exactly what they mean. Link
to
the RFC specifying particular meanings for those terms. This may
cause
the meaning of some parts of the spec to change if these terms were
previously used with different intended or implied meanings.

The term "hart" is used extensively without definition. The idea of
an
EEI is used in the following commit "sbi: Specify the instruction
set".

What exactly constitutes a valid **hartid** was not previously
explicitly defined. I have taken a broad view here, and tried not to
constrain valid hartids past what is reasonable. A more narrow
interpretation could allow more efficient implementations in some
instances.

Signed-off-by: Sean Anderson <seanga2@...>
---

riscv-sbi.adoc | 19 +++++++++++++++++++
1 file changed, 19 insertions(+)

diff --git a/riscv-sbi.adoc b/riscv-sbi.adoc
index f8770fa..d2e28f0 100644
--- a/riscv-sbi.adoc
+++ b/riscv-sbi.adoc
@@ -32,6 +32,25 @@ This document describes a draft of version 0.2 of
the RISC-V SBI specification.
because the legacy extension is optional and v0.1 of the SBI
doesn't allow
probing, but it's as good as we can do.

+=== Terminology
+
+Should, Shall, May, and Must::
+These terms are defined in link:
https://tools.ietf.org/html/rfc2119[RFC 2119].
+In particular, they may be used without ALL CAPS.
+
+Hart and Execution environment interface::
+These terms are defined in the
+link:https://riscv.org/technical/specifications/[RISC-V ISA
specification, volume 1, section 1.2].
+The RISC-V SBI specification specifies some components of an
execution
+environment interface.
+
+Valid **hartid**s::
+A *hartid* is valid if it identifies a hart within the execution
environment. In
+addition, if the <<hsm-extension>> is enabled, **hartid**s
identifying harts
+which can be managed or queried are also valid. The set of harts
which can be
+managed or queried may change over time. Valid **hartid**s should
correspond to
+the value of the `mhartid` CSR on particular harts.
+

There is a brief valid hart definition in binary encoding section as
well.

"any of the hartid from hart_mask is not valid i.e. either the hartid
is not enabled by the platform or is not available to the supervisor"

Do we need to define it again in a separate terimnology section or just
extend current definition to be more broad.

== Binary Encoding

All SBI functions share a single binary encoding, which facilitates
the mixing

--
Regards,
Atish