Merge #17

17: Update docs and bump version r=dvc94ch a=Disasm

cc @rust-embedded/riscv

Co-authored-by: Vadim Kaushan <admin@disasm.info>

Cargo.toml

@@ -1,10 +1,10 @@
 [package]
 name = "riscv"
-version = "0.3.0"
+version = "0.4.0"
 repository = "https://github.com/rust-embedded/riscv"
 authors = ["David Craven <david@craven.ch>"]
 categories = ["embedded", "hardware-support", "no-std"]
-description = "Low level access to RISCV processors"
+description = "Low level access to RISC-V processors"
 keywords = ["riscv", "register", "peripheral"]
 license = "ISC"
 

src/asm.rs

@@ -1,7 +1,8 @@
 //! Assembly instructions
 
 macro_rules! instruction {
-    ($fnname:ident, $asm:expr, $asm_fn:ident) => (
+    ($(#[$attr:meta])*, $fnname:ident, $asm:expr, $asm_fn:ident) => (
+        $(#[$attr])*
         #[inline]
         pub unsafe fn $fnname() {
             match () {
@@ -25,12 +26,35 @@ macro_rules! instruction {
 }
 
 
-/// Priviledged ISA Instructions
-instruction!(ebreak, "ebreak", __ebreak);
-instruction!(wfi, "wfi", __wfi);
-instruction!(sfence_vma_all, "sfence.vma", __sfence_vma_all);
+instruction!(
+    /// `EBREAK` instruction wrapper
+    ///
+    /// Generates a breakpoint exception.
+    , ebreak, "ebreak", __ebreak);
+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.
+    , wfi, "wfi", __wfi);
+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", __sfence_vma_all);
 
 
+/// `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]
 #[allow(unused_variables)]
 pub unsafe fn sfence_vma(asid: usize, addr: usize) {

src/lib.rs

@@ -1,10 +1,10 @@
-//! Low level access to RISCV processors
+//! Low level access to RISC-V processors
 //!
 //! This crate provides:
 //!
 //! - Access to core registers like mstatus or mcause.
 //! - Interrupt manipulation mechanisms.
-//! - Safe wrappers around assembly instructions like `mret`.
+//! - Wrappers around assembly instructions like `WFI`.
 
 #![no_std]
 #![deny(warnings)]

src/register/mod.rs

@@ -1,4 +1,4 @@
-//! RISCV CSR's
+//! RISC-V CSR's
 //!
 //! The following registers are not available on 64-bit implementations.
 //!