「RISC-V Arch」SBI 规范解读（上）

术语

---

SBI，Supervisor Binary Interface，管理二进制接口

U-Mode，User mode，用户模式

S-Mode，Supervisor mode，监督模式

VS-Mode，Virtualization Supervisor mode，虚拟机监督模式

M-Mode，Machine mode，机器模式，类似 ARM 的 EL3

HS-Mode，Hypervisor mode，管理模式，类似 ARM 的 EL2

SEE， Supervisor Execution Environment ，监督执行环境

规范修正历史

---

Version 1.0.0

•发布前更新版本

Version 1.0-rc3

•更新调用规约

•修正 PMU 一个类型

•增加缩写表

Version 1.0-rc2

•更新 RISC-V 格式

•提升指令

•删除 RV32 的参考

Version 1.0-rc1

•一个类型修改

Version 0.3.0

•一些类型修改

•更新 license 详细信息，取代超链接方式

Version 0.3-rc1

•改善文档风格和命名方式

•添加 SBI 系统复位支持

•改善 SBI 指令部分

•改善 SBI hart 状态管理的文档

•SBI hart 状态管理添加 suspend 功能

•增加性能监视器单元扩展

•澄清 SBI 不能是部分实现的

Version 0.2

•将 v0.1 放到 lagency 部分以达到向前兼容，比如 v0.1 不支持 probe。

第一章 介绍

---

这个规范描述了 RISC-V 超级二进制接口，即SBI，通过 SBI 接口， RISC-V 能够实现 S 模式、VS 模式代码能够在不同的平台之间的可移植性。SBI 遵循了 RISC-V 的设计哲学，由一个非常小的核心部分和一些可选的模块扩展组成。

SBI 整体来说是一个扩展，也就是说要不实现，要么就要完整实现。如果 sbi_probe_extention 指示出某个功能可用，那么所有版本要求的功能都需要实现，这个版本可以通过 sbi_get_spec_version 来获得。

高特权软件向管理模式提供 SBI 接口支持，这个软件可以叫做 SBI 实现或者 SEE。SEE 可以是图1中的 M 模式下运行时固件，也可以是图2 中的 HS 模式运行的虚拟机管理程序。

图1 无虚拟化扩展 RISC-V 系统

图2 有虚拟化扩展的 RISC-V 系统

 SBI 规范不会指定任何硬件发现的方法，S 模式软件必须通过其他工业标准来获取，比如 Device Tree 或者 ACPI。

第二章 规范中的术语和缩写

---

 第三章 二进制编码

---

所有的 SBI 功能/函数都共享同样的二进制编码，混合了各种 SBI 扩展。SBI 规范遵循下面的调用规约：

• ECALL 用做 supervisor 和 SEE 之间的控制传输指令；
• a7 是编码的 SBI 扩展 ID （EID）；
• a6 是编码的是 EID 中具体的 SBI 函数 ID （FID），由 SBI v0.2 定义；
• 除了 a0 和 a1寄存器以外，其他寄存器必须由被调用者保存
• SBI 函数必须在 a0 和 a1 中返回一对数值，a0 是返回的错误码，a1 是数据，和如下 C 结构体类似

struct sbiret {long error;long value;};

 为了命名的兼容性，SBI EID 和 FID 都采用 32 位的寄存器，在寄存器传输时，符合上面的调用规约。

表1 提供了标准的 SBI 错误码

表1 SBI 标准错误码

 使用 ECALL 时，如果 EID 或 FID 不支持，那么必须返回错误码 SBI_ERR_NOT_SUPPORTED。

每一个 SBI 函数应该首选 unsigned long 作为数据类型。这会使得规范简单并且容易被 RISC-V ISA 类型接受。这种情况下数据被定义为 32位宽，高特权软件必须保证其只使用 32位 数据。

如果 SBI 函数想要给高特权模式传递一个 harts 列表，那么必须使用下面的 hart 掩码。这个适用于 v0.2及以后的版本。

任何需要一个 hart 掩码的函数，不要传递下面两个参数：

• unsigned long hart_mask，一个包含了hart id的标量位向量
• unsigned long hart_mask_base，一个位向量中必须进行计算的 hart id 起始位置

在一个 SBI 函数调用中，最大的 hart 数通过 XLEN 设置，如果低特权级别想要传输更多关于 XLEN 的信息，那么就需要调用多个 SBI 函数调用实例，hart_mask_base 能够设置为 -1 来指示 可以忽略 hart_mask，需要考虑所有可用的 hart。

任何一个使用 hart 掩码的函数可能会返回下表中的错误码，这些错误码是函数特定的错误码。

表2 HART 掩码错误

 第四章 基础扩展（EID #0x10）

---

基础扩展已经是尽可能的最小化了，因此基础扩展只包含了获得 SBI 扩展集及其版本的一些功能。SBI 实现必须实现所有基础扩展中的函数，也就是说不能返回任何错误码。

4.1 函数：获取 SBI 标准版本(FID #0)

struct sbiret sbi_get_spec_version(void);

返回当前 SBI 规范版本，这个函数必须总是成功的，最高位为 0 预留，24~30 共 7 位为主版本号，0~23 共 24 位为次版本号。 

4.2 函数：获取 SBI 实现 ID (FID #1)

struct sbiret sbi_get_impl_id(void);

返回当前 SBI 实现 ID，每个实现都具有不同的 SBI ID，可以通过这个 ID 来探测实现支持的扩展情况。 

4.3 函数：获取 SBI 实现版本 (FID #2)

struct sbiret sbi_get_impl_version(void);

返回当前 SBI 实现的版本号，版本号的编码格式由 SBI 实现来定义。

4.4 函数：探测 SBI 扩展 (FID #3)

struct sbiret sbi_probe_extension(long extension_id);

如果给定扩展 ID 不存在则返回 0，否则返回 1，当然实现也可以根据需要再定义一些其他值。 

4.5 函数：获取机器供应商 ID (FID #4)

struct sbiret sbi_get_mvendorid(void);

返回一个合法的 mvendorid CSR 值，0 是合法的 CSR 值。 

4.6 函数：获取机器架构 ID (FID #5)

struct sbiret sbi_get_marchid(void);

返回一个合法的 marchid CSR 的值，0 是合法的 CSR 值。 

4.7 函数：获取机器实现 ID (FID #6)

struct sbiret sbi_get_mimpid(void);

返回一个合法的 mimpid CSR，0 是合法的 CSR 值。 

4.8 函数列表

表3 基础函数列表

 4.9 SBI 实现 IDs

表4 SBI 实现 IDs

 第五章 遗留扩展（EIDs #0x00 - 0x0F）

---

遗留 SBI 扩展和 SBI v0.2及以上规范的扩展的调用规约有点不同：

• 遗留扩展忽略了 a6 寄存器中的 SBI FID，因为他们会被编码成多个 SBI EID
• a1 寄存器不返回任何数值
• 调用者在 SBI 调用过程中需要保存除 a0 以外的所有寄存器
• a0 寄存器返回的数值是由具体遗留扩展来定义的

SBI 实现在代替 S 模式访问内存时发生的页和访问故障，会通过 sepc CSR 重定向回 S 模式，并指出出错的 ECALL 指令。

遗留的 SBI 扩展已经被废弃，取而代之的时后面列出来的扩展，而遗留的控制台 console SBI 函数sbi_console_getchar() 、sbi_console_putchar()也被废弃了，它们是没有替代函数的。

5.1 扩展：设置定时器（EID #0x00）

long sbi_set_timer(uint64_t stime_value)

设置 stime_value 时间后的闹钟事件，这个函数回清除定时器的中断标志 pending bit。

如果 S 模式想清除中断并且不想继续处理定时器事件，可以通过设置参数为 -1 或者 清除 sie.SITE CSR 寄存器来实现。

SBI 调用成功时返回 0，失败时返回实现定义的负数错误码。 

5.2 扩展：控制台输出（EID #0x01）

long sbi_console_putchar(int ch)

 将 ch 中的字符写到调试控制台，和sbi_console_getchar()不同，SBI 调用在控制台不为空时会阻塞，或者如果控制台没有准备好接收数据时也会阻塞。如果控制台本身不存在，则字符会被直接丢弃。

SBI 调用成功时返回 0，失败时返回实现定义的负数错误码。 

5.3 扩展：控制台输入（EID #0x02）

long sbi_console_getchar(void)

从调试控制台读取一个字符。

SBI 调用成功时会返回一个字符，失败时返回 -1。 

5.4 扩展：清除 IPI（EID #0x03）

long sbi_clear_ipi(void)

 清除 Pending 的 IPI，IPI 只有在调用该函数时才会被清除，这个接口已经废弃了，因为 S 模式可以直接通过 sip.SSIP CSR 位来清除 IPI。

如果没有需要清除的 IPI，则返回 0，否则返回正数来表示有 IPI 在等待，这个数值由实现定义。

5.5 扩展：发送 IPI（EID #0x04）

long sbi_send_ipi(const unsigned long *hart_mask)

发送核间中断给 hart_mask 中定义的 hart。核间中断在接收端显示为 S 模式的软件中断。

hart_mask 是一个指向接收点的虚拟地址位图，这个位图由无符号长整形序列表示。 

5.6 扩展：Remote FENCE.I（EID #0x05）

long sbi_remote_fence_i(const unsigned long *hart_mask)

让指远端执行 FENCE.I 指令，位图和发送 IPI 的位图定义相同。

成功时返回 0，失败时返回负数由实现定义的值。

5.7 扩展：Remote SFENCE.VMA（EID #0x06）

long sbi_remote_sfence_vma(const unsigned long *hart_mask,                           unsigned long start,                           unsigned long size)

让指远端执行 FENCE.VMA 指令，覆盖虚拟地址指定的范围。

成功时返回 0，失败时返回负数由实现定义的值。

5.8 扩展：Remote SFENCE.VMA 使用 ASID（EID #0x07）

long sbi_remote_sfence_vma_asid(const unsigned long *hart_mask,                                                                                        unsigned long start,                                unsigned long size,                                unsigned long asid)

让指远端执行 FENCE.VMA 指令，覆盖虚拟地址指定的范围和指定的 ASID。

成功时返回 0，失败时返回负数由实现定义的值。

5.9 扩展：系统关机（EID #0x08）

void sbi_shutdown(void)

将所有远端设置位关机状态（从 S 模式视角来看）。

SBI 调用不返回任何能够指定成功或失败的值。 

5.10 函数列表

表5 遗留函数列表

皮格马利翁效应心理学指出，赞美、赞同能够产生奇迹，越具体，效果越好~

“收藏夹吃灰”是学“器”练“术”非常聪明的方法，帮助我们避免日常低效的勤奋~