1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265
//! # mem-storage //! //! mem-storage is an abstraction over a chunk of memory, that is readable and writable. //! It can be used in in everything, that requires some sort of memory, e.g. the RAM in an emulator. //! This crate can also be used in no_std environment. //! //! ## Motivation //! //! Every time I write an emulator, I don't like to make //! a `struct Memory` over and over again and always copy paste methods like //! `read_u8`, `read_u16`, etc. So I came up with a generic solution for this problem. //! //! ## Usage //! //! ### Use the MemoryStorage trait //! //! ```compile_fail //! use mem_storage::MemoryStorage; //! //! let mem = MyMemory::new(); //! //! /// The `read` and `write` method will read / write data using little endian format. //! /// For big endian format use `read_be` and `write_be`. //! mem.write(0xABCD, 123); //! //! let value = mem.read::<u8>(0xABCD); //! assert_eq!(123u8, value); //! //! mem.write(0x1000, 12345u64); //! //! let value = mem.read::<u64>(0x1000); //! assert_eq!(12345u64, value); //! //! mem.write_be(0x2000, 1234567u64); //! //! let value = mem.read_be::<u64>(0x2000); //! assert_eq!(1234567u64, value); //! ``` //! //! ### Implement the Memory trait //! //! ``` //! use mem_storage::MemoryStorage; //! //! /// This time your struct is responsible for storing the data. //! struct MyMemory { //! ram: Vec<u8>, //! } //! //! impl MyMemory { //! fn new() -> Self { //! // Create 1KiB of zero initialized memory //! Self { ram: vec![0u8; 1024 * 1024] } //! } //! } //! //! impl MemoryStorage for MyMemory { //! /// If an `Err` is returned, the addr is out of bounds //! type Error = (); //! //! fn get<I>(&self, index: I) -> Result<&I::Output, Self::Error> //! where //! I: std::slice::SliceIndex<[u8]>, //! { //! self.ram.get(index).ok_or(()) //! } //! //! fn get_mut<I>(&mut self, index: I) -> Result<&mut I::Output, Self::Error> //! where //! I: std::slice::SliceIndex<[u8]>, //! { //! self.ram.get_mut(index).ok_or(()) //! } //! //! fn try_read_byte(&self, addr: usize) -> Result<u8, Self::Error> { //! self.ram.get(addr).copied().ok_or(()) //! } //! //! fn try_write_byte(&mut self, addr: usize, value: u8) -> Result<(), Self::Error> { //! let mut value = self.ram.get_mut(addr).ok_or(())?; //! *value = *value; //! Ok(()) //! } //! //! // The trait will provide a generic `read` and `read_be` method for you. //! } //! ``` //! //! ## License //! //! This project is double-licensed under the Zlib or Apache2.0 license. #![no_std] #![warn(rust_2018_idioms)] #![warn(missing_docs)] #![warn(clippy::all)] use core::slice::SliceIndex; /// The `Memory` trait represents a chunk of memory that can read from, /// or written to. pub trait MemoryStorage { /// The `Error` type can be used to indicate if memory access was invalid. /// /// Usually this is just `()` and if `Err(())` is returned, it means that the address is out of bounds. type Error: core::fmt::Debug; /// Returns a reference to an element or subslice depending on the type of /// index. fn get<I>(&self, index: I) -> Result<&I::Output, Self::Error> where I: SliceIndex<[u8]>; /// Returns a mutable reference to an element or subslice depending on the type of /// index. fn get_mut<I>(&mut self, index: I) -> Result<&mut I::Output, Self::Error> where I: SliceIndex<[u8]>; /// Tries to read a byte at the given address. /// /// Returns `Err(x)` if the method failed to read a byte from the address. fn try_read_byte(&self, addr: usize) -> Result<u8, Self::Error>; /// Tries to write a byte to the given address. /// /// Returns `Err(x)` if the method failed to write a byte to the address. fn try_write_byte(&mut self, addr: usize, byte: u8) -> Result<(), Self::Error>; /// Reads a byte at the given address. /// /// Panics if the read failed fn read_byte(&self, addr: usize) -> u8 { self.try_read_byte(addr) .expect("failed to read from memory") } /// Writes a byte to the given address. /// /// Panics if the write failed fn write_byte(&mut self, addr: usize, byte: u8) { self.try_write_byte(addr, byte) .expect("failed to write to memory") } /// Tries to read a generic `Value` at the given address using little endian format. /// /// Returns `Err(x)` if the method failed to read a value at the address. fn try_read<V: Value>(&self, addr: usize) -> Result<V, Self::Error> { let size = core::mem::size_of::<V>(); let slice = self.get(addr..addr + size)?; // Safety: `Value` is only implemented for all primitive number types, and can not be implemented // for any other types. Thus a transmute between raw bytes and a `Value` is safe. // The length of the `slice` is checked before this method is called. let value = unsafe { debug_assert_eq!(core::mem::size_of::<V>(), slice.len()); let slice = core::slice::from_raw_parts(slice.as_ptr() as *const V, 1); slice[0].to_le() }; Ok(value) } /// Reads a generic `Value` at the given address using little endian format. /// /// Panics if the method failed to read a value at the address. fn read<V: Value>(&self, addr: usize) -> V { self.try_read::<V>(addr).expect("failed to read memory") } /// Tries to read a generic `Value` at the given address using big endian format. /// /// Returns `Err(x)` if the method failed to read a value at the address. fn try_read_be<V: Value>(&self, addr: usize) -> Result<V, Self::Error> { self.try_read(addr).map(Value::to_be) } /// Reads a generic `Value` at the given address using big endian format. /// /// Panics if the method failed to read a value at the address. fn read_be<V: Value>(&self, addr: usize) -> V { self.read::<V>(addr).to_be() } /// Tries to write a generic `Value` to the given address using little endian format. /// /// Returns `Err(x)` if the method failed to write a value to the address. fn try_write<V: Value>(&mut self, addr: usize, val: V) -> Result<(), Self::Error> { let size = core::mem::size_of::<V>(); let val = val.to_le(); let slice = self.get_mut(addr..addr + size)?; // Safety: `Value` is only implemented for all primitive number types, and can not be implemented // for any other types. Thus a transmute between raw bytes and a `Value` is safe. let raw_value = unsafe { let ptr: *const V = &val; core::slice::from_raw_parts(ptr as *const u8, size) }; slice.copy_from_slice(raw_value); Ok(()) } /// Writes a generic `Value` to the given address using little endian format. /// /// Panics if the method failed to write a value to the address. fn write<V: Value>(&mut self, addr: usize, val: V) { self.try_write::<V>(addr, val) .expect("failed to write memory") } /// Tries to write a generic `Value` to the given address using big endian format. /// /// Returns `Err(x)` if the method failed to write a value to the address. fn try_write_be<V: Value>(&mut self, addr: usize, val: V) -> Result<(), Self::Error> { self.try_write(addr, val.to_be()) } /// Writes a generic `Value` to the given address using big endian format. /// /// Panics if the method failed to write a value to the address. fn write_be<V: Value>(&mut self, addr: usize, val: V) { self.write(addr, val.to_be()); } } macro_rules! impl_trait { ($($ty:path),*) => { $( impl Value for $ty { fn to_le(self) -> Self { self.to_le() } fn to_be(self) -> Self { self.to_be() } } )* }; } /// A marker trait that is implemented for all number types that can be read from and written to /// a `Memory`. pub trait Value: private::Sealed + Sized + Copy { /// Converts `self` to little endian format. fn to_le(self) -> Self; /// Converts `self` to big endian format. fn to_be(self) -> Self; } impl_trait!(u8, i8, u16, i16, u32, i32, u64, i64, u128, i128); mod private { pub trait Sealed {} macro_rules! impl_trait { ($($ty:path),*) => { $(impl Sealed for $ty {})* }; } impl_trait!(u8, i8, u16, i16, u32, i32, u64, i64, u128, i128); }