revm_interpreter/interpreter/
shared_memory.rs

1use super::MemoryTr;
2use crate::InstructionResult;
3use context_interface::cfg::GasParams;
4use core::{
5    cell::{Ref, RefCell, RefMut},
6    cmp::min,
7    fmt,
8    ops::Range,
9};
10use primitives::{hex, B256, U256};
11use std::{rc::Rc, vec::Vec};
12
13trait RefcellExt<T> {
14    fn dbg_borrow(&self) -> Ref<'_, T>;
15    fn dbg_borrow_mut(&self) -> RefMut<'_, T>;
16}
17
18impl<T> RefcellExt<T> for RefCell<T> {
19    #[inline]
20    fn dbg_borrow(&self) -> Ref<'_, T> {
21        match self.try_borrow() {
22            Ok(b) => b,
23            Err(e) => debug_unreachable!("{e}"),
24        }
25    }
26
27    #[inline]
28    fn dbg_borrow_mut(&self) -> RefMut<'_, T> {
29        match self.try_borrow_mut() {
30            Ok(b) => b,
31            Err(e) => debug_unreachable!("{e}"),
32        }
33    }
34}
35
36/// A sequential memory shared between calls, which uses
37/// a `Vec` for internal representation.
38/// A [SharedMemory] instance should always be obtained using
39/// the `new` static method to ensure memory safety.
40#[derive(Clone, PartialEq, Eq)]
41#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
42pub struct SharedMemory {
43    /// The underlying buffer.
44    buffer: Option<Rc<RefCell<Vec<u8>>>>,
45    /// Memory checkpoints for each depth.
46    /// Invariant: these are always in bounds of `data`.
47    my_checkpoint: usize,
48    /// Child checkpoint that we need to free context to.
49    child_checkpoint: Option<usize>,
50    /// Memory limit. See [`Cfg`](context_interface::Cfg).
51    #[cfg(feature = "memory_limit")]
52    memory_limit: u64,
53}
54
55impl fmt::Debug for SharedMemory {
56    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
57        f.debug_struct("SharedMemory")
58            .field("current_len", &self.len())
59            .field("context_memory", &hex::encode(&*self.context_memory()))
60            .finish_non_exhaustive()
61    }
62}
63
64impl Default for SharedMemory {
65    #[inline]
66    fn default() -> Self {
67        Self::new()
68    }
69}
70
71impl MemoryTr for SharedMemory {
72    fn set_data(&mut self, memory_offset: usize, data_offset: usize, len: usize, data: &[u8]) {
73        self.set_data(memory_offset, data_offset, len, data);
74    }
75
76    fn set(&mut self, memory_offset: usize, data: &[u8]) {
77        self.set(memory_offset, data);
78    }
79
80    fn size(&self) -> usize {
81        self.len()
82    }
83
84    fn copy(&mut self, destination: usize, source: usize, len: usize) {
85        self.copy(destination, source, len);
86    }
87
88    fn slice(&self, range: Range<usize>) -> Ref<'_, [u8]> {
89        self.slice_range(range)
90    }
91
92    fn local_memory_offset(&self) -> usize {
93        self.my_checkpoint
94    }
95
96    fn set_data_from_global(
97        &mut self,
98        memory_offset: usize,
99        data_offset: usize,
100        len: usize,
101        data_range: Range<usize>,
102    ) {
103        self.global_to_local_set_data(memory_offset, data_offset, len, data_range);
104    }
105
106    /// Returns a byte slice of the memory region at the given offset.
107    ///
108    /// # Panics
109    ///
110    /// Panics on out of bounds access in debug builds only.
111    ///
112    /// # Safety
113    ///
114    /// In release builds, calling this method with an out-of-bounds range triggers undefined
115    /// behavior. Callers must ensure that the range is within the bounds of the buffer.
116    #[inline]
117    #[cfg_attr(debug_assertions, track_caller)]
118    fn global_slice(&self, range: Range<usize>) -> Ref<'_, [u8]> {
119        self.global_slice_range(range)
120    }
121
122    fn resize(&mut self, new_size: usize) -> bool {
123        self.resize(new_size);
124        true
125    }
126
127    /// Returns `true` if the `new_size` for the current context memory will
128    /// make the shared buffer length exceed the `memory_limit`.
129    #[cfg(feature = "memory_limit")]
130    #[inline]
131    fn limit_reached(&self, offset: usize, len: usize) -> bool {
132        self.my_checkpoint
133            .saturating_add(offset)
134            .saturating_add(len) as u64
135            > self.memory_limit
136    }
137}
138
139impl SharedMemory {
140    /// Creates a new memory instance that can be shared between calls.
141    ///
142    /// The default initial capacity is 4KiB.
143    #[inline]
144    pub fn new() -> Self {
145        Self::with_capacity(4 * 1024) // from evmone
146    }
147
148    /// Creates a new invalid memory instance.
149    #[inline]
150    pub fn invalid() -> Self {
151        Self {
152            buffer: None,
153            my_checkpoint: 0,
154            child_checkpoint: None,
155            #[cfg(feature = "memory_limit")]
156            memory_limit: 0,
157        }
158    }
159
160    /// Creates a new memory instance with a given shared buffer.
161    pub fn new_with_buffer(buffer: Rc<RefCell<Vec<u8>>>) -> Self {
162        Self {
163            buffer: Some(buffer),
164            my_checkpoint: 0,
165            child_checkpoint: None,
166            #[cfg(feature = "memory_limit")]
167            memory_limit: u64::MAX,
168        }
169    }
170
171    /// Creates a new memory instance that can be shared between calls with the given `capacity`.
172    #[inline]
173    pub fn with_capacity(capacity: usize) -> Self {
174        Self {
175            buffer: Some(Rc::new(RefCell::new(Vec::with_capacity(capacity)))),
176            my_checkpoint: 0,
177            child_checkpoint: None,
178            #[cfg(feature = "memory_limit")]
179            memory_limit: u64::MAX,
180        }
181    }
182
183    /// Creates a new memory instance that can be shared between calls,
184    /// with `memory_limit` as upper bound for allocation size.
185    ///
186    /// The default initial capacity is 4KiB.
187    #[cfg(feature = "memory_limit")]
188    #[inline]
189    pub fn new_with_memory_limit(memory_limit: u64) -> Self {
190        Self {
191            memory_limit,
192            ..Self::new()
193        }
194    }
195
196    /// Sets the memory limit in bytes.
197    #[inline]
198    pub fn set_memory_limit(&mut self, limit: u64) {
199        #[cfg(feature = "memory_limit")]
200        {
201            self.memory_limit = limit;
202        }
203        // for clippy.
204        let _ = limit;
205    }
206
207    #[inline]
208    fn buffer(&self) -> &Rc<RefCell<Vec<u8>>> {
209        debug_assert!(self.buffer.is_some(), "cannot use SharedMemory::empty");
210        unsafe { self.buffer.as_ref().unwrap_unchecked() }
211    }
212
213    #[inline]
214    fn buffer_ref(&self) -> Ref<'_, Vec<u8>> {
215        self.buffer().dbg_borrow()
216    }
217
218    #[inline]
219    fn buffer_ref_mut(&self) -> RefMut<'_, Vec<u8>> {
220        self.buffer().dbg_borrow_mut()
221    }
222
223    /// Returns a byte slice of the backing buffer, applying `base` to `range`.
224    #[inline]
225    #[cfg_attr(debug_assertions, track_caller)]
226    fn slice_range_with_base(&self, range: Range<usize>, base: usize) -> Ref<'_, [u8]> {
227        let buffer = self.buffer_ref();
228        Ref::map(buffer, |b| {
229            match b.get(range.start + base..range.end + base) {
230                Some(slice) => slice,
231                None => debug_unreachable!("slice OOB: range; len: {}", self.len()),
232            }
233        })
234    }
235
236    /// Prepares the shared memory for a new child context.
237    ///
238    /// # Panics
239    ///
240    /// Panics if this function was already called without freeing child context.
241    #[inline]
242    pub fn new_child_context(&mut self) -> SharedMemory {
243        if self.child_checkpoint.is_some() {
244            panic!("new_child_context was already called without freeing child context");
245        }
246        let new_checkpoint = self.full_len();
247        self.child_checkpoint = Some(new_checkpoint);
248        SharedMemory {
249            buffer: Some(self.buffer().clone()),
250            my_checkpoint: new_checkpoint,
251            // child_checkpoint is same as my_checkpoint
252            child_checkpoint: None,
253            #[cfg(feature = "memory_limit")]
254            memory_limit: self.memory_limit,
255        }
256    }
257
258    /// Prepares the shared memory for returning from child context. Do nothing if there is no child context.
259    #[inline]
260    pub fn free_child_context(&mut self) {
261        let Some(child_checkpoint) = self.child_checkpoint.take() else {
262            return;
263        };
264        unsafe {
265            self.buffer_ref_mut().set_len(child_checkpoint);
266        }
267    }
268
269    /// Returns the length of the current memory range.
270    #[inline]
271    pub fn len(&self) -> usize {
272        self.full_len() - self.my_checkpoint
273    }
274
275    fn full_len(&self) -> usize {
276        self.buffer_ref().len()
277    }
278
279    /// Returns `true` if the current memory range is empty.
280    #[inline]
281    pub fn is_empty(&self) -> bool {
282        self.len() == 0
283    }
284
285    /// Resizes the memory in-place so that `len` is equal to `new_len`.
286    #[inline]
287    pub fn resize(&mut self, new_size: usize) {
288        self.buffer()
289            .dbg_borrow_mut()
290            .resize(self.my_checkpoint + new_size, 0);
291    }
292
293    /// Returns a byte slice of the memory region at the given offset.
294    ///
295    /// # Panics
296    ///
297    /// Panics on out of bounds.
298    #[inline]
299    #[cfg_attr(debug_assertions, track_caller)]
300    pub fn slice_len(&self, offset: usize, size: usize) -> Ref<'_, [u8]> {
301        self.slice_range(offset..offset + size)
302    }
303
304    /// Returns a byte slice of the memory region at the given offset.
305    ///
306    /// # Panics
307    ///
308    /// Panics on out of bounds access in debug builds only.
309    ///
310    /// # Safety
311    ///
312    /// In release builds, calling this method with an out-of-bounds range triggers undefined
313    /// behavior. Callers must ensure that the range is within the bounds of the memory (i.e.,
314    /// `range.end <= self.len()`).
315    #[inline]
316    #[cfg_attr(debug_assertions, track_caller)]
317    pub fn slice_range(&self, range: Range<usize>) -> Ref<'_, [u8]> {
318        self.slice_range_with_base(range, self.my_checkpoint)
319    }
320
321    /// Returns a byte slice of the memory region at the given offset.
322    ///
323    /// # Panics
324    ///
325    /// Panics on out of bounds access in debug builds only.
326    ///
327    /// # Safety
328    ///
329    /// In release builds, calling this method with an out-of-bounds range triggers undefined
330    /// behavior. Callers must ensure that the range is within the bounds of the buffer.
331    #[inline]
332    #[cfg_attr(debug_assertions, track_caller)]
333    pub fn global_slice_range(&self, range: Range<usize>) -> Ref<'_, [u8]> {
334        self.slice_range_with_base(range, 0)
335    }
336
337    /// Returns a byte slice of the memory region at the given offset.
338    ///
339    /// # Panics
340    ///
341    /// Panics on out of bounds access in debug builds only.
342    ///
343    /// # Safety
344    ///
345    /// In release builds, calling this method with out-of-bounds parameters triggers undefined
346    /// behavior. Callers must ensure that `offset + size` does not exceed the length of the
347    /// memory.
348    #[inline]
349    #[cfg_attr(debug_assertions, track_caller)]
350    pub fn slice_mut(&mut self, offset: usize, size: usize) -> RefMut<'_, [u8]> {
351        let buffer = self.buffer_ref_mut();
352        RefMut::map(buffer, |b| {
353            match b.get_mut(self.my_checkpoint + offset..self.my_checkpoint + offset + size) {
354                Some(slice) => slice,
355                None => debug_unreachable!("slice OOB: {offset}..{}", offset + size),
356            }
357        })
358    }
359
360    /// Returns the byte at the given offset.
361    ///
362    /// # Panics
363    ///
364    /// Panics on out of bounds.
365    #[inline]
366    pub fn get_byte(&self, offset: usize) -> u8 {
367        self.slice_len(offset, 1)[0]
368    }
369
370    /// Returns a 32-byte slice of the memory region at the given offset.
371    ///
372    /// # Panics
373    ///
374    /// Panics on out of bounds.
375    #[inline]
376    pub fn get_word(&self, offset: usize) -> B256 {
377        (*self.slice_len(offset, 32)).try_into().unwrap()
378    }
379
380    /// Returns a U256 of the memory region at the given offset.
381    ///
382    /// # Panics
383    ///
384    /// Panics on out of bounds.
385    #[inline]
386    pub fn get_u256(&self, offset: usize) -> U256 {
387        self.get_word(offset).into()
388    }
389
390    /// Sets the `byte` at the given `index`.
391    ///
392    /// # Panics
393    ///
394    /// Panics on out of bounds.
395    #[inline]
396    #[cfg_attr(debug_assertions, track_caller)]
397    pub fn set_byte(&mut self, offset: usize, byte: u8) {
398        self.set(offset, &[byte]);
399    }
400
401    /// Sets the given 32-byte `value` to the memory region at the given `offset`.
402    ///
403    /// # Panics
404    ///
405    /// Panics on out of bounds.
406    #[inline]
407    #[cfg_attr(debug_assertions, track_caller)]
408    pub fn set_word(&mut self, offset: usize, value: &B256) {
409        self.set(offset, &value[..]);
410    }
411
412    /// Sets the given U256 `value` to the memory region at the given `offset`.
413    ///
414    /// # Panics
415    ///
416    /// Panics on out of bounds.
417    #[inline]
418    #[cfg_attr(debug_assertions, track_caller)]
419    pub fn set_u256(&mut self, offset: usize, value: U256) {
420        self.set(offset, &value.to_be_bytes::<32>());
421    }
422
423    /// Set memory region at given `offset`.
424    ///
425    /// # Panics
426    ///
427    /// Panics on out of bounds.
428    #[inline]
429    #[cfg_attr(debug_assertions, track_caller)]
430    pub fn set(&mut self, offset: usize, value: &[u8]) {
431        if !value.is_empty() {
432            self.slice_mut(offset, value.len()).copy_from_slice(value);
433        }
434    }
435
436    /// Set memory from data. Our memory offset+len is expected to be correct but we
437    /// are doing bound checks on data/data_offeset/len and zeroing parts that is not copied.
438    ///
439    /// # Panics
440    ///
441    /// Panics if memory is out of bounds.
442    #[inline]
443    #[cfg_attr(debug_assertions, track_caller)]
444    pub fn set_data(&mut self, memory_offset: usize, data_offset: usize, len: usize, data: &[u8]) {
445        let mut dst = self.context_memory_mut();
446        unsafe { set_data(dst.as_mut(), data, memory_offset, data_offset, len) };
447    }
448
449    /// Set data from global memory to local memory. If global range is smaller than len, zeroes the rest.
450    #[inline]
451    #[cfg_attr(debug_assertions, track_caller)]
452    pub fn global_to_local_set_data(
453        &mut self,
454        memory_offset: usize,
455        data_offset: usize,
456        len: usize,
457        data_range: Range<usize>,
458    ) {
459        let mut buffer = self.buffer_ref_mut();
460        let (src, dst) = buffer.split_at_mut(self.my_checkpoint);
461        let src = if data_range.is_empty() {
462            &mut []
463        } else {
464            src.get_mut(data_range).unwrap()
465        };
466        unsafe { set_data(dst, src, memory_offset, data_offset, len) };
467    }
468
469    /// Copies elements from one part of the memory to another part of itself.
470    ///
471    /// # Panics
472    ///
473    /// Panics on out of bounds.
474    #[inline]
475    #[cfg_attr(debug_assertions, track_caller)]
476    pub fn copy(&mut self, dst: usize, src: usize, len: usize) {
477        self.context_memory_mut().copy_within(src..src + len, dst);
478    }
479
480    /// Returns a reference to the memory of the current context, the active memory.
481    ///
482    /// # Panics
483    ///
484    /// Panics if the checkpoint is invalid in debug builds only.
485    ///
486    /// # Safety
487    ///
488    /// In release builds, calling this method with an invalid checkpoint triggers undefined
489    /// behavior. The checkpoint must be within the bounds of the buffer.
490    #[inline]
491    pub fn context_memory(&self) -> Ref<'_, [u8]> {
492        let buffer = self.buffer_ref();
493        Ref::map(buffer, |b| match b.get(self.my_checkpoint..) {
494            Some(slice) => slice,
495            None => debug_unreachable!("Context memory should be always valid"),
496        })
497    }
498
499    /// Returns a mutable reference to the memory of the current context.
500    ///
501    /// # Panics
502    ///
503    /// Panics if the checkpoint is invalid in debug builds only.
504    ///
505    /// # Safety
506    ///
507    /// In release builds, calling this method with an invalid checkpoint triggers undefined
508    /// behavior. The checkpoint must be within the bounds of the buffer.
509    #[inline]
510    pub fn context_memory_mut(&mut self) -> RefMut<'_, [u8]> {
511        let buffer = self.buffer_ref_mut();
512        RefMut::map(buffer, |b| match b.get_mut(self.my_checkpoint..) {
513            Some(slice) => slice,
514            None => debug_unreachable!("Context memory should be always valid"),
515        })
516    }
517}
518
519/// Copies data from src to dst taking into account the offsets and len.
520///
521/// If src does not have enough data, it nullifies the rest of dst that is not copied.
522///
523/// # Safety
524///
525/// Assumes that dst has enough space to copy the data.
526/// Assumes that src has enough data to copy.
527/// Assumes that dst_offset and src_offset are in bounds.
528/// Assumes that dst and src are valid.
529/// Assumes that dst and src do not overlap.
530unsafe fn set_data(dst: &mut [u8], src: &[u8], dst_offset: usize, src_offset: usize, len: usize) {
531    if len == 0 {
532        return;
533    }
534    if src_offset >= src.len() {
535        // Nullify all memory slots
536        dst.get_mut(dst_offset..dst_offset + len).unwrap().fill(0);
537        return;
538    }
539    let src_end = min(src_offset + len, src.len());
540    let src_len = src_end - src_offset;
541    debug_assert!(src_offset < src.len() && src_end <= src.len());
542    let data = unsafe { src.get_unchecked(src_offset..src_end) };
543    unsafe {
544        dst.get_unchecked_mut(dst_offset..dst_offset + src_len)
545            .copy_from_slice(data)
546    };
547
548    // Nullify rest of memory slots
549    // SAFETY: Memory is assumed to be valid, and it is commented where this assumption is made.
550    unsafe {
551        dst.get_unchecked_mut(dst_offset + src_len..dst_offset + len)
552            .fill(0)
553    };
554}
555
556/// Returns number of words what would fit to provided number of bytes,
557/// i.e. it rounds up the number bytes to number of words.
558#[inline]
559pub const fn num_words(len: usize) -> usize {
560    len.div_ceil(32)
561}
562
563/// Performs EVM memory resize.
564#[inline]
565pub fn resize_memory<Memory: MemoryTr>(
566    gas: &mut crate::Gas,
567    memory: &mut Memory,
568    gas_table: &GasParams,
569    offset: usize,
570    len: usize,
571) -> Result<(), InstructionResult> {
572    #[cfg(feature = "memory_limit")]
573    if memory.limit_reached(offset, len) {
574        return Err(InstructionResult::MemoryLimitOOG);
575    }
576
577    let new_num_words = num_words(offset.saturating_add(len));
578    if new_num_words > gas.memory().words_num {
579        return resize_memory_cold(gas, memory, gas_table, new_num_words);
580    }
581
582    Ok(())
583}
584
585#[cold]
586#[inline(never)]
587fn resize_memory_cold<Memory: MemoryTr>(
588    gas: &mut crate::Gas,
589    memory: &mut Memory,
590    gas_table: &GasParams,
591    new_num_words: usize,
592) -> Result<(), InstructionResult> {
593    let cost = gas_table.memory_cost(new_num_words);
594    let cost = unsafe {
595        gas.memory_mut()
596            .set_words_num(new_num_words, cost)
597            .unwrap_unchecked()
598    };
599
600    if !gas.record_cost(cost) {
601        return Err(InstructionResult::MemoryOOG);
602    }
603    memory.resize(new_num_words * 32);
604    Ok(())
605}
606
607#[cfg(test)]
608mod tests {
609    use super::*;
610
611    #[test]
612    fn test_num_words() {
613        assert_eq!(num_words(0), 0);
614        assert_eq!(num_words(1), 1);
615        assert_eq!(num_words(31), 1);
616        assert_eq!(num_words(32), 1);
617        assert_eq!(num_words(33), 2);
618        assert_eq!(num_words(63), 2);
619        assert_eq!(num_words(64), 2);
620        assert_eq!(num_words(65), 3);
621        assert_eq!(num_words(usize::MAX - 31), usize::MAX / 32);
622        assert_eq!(num_words(usize::MAX - 30), (usize::MAX / 32) + 1);
623        assert_eq!(num_words(usize::MAX), (usize::MAX / 32) + 1);
624    }
625
626    #[test]
627    fn new_free_child_context() {
628        let mut sm1 = SharedMemory::new();
629
630        assert_eq!(sm1.buffer_ref().len(), 0);
631        assert_eq!(sm1.my_checkpoint, 0);
632
633        unsafe { sm1.buffer_ref_mut().set_len(32) };
634        assert_eq!(sm1.len(), 32);
635        let mut sm2 = sm1.new_child_context();
636
637        assert_eq!(sm2.buffer_ref().len(), 32);
638        assert_eq!(sm2.my_checkpoint, 32);
639        assert_eq!(sm2.len(), 0);
640
641        unsafe { sm2.buffer_ref_mut().set_len(96) };
642        assert_eq!(sm2.len(), 64);
643        let mut sm3 = sm2.new_child_context();
644
645        assert_eq!(sm3.buffer_ref().len(), 96);
646        assert_eq!(sm3.my_checkpoint, 96);
647        assert_eq!(sm3.len(), 0);
648
649        unsafe { sm3.buffer_ref_mut().set_len(128) };
650        let sm4 = sm3.new_child_context();
651        assert_eq!(sm4.buffer_ref().len(), 128);
652        assert_eq!(sm4.my_checkpoint, 128);
653        assert_eq!(sm4.len(), 0);
654
655        // Free contexts
656        drop(sm4);
657        sm3.free_child_context();
658        assert_eq!(sm3.buffer_ref().len(), 128);
659        assert_eq!(sm3.my_checkpoint, 96);
660        assert_eq!(sm3.len(), 32);
661
662        sm2.free_child_context();
663        assert_eq!(sm2.buffer_ref().len(), 96);
664        assert_eq!(sm2.my_checkpoint, 32);
665        assert_eq!(sm2.len(), 64);
666
667        sm1.free_child_context();
668        assert_eq!(sm1.buffer_ref().len(), 32);
669        assert_eq!(sm1.my_checkpoint, 0);
670        assert_eq!(sm1.len(), 32);
671    }
672
673    #[test]
674    fn resize() {
675        let mut sm1 = SharedMemory::new();
676        sm1.resize(32);
677        assert_eq!(sm1.buffer_ref().len(), 32);
678        assert_eq!(sm1.len(), 32);
679        assert_eq!(sm1.buffer_ref().get(0..32), Some(&[0_u8; 32] as &[u8]));
680
681        let mut sm2 = sm1.new_child_context();
682        sm2.resize(96);
683        assert_eq!(sm2.buffer_ref().len(), 128);
684        assert_eq!(sm2.len(), 96);
685        assert_eq!(sm2.buffer_ref().get(32..128), Some(&[0_u8; 96] as &[u8]));
686
687        sm1.free_child_context();
688        assert_eq!(sm1.buffer_ref().len(), 32);
689        assert_eq!(sm1.len(), 32);
690        assert_eq!(sm1.buffer_ref().get(0..32), Some(&[0_u8; 32] as &[u8]));
691    }
692}
revm_interpreter/interpreter/shared_memory.rs

revm_interpreter/interpreter/
shared_memory.rs
