riscv: add result module

Adds the `result` module to contain types for fallible functions.

For discussion, see:
<#212 (comment)>

Author: rmsyn

riscv-pac/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+### Added
+
+- Add `result` module for `Error` and `Result` types
+
 ## [v0.1.1] - 2024-02-15
 
 - Fix crates.io badge links

riscv-pac/src/lib.rs

@@ -1,5 +1,7 @@
 #![no_std]
 
+pub mod result;
+
 /// Trait for enums of target-specific external interrupt numbers.
 ///
 /// This trait should be implemented by a peripheral access crate (PAC)

riscv-pac/src/result.rs

@@ -0,0 +1,48 @@
+use core::fmt;
+
+/// Convenience alias for the [Result](core::result::Result) type for the library.
+pub type Result<T> = core::result::Result<T, Error>;
+
+/// Represents error variants for the library.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum Error {
+    /// Attempted out-of-bounds access.
+    IndexOutOfBounds {
+        index: usize,
+        min: usize,
+        max: usize,
+    },
+    /// Invalid field value.
+    InvalidValue {
+        field: &'static str,
+        value: usize,
+        bitmask: usize,
+    },
+    /// Invalid value of a register field that does not match any known variants.
+    InvalidVariant { field: &'static str, value: usize },
+    /// Unimplemented function or type.
+    Unimplemented,
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::IndexOutOfBounds { index, min, max } => write!(
+                f,
+                "out-of-bounds access, index: {index}, min: {min}, max: {max}"
+            ),
+            Self::InvalidValue {
+                field,
+                value,
+                bitmask,
+            } => write!(
+                f,
+                "invalid {field} field value: {value:#x}, valid bitmask: {bitmask:#x}",
+            ),
+            Self::InvalidVariant { field, value } => {
+                write!(f, "invalid {field} field variant: {value:#x}")
+            }
+            Self::Unimplemented => write!(f, "unimplemented"),
+        }
+    }
+}

riscv/Cargo.toml

@@ -26,3 +26,4 @@ critical-section-single-hart = ["critical-section/restore-state-bool"]
 [dependencies]
 critical-section = "1.1.2"
 embedded-hal = "1.0.0"
+riscv-pac = { path = "../riscv-pac", version = "0.1.1", default-features = false }

riscv/src/lib.rs

@@ -40,6 +40,7 @@ pub(crate) mod bits;
 pub mod delay;
 pub mod interrupt;
 pub mod register;
+pub use riscv_pac::*;
 
 #[macro_use]
 mod macros;