From 16fdb167306ea5e338a6c2737dd46894e8b801f2 Mon Sep 17 00:00:00 2001
From: Vadim Kaushan <admin@disasm.info>
Date: Thu, 24 Jan 2019 17:20:23 +0300
Subject: [PATCH] Update docs

---
 src/asm.rs | 34 +++++++++++++++++++++++++++++-----
 src/lib.rs |  2 +-
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/src/asm.rs b/src/asm.rs
index cf451a3..8ce24b7 100644
--- a/src/asm.rs
+++ b/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) {
diff --git a/src/lib.rs b/src/lib.rs
index 761d2d8..f1c0fe5 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -4,7 +4,7 @@
 //!
 //! - 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)]