Skip to content

Commit 351a23f

Browse files
YdrMasterYdrMaster
committed
style(sbi-rt): 规范并加文档
1 parent 47290a2 commit 351a23f

File tree

9 files changed

+197
-101
lines changed

9 files changed

+197
-101
lines changed

‎sbi-rt/src/base.rs

Lines changed: 38 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,71 @@
11
//! Chapter 4. Base Extension (EID #0x10)
22
33
use crate::binary::{sbi_call_0, sbi_call_1};
4+
use fid::*;
45

56
pub const EID_BASE: usize = 0x10;
7+
pub use impl_id::*;
68

7-
const FID_GET_SPEC_VERSION: usize = 0x0;
8-
const FID_GET_SBI_IMPL_ID: usize = 0x1;
9-
const FID_GET_SBI_IMPL_VERSION: usize = 0x2;
10-
const FID_PROBE_EXTENSION: usize = 0x3;
11-
const FID_GET_MVENDORID: usize = 0x4;
12-
const FID_GET_MARCHID: usize = 0x5;
13-
const FID_GET_MIMPID: usize = 0x6;
14-
9+
/// §4.1
1510
#[inline]
1611
pub fn get_spec_version() -> usize {
17-
sbi_call_0(EID_BASE, FID_GET_SPEC_VERSION).value
12+
sbi_call_0(EID_BASE, GET_SPEC_VERSION).value
1813
}
1914

15+
/// §4.2
2016
#[inline]
2117
pub fn get_sbi_impl_id() -> usize {
22-
sbi_call_0(EID_BASE, FID_GET_SBI_IMPL_ID).value
18+
sbi_call_0(EID_BASE, GET_SBI_IMPL_ID).value
2319
}
2420

21+
/// §4.3
2522
#[inline]
2623
pub fn get_sbi_impl_version() -> usize {
27-
sbi_call_0(EID_BASE, FID_GET_SBI_IMPL_VERSION).value
24+
sbi_call_0(EID_BASE, GET_SBI_IMPL_VERSION).value
2825
}
2926

27+
/// §4.4
3028
#[inline]
3129
pub fn probe_extension(extension_id: usize) -> usize {
32-
sbi_call_1(EID_BASE, FID_PROBE_EXTENSION, extension_id).value
30+
sbi_call_1(EID_BASE, PROBE_EXTENSION, extension_id).value
3331
}
3432

33+
/// §4.5
3534
#[inline]
3635
pub fn get_mvendorid() -> usize {
37-
sbi_call_0(EID_BASE, FID_GET_MVENDORID).value
36+
sbi_call_0(EID_BASE, GET_MVENDORID).value
3837
}
3938

39+
/// §4.6
4040
#[inline]
4141
pub fn get_marchid() -> usize {
42-
sbi_call_0(EID_BASE, FID_GET_MARCHID).value
42+
sbi_call_0(EID_BASE, GET_MARCHID).value
4343
}
4444

45+
/// §4.7
4546
#[inline]
4647
pub fn get_mimpid() -> usize {
47-
sbi_call_0(EID_BASE, FID_GET_MIMPID).value
48+
sbi_call_0(EID_BASE, GET_MIMPID).value
49+
}
50+
51+
/// §4.8
52+
mod fid {
53+
pub(super) const GET_SPEC_VERSION: usize = 0x0;
54+
pub(super) const GET_SBI_IMPL_ID: usize = 0x1;
55+
pub(super) const GET_SBI_IMPL_VERSION: usize = 0x2;
56+
pub(super) const PROBE_EXTENSION: usize = 0x3;
57+
pub(super) const GET_MVENDORID: usize = 0x4;
58+
pub(super) const GET_MARCHID: usize = 0x5;
59+
pub(super) const GET_MIMPID: usize = 0x6;
60+
}
61+
62+
/// §4.9
63+
mod impl_id {
64+
pub const IMPL_BBL: usize = 0;
65+
pub const IMPL_OPEN_SBI: usize = 1;
66+
pub const IMPL_XVISOR: usize = 2;
67+
pub const IMPL_KVM: usize = 3;
68+
pub const IMPL_RUST_SBI: usize = 4;
69+
pub const IMPL_DIOSIX: usize = 5;
70+
pub const IMPL_COFFER: usize = 6;
4871
}

‎sbi-rt/src/binary.rs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,8 @@ pub enum Error {
5454
}
5555

5656
impl SbiRet {
57-
pub const fn result(&self) -> Result<usize, Error> {
57+
/// Converts to a [`Result`].
58+
pub const fn into_result(self) -> Result<usize, Error> {
5859
match self.error {
5960
RET_SUCCESS => Ok(self.value),
6061
RET_ERR_FAILED => Err(Error::Failed),

‎sbi-rt/src/hsm.rs

Lines changed: 21 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,10 @@
11
//! Chapter 9. Hart State Management Extension (EID #0x48534D "HSM")
22
33
use crate::binary::{eid_from_str, sbi_call_0, sbi_call_1, sbi_call_3, SbiRet};
4+
use fid::*;
45

56
pub const EID_HSM: usize = eid_from_str("HSM") as _;
67

7-
const FID_HART_START: usize = 0;
8-
const FID_HART_STOP: usize = 1;
9-
const FID_HART_GET_STATUS: usize = 2;
10-
const FID_HART_SUSPEND: usize = 3;
11-
128
pub const HART_STATE_STARTED: usize = 0;
139
pub const HART_STATE_STOPPED: usize = 1;
1410
pub const HART_STATE_START_PENDING: usize = 2;
@@ -17,28 +13,43 @@ pub const HART_STATE_SUSPENDED: usize = 4;
1713
pub const HART_STATE_SUSPEND_PENDING: usize = 5;
1814
pub const HART_STATE_RESUME_PENDING: usize = 6;
1915

16+
pub const HART_SUSPEND_TYPE_RETENTIVE: u32 = 0;
17+
pub const HART_SUSPEND_TYPE_NON_RETENTIVE: u32 = 0x8000_0000;
18+
19+
/// §9.1
2020
#[inline]
2121
pub fn hart_start(hartid: usize, start_addr: usize, opaque: usize) -> SbiRet {
22-
sbi_call_3(EID_HSM, FID_HART_START, hartid, start_addr, opaque)
22+
sbi_call_3(EID_HSM, HART_START, hartid, start_addr, opaque)
2323
}
2424

25+
/// §9.2
2526
#[inline]
2627
pub fn hart_stop() -> SbiRet {
27-
sbi_call_0(EID_HSM, FID_HART_STOP)
28+
sbi_call_0(EID_HSM, HART_STOP)
2829
}
2930

31+
/// §9.3
3032
#[inline]
3133
pub fn hart_get_status(hartid: usize) -> SbiRet {
32-
sbi_call_1(EID_HSM, FID_HART_GET_STATUS, hartid)
34+
sbi_call_1(EID_HSM, HART_GET_STATUS, hartid)
3335
}
3436

37+
/// §9.4
3538
#[inline]
3639
pub fn hart_suspend(suspend_type: u32, resume_addr: usize, opaque: usize) -> SbiRet {
3740
sbi_call_3(
3841
EID_HSM,
39-
FID_HART_SUSPEND,
40-
suspend_type as usize,
42+
HART_SUSPEND,
43+
suspend_type as _,
4144
resume_addr,
4245
opaque,
4346
)
4447
}
48+
49+
/// §9.5
50+
mod fid {
51+
pub(super) const HART_START: usize = 0;
52+
pub(super) const HART_STOP: usize = 1;
53+
pub(super) const HART_GET_STATUS: usize = 2;
54+
pub(super) const HART_SUSPEND: usize = 3;
55+
}

‎sbi-rt/src/legacy.rs

Lines changed: 54 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,105 @@
11
//! Chapter 5. Legacy Extensions (EIDs #0x00 - #0x0F)
22
3-
const SBI_SET_TIMER: usize = 0;
4-
const SBI_CONSOLE_PUTCHAR: usize = 1;
5-
const SBI_CONSOLE_GETCHAR: usize = 2;
6-
const SBI_CLEAR_IPI: usize = 3;
7-
const SBI_SEND_IPI: usize = 4;
8-
const SBI_REMOTE_FENCE_I: usize = 5;
9-
const SBI_REMOTE_SFENCE_VMA: usize = 6;
10-
const SBI_REMOTE_SFENCE_VMA_ASID: usize = 7;
11-
const SBI_SHUTDOWN: usize = 8;
3+
pub use id::*;
124

5+
/// §5.1
6+
///
7+
/// No replacement.
138
#[deprecated = "replaced by `set_timer` from Timer extension"]
149
#[inline]
1510
pub fn set_timer(stime_value: u64) -> usize {
1611
match () {
1712
#[cfg(target_pointer_width = "32")]
18-
() => sbi_call_legacy_2(SBI_SET_TIMER, stime_value as _, (stime_value >> 32) as _),
13+
() => sbi_call_legacy_2(LEGACY_SET_TIMER, stime_value as _, (stime_value >> 32) as _),
1914
#[cfg(target_pointer_width = "64")]
20-
() => sbi_call_legacy_1(SBI_SET_TIMER, stime_value as _),
15+
() => sbi_call_legacy_1(LEGACY_SET_TIMER, stime_value as _),
2116
}
2217
}
2318

19+
/// §5.2
20+
///
21+
/// No replacement.
2422
#[deprecated = "no replacement"]
2523
#[inline]
2624
pub fn console_putchar(c: usize) -> usize {
27-
sbi_call_legacy_1(SBI_CONSOLE_PUTCHAR, c)
25+
sbi_call_legacy_1(LEGACY_CONSOLE_PUTCHAR, c)
2826
}
2927

28+
/// §5.3
3029
#[deprecated = "no replacement"]
3130
#[inline]
3231
pub fn console_getchar() -> usize {
33-
sbi_call_legacy_0(SBI_CONSOLE_GETCHAR)
32+
sbi_call_legacy_0(LEGACY_CONSOLE_GETCHAR)
3433
}
3534

35+
/// §5.4
36+
///
37+
/// No replacement. Just clear `sip.SSIP` directly.
3638
#[deprecated = "you can clear `sip.SSIP` CSR bit directly"]
3739
#[inline]
3840
pub fn clear_ipi() -> usize {
39-
sbi_call_legacy_0(SBI_CLEAR_IPI)
41+
sbi_call_legacy_0(LEGACY_CLEAR_IPI)
4042
}
4143

42-
#[deprecated = "replaced by `send_ipi` from IPI extension"]
44+
/// §5.5
45+
///
46+
/// Replaced by [`send_ipi`](super::send_ipi) from [`sPI`](super::EID_SPI) extension.
47+
#[deprecated = "replaced by `send_ipi` from `sPI` extension"]
4348
#[inline]
4449
pub fn send_ipi(hart_mask: usize) -> usize {
45-
sbi_call_legacy_1(SBI_SEND_IPI, hart_mask)
50+
sbi_call_legacy_1(LEGACY_SEND_IPI, hart_mask)
4651
}
4752

48-
#[deprecated = "replaced by `remote_fence_i` from RFENCE extension"]
53+
/// §5.6
54+
///
55+
/// Replaced by [`remote_fence_i`](super::remote_fence_i) from [`RFNC`](super::EID_RFNC) extension.
56+
#[deprecated = "replaced by `remote_fence_i` from `RFNC` extension"]
4957
#[inline]
5058
pub fn remote_fence_i(hart_mask: usize) -> usize {
51-
sbi_call_legacy_1(SBI_REMOTE_FENCE_I, hart_mask)
59+
sbi_call_legacy_1(LEGACY_REMOTE_FENCE_I, hart_mask)
5260
}
5361

54-
#[deprecated = "replaced by `remote_fence_vma` from RFENCE extension"]
62+
/// §5.7
63+
///
64+
/// Replaced by [`remote_sfence_vma`](super::remote_sfence_vma) from [`RFNC`](super::EID_RFNC) extension.
65+
#[deprecated = "replaced by `remote_sfence_vma` from `RFNC` extension"]
5566
#[inline]
5667
pub fn remote_fence_vma(hart_mask: usize, start: usize, size: usize) -> usize {
57-
sbi_call_legacy_3(SBI_REMOTE_SFENCE_VMA, hart_mask, start, size)
68+
sbi_call_legacy_3(LEGACY_REMOTE_SFENCE_VMA, hart_mask, start, size)
5869
}
5970

60-
#[deprecated = "replaced by `remote_fence_vma_asid` from RFENCE extension"]
71+
/// §5.8
72+
///
73+
/// Replaced by [`remote_sfence_vma_asid`](super::remote_sfence_vma_asid) from [`RFNC`](super::EID_RFNC) extension.
74+
#[deprecated = "replaced by `remote_sfence_vma_asid` from `RFNC` extension"]
6175
#[inline]
6276
pub fn remote_fence_vma_asid(hart_mask: usize, start: usize, size: usize, asid: usize) -> usize {
63-
sbi_call_legacy_4(SBI_REMOTE_SFENCE_VMA_ASID, hart_mask, start, size, asid)
77+
sbi_call_legacy_4(LEGACY_REMOTE_SFENCE_VMA_ASID, hart_mask, start, size, asid)
6478
}
6579

66-
#[deprecated = "replaced by `system_reset` from System Reset extension"]
80+
/// §5.9
81+
///
82+
/// Replaced by [`system_reset`](super::system_reset) from [`SRST`](super::EID_SRST) extension.
83+
#[deprecated = "replaced by `system_reset` from System `SRST` extension"]
6784
#[inline]
6885
pub fn shutdown() -> ! {
69-
sbi_call_legacy_0(SBI_SHUTDOWN);
86+
sbi_call_legacy_0(LEGACY_SHUTDOWN);
7087
core::unreachable!()
7188
}
7289

90+
/// §5.10
91+
mod id {
92+
pub const LEGACY_SET_TIMER: usize = 0;
93+
pub const LEGACY_CONSOLE_PUTCHAR: usize = 1;
94+
pub const LEGACY_CONSOLE_GETCHAR: usize = 2;
95+
pub const LEGACY_CLEAR_IPI: usize = 3;
96+
pub const LEGACY_SEND_IPI: usize = 4;
97+
pub const LEGACY_REMOTE_FENCE_I: usize = 5;
98+
pub const LEGACY_REMOTE_SFENCE_VMA: usize = 6;
99+
pub const LEGACY_REMOTE_SFENCE_VMA_ASID: usize = 7;
100+
pub const LEGACY_SHUTDOWN: usize = 8;
101+
}
102+
73103
#[inline(always)]
74104
fn sbi_call_legacy_0(eid: usize) -> usize {
75105
let error;

0 commit comments

Comments
 (0)