riscv 0.16.0

Low level access to RISC-V processors
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182

//! Assembly instructions

macro_rules! instruction {
    ($(#[$attr:meta])*, unsafe $fnname:ident, $asm:expr, $($options:tt)*) => (
        $(#[$attr])*
        #[inline(always)]
        pub unsafe fn $fnname() {
            #[cfg(any(target_arch = "riscv32", target_arch = "riscv64"))]
            core::arch::asm!($asm, $($options)*);
            #[cfg(not(any(target_arch = "riscv32", target_arch = "riscv64")))]
            unimplemented!();
        }
    );
    ($(#[$attr:meta])*, $fnname:ident, $asm:expr, $($options:tt)*) => (
        $(#[$attr])*
        #[inline(always)]
        pub fn $fnname() {
            #[cfg(any(target_arch = "riscv32", target_arch = "riscv64"))]
            unsafe { core::arch::asm!($asm, $($options)*) };
            #[cfg(not(any(target_arch = "riscv32", target_arch = "riscv64")))]
            unimplemented!();
        }
    )
}

instruction!(
    /// `NOP` instruction wrapper
    ///
    /// The `NOP` instruction does not change any architecturally visible state, except for
    /// advancing the PC and incrementing any applicable performance counters.
    ///
    /// This function generates a no-operation; it's useful to prevent delay loops from being
    /// optimized away.
    , nop, "nop", options(nomem, nostack, preserves_flags));

instruction!(
    /// `WFI` instruction wrapper
    ///
    /// Provides a hint to the implementation that the current hart can be stalled until an
    /// interrupt might need servicing. The WFI instruction is just a hint, and a legal
    /// implementation is to implement WFI as a NOP.
    ///
    /// # Behavior
    ///
    /// - May cause the hart to enter a low-power state
    /// - Will be interrupted by any enabled interrupt
    /// - No guarantee of actual power savings (implementation-dependent)
    ,wfi, "wfi", options(nomem, nostack, preserves_flags));

instruction!(
    /// `EBREAK` instruction wrapper
    ///
    /// Generates a breakpoint exception for use by debuggers.
    ///
    /// # Behavior
    ///
    /// When executed, this instruction causes a breakpoint exception to be raised,
    /// which will typically be handled by a debugger or exception handler.
    ///
    /// # Safety
    ///
    /// This function is unsafe because it unconditionally generates an exception,
    /// which can disrupt normal program flow. Only call this when you intend to
    /// trigger a breakpoint.
    , unsafe ebreak, "ebreak", options(nomem, nostack, preserves_flags));

instruction!(
    /// `ECALL` instruction wrapper
    ///
    /// Generates an environment call exception for system services.
    ///
    /// # Behavior
    ///
    /// When executed in different privilege modes:
    /// - U-mode: Generates environment-call-from-U-mode exception
    /// - S-mode: Generates environment-call-from-S-mode exception
    /// - M-mode: Generates environment-call-from-M-mode exception
    ///
    /// # Safety
    ///
    /// This function is unsafe because:
    /// - It unconditionally generates an exception
    /// - The stack pointer is **NOT** automatically saved/restored
    /// - The exception handler is responsible for proper context management
    /// - Improper use can crash the system
    , unsafe ecall, "ecall", options(nomem, nostack, preserves_flags));

instruction!(
    /// `SFENCE.VMA` instruction wrapper (all address spaces and page table levels)
    ///
    /// Synchronizes updates to in-memory memory-management data structures with current execution.
    /// Instruction execution causes implicit reads and writes to these data structures; however, these implicit references
    /// are ordinarily not ordered with respect to loads and stores in the instruction stream.
    /// Executing an `SFENCE.VMA` instruction guarantees that any stores in the instruction stream prior to the
    /// `SFENCE.VMA` are ordered before all implicit references subsequent to the `SFENCE.VMA`.
    , sfence_vma_all, "sfence.vma", options(nostack));

instruction!(
    /// `FENCE` instruction wrapper
    ///
    /// The FENCE instruction is used to order device I/O and memory accesses as viewed by other RISC-V
    /// harts and external devices or coprocessors. Any combination of device input (I), device output
    /// (O), memory reads (R), and memory writes (W) may be ordered with respect to any combination
    /// of the same. Informally, no other RISC-V hart or external device can observe any operation in the
    /// successor set following a FENCE before any operation in the predecessor set preceding the FENCE.
    ///
    /// The FENCE instruction also orders memory reads and writes made by the hart as observed by
    /// memory reads and writes made by an external device. However, FENCE does not order observations
    /// of events made by an external device using any other signaling mechanism.
    , fence, "fence", options(nostack));

instruction!(
    /// `FENCE.I` instruction wrapper
    ///
    /// Used to synchronize the instruction and data streams. RISC-V does not guarantee that
    /// stores to instruction memory will be made visible to instruction fetches on a
    /// RISC-V hart until that hart executes a FENCE.I instruction.
    ///
    /// A FENCE.I instruction ensures that a subsequent instruction fetch on a RISC-V hart
    /// will see any previous data stores already visible to the same RISC-V hart.
    /// FENCE.I does not ensure that other RISC-V harts’ instruction fetches will observe the
    /// local hart’s stores in a multiprocessor system. To make a store to instruction memory
    /// visible to all RISC-V harts, the writing hart also has to execute a data FENCE before
    /// requesting that all remote RISC-V harts execute a FENCE.I.
    ///
    /// The unused fields in the FENCE.I instruction, imm\[11:0\], rs1, and rd, are reserved for
    /// finer-grain fences in future extensions. For forward compatibility, base
    /// implementations shall ignore these fields, and standard software shall zero these fields.
    , fence_i, "fence.i", options(nostack));

/// `SFENCE.VMA` instruction wrapper
///
/// Synchronizes updates to in-memory memory-management data structures with current execution.
/// Instruction execution causes implicit reads and writes to these data structures; however, these implicit references
/// are ordinarily not ordered with respect to loads and stores in the instruction stream.
/// Executing an `SFENCE.VMA` instruction guarantees that any stores in the instruction stream prior to the
/// `SFENCE.VMA` are ordered before all implicit references subsequent to the `SFENCE.VMA`.
#[inline(always)]
#[cfg_attr(
    not(any(target_arch = "riscv32", target_arch = "riscv64")),
    allow(unused_variables)
)]
pub fn sfence_vma(asid: usize, addr: usize) {
    #[cfg(any(target_arch = "riscv32", target_arch = "riscv64"))]
    unsafe {
        core::arch::asm!("sfence.vma {}, {}", in(reg) addr, in(reg) asid, options(nostack));
    }
    #[cfg(not(any(target_arch = "riscv32", target_arch = "riscv64")))]
    unimplemented!();
}

/// Blocks the program for *at least* `cycles` CPU cycles.
///
/// This is implemented in assembly so its execution time is independent of the optimization
/// level, however it is dependent on the specific architecture and core configuration.
///
/// NOTE that the delay can take much longer if interrupts are serviced during its execution
/// and the execution time may vary with other factors. This delay is mainly useful for simple
/// timer-less initialization of peripherals if and only if accurate timing is not essential. In
/// any other case please use a more accurate method to produce a delay.
#[inline]
#[cfg_attr(
    not(any(target_arch = "riscv32", target_arch = "riscv64")),
    allow(unused_variables)
)]
pub fn delay(cycles: u32) {
    #[cfg(any(target_arch = "riscv32", target_arch = "riscv64"))]
    {
        let real_cyc = 1 + cycles / 2;
        unsafe {
            core::arch::asm!(
                "2:",
                "addi {0}, {0}, -1",
                "bne {0}, zero, 2b",
                inout(reg) real_cyc => _,
                options(nomem, nostack),
            );
        }
    }
    #[cfg(not(any(target_arch = "riscv32", target_arch = "riscv64")))]
    unimplemented!();
}