Skip to main content

reverie_memory/
lib.rs

1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of this source tree.
7 */
8
9mod addr;
10mod local;
11
12use core::mem;
13use std::ffi::CString;
14use std::io;
15
16pub use addr::Addr;
17pub use addr::AddrMut;
18pub use addr::AddrSlice;
19pub use addr::AddrSliceMut;
20pub use local::LocalMemory;
21use syscalls::Errno;
22
23/// One numeric destination in another process's address space.
24///
25/// Unlike [`io::IoSliceMut`], this forms no Rust reference to the remote
26/// address. The address is only a kernel operand for a backend that has
27/// independently authenticated the stopped target task.
28#[derive(Clone, Copy, Debug, Eq, PartialEq)]
29pub struct RemoteIoVec {
30    address: usize,
31    length: usize,
32}
33
34impl RemoteIoVec {
35    pub fn new(address: AddrMut<u8>, length: usize) -> Result<Self, Errno> {
36        address.as_raw().checked_add(length).ok_or(Errno::EFAULT)?;
37        Ok(Self {
38            address: address.as_raw(),
39            length,
40        })
41    }
42
43    pub fn address(self) -> usize {
44        self.address
45    }
46
47    pub fn length(self) -> usize {
48        self.length
49    }
50}
51
52/// Trait for accessing potentially remote memory.
53pub trait MemoryAccess {
54    /// Reads bytes from the address space. Returns the number of bytes read.
55    ///
56    /// Note that there is no guarantee that all of the requested buffers will be
57    /// filled.
58    fn read_vectored(
59        &self,
60        read_from: &[io::IoSlice],
61        write_to: &mut [io::IoSliceMut],
62    ) -> Result<usize, Errno>;
63
64    /// Writes bytes to the address space. Returns the number of bytes written.
65    ///
66    /// Note that there is no guarantee that all of the requested buffers will
67    /// be written.
68    fn write_vectored(
69        &mut self,
70        read_from: &[io::IoSlice],
71        write_to: &mut [io::IoSliceMut],
72    ) -> Result<usize, Errno>;
73
74    /// Performs one synchronous native write to the exact expected task.
75    ///
76    /// An implementation must check its actual task against `expected_tid`
77    /// before any effect, respect the target's VMA access permissions, and
78    /// return the unmodified native byte count or errno. It must not retry a
79    /// short transfer, collapse `EFAULT` to zero, or fall back to ptrace writes.
80    /// All effects must finish before return: no detached work or retained
81    /// buffer references are permitted. Remote protection keys are not proved
82    /// by this interface; the caller separately owns task-generation, mapping,
83    /// foreground and lifetime authority throughout the operation.
84    ///
85    /// Backends without this exact capability refuse without accessing memory.
86    /// An implementation may also cap the number of `remote` segments and
87    /// refuse a longer list with `E2BIG`, again without accessing memory; the
88    /// ptrace backend accepts at most two.
89    fn write_native_user_vectored(
90        &mut self,
91        _expected_tid: i32,
92        _local: &[io::IoSlice],
93        _remote: &[RemoteIoVec],
94    ) -> Result<usize, Errno> {
95        Err(Errno::EOPNOTSUPP)
96    }
97
98    /// Performs a read starting at the given address. The number of bytes read
99    /// is returned. The buffer is not guaranteed to be completely filled.
100    fn read<'a, A>(&self, addr: A, buf: &mut [u8]) -> Result<usize, Errno>
101    where
102        A: Into<Addr<'a, u8>>,
103    {
104        let slice = unsafe { AddrSlice::from_raw_parts(addr.into(), buf.len()) };
105        let from = [unsafe { slice.as_ioslice() }];
106        let mut to = [io::IoSliceMut::new(buf)];
107        self.read_vectored(&from, &mut to)
108    }
109
110    /// Performs a write starting at the given address. The number of bytes
111    /// written is returned. There is no guarantee that the given buffer will be
112    /// fully written.
113    fn write(&mut self, addr: AddrMut<u8>, buf: &[u8]) -> Result<usize, Errno> {
114        let mut slice = unsafe { AddrSliceMut::from_raw_parts(addr, buf.len()) };
115        let from = [io::IoSlice::new(buf)];
116        let mut to = [unsafe { slice.as_ioslice_mut() }];
117        self.write_vectored(&from, &mut to)
118    }
119
120    /// Writes one prefix while respecting the target's user mapping permissions.
121    ///
122    /// Unlike debugger writes, this must not force access to read-only memory.
123    /// Supported implementations perform one increasing-address copy, without
124    /// retrying a short transfer. A nonempty first-byte fault is `EFAULT`;
125    /// otherwise the count describes exactly the bytes copied. A short count
126    /// does not imply that the next byte is unwritable or identify a fault.
127    /// Nonempty address-plus-length overflow is `EFAULT` before copying.
128    ///
129    /// A healthy supported empty copy returns zero without inspecting `addr`.
130    /// Other errors retain their identity. A terminal backend failure may
131    /// override a count or ordinary fault after effects, including on an empty
132    /// operation. Callers must preserve those effects, stop, and not commit a
133    /// consuming transaction or retry a terminal error as an ordinary fault.
134    ///
135    /// The default is unsupported, including for empty copies. `ENOSYS` means
136    /// a missing backend capability: the consuming Tool must report a backend
137    /// or Tool failure rather than forwarding it as a guest syscall errno.
138    /// It must not fall back to generic debugger writes.
139    ///
140    /// This synchronous operation may block and adds no scheduling guarantee
141    /// or snapshot of concurrent mapping changes. Permissions are those the
142    /// backend supports; this does not add PKRU or tagged-address emulation.
143    fn write_with_user_access(&mut self, _addr: AddrMut<u8>, _buf: &[u8]) -> Result<usize, Errno> {
144        Err(Errno::ENOSYS)
145    }
146
147    /// Atomically replaces the aligned 32-bit word at `addr` with `desired`
148    /// if it holds `expected`, and returns the value the word held: the store
149    /// happened exactly when that value equals `expected`. This is the
150    /// compare-and-exchange Linux performs on a futex word
151    /// (`futex_cmpxchg_value_locked`), with the same visibility to other
152    /// threads and processes that map the word.
153    ///
154    /// A misaligned address is `EINVAL`, and an address that cannot be read
155    /// and written is `EFAULT`, both without storing.
156    ///
157    /// The default is unsupported. `ENOSYS` means a missing backend
158    /// capability, as for [`Self::write_with_user_access`]: the consuming Tool
159    /// must not emulate it with a separate read and write.
160    fn compare_exchange_u32(
161        &mut self,
162        _addr: AddrMut<u32>,
163        _expected: u32,
164        _desired: u32,
165    ) -> Result<u32, Errno> {
166        Err(Errno::ENOSYS)
167    }
168
169    /// Reads exactly the number of bytes wanted by `buf`.
170    fn read_exact<'a, A>(&self, addr: A, mut buf: &mut [u8]) -> Result<(), Errno>
171    where
172        A: Into<Addr<'a, u8>>,
173    {
174        let mut addr = addr.into();
175
176        while !buf.is_empty() {
177            match self.read(addr, buf)? {
178                0 => break,
179                n => {
180                    addr = unsafe { addr.add(n) };
181                    buf = &mut buf[n..];
182                }
183            }
184        }
185
186        if !buf.is_empty() {
187            // Failed to fill the whole buffer.
188            Err(Errno::EFAULT)
189        } else {
190            Ok(())
191        }
192    }
193
194    /// Reads exactly the number of bytes wanted by `buf`, while respecting the
195    /// target process's userspace memory protections.
196    ///
197    /// This performs one read rather than retrying a partial transfer. A short
198    /// read therefore reports `EFAULT`, matching the all-or-error behavior of
199    /// Linux helpers such as `copy_from_user`.
200    fn read_exact_with_user_access<'a, A>(&self, addr: A, buf: &mut [u8]) -> Result<(), Errno>
201    where
202        A: Into<Addr<'a, u8>>,
203    {
204        let addr = addr.into();
205        addr.as_raw().checked_add(buf.len()).ok_or(Errno::EFAULT)?;
206
207        if self.read(addr, buf)? == buf.len() {
208            Ok(())
209        } else {
210            Err(Errno::EFAULT)
211        }
212    }
213
214    /// Reads exactly the number of bytes wanted by `buf`.
215    fn write_exact(&mut self, mut addr: AddrMut<u8>, mut buf: &[u8]) -> Result<(), Errno> {
216        while !buf.is_empty() {
217            match self.write(addr, buf)? {
218                0 => break,
219                n => {
220                    addr = unsafe { addr.add(n) };
221                    buf = &buf[n..];
222                }
223            }
224        }
225
226        if !buf.is_empty() {
227            // Failed to fill the whole buffer.
228            Err(Errno::EFAULT)
229        } else {
230            Ok(())
231        }
232    }
233
234    /// Reads a value at the given address.
235    fn read_value<'a, A, T>(&self, addr: A) -> Result<T, Errno>
236    where
237        A: Into<Addr<'a, T>>,
238        T: Sized + 'a,
239    {
240        let addr = addr.into();
241        let mut value = mem::MaybeUninit::uninit();
242
243        let value_buf = unsafe {
244            ::core::slice::from_raw_parts_mut(value.as_mut_ptr() as *mut u8, mem::size_of::<T>())
245        };
246
247        self.read_exact(addr.cast::<u8>(), value_buf)?;
248
249        Ok(unsafe { value.assume_init() })
250    }
251
252    /// Writes a value to the given address.
253    fn write_value<'a, A, T>(&mut self, addr: A, value: &T) -> Result<(), Errno>
254    where
255        A: Into<AddrMut<'a, T>>,
256        T: Sized + 'a,
257    {
258        let addr = addr.into();
259
260        let value_buf = unsafe {
261            ::core::slice::from_raw_parts(value as *const _ as *const u8, mem::size_of::<T>())
262        };
263
264        self.write_exact(addr.cast::<u8>(), value_buf)?;
265
266        Ok(())
267    }
268
269    /// Reads a slice of values. Returns an error if the buffer fails to get
270    /// fully filled.
271    fn read_values<T>(&self, addr: Addr<T>, buf: &mut [T]) -> Result<(), Errno>
272    where
273        T: Sized,
274    {
275        let buf = unsafe {
276            ::core::slice::from_raw_parts_mut(buf.as_mut_ptr() as *mut u8, mem::size_of_val(buf))
277        };
278
279        self.read_exact(addr.cast::<u8>(), buf)
280    }
281
282    /// Writes a slice of values. Returns an error if the buffer fails to get
283    /// fully written.
284    fn write_values<T>(&mut self, addr: AddrMut<T>, buf: &[T]) -> Result<(), Errno>
285    where
286        T: Sized,
287    {
288        let buf = unsafe {
289            ::core::slice::from_raw_parts(buf.as_ptr() as *const u8, mem::size_of_val(buf))
290        };
291
292        self.write_exact(addr.cast::<u8>(), buf)
293    }
294
295    /// Reads memory at the given starting address while the boolean returned by
296    /// the predicate `pred` is true.
297    fn read_while<F>(&self, mut addr: Addr<u8>, buf: &mut [u8], mut pred: F) -> Result<usize, Errno>
298    where
299        F: FnMut(&[u8]) -> Option<usize>,
300    {
301        let mut count = 0usize;
302
303        loop {
304            let read = self.read(addr, buf)?;
305            if read == 0 {
306                // We hit an "EOF" (an EFAULT) and the predicate never matched.
307                // The predicate should *eventually* return true, so this is
308                // always an error.
309                return Err(Errno::EFAULT);
310            }
311
312            if let Some(used) = pred(&buf[..read]) {
313                return count.checked_add(used).ok_or(Errno::EFAULT);
314            }
315
316            // Only advance when another chunk is needed. Addresses may name
317            // remote memory, so neither in-bounds pointer arithmetic nor a
318            // wrapping address is valid for this traversal.
319            let next = addr.as_raw().checked_add(read).ok_or(Errno::EFAULT)?;
320            addr = Addr::from_raw(next).ok_or(Errno::EFAULT)?;
321            count = count.checked_add(read).ok_or(Errno::EFAULT)?;
322        }
323    }
324
325    /// Reads a NUL terminated string using the provided buffer to read it in
326    /// chunks. Change the size of the buffer to adjust how many bytes are read
327    /// at one time. Increasing the buffer size can be more efficient when
328    /// reading a remote C string because it reduces the number of syscalls that
329    /// are made.
330    fn read_cstring_with_buf(&self, addr: Addr<u8>, buf: &mut [u8]) -> Result<CString, Errno> {
331        let mut accumulator = Vec::new();
332
333        self.read_while(addr, buf, |slice| {
334            if let Some(nul) = slice.iter().position(|&b| b == 0) {
335                // Stop once we find a NUL terminator.
336                accumulator.extend(&slice[..nul]);
337                Some(nul)
338            } else {
339                accumulator.extend(slice);
340                None
341            }
342        })?;
343
344        // unsafe is okay here; the vector is guaranteed to not contain a nul
345        // byte.
346        Ok(unsafe { CString::from_vec_unchecked(accumulator) })
347    }
348
349    /// Reads a null-terminated string starting at the given address.
350    fn read_cstring(&self, addr: Addr<u8>) -> Result<CString, Errno> {
351        // Assume most strings are smallish. We need to balance the overhead of
352        // copying data vs the average length of C-strings.
353        let mut buf: [u8; 512] = [0; 512];
354
355        self.read_cstring_with_buf(addr, &mut buf)
356    }
357
358    /// Returns a struct that implements `std::io::Read`. This is useful when
359    /// reading memory sequentially.
360    fn reader<'a, T>(&'a self, addr: Addr<'a, T>) -> MemoryReader<'a, Self, T>
361    where
362        Self: Sized,
363    {
364        MemoryReader::new(self, addr)
365    }
366
367    /// Returns a struct that implements `std::io::Write`. This is useful when
368    /// writing memory sequentially.
369    fn writer<'a, T>(&'a mut self, addr: AddrMut<'a, T>) -> MemoryWriter<'a, Self, T>
370    where
371        Self: Sized,
372    {
373        MemoryWriter::new(self, addr)
374    }
375}
376
377/// A wrapper around both an address space and a pointer for sequential reads.
378pub struct MemoryReader<'a, M, T> {
379    memory: &'a M,
380
381    addr: Addr<'a, T>,
382}
383
384impl<'a, M, T> MemoryReader<'a, M, T> {
385    /// Creates a new `MemoryReader`. All reads will start at `addr`. It is the
386    /// callers job to avoid buffer overruns.
387    pub fn new(memory: &'a M, addr: Addr<'a, T>) -> Self {
388        MemoryReader { memory, addr }
389    }
390}
391
392impl<'a, M, T> MemoryReader<'a, M, T>
393where
394    M: MemoryAccess,
395    T: Sized + Copy,
396{
397    /// Reads a single typed value from the buffer.
398    pub fn read_value(&mut self) -> Result<T, Errno> {
399        let value = self.memory.read_value(self.addr)?;
400        self.addr = unsafe { self.addr.add(1) };
401        Ok(value)
402    }
403}
404
405impl<'a, M> io::Read for MemoryReader<'a, M, u8>
406where
407    M: MemoryAccess,
408{
409    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
410        let count = self.memory.read(self.addr, buf)?;
411
412        self.addr = unsafe { self.addr.add(count) };
413
414        Ok(count)
415    }
416}
417
418/// A wrapper around both an address space and a pointer for sequential writes.
419pub struct MemoryWriter<'a, M, T> {
420    memory: &'a mut M,
421
422    addr: AddrMut<'a, T>,
423}
424
425impl<'a, M, T> MemoryWriter<'a, M, T> {
426    /// Creates a new `MemoryWriter`. All writes will start at `addr`. It is the
427    /// callers job to avoid buffer overruns.
428    pub fn new(memory: &'a mut M, addr: AddrMut<'a, T>) -> Self {
429        MemoryWriter { memory, addr }
430    }
431}
432
433impl<'a, M, T> MemoryWriter<'a, M, T>
434where
435    M: MemoryAccess,
436    T: Sized + Copy,
437{
438    /// Reads a single typed value from the buffer.
439    pub fn write_value(&mut self, value: &T) -> Result<(), Errno> {
440        self.memory.write_value(self.addr, value)?;
441        self.addr = unsafe { self.addr.add(1) };
442        Ok(())
443    }
444}
445
446impl<'a, M> io::Write for MemoryWriter<'a, M, u8>
447where
448    M: MemoryAccess,
449{
450    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
451        let count = self.memory.write(self.addr, buf)?;
452
453        self.addr = unsafe { self.addr.add(count) };
454
455        Ok(count)
456    }
457
458    fn flush(&mut self) -> io::Result<()> {
459        // Flush doesn't make any sense when writing to memory.
460        Ok(())
461    }
462}
463
464#[cfg(test)]
465mod user_access_default_tests {
466    use super::*;
467    struct LegacyWriter {
468        calls: usize,
469    }
470    impl MemoryAccess for LegacyWriter {
471        fn read_vectored(
472            &self,
473            _: &[io::IoSlice],
474            _: &mut [io::IoSliceMut],
475        ) -> Result<usize, Errno> {
476            panic!("copyout must not probe memory")
477        }
478        fn write_vectored(
479            &mut self,
480            _: &[io::IoSlice],
481            _: &mut [io::IoSliceMut],
482        ) -> Result<usize, Errno> {
483            panic!("new capability must not fall back to vectored debugger writes")
484        }
485        fn write(&mut self, _: AddrMut<u8>, bytes: &[u8]) -> Result<usize, Errno> {
486            self.calls += 1;
487            Ok(bytes.len())
488        }
489    }
490    #[test]
491    fn unsupported_user_copy_never_falls_back_to_debugger_write() {
492        let mut memory = LegacyWriter { calls: 0 };
493        let address = AddrMut::from_raw(usize::MAX).unwrap();
494        for bytes in [&[][..], &[1, 2, 3, 4, 5, 6, 7][..], &[0; 8][..]] {
495            assert_eq!(
496                memory.write_with_user_access(address, bytes),
497                Err(Errno::ENOSYS)
498            );
499            assert_eq!(memory.calls, 0);
500        }
501        assert_eq!(memory.write(address, &[0; 8]), Ok(8));
502        assert_eq!(memory.calls, 1);
503    }
504}
505
506#[cfg(test)]
507mod native_user_write_tests {
508    use super::*;
509
510    #[test]
511    fn native_user_write_default_refuses_without_using_ordinary_memory_access() {
512        struct Unsupported;
513        impl MemoryAccess for Unsupported {
514            fn read_vectored(
515                &self,
516                _: &[io::IoSlice],
517                _: &mut [io::IoSliceMut],
518            ) -> Result<usize, Errno> {
519                panic!("native write must not call ordinary read");
520            }
521
522            fn write_vectored(
523                &mut self,
524                _: &[io::IoSlice],
525                _: &mut [io::IoSliceMut],
526            ) -> Result<usize, Errno> {
527                panic!("native write must not call ordinary write");
528            }
529        }
530
531        let mut memory = Unsupported;
532        let local = [io::IoSlice::new(b"newbytes")];
533        let target = [0xa5; 8];
534        let remote = [RemoteIoVec::new(AddrMut::from_ptr(target.as_ptr()).unwrap(), 8).unwrap()];
535        let result = memory.write_native_user_vectored(1, &local, &remote);
536        assert_eq!(result, Err(Errno::EOPNOTSUPP));
537        assert_eq!(Errno::EOPNOTSUPP, Errno::new(libc::ENOTSUP));
538        assert_eq!(target, [0xa5; 8]);
539    }
540}
541
542#[cfg(test)]
543mod compare_exchange_default_tests {
544    use super::*;
545
546    #[test]
547    fn compare_exchange_default_refuses_without_using_ordinary_memory_access() {
548        struct Unsupported;
549        impl MemoryAccess for Unsupported {
550            fn read_vectored(
551                &self,
552                _: &[io::IoSlice],
553                _: &mut [io::IoSliceMut],
554            ) -> Result<usize, Errno> {
555                panic!("compare-exchange must not fall back to a read");
556            }
557
558            fn write_vectored(
559                &mut self,
560                _: &[io::IoSlice],
561                _: &mut [io::IoSliceMut],
562            ) -> Result<usize, Errno> {
563                panic!("compare-exchange must not fall back to a write");
564            }
565        }
566
567        let word = 7u32;
568        let address = AddrMut::from_ptr(&word as *const u32).unwrap();
569        assert_eq!(
570            Unsupported.compare_exchange_u32(address, 7, 8),
571            Err(Errno::ENOSYS)
572        );
573        assert_eq!(word, 7);
574    }
575}