Adding more documentation

src/lib.rs

@@ -15,7 +15,13 @@ use core::ptr;
 pub mod ubsan;
 #[cfg(feature = "std")]
 mod userspace;
-mod primitives;
+
+/// This module contains the primitives that need to be implemented to enable the usage of this
+/// library in a program environment.
+///
+/// An implementation for the user space is provided in [`crate::userspace`] and can be enabled
+/// with the `std` feature.
+pub mod primitives;
 mod spinlock;
 
 pub fn test() {

src/primitives.rs

@@ -1,7 +1,16 @@
 extern "C" {
-    pub fn zan_write(buffer: *const u8, nbytes: usize);
-    pub fn zan_abort();
-    pub fn zan_disable_interrupts();
+/// Prints out an error message to a debug output
+///
+/// # Arguments
+/// * `buffer`: pointer to character array containing at least `nbytes`
+/// * `nbytes`: number of bytes in the buffer
+pub fn zan_write(buffer: *const u8, nbytes: usize);
+
+/// Aborts the program
+pub fn zan_abort();
+
+/// Tries to disable interrupts or signals to ensure coherent debug output
+pub fn zan_disable_interrupts();
 }
 
 

src/ubsan/mod.rs

@@ -11,7 +11,7 @@ use crate::eprintln;
 
 
 static LOCK: Spinlock = Spinlock::new();
-static PROLOGUE_HEADER: &str = "=== UNDEFINED BEHAVIOUR DETECTED ===";
+const PROLOGUE_HEADER: &str = "=== UNDEFINED BEHAVIOUR DETECTED ===";
 const TYPE_CHECK_KINDS: [&str; 8] = [
     "load of",
     "store to",

src/userspace.rs

@@ -5,17 +5,19 @@ use std::io::Write;
 use std::process::exit;
 use std::slice;
 
+/// Write error message to stderr
 #[no_mangle]
 pub unsafe extern "C" fn zan_write(buffer: *const u8, nbytes: usize) {
     let buf = slice::from_raw_parts(buffer, nbytes);
     stderr().write_all(buf).unwrap();
 }
 
+/// Abort the program by exiting with error code
 #[no_mangle]
 pub unsafe extern "C" fn zan_abort() {
     exit(1);
 }
 
+/// Right now this does nothing, but it would be great to disable UNIX signals for example
 #[no_mangle]
-// didn't find a sane way to do this without additional crates
-pub fn zan_disable_interrupts() {}
+pub unsafe fn zan_disable_interrupts() {}