wasmer/utils/mem/
mod.rs

1pub(crate) mod access;
2pub(crate) mod ptr;
3pub use ptr::*;
4
5use std::{
6    marker::PhantomData,
7    mem::{self, MaybeUninit},
8    ops::Range,
9    slice,
10    string::FromUtf8Error,
11};
12
13use crate::{buffer::MemoryBuffer, error::RuntimeError, view::MemoryView};
14use access::{WasmRefAccess, WasmSliceAccess};
15use thiserror::Error;
16pub use wasmer_types::{Memory32, Memory64, MemorySize, ValueType};
17
18/// Error for invalid [`Memory`][crate::Memory] access.
19#[derive(Clone, Copy, Debug, Error)]
20#[non_exhaustive]
21pub enum MemoryAccessError {
22    /// Memory access is outside heap bounds.
23    #[error("memory access out of bounds")]
24    HeapOutOfBounds,
25    /// Address calculation overflow.
26    #[error("address calculation overflow")]
27    Overflow,
28    /// String is not valid UTF-8.
29    #[error("string is not valid utf-8")]
30    NonUtf8String,
31    /// Pointer to memory is unaligned.
32    #[error("unaligned pointer read")]
33    UnalignedPointerRead,
34}
35
36impl From<MemoryAccessError> for RuntimeError {
37    fn from(err: MemoryAccessError) -> Self {
38        Self::new(err.to_string())
39    }
40}
41impl From<FromUtf8Error> for MemoryAccessError {
42    fn from(_err: FromUtf8Error) -> Self {
43        Self::NonUtf8String
44    }
45}
46
47/// Reference to a value in Wasm memory.
48///
49/// The type of the value must satisfy the requirements of the `ValueType`
50/// trait which guarantees that reading and writing such a value to untrusted
51/// memory is safe.
52///
53/// The address is required to be aligned: unaligned accesses cause undefined behavior.
54///
55/// This wrapper safely handles concurrent modifications of the data by another
56/// thread.
57#[derive(Clone, Copy)]
58pub struct WasmRef<'a, T: ValueType> {
59    #[allow(unused)]
60    pub(crate) buffer: MemoryBuffer<'a>,
61    pub(crate) offset: u64,
62    marker: PhantomData<*mut T>,
63}
64
65impl<'a, T: ValueType> WasmRef<'a, T> {
66    /// Creates a new `WasmRef` at the given offset in a memory.
67    #[inline]
68    pub fn new(view: &'a MemoryView, offset: u64) -> Self {
69        Self {
70            buffer: view.buffer(),
71            offset,
72            marker: PhantomData,
73        }
74    }
75
76    /// Get the offset into Wasm linear memory for this `WasmRef`.
77    #[inline]
78    pub fn offset(self) -> u64 {
79        self.offset
80    }
81
82    /// Get a `WasmPtr` for this `WasmRef`.
83    #[inline]
84    pub fn as_ptr32(self) -> WasmPtr<T, Memory32> {
85        WasmPtr::new(self.offset as u32)
86    }
87
88    /// Get a 64-bit `WasmPtr` for this `WasmRef`.
89    #[inline]
90    pub fn as_ptr64(self) -> WasmPtr<T, Memory64> {
91        WasmPtr::new(self.offset)
92    }
93
94    /// Get a `WasmPtr` for this `WasmRef`.
95    #[inline]
96    pub fn as_ptr<M: MemorySize>(self) -> WasmPtr<T, M> {
97        let offset: M::Offset = self
98            .offset
99            .try_into()
100            .map_err(|_| "invalid offset into memory")
101            .unwrap();
102        WasmPtr::<T, M>::new(offset)
103    }
104
105    /// Reads the location pointed to by this `WasmRef`.
106    #[inline]
107    pub fn read(self) -> Result<T, MemoryAccessError> {
108        let mut out = MaybeUninit::uninit();
109        let buf =
110            unsafe { slice::from_raw_parts_mut(out.as_mut_ptr() as *mut u8, mem::size_of::<T>()) };
111        self.buffer.read(self.offset, buf)?;
112        Ok(unsafe { out.assume_init() })
113        // Ok(self.access()?.read())
114    }
115
116    /// Writes to the location pointed to by this `WasmRef`.
117    #[inline]
118    pub fn write(self, val: T) -> Result<(), MemoryAccessError> {
119        self.access()?.write(val);
120        Ok(())
121    }
122
123    /// Gains direct access to the memory of this slice
124    #[inline]
125    pub fn access(self) -> Result<WasmRefAccess<'a, T>, MemoryAccessError> {
126        WasmRefAccess::new(self, self.buffer.is_owned())
127    }
128}
129
130impl<T: ValueType> std::fmt::Debug for WasmRef<'_, T> {
131    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
132        write!(
133            f,
134            "WasmRef(offset: {}, pointer: {:#x})",
135            self.offset, self.offset
136        )
137    }
138}
139
140/// Reference to an array of values in Wasm memory.
141///
142/// The type of the value must satisfy the requirements of the `ValueType`
143/// trait which guarantees that reading and writing such a value to untrusted
144/// memory is safe.
145///
146/// The address is not required to be aligned: unaligned accesses are fully
147/// supported.
148///
149/// This wrapper safely handles concurrent modifications of the data by another
150/// thread.
151#[derive(Clone, Copy)]
152pub struct WasmSlice<'a, T: ValueType> {
153    pub(crate) buffer: MemoryBuffer<'a>,
154    pub(crate) offset: u64,
155    pub(crate) len: u64,
156    marker: PhantomData<*mut T>,
157}
158
159impl<'a, T: ValueType> WasmSlice<'a, T> {
160    /// Creates a new `WasmSlice` starting at the given offset in memory and
161    /// with the given number of elements.
162    ///
163    /// Returns a `MemoryAccessError` if the slice length overflows or extends
164    /// beyond the linear memory.
165    #[inline]
166    pub fn new(view: &'a MemoryView, offset: u64, len: u64) -> Result<Self, MemoryAccessError> {
167        let total_len = len
168            .checked_mul(mem::size_of::<T>() as u64)
169            .ok_or(MemoryAccessError::Overflow)?;
170        let end = offset
171            .checked_add(total_len)
172            .ok_or(MemoryAccessError::Overflow)?;
173        if end > view.data_size() {
174            return Err(MemoryAccessError::HeapOutOfBounds);
175        }
176        Ok(Self {
177            buffer: view.buffer(),
178            offset,
179            len,
180            marker: PhantomData,
181        })
182    }
183
184    /// Get the offset into Wasm linear memory for this `WasmSlice`.
185    #[inline]
186    pub fn offset(self) -> u64 {
187        self.offset
188    }
189
190    /// Get a 32-bit `WasmPtr` for this `WasmRef`.
191    #[inline]
192    pub fn as_ptr32(self) -> WasmPtr<T, Memory32> {
193        WasmPtr::new(self.offset as u32)
194    }
195
196    /// Get a 64-bit `WasmPtr` for this `WasmRef`.
197    #[inline]
198    pub fn as_ptr64(self) -> WasmPtr<T, Memory64> {
199        WasmPtr::new(self.offset)
200    }
201
202    /// Get the number of elements in this slice.
203    #[inline]
204    pub fn len(self) -> u64 {
205        self.len
206    }
207
208    /// Returns `true` if the number of elements is 0.
209    #[inline]
210    pub fn is_empty(self) -> bool {
211        self.len == 0
212    }
213
214    /// Returns `true` if accessing this slice requires an owned host buffer.
215    #[inline]
216    pub fn is_owned(self) -> bool {
217        self.buffer.is_owned()
218    }
219
220    /// Get a `WasmRef` to an element in the slice.
221    #[inline]
222    pub fn index(self, idx: u64) -> WasmRef<'a, T> {
223        if idx >= self.len {
224            panic!("WasmSlice out of bounds");
225        }
226        let offset = self.offset + idx * mem::size_of::<T>() as u64;
227        WasmRef {
228            buffer: self.buffer,
229            offset,
230            marker: PhantomData,
231        }
232    }
233
234    /// Get a `WasmSlice` for a subslice of this slice.
235    #[inline]
236    pub fn subslice(self, range: Range<u64>) -> Self {
237        if range.start > range.end || range.end > self.len {
238            panic!("WasmSlice out of bounds");
239        }
240        let offset = self.offset + range.start * mem::size_of::<T>() as u64;
241        Self {
242            buffer: self.buffer,
243            offset,
244            len: range.end - range.start,
245            marker: PhantomData,
246        }
247    }
248
249    /// Get an iterator over the elements in this slice.
250    #[inline]
251    pub fn iter(self) -> WasmSliceIter<'a, T> {
252        WasmSliceIter { slice: self }
253    }
254
255    /// Gains direct access to the memory of this slice
256    #[inline]
257    pub fn access(self) -> Result<WasmSliceAccess<'a, T>, MemoryAccessError> {
258        WasmSliceAccess::new(self, self.buffer.is_owned())
259    }
260
261    /// Reads an element of this slice.
262    #[inline]
263    pub fn read(self, idx: u64) -> Result<T, MemoryAccessError> {
264        self.index(idx).read()
265    }
266
267    /// Writes to an element of this slice.
268    #[inline]
269    pub fn write(self, idx: u64, val: T) -> Result<(), MemoryAccessError> {
270        self.index(idx).write(val)
271    }
272
273    /// Reads the entire slice into the given buffer.
274    ///
275    /// The length of the buffer must match the length of the slice.
276    #[inline]
277    pub fn read_slice(self, buf: &mut [T]) -> Result<(), MemoryAccessError> {
278        assert_eq!(
279            buf.len() as u64,
280            self.len,
281            "slice length doesn't match WasmSlice length"
282        );
283        let size = std::mem::size_of_val(buf);
284        let bytes =
285            unsafe { slice::from_raw_parts_mut(buf.as_mut_ptr() as *mut MaybeUninit<u8>, size) };
286        self.buffer.read_uninit(self.offset, bytes)?;
287        Ok(())
288    }
289
290    /// Reads the entire slice into the given uninitialized buffer.
291    ///
292    /// The length of the buffer must match the length of the slice.
293    ///
294    /// This method returns an initialized view of the buffer.
295    #[inline]
296    pub fn read_slice_uninit(
297        self,
298        buf: &mut [MaybeUninit<T>],
299    ) -> Result<&mut [T], MemoryAccessError> {
300        assert_eq!(
301            buf.len() as u64,
302            self.len,
303            "slice length doesn't match WasmSlice length"
304        );
305        let bytes = unsafe {
306            slice::from_raw_parts_mut(
307                buf.as_mut_ptr() as *mut MaybeUninit<u8>,
308                buf.len() * mem::size_of::<T>(),
309            )
310        };
311        self.buffer.read_uninit(self.offset, bytes)?;
312        Ok(unsafe { slice::from_raw_parts_mut(buf.as_mut_ptr() as *mut T, buf.len()) })
313    }
314
315    /// Write the given slice into this `WasmSlice`.
316    ///
317    /// The length of the slice must match the length of the `WasmSlice`.
318    #[inline]
319    pub fn write_slice(self, data: &[T]) -> Result<(), MemoryAccessError> {
320        assert_eq!(
321            data.len() as u64,
322            self.len,
323            "slice length doesn't match WasmSlice length"
324        );
325        let size = std::mem::size_of_val(data);
326        let bytes = unsafe { slice::from_raw_parts(data.as_ptr() as *const u8, size) };
327        self.buffer.write(self.offset, bytes)
328    }
329
330    /// Reads this `WasmSlice` into a `slice`.
331    #[inline]
332    pub fn read_to_slice(self, buf: &mut [MaybeUninit<u8>]) -> Result<usize, MemoryAccessError> {
333        let len = self.len.try_into().expect("WasmSlice length overflow");
334        self.buffer.read_uninit(self.offset, buf)?;
335        Ok(len)
336    }
337
338    /// Reads this `WasmSlice` into a `Vec`.
339    #[inline]
340    pub fn read_to_vec(self) -> Result<Vec<T>, MemoryAccessError> {
341        let len = self.len.try_into().expect("WasmSlice length overflow");
342        let mut vec = Vec::with_capacity(len);
343        let bytes = unsafe {
344            slice::from_raw_parts_mut(
345                vec.as_mut_ptr() as *mut MaybeUninit<u8>,
346                len * mem::size_of::<T>(),
347            )
348        };
349        self.buffer.read_uninit(self.offset, bytes)?;
350        unsafe {
351            vec.set_len(len);
352        }
353        Ok(vec)
354    }
355
356    /// Reads this `WasmSlice` into a `BytesMut`
357    #[inline]
358    pub fn read_to_bytes(self) -> Result<bytes::BytesMut, MemoryAccessError> {
359        let len = self.len.try_into().expect("WasmSlice length overflow");
360        let mut ret = bytes::BytesMut::with_capacity(len);
361        let bytes = unsafe {
362            slice::from_raw_parts_mut(
363                ret.as_mut_ptr() as *mut MaybeUninit<u8>,
364                len * mem::size_of::<T>(),
365            )
366        };
367        self.buffer.read_uninit(self.offset, bytes)?;
368        unsafe {
369            ret.set_len(len);
370        }
371        Ok(ret)
372    }
373}
374
375impl<T: ValueType> std::fmt::Debug for WasmSlice<'_, T> {
376    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
377        write!(
378            f,
379            "WasmSlice(offset: {}, len: {}, pointer: {:#x})",
380            self.offset, self.len, self.offset
381        )
382    }
383}
384
385/// Iterator over the elements of a `WasmSlice`.
386pub struct WasmSliceIter<'a, T: ValueType> {
387    slice: WasmSlice<'a, T>,
388}
389
390impl<'a, T: ValueType> Iterator for WasmSliceIter<'a, T> {
391    type Item = WasmRef<'a, T>;
392
393    fn next(&mut self) -> Option<Self::Item> {
394        if !self.slice.is_empty() {
395            let elem = self.slice.index(0);
396            self.slice = self.slice.subslice(1..self.slice.len());
397            Some(elem)
398        } else {
399            None
400        }
401    }
402
403    fn size_hint(&self) -> (usize, Option<usize>) {
404        (0..self.slice.len()).size_hint()
405    }
406}
407
408impl<T: ValueType> DoubleEndedIterator for WasmSliceIter<'_, T> {
409    fn next_back(&mut self) -> Option<Self::Item> {
410        if !self.slice.is_empty() {
411            let elem = self.slice.index(self.slice.len() - 1);
412            self.slice = self.slice.subslice(0..self.slice.len() - 1);
413            Some(elem)
414        } else {
415            None
416        }
417    }
418}
419
420impl<T: ValueType> ExactSizeIterator for WasmSliceIter<'_, T> {}
wasmer/utils/mem/mod.rs

wasmer/utils/mem/
mod.rs
