wasmtime/runtime/memory.rs
1use crate::Trap;
2use crate::prelude::*;
3use crate::runtime::vm::VMMemoryImport;
4use crate::store::{StoreInstanceId, StoreOpaque};
5use crate::trampoline::generate_memory_export;
6use crate::{AsContext, AsContextMut, Engine, MemoryType, StoreContext, StoreContextMut};
7use core::cell::UnsafeCell;
8use core::fmt;
9use core::slice;
10use core::time::Duration;
11use wasmtime_environ::DefinedMemoryIndex;
12
13pub use crate::runtime::vm::WaitResult;
14
15/// Error for out of bounds [`Memory`] access.
16#[derive(Debug)]
17#[non_exhaustive]
18pub struct MemoryAccessError {
19 // Keep struct internals private for future extensibility.
20 _private: (),
21}
22
23impl fmt::Display for MemoryAccessError {
24 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
25 write!(f, "out of bounds memory access")
26 }
27}
28
29#[cfg(feature = "std")]
30impl std::error::Error for MemoryAccessError {}
31
32/// A WebAssembly linear memory.
33///
34/// WebAssembly memories represent a contiguous array of bytes that have a size
35/// that is always a multiple of the WebAssembly page size, currently 64
36/// kilobytes.
37///
38/// WebAssembly memory is used for global data (not to be confused with wasm
39/// `global` items), statics in C/C++/Rust, shadow stack memory, etc. Accessing
40/// wasm memory is generally quite fast.
41///
42/// Memories, like other wasm items, are owned by a [`Store`](crate::Store).
43///
44/// # `Memory` and Safety
45///
46/// Linear memory is a lynchpin of safety for WebAssembly. In Wasmtime there are
47/// safe methods of interacting with a [`Memory`]:
48///
49/// * [`Memory::read`]
50/// * [`Memory::write`]
51/// * [`Memory::data`]
52/// * [`Memory::data_mut`]
53///
54/// Note that all of these consider the entire store context as borrowed for the
55/// duration of the call or the duration of the returned slice. This largely
56/// means that while the function is running you'll be unable to borrow anything
57/// else from the store. This includes getting access to the `T` on
58/// [`Store<T>`](crate::Store), but it also means that you can't recursively
59/// call into WebAssembly for instance.
60///
61/// If you'd like to dip your toes into handling [`Memory`] in a more raw
62/// fashion (e.g. by using raw pointers or raw slices), then there's a few
63/// important points to consider when doing so:
64///
65/// * Any recursive calls into WebAssembly can possibly modify any byte of the
66/// entire memory. This means that whenever wasm is called Rust can't have any
67/// long-lived borrows live across the wasm function call. Slices like `&mut
68/// [u8]` will be violated because they're not actually exclusive at that
69/// point, and slices like `&[u8]` are also violated because their contents
70/// may be mutated.
71///
72/// * WebAssembly memories can grow, and growth may change the base pointer.
73/// This means that even holding a raw pointer to memory over a wasm function
74/// call is also incorrect. Anywhere in the function call the base address of
75/// memory may change. Note that growth can also be requested from the
76/// embedding API as well.
77///
78/// As a general rule of thumb it's recommended to stick to the safe methods of
79/// [`Memory`] if you can. It's not advised to use raw pointers or `unsafe`
80/// operations because of how easy it is to accidentally get things wrong.
81///
82/// Some examples of safely interacting with memory are:
83///
84/// ```rust
85/// use wasmtime::{Memory, Store, MemoryAccessError};
86///
87/// // Memory can be read and written safely with the `Memory::read` and
88/// // `Memory::write` methods.
89/// // An error is returned if the copy did not succeed.
90/// fn safe_examples(mem: Memory, store: &mut Store<()>) -> Result<(), MemoryAccessError> {
91/// let offset = 5;
92/// mem.write(&mut *store, offset, b"hello")?;
93/// let mut buffer = [0u8; 5];
94/// mem.read(&store, offset, &mut buffer)?;
95/// assert_eq!(b"hello", &buffer);
96///
97/// // Note that while this is safe care must be taken because the indexing
98/// // here may panic if the memory isn't large enough.
99/// assert_eq!(&mem.data(&store)[offset..offset + 5], b"hello");
100/// mem.data_mut(&mut *store)[offset..offset + 5].copy_from_slice(b"bye!!");
101///
102/// Ok(())
103/// }
104/// ```
105///
106/// It's worth also, however, covering some examples of **incorrect**,
107/// **unsafe** usages of `Memory`. Do not do these things!
108///
109/// ```rust
110/// # use anyhow::Result;
111/// use wasmtime::{Memory, Store};
112///
113/// // NOTE: All code in this function is not safe to execute and may cause
114/// // segfaults/undefined behavior at runtime. Do not copy/paste these examples
115/// // into production code!
116/// unsafe fn unsafe_examples(mem: Memory, store: &mut Store<()>) -> Result<()> {
117/// // First and foremost, any borrow can be invalidated at any time via the
118/// // `Memory::grow` function. This can relocate memory which causes any
119/// // previous pointer to be possibly invalid now.
120/// unsafe {
121/// let pointer: &u8 = &*mem.data_ptr(&store);
122/// mem.grow(&mut *store, 1)?; // invalidates `pointer`!
123/// // println!("{}", *pointer); // FATAL: use-after-free
124/// }
125///
126/// // Note that the use-after-free also applies to slices, whether they're
127/// // slices of bytes or strings.
128/// unsafe {
129/// let mem_slice = std::slice::from_raw_parts(
130/// mem.data_ptr(&store),
131/// mem.data_size(&store),
132/// );
133/// let slice: &[u8] = &mem_slice[0x100..0x102];
134/// mem.grow(&mut *store, 1)?; // invalidates `slice`!
135/// // println!("{:?}", slice); // FATAL: use-after-free
136/// }
137///
138/// // The `Memory` type may be stored in other locations, so if you hand
139/// // off access to the `Store` then those locations may also call
140/// // `Memory::grow` or similar, so it's not enough to just audit code for
141/// // calls to `Memory::grow`.
142/// unsafe {
143/// let pointer: &u8 = &*mem.data_ptr(&store);
144/// some_other_function(store); // may invalidate `pointer` through use of `store`
145/// // println!("{:?}", pointer); // FATAL: maybe a use-after-free
146/// }
147///
148/// // An especially subtle aspect of accessing a wasm instance's memory is
149/// // that you need to be extremely careful about aliasing. Anyone at any
150/// // time can call `data_unchecked()` or `data_unchecked_mut()`, which
151/// // means you can easily have aliasing mutable references:
152/// unsafe {
153/// let ref1: &u8 = &*mem.data_ptr(&store).add(0x100);
154/// let ref2: &mut u8 = &mut *mem.data_ptr(&store).add(0x100);
155/// // *ref2 = *ref1; // FATAL: violates Rust's aliasing rules
156/// }
157///
158/// Ok(())
159/// }
160/// # fn some_other_function(store: &mut Store<()>) {}
161/// ```
162///
163/// Overall there's some general rules of thumb when unsafely working with
164/// `Memory` and getting raw pointers inside of it:
165///
166/// * If you never have a "long lived" pointer into memory, you're likely in the
167/// clear. Care still needs to be taken in threaded scenarios or when/where
168/// data is read, but you'll be shielded from many classes of issues.
169/// * Long-lived pointers must always respect Rust'a aliasing rules. It's ok for
170/// shared borrows to overlap with each other, but mutable borrows must
171/// overlap with nothing.
172/// * Long-lived pointers are only valid if they're not invalidated for their
173/// lifetime. This means that [`Store`](crate::Store) isn't used to reenter
174/// wasm or the memory itself is never grown or otherwise modified/aliased.
175///
176/// At this point it's worth reiterating again that unsafely working with
177/// `Memory` is pretty tricky and not recommended! It's highly recommended to
178/// use the safe methods to interact with [`Memory`] whenever possible.
179///
180/// ## `Memory` Safety and Threads
181///
182/// Currently the `wasmtime` crate does not implement the wasm threads proposal,
183/// but it is planned to do so. It may be interesting to readers to see how this
184/// affects memory safety and what was previously just discussed as well.
185///
186/// Once threads are added into the mix, all of the above rules still apply.
187/// There's an additional consideration that all reads and writes can happen
188/// concurrently, though. This effectively means that any borrow into wasm
189/// memory are virtually never safe to have.
190///
191/// Mutable pointers are fundamentally unsafe to have in a concurrent scenario
192/// in the face of arbitrary wasm code. Only if you dynamically know for sure
193/// that wasm won't access a region would it be safe to construct a mutable
194/// pointer. Additionally even shared pointers are largely unsafe because their
195/// underlying contents may change, so unless `UnsafeCell` in one form or
196/// another is used everywhere there's no safety.
197///
198/// One important point about concurrency is that while [`Memory::grow`] can
199/// happen concurrently it will never relocate the base pointer. Shared
200/// memories must always have a maximum size and they will be preallocated such
201/// that growth will never relocate the base pointer. The current size of the
202/// memory may still change over time though.
203///
204/// Overall the general rule of thumb for shared memories is that you must
205/// atomically read and write everything. Nothing can be borrowed and everything
206/// must be eagerly copied out. This means that [`Memory::data`] and
207/// [`Memory::data_mut`] won't work in the future (they'll probably return an
208/// error) for shared memories when they're implemented. When possible it's
209/// recommended to use [`Memory::read`] and [`Memory::write`] which will still
210/// be provided.
211#[derive(Copy, Clone, Debug)]
212#[repr(C)] // here for the C API
213pub struct Memory {
214 /// The internal store instance that this memory belongs to.
215 instance: StoreInstanceId,
216 /// The index of the memory, within `instance` above, that this memory
217 /// refers to.
218 index: DefinedMemoryIndex,
219}
220
221// Double-check that the C representation in `extern.h` matches our in-Rust
222// representation here in terms of size/alignment/etc.
223const _: () = {
224 #[repr(C)]
225 struct Tmp(u64, u32);
226 #[repr(C)]
227 struct C(Tmp, u32);
228 assert!(core::mem::size_of::<C>() == core::mem::size_of::<Memory>());
229 assert!(core::mem::align_of::<C>() == core::mem::align_of::<Memory>());
230 assert!(core::mem::offset_of!(Memory, instance) == 0);
231};
232
233impl Memory {
234 /// Creates a new WebAssembly memory given the configuration of `ty`.
235 ///
236 /// The `store` argument will be the owner of the returned [`Memory`]. All
237 /// WebAssembly memory is initialized to zero.
238 ///
239 /// # Panics
240 ///
241 /// This function will panic if the [`Store`](`crate::Store`) has a
242 /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`) (see also:
243 /// [`Store::limiter_async`](`crate::Store::limiter_async`)). When
244 /// using an async resource limiter, use [`Memory::new_async`] instead.
245 ///
246 /// # Examples
247 ///
248 /// ```
249 /// # use wasmtime::*;
250 /// # fn main() -> anyhow::Result<()> {
251 /// let engine = Engine::default();
252 /// let mut store = Store::new(&engine, ());
253 ///
254 /// let memory_ty = MemoryType::new(1, None);
255 /// let memory = Memory::new(&mut store, memory_ty)?;
256 ///
257 /// let module = Module::new(&engine, "(module (memory (import \"\" \"\") 1))")?;
258 /// let instance = Instance::new(&mut store, &module, &[memory.into()])?;
259 /// // ...
260 /// # Ok(())
261 /// # }
262 /// ```
263 pub fn new(mut store: impl AsContextMut, ty: MemoryType) -> Result<Memory> {
264 Self::_new(store.as_context_mut().0, ty)
265 }
266
267 /// Async variant of [`Memory::new`]. You must use this variant with
268 /// [`Store`](`crate::Store`)s which have a
269 /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`).
270 ///
271 /// # Panics
272 ///
273 /// This function will panic when used with a non-async
274 /// [`Store`](`crate::Store`).
275 #[cfg(feature = "async")]
276 pub async fn new_async(
277 mut store: impl AsContextMut<Data: Send>,
278 ty: MemoryType,
279 ) -> Result<Memory> {
280 let mut store = store.as_context_mut();
281 assert!(
282 store.0.async_support(),
283 "cannot use `new_async` without enabling async support on the config"
284 );
285 store.on_fiber(|store| Self::_new(store.0, ty)).await?
286 }
287
288 /// Helper function for attaching the memory to a "frankenstein" instance
289 fn _new(store: &mut StoreOpaque, ty: MemoryType) -> Result<Memory> {
290 unsafe {
291 let export = generate_memory_export(store, &ty, None)?;
292 Ok(Memory::from_wasmtime_memory(export, store))
293 }
294 }
295
296 /// Returns the underlying type of this memory.
297 ///
298 /// # Panics
299 ///
300 /// Panics if this memory doesn't belong to `store`.
301 ///
302 /// # Examples
303 ///
304 /// ```
305 /// # use wasmtime::*;
306 /// # fn main() -> anyhow::Result<()> {
307 /// let engine = Engine::default();
308 /// let mut store = Store::new(&engine, ());
309 /// let module = Module::new(&engine, "(module (memory (export \"mem\") 1))")?;
310 /// let instance = Instance::new(&mut store, &module, &[])?;
311 /// let memory = instance.get_memory(&mut store, "mem").unwrap();
312 /// let ty = memory.ty(&store);
313 /// assert_eq!(ty.minimum(), 1);
314 /// # Ok(())
315 /// # }
316 /// ```
317 pub fn ty(&self, store: impl AsContext) -> MemoryType {
318 let store = store.as_context();
319 MemoryType::from_wasmtime_memory(self.wasmtime_ty(store.0))
320 }
321
322 /// Safely reads memory contents at the given offset into a buffer.
323 ///
324 /// The entire buffer will be filled.
325 ///
326 /// If `offset + buffer.len()` exceed the current memory capacity, then the
327 /// buffer is left untouched and a [`MemoryAccessError`] is returned.
328 ///
329 /// # Panics
330 ///
331 /// Panics if this memory doesn't belong to `store`.
332 pub fn read(
333 &self,
334 store: impl AsContext,
335 offset: usize,
336 buffer: &mut [u8],
337 ) -> Result<(), MemoryAccessError> {
338 let store = store.as_context();
339 let slice = self
340 .data(&store)
341 .get(offset..)
342 .and_then(|s| s.get(..buffer.len()))
343 .ok_or(MemoryAccessError { _private: () })?;
344 buffer.copy_from_slice(slice);
345 Ok(())
346 }
347
348 /// Safely writes contents of a buffer to this memory at the given offset.
349 ///
350 /// If the `offset + buffer.len()` exceeds the current memory capacity, then
351 /// none of the buffer is written to memory and a [`MemoryAccessError`] is
352 /// returned.
353 ///
354 /// # Panics
355 ///
356 /// Panics if this memory doesn't belong to `store`.
357 pub fn write(
358 &self,
359 mut store: impl AsContextMut,
360 offset: usize,
361 buffer: &[u8],
362 ) -> Result<(), MemoryAccessError> {
363 let mut context = store.as_context_mut();
364 self.data_mut(&mut context)
365 .get_mut(offset..)
366 .and_then(|s| s.get_mut(..buffer.len()))
367 .ok_or(MemoryAccessError { _private: () })?
368 .copy_from_slice(buffer);
369 Ok(())
370 }
371
372 /// Returns this memory as a native Rust slice.
373 ///
374 /// Note that this method will consider the entire store context provided as
375 /// borrowed for the duration of the lifetime of the returned slice.
376 ///
377 /// # Panics
378 ///
379 /// Panics if this memory doesn't belong to `store`.
380 pub fn data<'a, T: 'static>(&self, store: impl Into<StoreContext<'a, T>>) -> &'a [u8] {
381 unsafe {
382 let store = store.into();
383 let definition = store[self.instance].memory(self.index);
384 debug_assert!(!self.ty(store).is_shared());
385 slice::from_raw_parts(definition.base.as_ptr(), definition.current_length())
386 }
387 }
388
389 /// Returns this memory as a native Rust mutable slice.
390 ///
391 /// Note that this method will consider the entire store context provided as
392 /// borrowed for the duration of the lifetime of the returned slice.
393 ///
394 /// # Panics
395 ///
396 /// Panics if this memory doesn't belong to `store`.
397 pub fn data_mut<'a, T: 'static>(
398 &self,
399 store: impl Into<StoreContextMut<'a, T>>,
400 ) -> &'a mut [u8] {
401 unsafe {
402 let store = store.into();
403 let definition = store[self.instance].memory(self.index);
404 debug_assert!(!self.ty(store).is_shared());
405 slice::from_raw_parts_mut(definition.base.as_ptr(), definition.current_length())
406 }
407 }
408
409 /// Same as [`Memory::data_mut`], but also returns the `T` from the
410 /// [`StoreContextMut`].
411 ///
412 /// This method can be used when you want to simultaneously work with the
413 /// `T` in the store as well as the memory behind this [`Memory`]. Using
414 /// [`Memory::data_mut`] would consider the entire store borrowed, whereas
415 /// this method allows the Rust compiler to see that the borrow of this
416 /// memory and the borrow of `T` are disjoint.
417 ///
418 /// # Panics
419 ///
420 /// Panics if this memory doesn't belong to `store`.
421 pub fn data_and_store_mut<'a, T: 'static>(
422 &self,
423 store: impl Into<StoreContextMut<'a, T>>,
424 ) -> (&'a mut [u8], &'a mut T) {
425 // Note the unsafety here. Our goal is to simultaneously borrow the
426 // memory and custom data from `store`, and the store it's connected
427 // to. Rust will not let us do that, however, because we must call two
428 // separate methods (both of which borrow the whole `store`) and one of
429 // our borrows is mutable (the custom data).
430 //
431 // This operation, however, is safe because these borrows do not overlap
432 // and in the process of borrowing them mutability doesn't actually
433 // touch anything. This is akin to mutably borrowing two indices in an
434 // array, which is safe so long as the indices are separate.
435 unsafe {
436 let mut store = store.into();
437 let data = &mut *(store.data_mut() as *mut T);
438 (self.data_mut(store), data)
439 }
440 }
441
442 /// Returns the base pointer, in the host's address space, that the memory
443 /// is located at.
444 ///
445 /// For more information and examples see the documentation on the
446 /// [`Memory`] type.
447 ///
448 /// # Panics
449 ///
450 /// Panics if this memory doesn't belong to `store`.
451 pub fn data_ptr(&self, store: impl AsContext) -> *mut u8 {
452 store.as_context()[self.instance]
453 .memory(self.index)
454 .base
455 .as_ptr()
456 }
457
458 /// Returns the byte length of this memory.
459 ///
460 /// WebAssembly memories are made up of a whole number of pages, so the byte
461 /// size returned will always be a multiple of this memory's page size. Note
462 /// that different Wasm memories may have different page sizes. You can get
463 /// a memory's page size via the [`Memory::page_size`] method.
464 ///
465 /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or
466 /// `65536`) but [the custom-page-sizes proposal] allows a memory to opt
467 /// into a page size of `1`. Future extensions might allow any power of two
468 /// as a page size.
469 ///
470 /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
471 ///
472 /// For more information and examples see the documentation on the
473 /// [`Memory`] type.
474 ///
475 /// # Panics
476 ///
477 /// Panics if this memory doesn't belong to `store`.
478 pub fn data_size(&self, store: impl AsContext) -> usize {
479 self.internal_data_size(store.as_context().0)
480 }
481
482 pub(crate) fn internal_data_size(&self, store: &StoreOpaque) -> usize {
483 store[self.instance].memory(self.index).current_length()
484 }
485
486 /// Returns the size, in units of pages, of this Wasm memory.
487 ///
488 /// WebAssembly memories are made up of a whole number of pages, so the byte
489 /// size returned will always be a multiple of this memory's page size. Note
490 /// that different Wasm memories may have different page sizes. You can get
491 /// a memory's page size via the [`Memory::page_size`] method.
492 ///
493 /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or
494 /// `65536`) but [the custom-page-sizes proposal] allows a memory to opt
495 /// into a page size of `1`. Future extensions might allow any power of two
496 /// as a page size.
497 ///
498 /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
499 ///
500 /// # Panics
501 ///
502 /// Panics if this memory doesn't belong to `store`.
503 pub fn size(&self, store: impl AsContext) -> u64 {
504 self.internal_size(store.as_context().0)
505 }
506
507 pub(crate) fn internal_size(&self, store: &StoreOpaque) -> u64 {
508 let byte_size = self.internal_data_size(store);
509 let page_size = usize::try_from(self._page_size(store)).unwrap();
510 u64::try_from(byte_size / page_size).unwrap()
511 }
512
513 /// Returns the size of a page, in bytes, for this memory.
514 ///
515 /// WebAssembly memories are made up of a whole number of pages, so the byte
516 /// size (as returned by [`Memory::data_size`]) will always be a multiple of
517 /// their page size. Different Wasm memories may have different page sizes.
518 ///
519 /// By default this is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or `65536`)
520 /// but [the custom-page-sizes proposal] allows opting into a page size of
521 /// `1`. Future extensions might allow any power of two as a page size.
522 ///
523 /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
524 pub fn page_size(&self, store: impl AsContext) -> u64 {
525 self._page_size(store.as_context().0)
526 }
527
528 pub(crate) fn _page_size(&self, store: &StoreOpaque) -> u64 {
529 self.wasmtime_ty(store).page_size()
530 }
531
532 /// Returns the log2 of this memory's page size, in bytes.
533 ///
534 /// WebAssembly memories are made up of a whole number of pages, so the byte
535 /// size (as returned by [`Memory::data_size`]) will always be a multiple of
536 /// their page size. Different Wasm memories may have different page sizes.
537 ///
538 /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or
539 /// `65536`) but [the custom-page-sizes proposal] allows opting into a page
540 /// size of `1`. Future extensions might allow any power of two as a page
541 /// size.
542 ///
543 /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
544 pub fn page_size_log2(&self, store: impl AsContext) -> u8 {
545 self._page_size_log2(store.as_context().0)
546 }
547
548 pub(crate) fn _page_size_log2(&self, store: &StoreOpaque) -> u8 {
549 self.wasmtime_ty(store).page_size_log2
550 }
551
552 /// Grows this WebAssembly memory by `delta` pages.
553 ///
554 /// This will attempt to add `delta` more pages of memory on to the end of
555 /// this `Memory` instance. If successful this may relocate the memory and
556 /// cause [`Memory::data_ptr`] to return a new value. Additionally any
557 /// unsafely constructed slices into this memory may no longer be valid.
558 ///
559 /// On success returns the number of pages this memory previously had
560 /// before the growth succeeded.
561 ///
562 /// Note that, by default, a WebAssembly memory's page size is 64KiB (aka
563 /// 65536 or 2<sup>16</sup>). The [custom-page-sizes proposal] allows Wasm
564 /// memories to opt into a page size of one byte (and this may be further
565 /// relaxed to any power of two in a future extension).
566 ///
567 /// [custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
568 ///
569 /// # Errors
570 ///
571 /// Returns an error if memory could not be grown, for example if it exceeds
572 /// the maximum limits of this memory. A
573 /// [`ResourceLimiter`](crate::ResourceLimiter) is another example of
574 /// preventing a memory to grow.
575 ///
576 /// # Panics
577 ///
578 /// Panics if this memory doesn't belong to `store`.
579 ///
580 /// This function will panic if the [`Store`](`crate::Store`) has a
581 /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`) (see also:
582 /// [`Store::limiter_async`](`crate::Store::limiter_async`). When using an
583 /// async resource limiter, use [`Memory::grow_async`] instead.
584 ///
585 /// # Examples
586 ///
587 /// ```
588 /// # use wasmtime::*;
589 /// # fn main() -> anyhow::Result<()> {
590 /// let engine = Engine::default();
591 /// let mut store = Store::new(&engine, ());
592 /// let module = Module::new(&engine, "(module (memory (export \"mem\") 1 2))")?;
593 /// let instance = Instance::new(&mut store, &module, &[])?;
594 /// let memory = instance.get_memory(&mut store, "mem").unwrap();
595 ///
596 /// assert_eq!(memory.size(&store), 1);
597 /// assert_eq!(memory.grow(&mut store, 1)?, 1);
598 /// assert_eq!(memory.size(&store), 2);
599 /// assert!(memory.grow(&mut store, 1).is_err());
600 /// assert_eq!(memory.size(&store), 2);
601 /// assert_eq!(memory.grow(&mut store, 0)?, 2);
602 /// # Ok(())
603 /// # }
604 /// ```
605 pub fn grow(&self, mut store: impl AsContextMut, delta: u64) -> Result<u64> {
606 let store = store.as_context_mut().0;
607 let mem = self.wasmtime_memory(store);
608 unsafe {
609 match (*mem).grow(delta, Some(store))? {
610 Some(size) => {
611 let vm = (*mem).vmmemory();
612 store[self.instance].memory_ptr(self.index).write(vm);
613 let page_size = (*mem).page_size();
614 Ok(u64::try_from(size).unwrap() / page_size)
615 }
616 None => bail!("failed to grow memory by `{}`", delta),
617 }
618 }
619 }
620
621 /// Async variant of [`Memory::grow`]. Required when using a
622 /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`).
623 ///
624 /// # Panics
625 ///
626 /// This function will panic when used with a non-async
627 /// [`Store`](`crate::Store`).
628 #[cfg(feature = "async")]
629 pub async fn grow_async(
630 &self,
631 mut store: impl AsContextMut<Data: Send>,
632 delta: u64,
633 ) -> Result<u64> {
634 let mut store = store.as_context_mut();
635 assert!(
636 store.0.async_support(),
637 "cannot use `grow_async` without enabling async support on the config"
638 );
639 store.on_fiber(|store| self.grow(store, delta)).await?
640 }
641
642 fn wasmtime_memory(&self, store: &mut StoreOpaque) -> *mut crate::runtime::vm::Memory {
643 self.instance.get_mut(store).get_defined_memory(self.index)
644 }
645
646 pub(crate) unsafe fn from_wasmtime_memory(
647 wasmtime_export: crate::runtime::vm::ExportMemory,
648 store: &StoreOpaque,
649 ) -> Memory {
650 Memory {
651 instance: store.vmctx_id(wasmtime_export.vmctx),
652 index: wasmtime_export.index,
653 }
654 }
655
656 pub(crate) fn wasmtime_ty<'a>(&self, store: &'a StoreOpaque) -> &'a wasmtime_environ::Memory {
657 let module = store[self.instance].env_module();
658 let index = module.memory_index(self.index);
659 &module.memories[index]
660 }
661
662 pub(crate) fn vmimport(&self, store: &StoreOpaque) -> crate::runtime::vm::VMMemoryImport {
663 let instance = &store[self.instance];
664 crate::runtime::vm::VMMemoryImport {
665 from: instance.memory_ptr(self.index).into(),
666 vmctx: instance.vmctx().into(),
667 index: self.index,
668 }
669 }
670
671 pub(crate) fn comes_from_same_store(&self, store: &StoreOpaque) -> bool {
672 store.id() == self.instance.store_id()
673 }
674
675 /// Get a stable hash key for this memory.
676 ///
677 /// Even if the same underlying memory definition is added to the
678 /// `StoreData` multiple times and becomes multiple `wasmtime::Memory`s,
679 /// this hash key will be consistent across all of these memories.
680 #[cfg(feature = "coredump")]
681 pub(crate) fn hash_key(&self, store: &StoreOpaque) -> impl core::hash::Hash + Eq + use<> {
682 store[self.instance].memory_ptr(self.index).as_ptr().addr()
683 }
684}
685
686/// A linear memory. This trait provides an interface for raw memory buffers
687/// which are used by wasmtime, e.g. inside ['Memory']. Such buffers are in
688/// principle not thread safe. By implementing this trait together with
689/// MemoryCreator, one can supply wasmtime with custom allocated host managed
690/// memory.
691///
692/// # Safety
693///
694/// The memory should be page aligned and a multiple of page size.
695/// To prevent possible silent overflows, the memory should be protected by a
696/// guard page. Additionally the safety concerns explained in ['Memory'], for
697/// accessing the memory apply here as well.
698///
699/// Note that this is a relatively advanced feature and it is recommended to be
700/// familiar with wasmtime runtime code to use it.
701pub unsafe trait LinearMemory: Send + Sync + 'static {
702 /// Returns the number of allocated bytes which are accessible at this time.
703 fn byte_size(&self) -> usize;
704
705 /// Returns byte capacity of this linear memory's current allocation.
706 ///
707 /// Growth up to this value should not relocate the linear memory base
708 /// pointer.
709 fn byte_capacity(&self) -> usize;
710
711 /// Grows this memory to have the `new_size`, in bytes, specified.
712 ///
713 /// Returns `Err` if memory can't be grown by the specified amount
714 /// of bytes. The error may be downcastable to `std::io::Error`.
715 /// Returns `Ok` if memory was grown successfully.
716 fn grow_to(&mut self, new_size: usize) -> Result<()>;
717
718 /// Return the allocated memory as a mutable pointer to u8.
719 fn as_ptr(&self) -> *mut u8;
720}
721
722/// A memory creator. Can be used to provide a memory creator
723/// to wasmtime which supplies host managed memory.
724///
725/// # Safety
726///
727/// This trait is unsafe, as the memory safety depends on proper implementation
728/// of memory management. Memories created by the MemoryCreator should always be
729/// treated as owned by wasmtime instance, and any modification of them outside
730/// of wasmtime invoked routines is unsafe and may lead to corruption.
731///
732/// Note that this is a relatively advanced feature and it is recommended to be
733/// familiar with Wasmtime runtime code to use it.
734pub unsafe trait MemoryCreator: Send + Sync {
735 /// Create a new `LinearMemory` object from the specified parameters.
736 ///
737 /// The type of memory being created is specified by `ty` which indicates
738 /// both the minimum and maximum size, in wasm pages. The minimum and
739 /// maximum sizes, in bytes, are also specified as parameters to avoid
740 /// integer conversion if desired.
741 ///
742 /// The `reserved_size_in_bytes` value indicates the expected size of the
743 /// reservation that is to be made for this memory. If this value is `None`
744 /// than the implementation is free to allocate memory as it sees fit. If
745 /// the value is `Some`, however, then the implementation is expected to
746 /// reserve that many bytes for the memory's allocation, plus the guard
747 /// size at the end. Note that this reservation need only be a virtual
748 /// memory reservation, physical memory does not need to be allocated
749 /// immediately. In this case `grow` should never move the base pointer and
750 /// the maximum size of `ty` is guaranteed to fit within
751 /// `reserved_size_in_bytes`.
752 ///
753 /// The `guard_size_in_bytes` parameter indicates how many bytes of space,
754 /// after the memory allocation, is expected to be unmapped. JIT code will
755 /// elide bounds checks based on the `guard_size_in_bytes` provided, so for
756 /// JIT code to work correctly the memory returned will need to be properly
757 /// guarded with `guard_size_in_bytes` bytes left unmapped after the base
758 /// allocation.
759 ///
760 /// Note that the `reserved_size_in_bytes` and `guard_size_in_bytes` options
761 /// are tuned from the various [`Config`](crate::Config) methods about
762 /// memory sizes/guards. Additionally these two values are guaranteed to be
763 /// multiples of the system page size.
764 ///
765 /// Memory created from this method should be zero filled.
766 fn new_memory(
767 &self,
768 ty: MemoryType,
769 minimum: usize,
770 maximum: Option<usize>,
771 reserved_size_in_bytes: Option<usize>,
772 guard_size_in_bytes: usize,
773 ) -> Result<Box<dyn LinearMemory>, String>;
774}
775
776/// A constructor for externally-created shared memory.
777///
778/// The [threads proposal] adds the concept of "shared memory" to WebAssembly.
779/// This is much the same as a Wasm linear memory (i.e., [`Memory`]), but can be
780/// used concurrently by multiple agents. Because these agents may execute in
781/// different threads, [`SharedMemory`] must be thread-safe.
782///
783/// When the threads proposal is enabled, there are multiple ways to construct
784/// shared memory:
785/// 1. for imported shared memory, e.g., `(import "env" "memory" (memory 1 1
786/// shared))`, the user must supply a [`SharedMemory`] with the
787/// externally-created memory as an import to the instance--e.g.,
788/// `shared_memory.into()`.
789/// 2. for private or exported shared memory, e.g., `(export "env" "memory"
790/// (memory 1 1 shared))`, Wasmtime will create the memory internally during
791/// instantiation--access using `Instance::get_shared_memory()`.
792///
793/// [threads proposal]:
794/// https://github.com/WebAssembly/threads/blob/master/proposals/threads/Overview.md
795///
796/// # Examples
797///
798/// ```
799/// # use wasmtime::*;
800/// # fn main() -> anyhow::Result<()> {
801/// let mut config = Config::new();
802/// config.wasm_threads(true);
803/// let engine = Engine::new(&config)?;
804/// let mut store = Store::new(&engine, ());
805///
806/// let shared_memory = SharedMemory::new(&engine, MemoryType::shared(1, 2))?;
807/// let module = Module::new(&engine, r#"(module (memory (import "" "") 1 2 shared))"#)?;
808/// let instance = Instance::new(&mut store, &module, &[shared_memory.into()])?;
809/// // ...
810/// # Ok(())
811/// # }
812/// ```
813#[derive(Clone)]
814pub struct SharedMemory {
815 vm: crate::runtime::vm::SharedMemory,
816 engine: Engine,
817 page_size_log2: u8,
818}
819
820impl SharedMemory {
821 /// Construct a [`SharedMemory`] by providing both the `minimum` and
822 /// `maximum` number of 64K-sized pages. This call allocates the necessary
823 /// pages on the system.
824 #[cfg(feature = "threads")]
825 pub fn new(engine: &Engine, ty: MemoryType) -> Result<Self> {
826 if !ty.is_shared() {
827 bail!("shared memory must have the `shared` flag enabled on its memory type")
828 }
829 debug_assert!(ty.maximum().is_some());
830
831 let tunables = engine.tunables();
832 let ty = ty.wasmtime_memory();
833 let page_size_log2 = ty.page_size_log2;
834 let memory = crate::runtime::vm::SharedMemory::new(ty, tunables)?;
835
836 Ok(Self {
837 vm: memory,
838 engine: engine.clone(),
839 page_size_log2,
840 })
841 }
842
843 /// Return the type of the shared memory.
844 pub fn ty(&self) -> MemoryType {
845 MemoryType::from_wasmtime_memory(&self.vm.ty())
846 }
847
848 /// Returns the size, in WebAssembly pages, of this wasm memory.
849 pub fn size(&self) -> u64 {
850 let byte_size = u64::try_from(self.data_size()).unwrap();
851 let page_size = u64::from(self.page_size());
852 byte_size / page_size
853 }
854
855 /// Returns the size of a page, in bytes, for this memory.
856 ///
857 /// By default this is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or `65536`)
858 /// but [the custom-page-sizes proposal] allows opting into a page size of
859 /// `1`. Future extensions might allow any power of two as a page size.
860 ///
861 /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
862 pub fn page_size(&self) -> u32 {
863 debug_assert!(self.page_size_log2 == 0 || self.page_size_log2 == 16);
864 1 << self.page_size_log2
865 }
866
867 /// Returns the byte length of this memory.
868 ///
869 /// The returned value will be a multiple of the wasm page size, 64k.
870 ///
871 /// For more information and examples see the documentation on the
872 /// [`Memory`] type.
873 pub fn data_size(&self) -> usize {
874 self.vm.byte_size()
875 }
876
877 /// Return access to the available portion of the shared memory.
878 ///
879 /// The slice returned represents the region of accessible memory at the
880 /// time that this function was called. The contents of the returned slice
881 /// will reflect concurrent modifications happening on other threads.
882 ///
883 /// # Safety
884 ///
885 /// The returned slice is valid for the entire duration of the lifetime of
886 /// this instance of [`SharedMemory`]. The base pointer of a shared memory
887 /// does not change. This [`SharedMemory`] may grow further after this
888 /// function has been called, but the slice returned will not grow.
889 ///
890 /// Concurrent modifications may be happening to the data returned on other
891 /// threads. The `UnsafeCell<u8>` represents that safe access to the
892 /// contents of the slice is not possible through normal loads and stores.
893 ///
894 /// The memory returned must be accessed safely through the `Atomic*` types
895 /// in the [`std::sync::atomic`] module. Casting to those types must
896 /// currently be done unsafely.
897 pub fn data(&self) -> &[UnsafeCell<u8>] {
898 unsafe {
899 let definition = self.vm.vmmemory_ptr().as_ref();
900 slice::from_raw_parts(definition.base.as_ptr().cast(), definition.current_length())
901 }
902 }
903
904 /// Grows this WebAssembly memory by `delta` pages.
905 ///
906 /// This will attempt to add `delta` more pages of memory on to the end of
907 /// this `Memory` instance. If successful this may relocate the memory and
908 /// cause [`Memory::data_ptr`] to return a new value. Additionally any
909 /// unsafely constructed slices into this memory may no longer be valid.
910 ///
911 /// On success returns the number of pages this memory previously had
912 /// before the growth succeeded.
913 ///
914 /// # Errors
915 ///
916 /// Returns an error if memory could not be grown, for example if it exceeds
917 /// the maximum limits of this memory. A
918 /// [`ResourceLimiter`](crate::ResourceLimiter) is another example of
919 /// preventing a memory to grow.
920 pub fn grow(&self, delta: u64) -> Result<u64> {
921 match self.vm.grow(delta, None)? {
922 Some((old_size, _new_size)) => {
923 // For shared memory, the `VMMemoryDefinition` is updated inside
924 // the locked region.
925 Ok(u64::try_from(old_size).unwrap() / u64::from(self.page_size()))
926 }
927 None => bail!("failed to grow memory by `{}`", delta),
928 }
929 }
930
931 /// Equivalent of the WebAssembly `memory.atomic.notify` instruction for
932 /// this shared memory.
933 ///
934 /// This method allows embedders to notify threads blocked on the specified
935 /// `addr`, an index into wasm linear memory. Threads could include
936 /// wasm threads blocked on a `memory.atomic.wait*` instruction or embedder
937 /// threads blocked on [`SharedMemory::atomic_wait32`], for example.
938 ///
939 /// The `count` argument is the number of threads to wake up.
940 ///
941 /// This function returns the number of threads awoken.
942 ///
943 /// # Errors
944 ///
945 /// This function will return an error if `addr` is not within bounds or
946 /// not aligned to a 4-byte boundary.
947 pub fn atomic_notify(&self, addr: u64, count: u32) -> Result<u32, Trap> {
948 self.vm.atomic_notify(addr, count)
949 }
950
951 /// Equivalent of the WebAssembly `memory.atomic.wait32` instruction for
952 /// this shared memory.
953 ///
954 /// This method allows embedders to block the current thread until notified
955 /// via the `memory.atomic.notify` instruction or the
956 /// [`SharedMemory::atomic_notify`] method, enabling synchronization with
957 /// the wasm guest as desired.
958 ///
959 /// The `expected` argument is the expected 32-bit value to be stored at
960 /// the byte address `addr` specified. The `addr` specified is an index
961 /// into this linear memory.
962 ///
963 /// The optional `timeout` argument is the maximum amount of time to block
964 /// the current thread. If not specified the thread may sleep indefinitely.
965 ///
966 /// This function returns one of three possible values:
967 ///
968 /// * `WaitResult::Ok` - this function, loaded the value at `addr`, found
969 /// it was equal to `expected`, and then blocked (all as one atomic
970 /// operation). The thread was then awoken with a `memory.atomic.notify`
971 /// instruction or the [`SharedMemory::atomic_notify`] method.
972 /// * `WaitResult::Mismatch` - the value at `addr` was loaded but was not
973 /// equal to `expected` so the thread did not block and immediately
974 /// returned.
975 /// * `WaitResult::TimedOut` - all the steps of `Ok` happened, except this
976 /// thread was woken up due to a timeout.
977 ///
978 /// This function will not return due to spurious wakeups.
979 ///
980 /// # Errors
981 ///
982 /// This function will return an error if `addr` is not within bounds or
983 /// not aligned to a 4-byte boundary.
984 pub fn atomic_wait32(
985 &self,
986 addr: u64,
987 expected: u32,
988 timeout: Option<Duration>,
989 ) -> Result<WaitResult, Trap> {
990 self.vm.atomic_wait32(addr, expected, timeout)
991 }
992
993 /// Equivalent of the WebAssembly `memory.atomic.wait64` instruction for
994 /// this shared memory.
995 ///
996 /// For more information see [`SharedMemory::atomic_wait32`].
997 ///
998 /// # Errors
999 ///
1000 /// Returns the same error as [`SharedMemory::atomic_wait32`] except that
1001 /// the specified address must be 8-byte aligned instead of 4-byte aligned.
1002 pub fn atomic_wait64(
1003 &self,
1004 addr: u64,
1005 expected: u64,
1006 timeout: Option<Duration>,
1007 ) -> Result<WaitResult, Trap> {
1008 self.vm.atomic_wait64(addr, expected, timeout)
1009 }
1010
1011 /// Return a reference to the [`Engine`] used to configure the shared
1012 /// memory.
1013 pub(crate) fn engine(&self) -> &Engine {
1014 &self.engine
1015 }
1016
1017 /// Construct a single-memory instance to provide a way to import
1018 /// [`SharedMemory`] into other modules.
1019 pub(crate) fn vmimport(&self, store: &mut StoreOpaque) -> crate::runtime::vm::VMMemoryImport {
1020 let export_memory = generate_memory_export(store, &self.ty(), Some(&self.vm)).unwrap();
1021 VMMemoryImport {
1022 from: export_memory.definition.into(),
1023 vmctx: export_memory.vmctx.into(),
1024 index: export_memory.index,
1025 }
1026 }
1027
1028 /// Create a [`SharedMemory`] from an [`ExportMemory`] definition. This
1029 /// function is available to handle the case in which a Wasm module exports
1030 /// shared memory and the user wants host-side access to it.
1031 pub(crate) unsafe fn from_wasmtime_memory(
1032 wasmtime_export: crate::runtime::vm::ExportMemory,
1033 store: &StoreOpaque,
1034 ) -> Self {
1035 #[cfg_attr(not(feature = "threads"), allow(unused_variables, unreachable_code))]
1036 crate::runtime::vm::Instance::from_vmctx(wasmtime_export.vmctx, |handle| {
1037 let memory_index = handle.env_module().memory_index(wasmtime_export.index);
1038 let page_size = handle.memory_page_size(memory_index);
1039 debug_assert!(page_size.is_power_of_two());
1040 let page_size_log2 = u8::try_from(page_size.ilog2()).unwrap();
1041
1042 let memory = handle
1043 .get_defined_memory(wasmtime_export.index)
1044 .as_mut()
1045 .unwrap();
1046 match memory.as_shared_memory() {
1047 Some(mem) => Self {
1048 vm: mem.clone(),
1049 engine: store.engine().clone(),
1050 page_size_log2,
1051 },
1052 None => panic!("unable to convert from a shared memory"),
1053 }
1054 })
1055 }
1056}
1057
1058impl fmt::Debug for SharedMemory {
1059 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1060 f.debug_struct("SharedMemory").finish_non_exhaustive()
1061 }
1062}
1063
1064#[cfg(test)]
1065mod tests {
1066 use crate::*;
1067
1068 // Assert that creating a memory via `Memory::new` respects the limits/tunables
1069 // in `Config`.
1070 #[test]
1071 fn respect_tunables() {
1072 let mut cfg = Config::new();
1073 cfg.memory_reservation(0).memory_guard_size(0);
1074 let mut store = Store::new(&Engine::new(&cfg).unwrap(), ());
1075 let ty = MemoryType::new(1, None);
1076 let mem = Memory::new(&mut store, ty).unwrap();
1077 let store = store.as_context();
1078 let tunables = store.engine().tunables();
1079 assert_eq!(tunables.memory_guard_size, 0);
1080 assert!(
1081 !mem.wasmtime_ty(store.0)
1082 .can_elide_bounds_check(tunables, 12)
1083 );
1084 }
1085
1086 #[test]
1087 fn hash_key_is_stable_across_duplicate_store_data_entries() -> Result<()> {
1088 let mut store = Store::<()>::default();
1089 let module = Module::new(
1090 store.engine(),
1091 r#"
1092 (module
1093 (memory (export "m") 1 1)
1094 )
1095 "#,
1096 )?;
1097 let instance = Instance::new(&mut store, &module, &[])?;
1098
1099 // Each time we `get_memory`, we call `Memory::from_wasmtime` which adds
1100 // a new entry to `StoreData`, so `g1` and `g2` will have different
1101 // indices into `StoreData`.
1102 let m1 = instance.get_memory(&mut store, "m").unwrap();
1103 let m2 = instance.get_memory(&mut store, "m").unwrap();
1104
1105 // That said, they really point to the same memory.
1106 assert_eq!(m1.data(&store)[0], 0);
1107 assert_eq!(m2.data(&store)[0], 0);
1108 m1.data_mut(&mut store)[0] = 42;
1109 assert_eq!(m1.data(&mut store)[0], 42);
1110 assert_eq!(m2.data(&mut store)[0], 42);
1111
1112 // And therefore their hash keys are the same.
1113 assert!(m1.hash_key(&store.as_context().0) == m2.hash_key(&store.as_context().0));
1114
1115 // But the hash keys are different from different memories.
1116 let instance2 = Instance::new(&mut store, &module, &[])?;
1117 let m3 = instance2.get_memory(&mut store, "m").unwrap();
1118 assert!(m1.hash_key(&store.as_context().0) != m3.hash_key(&store.as_context().0));
1119
1120 Ok(())
1121 }
1122}