On 10/27/20 4:56 PM, Atish Patra wrote:

On Tue, 2020-10-27 at 16:31 -0400, Sean Anderson wrote:

On 10/27/20 4:06 PM, Atish Patra wrote:

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.

That definition is describing hartids, which may be different than
actual harts. For example, it is possible for a hartid to be valid
but
not strictly refer to a hart. Note in particular that a hart must be
guaranteed to retire instructions in finite time. So if I use the HSM
extension to stop a hart, it is no longer a hart.

It's still a hart and can retire instructions in finite time in M-mode.>
When HSM extension stops a hart, it just makes it unavailable to S-> mode.

Right, but the SBI spec is considering the S-mode execution environment.
Whether it's still a hart to M-mode is irrelevant (and if the hart was
powered down or physically removed it might not be a hart to M-mode
either).

However, its hartid
may remain valid.

I think it's also important to point out some hartids may change from
valid to invalid or vice versa. For example, a hypervisor may have
allow
all VMs to request harts from a common pool. If cpu core 5 gets
started
by one VM, its hartid should then become invalid for other harts to
manage. As another example, a hypervisor may associate different CPU
cores with differnt VMs. If a the hypervisor moves a core from one VM
to
another, then a new hartid will become valid for the VM it is added
to.

Yes. Just to clarify, I agree with the additional description you
provided for valid hartid. I was just suggesting to keep them in one
place to avoid ambiguity.

The meaning of "valid" depends on contenxt. Thus, we need to clearly
describe it.

Perhaps we should add a cross-reference like

any of the hartid from hart_mask is not valid, <<hartid,as defined above>>.

--Sean