feat: explicitly populate memory access errors and improved proc-macro code

Author: WolverinDEV

Cargo.lock

@@ -8,7 +8,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.1.3"
+version = "0.2.0"
 edition = "2021"
 authors = ["Markus Hadenfeldt <[email protected]>"]
 description = "raw_struct is a Rust procedural macro for easily declaring C-style structs that reference local or external memory, based on your memory implementation. It generates appropiate getter methods for easy access."

Cargo.toml

@@ -1,15 +1,17 @@
 # raw_struct   [![Latest Version]][crates.io] [![License: GPL v3]](./LICENSE) [![GitHub build status]][actions]
 
-[License: GPL v3]: https://img.shields.io/badge/License-GPLv3-blue.svg
-[Latest Version]: https://img.shields.io/crates/v/raw_struct.svg
+[license: gpl v3]: https://img.shields.io/badge/License-GPLv3-blue.svg
+[latest version]: https://img.shields.io/crates/v/raw_struct.svg
 [crates.io]: https://crates.io/crates/raw_struct
-[GitHub build status]: https://github.com/WolverinDEV/raw-struct/workflows/Rust/badge.svg?branch=master
+[github build status]: https://github.com/WolverinDEV/raw-struct/workflows/Rust/badge.svg?branch=master
 [actions]: https://github.com/WolverinDEV/raw-struct/actions?query=workflow%3ARust
 
 `raw_struct` is a Rust procedural macro for easily declaring C-style structs that reference local or external memory, based on your memory implementation. It generates appropiate getter methods for easy access. This crate has support for `no_std` environments.
 
 ## Usage
+
 To use `raw_struct`, simply define a struct with the raw_struct attribute as following:
+
 ```rust
 #[raw_struct(size = 0x10)]
 struct MyStruct {
@@ -25,10 +27,11 @@ struct MyStruct {
 ```
 
 To reference the declared struct in memory you can ether do so by `Reference` or `Copy`:
+
 ```rust
 let memory = [0u8; 0x10];
 {
-    let object = Reference::<dyn MyStruct>::new(0x00, Arc::new(memory.clone()));
+    let object = Reference::<dyn MyStruct, _>::new(0x00, Arc::new(memory.clone()));
     println!("field_a = {}", object.field_a()?);
     println!("field_b = {}", object.field_b()?);
 }
@@ -41,9 +44,15 @@ let memory = [0u8; 0x10];
 ```
 
 ## Examples
+
 Examples can be found within the examples directory of this repository. These examples demonstrate how to use raw_struct in various contexts.
 
 To run the examples, clone the repository and use the following command:
+
 ```bash
 cargo run --bin <example_name>
-```
+```
+
+## Performance
+
+In release mode, accessing `raw_structs` behind a `Copy<...>` is as efficient as general memory accesses, with **zero overhead**.

README.MD

@@ -1,7 +1,9 @@
 use std::{
     self,
     error::Error,
-    marker,
+    marker::{
+        self,
+    },
 };
 
 use raw_struct::{
@@ -12,12 +14,16 @@ use raw_struct::{
 };
 
 fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
+    /*
+     * Note:
+     * Accessing all the container entries evaluates in release mode to just a mov instruction.
+     */
     let buffer = [0x1122u64, 0x8877, 0x9988];
     let object = Copy::<dyn Container<u64>>::read_object(&buffer, 0x00)?;
 
     println!(
         "Memory size: 0x{:X}",
-        <dyn Container::<u64> as Viewable<_>>::MEMORY_SIZE
+        <dyn Container::<u64> as Viewable>::MEMORY_SIZE
     );
     println!("Vat a = 0x{:X}", object.var_a()?);
     println!("Inner = 0x{:X}", object.inner()?);

examples/dyn_memory/src/main.rs

@@ -18,18 +18,15 @@ use raw_struct::{
 };
 
 fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
-    let mut memory = [0u8; 0x20];
+    let mut memory = [0u8; 0x40];
     memory[0..4].copy_from_slice(&0x6Fu32.to_le_bytes());
     memory[4..8].copy_from_slice(&0x99u32.to_le_bytes());
 
-    println!(
-        "{}",
-        <dyn MyStruct as Viewable::<dyn MyStruct>>::MEMORY_SIZE
-    );
+    println!("{}", <dyn MyStruct as Viewable>::MEMORY_SIZE);
 
     let memory = Arc::new(memory);
     {
-        let object = Reference::<dyn MyStruct>::new(memory.clone(), 0x00);
+        let object = Reference::<dyn MyStruct, _>::new(memory.clone(), 0x00);
         println!("field_a = {}", object.field_a()?);
         println!("field_b = {}", object.field_b()?);
     }

examples/minimal/src/main.rs

@@ -10,7 +10,7 @@ description.workspace = true
 readme = "../README.MD"
 
 [dependencies]
-raw_struct_derive = { version = "0.1", path = "../raw_struct_derive" }
+raw_struct_derive = { version = "0.2", path = "../raw_struct_derive" }
 
 [features]
 no_std = []

raw_struct/Cargo.toml

@@ -30,7 +30,11 @@ pub trait Array<T: ?Sized> {
 }
 
 impl<T: FromMemoryView> dyn Array<T> {
-    pub fn element_at(&self, memory: &dyn MemoryView, index: usize) -> Result<T, AccessError> {
+    pub fn element_at<E>(
+        &self,
+        memory: &dyn MemoryView<Error = E>,
+        index: usize,
+    ) -> Result<T, AccessError<E>> {
         let offset = (index * mem::size_of::<T>()) as u64;
         T::read_object(memory, self.start_address() + offset).map_err(|err| AccessError {
             source: err,
@@ -42,11 +46,11 @@ impl<T: FromMemoryView> dyn Array<T> {
         })
     }
 
-    pub fn elements(
+    pub fn elements<E>(
         &self,
-        memory: &dyn MemoryView,
+        memory: &dyn MemoryView<Error = E>,
         range: Range<usize>,
-    ) -> Result<Vec<T>, AccessError> {
+    ) -> Result<Vec<T>, AccessError<E>> {
         let element_count = range.end - range.start;
         let mut result = Vec::with_capacity(element_count);
 
@@ -75,17 +79,21 @@ impl<T: FromMemoryView> dyn Array<T> {
     }
 }
 
-impl<T: ?Sized + Viewable<T>> dyn Array<T> {
-    pub fn element_reference(&self, memory: Arc<dyn MemoryView>, index: usize) -> Reference<T> {
+impl<T: ?Sized + Viewable> dyn Array<T> {
+    pub fn element_reference<E: 'static>(
+        &self,
+        memory: Arc<dyn MemoryView<Error = E>>,
+        index: usize,
+    ) -> Reference<T, E> {
         let offset = (index * T::MEMORY_SIZE) as u64;
         Reference::new(memory, self.start_address() + offset)
     }
 
-    pub fn elements_reference(
+    pub fn elements_reference<E: 'static>(
         &self,
-        memory: Arc<dyn MemoryView>,
+        memory: Arc<dyn MemoryView<Error = E>>,
         range: Range<usize>,
-    ) -> Vec<Reference<T>> {
+    ) -> Vec<Reference<T, E>> {
         Vec::from_iter(range.map(|index| {
             Reference::new(
                 memory.clone(),
@@ -95,15 +103,15 @@ impl<T: ?Sized + Viewable<T>> dyn Array<T> {
     }
 }
 
-impl<T: ?Sized + Viewable<T>> dyn Array<T>
+impl<T: ?Sized + Viewable> dyn Array<T>
 where
-    T::Implementation<T::Memory>: marker::Copy,
+    T::Instance<T::Memory>: marker::Copy,
 {
-    pub fn element_copy(
+    pub fn element_copy<E>(
         &self,
-        memory: &dyn MemoryView,
+        memory: &dyn MemoryView<Error = E>,
         index: usize,
-    ) -> Result<Copy<T>, AccessError> {
+    ) -> Result<Copy<T>, AccessError<E>> {
         let offset = (index * T::MEMORY_SIZE) as u64;
         Copy::read_object(memory, self.start_address() + offset).map_err(|err| AccessError {
             source: err,
@@ -115,11 +123,11 @@ where
         })
     }
 
-    pub fn elements_copy(
+    pub fn elements_copy<E>(
         &self,
-        memory: &dyn MemoryView,
+        memory: &dyn MemoryView<Error = E>,
         range: Range<usize>,
-    ) -> Result<Vec<Copy<T>>, AccessError> {
+    ) -> Result<Vec<Copy<T>>, AccessError<E>> {
         let element_count = range.end - range.start;
         let mut result = Vec::<T::Memory>::with_capacity(element_count);
 

raw_struct/src/builtins/array.rs

@@ -54,7 +54,10 @@ impl<T: ?Sized> Ptr64<T> {
 impl<T: marker::Copy> Ptr64<T> {
     /// Create a copy of the value the pointer points to
     #[must_use = "copied result must be used"]
-    pub fn read_value(&self, memory: &dyn MemoryView) -> Result<Option<T>, AccessError> {
+    pub fn read_value<E>(
+        &self,
+        memory: &dyn MemoryView<Error = E>,
+    ) -> Result<Option<T>, AccessError<E>> {
         if self.address > 0 {
             let memory = T::read_object(memory, self.address).map_err(|err| AccessError {
                 source: err,
@@ -74,9 +77,12 @@ impl<T: marker::Copy> Ptr64<T> {
     }
 }
 
-impl<T: ?Sized + Viewable<T>> Ptr64<T> {
+impl<T: ?Sized + Viewable> Ptr64<T> {
     #[must_use]
-    pub fn value_reference(&self, memory: Arc<dyn MemoryView>) -> Option<Reference<T>> {
+    pub fn value_reference<E: 'static>(
+        &self,
+        memory: Arc<dyn MemoryView<Error = E>>,
+    ) -> Option<Reference<T, E>> {
         if self.address > 0 {
             Some(Reference::new(memory, self.address))
         } else {
@@ -86,7 +92,10 @@ impl<T: ?Sized + Viewable<T>> Ptr64<T> {
 
     /// Create a copy of the value the pointer points to
     #[must_use = "copied result must be used"]
-    pub fn value_copy(&self, memory: &dyn MemoryView) -> Result<Option<Copy<T>>, AccessError> {
+    pub fn value_copy<E>(
+        &self,
+        memory: &dyn MemoryView<Error = E>,
+    ) -> Result<Option<Copy<T>>, AccessError<E>> {
         if self.address > 0 {
             let memory =
                 T::Memory::read_object(memory, self.address).map_err(|err| AccessError {

raw_struct/src/builtins/ptr.rs

@@ -4,21 +4,18 @@ use core::{
     ops::Deref,
 };
 
-use crate::{
-    view::Viewable,
-    ViewableImplementation,
-};
+use crate::view::Viewable;
 
 /// A Copy represents an owned copy of the struct binary contents
 #[repr(transparent)]
-pub struct Copy<T: ?Sized + Viewable<T>> {
-    inner: T::Implementation<T::Memory>,
+pub struct Copy<T: ?Sized + Viewable> {
+    inner: T::Instance<T::Memory>,
 }
 
-impl<T: ?Sized + Viewable<T>> Copy<T> {
+impl<T: ?Sized + Viewable> Copy<T> {
     pub fn new(inner: T::Memory) -> Self {
         Self {
-            inner: T::create(inner),
+            inner: T::create_view(inner),
         }
     }
 
@@ -30,18 +27,18 @@ impl<T: ?Sized + Viewable<T>> Copy<T> {
     }
 }
 
-impl<T: ?Sized + Viewable<T>> Deref for Copy<T> {
-    type Target = T;
+impl<T: ?Sized + Viewable> Deref for Copy<T> {
+    type Target = T::Instance<T::Memory>;
 
     fn deref(&self) -> &Self::Target {
-        self.inner.as_trait()
+        &self.inner
     }
 }
 
 impl<T> Clone for Copy<T>
 where
-    T: ?Sized + Viewable<T>,
-    T::Implementation<T::Memory>: Clone,
+    T: ?Sized + Viewable,
+    T::Instance<T::Memory>: Clone,
 {
     fn clone(&self) -> Self {
         Self {
@@ -52,7 +49,7 @@ where
 
 impl<T> marker::Copy for Copy<T>
 where
-    T: ?Sized + Viewable<T>,
-    T::Implementation<T::Memory>: marker::Copy,
+    T: ?Sized + Viewable,
+    T::Instance<T::Memory>: marker::Copy,
 {
 }

raw_struct/src/copy.rs

@@ -1,16 +1,16 @@
 use alloc::{
     borrow::Cow,
-    boxed::Box,
     format,
 };
 #[cfg(feature = "no_std")]
 pub use core::error::Error as ErrorType;
-use core::fmt;
+use core::{
+    convert::Infallible,
+    fmt,
+};
 #[cfg(not(feature = "no_std"))]
 pub use std::error::Error as ErrorType;
 
-pub type Error = Box<dyn ErrorType + Send + Sync + 'static>;
-
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum AccessMode {
     Read,
@@ -38,8 +38,8 @@ impl fmt::Display for AccessViolation {
 impl ErrorType for AccessViolation {}
 
 #[derive(Debug)]
-pub struct AccessError {
-    pub source: Error,
+pub struct AccessError<S = Infallible> {
+    pub source: S,
 
     pub offset: u64,
     pub size: usize,
@@ -49,7 +49,7 @@ pub struct AccessError {
     pub member: Option<Cow<'static, str>>,
 }
 
-impl fmt::Display for AccessError {
+impl<S: fmt::Display> fmt::Display for AccessError<S> {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(
             f,
@@ -67,8 +67,8 @@ impl fmt::Display for AccessError {
     }
 }
 
-impl ErrorType for AccessError {
+impl<S: ErrorType + 'static> ErrorType for AccessError<S> {
     fn source(&self) -> Option<&(dyn ErrorType + 'static)> {
-        Some(&*self.source)
+        Some(&self.source)
     }
 }