The length of int, long, unsigned long is compiler specific. We do not wan=
t
to require the SBI and the operating system to use the same compiler.
Instead the SBI standard shall define a binary interface independent of th=
e
compiler used.
* Define the constant XLEN in the text.
* Define types intn_t and uintn_t with width XLEN.
* Replace int, long, unsigned long by int32_t, intn_t, uintn_t.
32bit and 64bit GCC and Clang use 32 bit for int, 32 bit for long on RV32,
and 64 bit for long on RV64. Thus SBI implementations and consumers using
these compilers will not have to be changed.
Signed-off-by: Heinrich Schuchardt <xypron.glpk@...>
=2D--
riscv-sbi.adoc | 126 ++++++++++++++++++++++++++-----------------------
1 file changed, 68 insertions(+), 58 deletions(-)
diff --git a/riscv-sbi.adoc b/riscv-sbi.adoc
index 090f10a..ad6911f 100644
=2D-- a/riscv-sbi.adoc
+++ b/riscv-sbi.adoc
@@ -79,6 +79,17 @@ function calls except that:
* `a7` (or `t0` on RV32E-based systems) encodes the SBI extension ID (*EI=
D*),
which matches how the system call ID is encoded in Linux system call AB=
I.
+Throughout the text the constant XLEN refers to the number of bits in an =
integer
+register (32 for RV32, 64 for RV64, 128 for RV128). As C types like int a=
nd long
+are compiler specific we use the following types in our API description:
+
+[cols=3D"1,2", width=3D90%, align=3D"center", options=3D"header"]
+|=3D=3D=3D
+| Type | Definition
+| intn_t | signed integer type with XLEN bits
+| uintn_t | unsigned integer type with XLEN bits
+|=3D=3D=3D
+
Many SBI extensions also chose to encode an additional SBI function ID (*=
FID*)
in `a6`, a scheme similar to the `ioctl()` system call on many UNIX opera=
ting
systems. This allows SBI extensions to encode multiple functions within t=
he
@@ -94,8 +105,8 @@ returning an error code. This is analogous to returning=
the C structure
[source, C]
----
struct sbiret {
- long error;
- long value;
+ intn_t error;
+ intn_t value;
};
----
@@ -116,7 +127,7 @@ Standard SBI error codes are listed below
An `ECALL` with an unsupported SBI extension ID (*EID*) or an unsupported=
SBI
function ID (*FID*) must return the error code `SBI_ERR_NOT_SUPPORTED`.
-Every SBI function should prefer `unsigned long` as the data type. It kee=
ps
+Every SBI function should prefer `uintn_t` as the data type. It keeps
the specification simple and easily adaptable for all RISC-V ISA types (i=
.e.
RV32, RV64 and RV128). In case the data is defined as 32bit wide, higher
privilege software must ensure that it only uses 32 bit data only.
@@ -127,8 +138,8 @@ defined in or after v0.2.
Any function, requiring a hart mask, need to pass following two arguments=
.
-* `unsigned long hart_mask` is a scalar bit-vector containing hartids
-* `unsigned long hart_mask_base` is the starting hartid from which bit-ve=
ctor
+* `uintn_t hart_mask` is a scalar bit-vector containing hartids
+* `uintn_t hart_mask_base` is the starting hartid from which bit-vector
must be computed.
In a single SBI function call, maximum number harts that can be set is
@@ -193,7 +204,7 @@ number is specific to the SBI implementation.
[source, C]
----
-struct sbiret sbi_probe_extension(long extension_id);
+struct sbiret sbi_probe_extension(intn_t extension_id);
----
Returns 0 if the given SBI extension ID (*EID*) is not available, or an
@@ -286,7 +297,7 @@ interrupt by clearing `sie.STIE` CSR bit.
[source, C]
----
-void sbi_console_putchar(int ch)
+void sbi_console_putchar(int32_t ch)
----
Write data present in *ch* to debug console.
@@ -322,7 +333,7 @@ S-mode code can clear `sip.SSIP` CSR bit directly.
[source, C]
----
-void sbi_send_ipi(const unsigned long *hart_mask)
+void sbi_send_ipi(const uintn_t *hart_mask)
----
Send an inter-processor interrupt to all the harts defined in hart_mask.
@@ -330,15 +341,14 @@ Interprocessor interrupts manifest at the receiving =
harts as Supervisor
Software Interrupts.
hart_mask is a virtual address that points to a bit-vector of harts. The
-bit vector is represented as a sequence of unsigned longs whose length
-equals the number of harts in the system divided by the number of bits
-in an unsigned long, rounded up to the next integer.
+bit vector is represented as a sequence of uintn_t whose length equals th=
e
+number of harts in the system divided by XLEN, rounded up to the next int=
eger.
=3D=3D=3D Extension: Remote FENCE.I (EID #0x05)
[source, C]
----
-void sbi_remote_fence_i(const unsigned long *hart_mask)
+void sbi_remote_fence_i(const uintn_t *hart_mask)
----
Instructs remote harts to execute `FENCE.I` instruction. The `hart_mask`
@@ -348,9 +358,9 @@ is same as described in `sbi_send_ipi()`.
[source, C]
----
-void sbi_remote_sfence_vma(const unsigned long *hart_mask,
- unsigned long start,
- unsigned long size)
+void sbi_remote_sfence_vma(const uintn_t *hart_mask,
+ uintn_t start,
+ uintn_t size)
----
Instructs the remote harts to execute one or more `SFENCE.VMA` instructio=
ns,
@@ -360,10 +370,10 @@ covering the range of virtual addresses between star=
t and size.
[source, C]
----
-void sbi_remote_sfence_vma_asid(const unsigned long *hart_mask,
- unsigned long start,
- unsigned long size,
- unsigned long asid)
+void sbi_remote_sfence_vma_asid(const uintn_t *hart_mask,
+ uintn_t start,
+ uintn_t size,
+ uintn_t asid)
----
Instruct the remote harts to execute one or more `SFENCE.VMA` instruction=
s,
@@ -436,8 +446,8 @@ follow the `hart_mask` as defined in the binary encodi=
ng section.
[source, C]
----
-struct sbiret sbi_send_ipi(unsigned long hart_mask,
- unsigned long hart_mask_base)
+struct sbiret sbi_send_ipi(uintn_t hart_mask,
+ uintn_t hart_mask_base)
----
Send an inter-processor interrupt to all the harts defined in hart_mask.
@@ -477,8 +487,8 @@ The remote fence function acts as a full TLB flush if
[source, C]
----
-struct sbiret sbi_remote_fence_i(unsigned long hart_mask,
- unsigned long hart_mask_base)
+struct sbiret sbi_remote_fence_i(uintn_t hart_mask,
+ uintn_t hart_mask_base)
----
Instructs remote harts to execute `FENCE.I` instruction.
@@ -494,10 +504,10 @@ Instructs remote harts to execute `FENCE.I` instruct=
ion.
[source, C]
----
-struct sbiret sbi_remote_sfence_vma(unsigned long hart_mask,
- unsigned long hart_mask_base,
- unsigned long start_addr,
- unsigned long size)
+struct sbiret sbi_remote_sfence_vma(uintn_t hart_mask,
+ uintn_t hart_mask_base,
+ uintn_t start_addr,
+ uintn_t size)
----
Instructs the remote harts to execute one or more `SFENCE.VMA` instructio=
ns,
@@ -517,11 +527,11 @@ covering the range of virtual addresses between star=
t and size.
[source, C]
----
-struct sbiret sbi_remote_sfence_vma_asid(unsigned long hart_mask,
- unsigned long hart_mask_base,
- unsigned long start_addr,
- unsigned long size,
- unsigned long asid)
+struct sbiret sbi_remote_sfence_vma_asid(uintn_t hart_mask,
+ uintn_t hart_mask_base,
+ uintn_t start_addr,
+ uintn_t size,
+ uintn_t asid)
----
Instruct the remote harts to execute one or more `SFENCE.VMA` instruction=
s,
@@ -542,11 +552,11 @@ only the given `ASID`.
[source, C]
----
-struct sbiret sbi_remote_hfence_gvma_vmid(unsigned long hart_mask,
- unsigned long hart_mask_base,
- unsigned long start_addr,
- unsigned long size,
- unsigned long vmid)
+struct sbiret sbi_remote_hfence_gvma_vmid(uintn_t hart_mask,
+ uintn_t hart_mask_base,
+ uintn_t start_addr,
+ uintn_t size,
+ uintn_t vmid)
----
Instruct the remote harts to execute one or more `HFENCE.GVMA` instructio=
ns,
@@ -571,10 +581,10 @@ hypervisor extension.
[source, C]
----
-struct sbiret sbi_remote_hfence_gvma(unsigned long hart_mask,
- unsigned long hart_mask_base,
- unsigned long start_addr,
- unsigned long size)
+struct sbiret sbi_remote_hfence_gvma(uintn_t hart_mask,
+ uintn_t hart_mask_base,
+ uintn_t start_addr,
+ uintn_t size)
----
Instruct the remote harts to execute one or more `HFENCE.GVMA` instructio=
ns,
@@ -599,11 +609,11 @@ extension.
[source, C]
----
-struct sbiret sbi_remote_hfence_vvma_asid(unsigned long hart_mask,
- unsigned long hart_mask_base,
- unsigned long start_addr,
- unsigned long size,
- unsigned long asid)
+struct sbiret sbi_remote_hfence_vvma_asid(uintn_t hart_mask,
+ uintn_t hart_mask_base,
+ uintn_t start_addr,
+ uintn_t size,
+ uintn_t asid)
----
Instruct the remote harts to execute one or more `HFENCE.VVMA` instructio=
ns,
@@ -628,10 +638,10 @@ call is only valid for harts implementing hypervisor=
extension.
[source, C]
----
-struct sbiret sbi_remote_hfence_vvma(unsigned long hart_mask,
- unsigned long hart_mask_base,
- unsigned long start_addr,
- unsigned long size)
+struct sbiret sbi_remote_hfence_vvma(uintn_t hart_mask,
+ uintn_t hart_mask_base,
+ uintn_t start_addr,
+ uintn_t size)
----
Instruct the remote harts to execute one or more `HFENCE.VVMA` instructio=
ns,
@@ -748,9 +758,9 @@ following approaches:
[source, C]
----
-struct sbiret sbi_hart_start(unsigned long hartid,
- unsigned long start_addr,
- unsigned long opaque)
+struct sbiret sbi_hart_start(uintn_t hartid,
+ uintn_t start_addr,
+ uintn_t opaque)
----
Request the SBI implementation to start executing the target hart in
@@ -834,7 +844,7 @@ The possible error codes returned in `sbiret.error` ar=
e shown in the
[source, C]
----
-struct sbiret sbi_hart_get_status(unsigned long hartid)
+struct sbiret sbi_hart_get_status(uintn_t hartid)
----
Get the current status (or HSM state id) of the given hart in `sbiret.val=
ue`,
@@ -867,8 +877,8 @@ of the hart at the time of return value verification.
[source, C]
----
struct sbiret sbi_hart_suspend(uint32_t suspend_type,
- unsigned long resume_addr,
- unsigned long opaque)
+ uintn_t resume_addr,
+ uintn_t opaque)
----
Request the SBI implementation to put the calling hart in a platform spec=
fic
@@ -972,8 +982,8 @@ implementation could be machine mode firmware or hyper=
visor.
[source, C]
----
-struct sbiret sbi_system_reset(unsigned long reset_type,
- unsigned long reset_reason)
+struct sbiret sbi_system_reset(uintn_t reset_type,
+ uintn_t reset_reason)
----
Reset the system based on provided `reset_type` and `reset_reason`. This =
is
=2D-
2.30.1
