minidump-writer 0.12.0

Rust rewrite of Breakpad's minidump_writer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

//! Common module reader types.
use {
    crate::process_reader::{CopyFromProcessError, ProcessReader},
    std::borrow::Cow,
};

#[cfg(any(target_os = "linux", target_os = "android"))]
pub use crate::linux::module_reader::*;

#[cfg(target_os = "windows")]
pub use crate::windows::module_reader::*;

#[cfg(target_os = "macos")]
pub use crate::mac::module_reader::*;

/// Module memory, which may either be represented by a slice or by an offset into a process's
/// address space.
#[derive(Clone, Copy)]
pub enum ModuleMemory<'a> {
    Slice(&'a [u8]),
    Process {
        reader: &'a ProcessReader,
        start_address: u64,
    },
}

impl<'buf> From<&'buf [u8]> for ModuleMemory<'buf> {
    fn from(value: &'buf [u8]) -> Self {
        Self::Slice(value)
    }
}

#[derive(Debug, thiserror::Error, serde::Serialize)]
#[error("Error reading {length} bytes at {offset:#x}{}: {error}",
    .start_address.map(|s| format!(" (module start address {s:#x})")).unwrap_or_default()
)]
pub struct ModuleMemoryReadError {
    offset: u64,
    length: u64,
    start_address: Option<u64>,
    #[source]
    error: ReadError,
}

#[derive(Debug, thiserror::Error, serde::Serialize)]
pub enum ReadError {
    #[error("Attempted to read 0 bytes from process memory")]
    ZeroLengthProcessRead,
    #[error("Read overflowed the address space")]
    Overflow,
    #[error("Read was out of slice memory bounds")]
    OutOfBounds,
    #[error(transparent)]
    CopyError(#[from] CopyFromProcessError),
}

impl<'a> ModuleMemory<'a> {
    pub fn from_process(reader: &'a ProcessReader, start_address: usize) -> Self {
        Self::Process {
            reader,
            start_address: start_address as u64,
        }
    }

    #[inline]
    pub fn read(&self, offset: u64, length: u64) -> Result<Cow<'a, [u8]>, ModuleMemoryReadError> {
        let error = move |start_address, error| ModuleMemoryReadError {
            start_address,
            offset,
            length,
            error,
        };

        match self {
            Self::Process {
                reader,
                start_address,
            } => {
                let error = |e| error(Some(*start_address), e);
                let len = std::num::NonZeroUsize::new(length as usize)
                    .ok_or_else(|| error(ReadError::ZeroLengthProcessRead))?;
                let proc_offset = start_address
                    .checked_add(offset)
                    .ok_or_else(|| error(ReadError::Overflow))?;
                reader
                    .read_to_vec(proc_offset as _, len)
                    .map(Cow::Owned)
                    .map_err(|err| error(err.into()))
            }
            Self::Slice(s) => {
                let error = |e| error(None, e);
                let end = offset
                    .checked_add(length)
                    .ok_or_else(|| error(ReadError::Overflow))?;
                s.get(offset as usize..end as usize)
                    .map(Cow::Borrowed)
                    .ok_or_else(|| error(ReadError::OutOfBounds))
            }
        }
    }

    /// Calculates the relative address of the specified absolute address
    #[inline]
    pub fn absolute_to_relative(&self, addr: u64) -> Option<u64> {
        let Self::Process { start_address, .. } = self else {
            return Some(addr);
        };
        addr.checked_sub(*start_address)
    }

    /// Calculates the absolute address of the specified relative address
    #[inline]
    pub fn relative_to_absolute(&self, addr: u64) -> Option<u64> {
        let Self::Process { start_address, .. } = self else {
            return Some(addr);
        };
        start_address.checked_add(addr)
    }

    #[inline]
    pub fn is_process_memory(&self) -> bool {
        matches!(self, Self::Process { .. })
    }
}