rustc_middle/mir/interpret/
pointer.rs

1use std::fmt;
2use std::num::NonZero;
3
4use rustc_abi::{HasDataLayout, Size};
5use rustc_data_structures::static_assert_size;
6use rustc_macros::{HashStable, TyDecodable, TyEncodable};
7
8use super::AllocId;
9
10////////////////////////////////////////////////////////////////////////////////
11// Pointer arithmetic
12////////////////////////////////////////////////////////////////////////////////
13
14pub trait PointerArithmetic: HasDataLayout {
15    // These are not supposed to be overridden.
16
17    #[inline(always)]
18    fn pointer_size(&self) -> Size {
19        self.data_layout().pointer_size()
20    }
21
22    #[inline(always)]
23    fn max_size_of_val(&self) -> Size {
24        Size::from_bytes(self.target_isize_max())
25    }
26
27    #[inline]
28    fn target_usize_max(&self) -> u64 {
29        self.pointer_size().unsigned_int_max().try_into().unwrap()
30    }
31
32    #[inline]
33    fn target_isize_min(&self) -> i64 {
34        self.pointer_size().signed_int_min().try_into().unwrap()
35    }
36
37    #[inline]
38    fn target_isize_max(&self) -> i64 {
39        self.pointer_size().signed_int_max().try_into().unwrap()
40    }
41
42    #[inline]
43    fn truncate_to_target_usize(&self, val: u64) -> u64 {
44        self.pointer_size().truncate(val.into()).try_into().unwrap()
45    }
46
47    #[inline]
48    fn sign_extend_to_target_isize(&self, val: u64) -> i64 {
49        self.pointer_size().sign_extend(val.into()).try_into().unwrap()
50    }
51}
52
53impl<T: HasDataLayout> PointerArithmetic for T {}
54
55/// This trait abstracts over the kind of provenance that is associated with a `Pointer`. It is
56/// mostly opaque; the `Machine` trait extends it with some more operations that also have access to
57/// some global state.
58/// The `Debug` rendering is used to display bare provenance, and for the default impl of `fmt`.
59pub trait Provenance: Copy + PartialEq + fmt::Debug + 'static {
60    /// Says whether the `offset` field of `Pointer`s with this provenance is the actual physical address.
61    /// - If `false`, the offset *must* be relative. This means the bytes representing a pointer are
62    ///   different from what the Abstract Machine prescribes, so the interpreter must prevent any
63    ///   operation that would inspect the underlying bytes of a pointer, such as ptr-to-int
64    ///   transmutation. A `ReadPointerAsBytes` error will be raised in such situations.
65    /// - If `true`, the interpreter will permit operations to inspect the underlying bytes of a
66    ///   pointer, and implement ptr-to-int transmutation by stripping provenance.
67    const OFFSET_IS_ADDR: bool;
68
69    /// If wildcard provenance is implemented, contains the unique, general wildcard provenance variant.
70    const WILDCARD: Option<Self>;
71
72    /// Determines how a pointer should be printed.
73    fn fmt(ptr: &Pointer<Self>, f: &mut fmt::Formatter<'_>) -> fmt::Result;
74
75    /// If `OFFSET_IS_ADDR == false`, provenance must always be able to
76    /// identify the allocation this ptr points to (i.e., this must return `Some`).
77    /// Otherwise this function is best-effort (but must agree with `Machine::ptr_get_alloc`).
78    /// (Identifying the offset in that allocation, however, is harder -- use `Memory::ptr_get_alloc` for that.)
79    fn get_alloc_id(self) -> Option<AllocId>;
80
81    /// Defines the 'join' of provenance: what happens when doing a pointer load and different bytes have different provenance.
82    fn join(left: Self, right: Self) -> Option<Self>;
83}
84
85/// The type of provenance in the compile-time interpreter.
86/// This is a packed representation of:
87/// - an `AllocId` (non-zero)
88/// - an `immutable: bool`
89/// - a `shared_ref: bool`
90///
91/// with the extra invariant that if `immutable` is `true`, then so
92/// is `shared_ref`.
93#[derive(Copy, Clone, Eq, Hash, Ord, PartialEq, PartialOrd)]
94pub struct CtfeProvenance(NonZero<u64>);
95
96impl From<AllocId> for CtfeProvenance {
97    fn from(value: AllocId) -> Self {
98        let prov = CtfeProvenance(value.0);
99        assert!(
100            prov.alloc_id() == value,
101            "`AllocId` with the highest bits set cannot be used in CTFE"
102        );
103        prov
104    }
105}
106
107impl fmt::Debug for CtfeProvenance {
108    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
109        fmt::Debug::fmt(&self.alloc_id(), f)?; // propagates `alternate` flag
110        if self.immutable() {
111            write!(f, "<imm>")?;
112        }
113        Ok(())
114    }
115}
116
117const IMMUTABLE_MASK: u64 = 1 << 63; // the highest bit
118const SHARED_REF_MASK: u64 = 1 << 62;
119const ALLOC_ID_MASK: u64 = u64::MAX & !IMMUTABLE_MASK & !SHARED_REF_MASK;
120
121impl CtfeProvenance {
122    /// Returns the `AllocId` of this provenance.
123    #[inline(always)]
124    pub fn alloc_id(self) -> AllocId {
125        AllocId(NonZero::new(self.0.get() & ALLOC_ID_MASK).unwrap())
126    }
127
128    /// Returns whether this provenance is immutable.
129    #[inline]
130    pub fn immutable(self) -> bool {
131        self.0.get() & IMMUTABLE_MASK != 0
132    }
133
134    /// Returns whether this provenance is derived from a shared reference.
135    #[inline]
136    pub fn shared_ref(self) -> bool {
137        self.0.get() & SHARED_REF_MASK != 0
138    }
139
140    pub fn into_parts(self) -> (AllocId, bool, bool) {
141        (self.alloc_id(), self.immutable(), self.shared_ref())
142    }
143
144    pub fn from_parts((alloc_id, immutable, shared_ref): (AllocId, bool, bool)) -> Self {
145        let prov = CtfeProvenance::from(alloc_id);
146        if immutable {
147            // This sets both flags, so we don't even have to check `shared_ref`.
148            prov.as_immutable()
149        } else if shared_ref {
150            prov.as_shared_ref()
151        } else {
152            prov
153        }
154    }
155
156    /// Returns an immutable version of this provenance.
157    #[inline]
158    pub fn as_immutable(self) -> Self {
159        CtfeProvenance(self.0 | IMMUTABLE_MASK | SHARED_REF_MASK)
160    }
161
162    /// Returns a "shared reference" (but not necessarily immutable!) version of this provenance.
163    #[inline]
164    pub fn as_shared_ref(self) -> Self {
165        CtfeProvenance(self.0 | SHARED_REF_MASK)
166    }
167}
168
169impl Provenance for CtfeProvenance {
170    // With the `AllocId` as provenance, the `offset` is interpreted *relative to the allocation*,
171    // so ptr-to-int casts are not possible (since we do not know the global physical offset).
172    const OFFSET_IS_ADDR: bool = false;
173
174    // `CtfeProvenance` does not implement wildcard provenance.
175    const WILDCARD: Option<Self> = None;
176
177    fn fmt(ptr: &Pointer<Self>, f: &mut fmt::Formatter<'_>) -> fmt::Result {
178        // Print AllocId.
179        fmt::Debug::fmt(&ptr.provenance.alloc_id(), f)?; // propagates `alternate` flag
180        // Print offset only if it is non-zero.
181        if ptr.offset.bytes() > 0 {
182            write!(f, "+{:#x}", ptr.offset.bytes())?;
183        }
184        // Print immutable status.
185        if ptr.provenance.immutable() {
186            write!(f, "<imm>")?;
187        }
188        Ok(())
189    }
190
191    fn get_alloc_id(self) -> Option<AllocId> {
192        Some(self.alloc_id())
193    }
194
195    fn join(left: Self, right: Self) -> Option<Self> {
196        if left == right { Some(left) } else { None }
197    }
198}
199
200// We also need this impl so that one can debug-print `Pointer<AllocId>`
201impl Provenance for AllocId {
202    // With the `AllocId` as provenance, the `offset` is interpreted *relative to the allocation*,
203    // so ptr-to-int casts are not possible (since we do not know the global physical offset).
204    const OFFSET_IS_ADDR: bool = false;
205
206    // `AllocId` does not implement wildcard provenance.
207    const WILDCARD: Option<Self> = None;
208
209    fn fmt(ptr: &Pointer<Self>, f: &mut fmt::Formatter<'_>) -> fmt::Result {
210        // Forward `alternate` flag to `alloc_id` printing.
211        if f.alternate() {
212            write!(f, "{:#?}", ptr.provenance)?;
213        } else {
214            write!(f, "{:?}", ptr.provenance)?;
215        }
216        // Print offset only if it is non-zero.
217        if ptr.offset.bytes() > 0 {
218            write!(f, "+{:#x}", ptr.offset.bytes())?;
219        }
220        Ok(())
221    }
222
223    fn get_alloc_id(self) -> Option<AllocId> {
224        Some(self)
225    }
226
227    fn join(_left: Self, _right: Self) -> Option<Self> {
228        unreachable!()
229    }
230}
231
232/// Represents a pointer in the Miri engine.
233///
234/// Pointers are "tagged" with provenance information; typically the `AllocId` they belong to.
235#[derive(Copy, Clone, Eq, PartialEq, TyEncodable, TyDecodable, Hash)]
236#[derive(HashStable)]
237pub struct Pointer<Prov = CtfeProvenance> {
238    pub(super) offset: Size, // kept private to avoid accidental misinterpretation (meaning depends on `Prov` type)
239    pub provenance: Prov,
240}
241
242static_assert_size!(Pointer, 16);
243// `Option<Prov>` pointers are also passed around quite a bit
244// (but not stored in permanent machine state).
245static_assert_size!(Pointer<Option<CtfeProvenance>>, 16);
246
247// We want the `Debug` output to be readable as it is used by `derive(Debug)` for
248// all the Miri types.
249impl<Prov: Provenance> fmt::Debug for Pointer<Prov> {
250    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
251        Provenance::fmt(self, f)
252    }
253}
254
255impl<Prov: Provenance> fmt::Debug for Pointer<Option<Prov>> {
256    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
257        match self.provenance {
258            Some(prov) => Provenance::fmt(&Pointer::new(prov, self.offset), f),
259            None => write!(f, "{:#x}[noalloc]", self.offset.bytes()),
260        }
261    }
262}
263
264impl<Prov: Provenance> fmt::Display for Pointer<Option<Prov>> {
265    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
266        if self.provenance.is_none() && self.offset.bytes() == 0 {
267            write!(f, "null pointer")
268        } else {
269            fmt::Debug::fmt(self, f)
270        }
271    }
272}
273
274/// Produces a `Pointer` that points to the beginning of the `Allocation`.
275impl From<AllocId> for Pointer {
276    #[inline(always)]
277    fn from(alloc_id: AllocId) -> Self {
278        Pointer::new(alloc_id.into(), Size::ZERO)
279    }
280}
281impl From<CtfeProvenance> for Pointer {
282    #[inline(always)]
283    fn from(prov: CtfeProvenance) -> Self {
284        Pointer::new(prov, Size::ZERO)
285    }
286}
287
288impl<Prov> From<Pointer<Prov>> for Pointer<Option<Prov>> {
289    #[inline(always)]
290    fn from(ptr: Pointer<Prov>) -> Self {
291        let (prov, offset) = ptr.into_raw_parts();
292        Pointer::new(Some(prov), offset)
293    }
294}
295
296impl<Prov> Pointer<Option<Prov>> {
297    /// Convert this pointer that *might* have a provenance into a pointer that *definitely* has a
298    /// provenance, or an absolute address.
299    ///
300    /// This is rarely what you want; call `ptr_try_get_alloc_id` instead.
301    pub fn into_pointer_or_addr(self) -> Result<Pointer<Prov>, Size> {
302        match self.provenance {
303            Some(prov) => Ok(Pointer::new(prov, self.offset)),
304            None => Err(self.offset),
305        }
306    }
307
308    /// Returns the absolute address the pointer points to.
309    /// Only works if Prov::OFFSET_IS_ADDR is true!
310    pub fn addr(self) -> Size
311    where
312        Prov: Provenance,
313    {
314        assert!(Prov::OFFSET_IS_ADDR);
315        self.offset
316    }
317
318    /// Creates a pointer to the given address, with invalid provenance (i.e., cannot be used for
319    /// any memory access).
320    #[inline(always)]
321    pub fn without_provenance(addr: u64) -> Self {
322        Pointer { provenance: None, offset: Size::from_bytes(addr) }
323    }
324
325    #[inline(always)]
326    pub fn null() -> Self {
327        Pointer::without_provenance(0)
328    }
329}
330
331impl<Prov> Pointer<Prov> {
332    #[inline(always)]
333    pub fn new(provenance: Prov, offset: Size) -> Self {
334        Pointer { provenance, offset }
335    }
336
337    /// Obtain the constituents of this pointer. Note that the meaning of the offset depends on the
338    /// type `Prov`! This is a low-level function that should only be used when absolutely
339    /// necessary. Prefer `prov_and_relative_offset` if possible.
340    #[inline(always)]
341    pub fn into_raw_parts(self) -> (Prov, Size) {
342        (self.provenance, self.offset)
343    }
344
345    pub fn map_provenance(self, f: impl FnOnce(Prov) -> Prov) -> Self {
346        Pointer { provenance: f(self.provenance), ..self }
347    }
348
349    #[inline(always)]
350    pub fn wrapping_offset(self, i: Size, cx: &impl HasDataLayout) -> Self {
351        let res =
352            cx.data_layout().truncate_to_target_usize(self.offset.bytes().wrapping_add(i.bytes()));
353        Pointer { offset: Size::from_bytes(res), ..self }
354    }
355
356    #[inline(always)]
357    pub fn wrapping_signed_offset(self, i: i64, cx: &impl HasDataLayout) -> Self {
358        // It's wrapping anyway, so we can just cast to `u64`.
359        self.wrapping_offset(Size::from_bytes(i as u64), cx)
360    }
361}
362
363impl Pointer<CtfeProvenance> {
364    /// Return the provenance and relative offset stored in this pointer. Safer alternative to
365    /// `into_raw_parts` since the type ensures that the offset is indeed relative.
366    #[inline(always)]
367    pub fn prov_and_relative_offset(self) -> (CtfeProvenance, Size) {
368        (self.provenance, self.offset)
369    }
370}
rustc_middle/mir/interpret/pointer.rs

rustc_middle/mir/interpret/
pointer.rs
