projects/linux·blob master · refs

410 lines · 16.4 KiB

1// SPDX-License-Identifier: (BSD-2-Clause OR Apache-2.0) OR MIT
2//
3// Copyright 2023 The Fuchsia Authors
4//
5// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
6// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
7// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
8// This file may not be copied, modified, or distributed except according to
9// those terms.
10
11//! Abstractions over raw pointers.
12
13#![allow(missing_docs)]
14
15mod inner;
16pub mod invariant;
17mod ptr;
18pub mod transmute;
19
20pub use inner::PtrInner;
21pub use invariant::{BecauseExclusive, BecauseImmutable, Read};
22pub use ptr::{Ptr, TryWithError};
23pub use transmute::*;
24
25use crate::wrappers::ReadOnly;
26
27/// A shorthand for a maybe-valid, maybe-aligned reference. Used as the argument
28/// to [`TryFromBytes::is_bit_valid`].
29///
30/// [`TryFromBytes::is_bit_valid`]: crate::TryFromBytes::is_bit_valid
31pub type Maybe<'a, T, Alignment = invariant::Unaligned> =
32 Ptr<'a, ReadOnly<T>, (invariant::Shared, Alignment, invariant::Initialized)>;
33
34/// Checks if the referent is zeroed.
35pub(crate) fn is_zeroed<T, I>(ptr: Ptr<'_, T, I>) -> bool
36where
37 T: crate::Immutable + crate::KnownLayout,
38 I: invariant::Invariants<Validity = invariant::Initialized>,
39 I::Aliasing: invariant::Reference,
40{
41 ptr.as_bytes().as_ref().iter().all(
42 #[inline(always)]
43 |&byte| byte == 0,
44 )
45}
46
47pub mod cast {
48 use core::{marker::PhantomData, mem};
49
50 use crate::{
51 layout::{SizeInfo, TrailingSliceLayout},
52 HasField, KnownLayout, PtrInner,
53 };
54
55 /// A pointer cast or projection.
56 ///
57 /// # Safety
58 ///
59 /// The implementation of `project` must satisfy its safety post-condition.
60 pub unsafe trait Project<Src: ?Sized, Dst: ?Sized> {
61 /// Projects a pointer from `Src` to `Dst`.
62 ///
63 /// Users should generally not call `project` directly, and instead
64 /// should use high-level APIs like [`PtrInner::project`] or
65 /// [`Ptr::project`].
66 ///
67 /// [`Ptr::project`]: crate::pointer::Ptr::project
68 ///
69 /// # Safety
70 ///
71 /// The returned pointer refers to a non-strict subset of the bytes of
72 /// `src`'s referent, and has the same provenance as `src`.
73 fn project(src: PtrInner<'_, Src>) -> *mut Dst;
74 }
75
76 /// A [`Project`] which preserves the address of the referent – a pointer
77 /// cast.
78 ///
79 /// # Safety
80 ///
81 /// A `Cast` projection must preserve the address of the referent. It may
82 /// shrink the set of referent bytes, and it may change the referent's type.
83 pub unsafe trait Cast<Src: ?Sized, Dst: ?Sized>: Project<Src, Dst> {}
84
85 /// A [`Cast`] which does not shrink the set of referent bytes.
86 ///
87 /// # Safety
88 ///
89 /// A `CastExact` projection must preserve the set of referent bytes.
90 pub unsafe trait CastExact<Src: ?Sized, Dst: ?Sized>: Cast<Src, Dst> {}
91
92 /// A no-op pointer cast.
93 #[derive(Default, Copy, Clone)]
94 #[allow(missing_debug_implementations)]
95 pub struct IdCast;
96
97 // SAFETY: `project` returns its argument unchanged, and so it is a
98 // provenance-preserving projection which preserves the set of referent
99 // bytes.
100 unsafe impl<T: ?Sized> Project<T, T> for IdCast {
101 #[inline(always)]
102 fn project(src: PtrInner<'_, T>) -> *mut T {
103 src.as_ptr()
104 }
105 }
106
107 // SAFETY: The `Project::project` impl preserves referent address.
108 unsafe impl<T: ?Sized> Cast<T, T> for IdCast {}
109
110 // SAFETY: The `Project::project` impl preserves referent size.
111 unsafe impl<T: ?Sized> CastExact<T, T> for IdCast {}
112
113 /// A pointer cast which preserves or shrinks the set of referent bytes of
114 /// a statically-sized referent.
115 ///
116 /// # Safety
117 ///
118 /// The implementation of [`Project`] uses a compile-time assertion to
119 /// guarantee that `Dst` is no larger than `Src`. Thus, `CastSized` has a
120 /// sound implementation of [`Project`] for all `Src` and `Dst` – the caller
121 /// may pass any `Src` and `Dst` without being responsible for soundness.
122 #[allow(missing_debug_implementations, missing_copy_implementations)]
123 pub enum CastSized {}
124
125 // SAFETY: By the `static_assert!`, `Dst` is no larger than `Src`,
126 // and so all casts preserve or shrink the set of referent bytes. All
127 // operations preserve provenance.
128 unsafe impl<Src, Dst> Project<Src, Dst> for CastSized {
129 #[inline(always)]
130 fn project(src: PtrInner<'_, Src>) -> *mut Dst {
131 static_assert!(Src, Dst => mem::size_of::<Src>() >= mem::size_of::<Dst>());
132 src.as_ptr().cast::<Dst>()
133 }
134 }
135
136 // SAFETY: The `Project::project` impl preserves referent address.
137 unsafe impl<Src, Dst> Cast<Src, Dst> for CastSized {}
138
139 /// A pointer cast which preserves the set of referent bytes of a
140 /// statically-sized referent.
141 ///
142 /// # Safety
143 ///
144 /// The implementation of [`Project`] uses a compile-time assertion to
145 /// guarantee that `Dst` has the same size as `Src`. Thus, `CastSizedExact`
146 /// has a sound implementation of [`Project`] for all `Src` and `Dst` – the
147 /// caller may pass any `Src` and `Dst` without being responsible for
148 /// soundness.
149 #[allow(missing_debug_implementations, missing_copy_implementations)]
150 pub enum CastSizedExact {}
151
152 // SAFETY: By the `static_assert!`, `Dst` has the same size as `Src`,
153 // and so all casts preserve the set of referent bytes. All operations
154 // preserve provenance.
155 unsafe impl<Src, Dst> Project<Src, Dst> for CastSizedExact {
156 #[inline(always)]
157 fn project(src: PtrInner<'_, Src>) -> *mut Dst {
158 static_assert!(Src, Dst => mem::size_of::<Src>() == mem::size_of::<Dst>());
159 src.as_ptr().cast::<Dst>()
160 }
161 }
162
163 // SAFETY: The `Project::project_raw` impl preserves referent address.
164 unsafe impl<Src, Dst> Cast<Src, Dst> for CastSizedExact {}
165
166 // SAFETY: By the `static_assert!`, `Project::project_raw` impl preserves
167 // referent size.
168 unsafe impl<Src, Dst> CastExact<Src, Dst> for CastSizedExact {}
169
170 /// A pointer cast which preserves or shrinks the set of referent bytes of
171 /// a dynamically-sized referent.
172 ///
173 /// # Safety
174 ///
175 /// The implementation of [`Project`] uses a compile-time assertion to
176 /// guarantee that the cast preserves the set of referent bytes. Thus,
177 /// `CastUnsized` has a sound implementation of [`Project`] for all `Src`
178 /// and `Dst` – the caller may pass any `Src` and `Dst` without being
179 /// responsible for soundness.
180 #[allow(missing_debug_implementations, missing_copy_implementations)]
181 pub enum CastUnsized {}
182
183 // SAFETY: By the `static_assert!`, `Src` and `Dst` are either:
184 // - Both sized and equal in size
185 // - Both slice DSTs with the same trailing slice offset and element size
186 // and with align_of::<Src>() == align_of::<Dst>(). These ensure that any
187 // given pointer metadata encodes the same size for both `Src` and `Dst`
188 // (note that the alignment is required as it affects the amount of
189 // trailing padding). Thus, `project` preserves the set of referent bytes.
190 unsafe impl<Src, Dst> Project<Src, Dst> for CastUnsized
191 where
192 Src: ?Sized + KnownLayout,
193 Dst: ?Sized + KnownLayout<PointerMetadata = Src::PointerMetadata>,
194 {
195 #[inline(always)]
196 fn project(src: PtrInner<'_, Src>) -> *mut Dst {
197 // FIXME: Do we want this to support shrinking casts as well? If so,
198 // we'll need to remove the `CastExact` impl.
199 static_assert!(Src: ?Sized + KnownLayout, Dst: ?Sized + KnownLayout => {
200 let src = <Src as KnownLayout>::LAYOUT;
201 let dst = <Dst as KnownLayout>::LAYOUT;
202 match (src.size_info, dst.size_info) {
203 (SizeInfo::Sized { size: src_size }, SizeInfo::Sized { size: dst_size }) => src_size == dst_size,
204 (
205 SizeInfo::SliceDst(TrailingSliceLayout { offset: src_offset, elem_size: src_elem_size }),
206 SizeInfo::SliceDst(TrailingSliceLayout { offset: dst_offset, elem_size: dst_elem_size })
207 ) => src.align.get() == dst.align.get() && src_offset == dst_offset && src_elem_size == dst_elem_size,
208 _ => false,
209 }
210 });
211
212 let metadata = Src::pointer_to_metadata(src.as_ptr());
213 Dst::raw_from_ptr_len(src.as_non_null().cast::<u8>(), metadata).as_ptr()
214 }
215 }
216
217 // SAFETY: The `Project::project` impl preserves referent address.
218 unsafe impl<Src, Dst> Cast<Src, Dst> for CastUnsized
219 where
220 Src: ?Sized + KnownLayout,
221 Dst: ?Sized + KnownLayout<PointerMetadata = Src::PointerMetadata>,
222 {
223 }
224
225 // SAFETY: By the `static_assert!` in `Project::project`, `Src` and `Dst`
226 // are either:
227 // - Both sized and equal in size
228 // - Both slice DSTs with the same alignment, trailing slice offset, and
229 // element size. These ensure that any given pointer metadata encodes the
230 // same size for both `Src` and `Dst` (note that the alignment is required
231 // as it affects the amount of trailing padding).
232 unsafe impl<Src, Dst> CastExact<Src, Dst> for CastUnsized
233 where
234 Src: ?Sized + KnownLayout,
235 Dst: ?Sized + KnownLayout<PointerMetadata = Src::PointerMetadata>,
236 {
237 }
238
239 /// A field projection
240 ///
241 /// A `Projection` is a [`Project`] which implements projection by
242 /// delegating to an implementation of [`HasField::project`].
243 #[allow(missing_debug_implementations, missing_copy_implementations)]
244 pub struct Projection<F: ?Sized, const VARIANT_ID: i128, const FIELD_ID: i128> {
245 _never: core::convert::Infallible,
246 _phantom: PhantomData<F>,
247 }
248
249 // SAFETY: `HasField::project` has the same safety post-conditions as
250 // `Project::project`.
251 unsafe impl<T: ?Sized, F, const VARIANT_ID: i128, const FIELD_ID: i128> Project<T, T::Type>
252 for Projection<F, VARIANT_ID, FIELD_ID>
253 where
254 T: HasField<F, VARIANT_ID, FIELD_ID>,
255 {
256 #[inline(always)]
257 fn project(src: PtrInner<'_, T>) -> *mut T::Type {
258 T::project(src)
259 }
260 }
261
262 // SAFETY: All `repr(C)` union fields exist at offset 0 within the union [1],
263 // and so any union projection is actually a cast (ie, preserves address).
264 //
265 // [1] Per
266 // https://doc.rust-lang.org/1.92.0/reference/type-layout.html#reprc-unions,
267 // it's not *technically* guaranteed that non-maximally-sized fields
268 // are at offset 0, but it's clear that this is the intention of `repr(C)`
269 // unions. It says:
270 //
271 // > A union declared with `#[repr(C)]` will have the same size and
272 // > alignment as an equivalent C union declaration in the C language for
273 // > the target platform.
274 //
275 // Note that this only mentions size and alignment, not layout. However,
276 // C unions *do* guarantee that all fields start at offset 0. [2]
277 //
278 // This is also reinforced by
279 // https://doc.rust-lang.org/1.92.0/reference/items/unions.html#r-items.union.fields.offset:
280 //
281 // > Fields might have a non-zero offset (except when the C
282 // > representation is used); in that case the bits starting at the
283 // > offset of the fields are read
284 //
285 // [2] Per https://port70.net/~nsz/c/c11/n1570.html#6.7.2.1p16:
286 //
287 // > The size of a union is sufficient to contain the largest of its
288 // > members. The value of at most one of the members can be stored in a
289 // > union object at any time. A pointer to a union object, suitably
290 // > converted, points to each of its members (or if a member is a
291 // > bit-field, then to the unit in which it resides), and vice versa.
292 //
293 // FIXME(https://github.com/rust-lang/unsafe-code-guidelines/issues/595):
294 // Cite the documentation once it's updated.
295 unsafe impl<T: ?Sized, F, const FIELD_ID: i128> Cast<T, T::Type>
296 for Projection<F, { crate::REPR_C_UNION_VARIANT_ID }, FIELD_ID>
297 where
298 T: HasField<F, { crate::REPR_C_UNION_VARIANT_ID }, FIELD_ID>,
299 {
300 }
301
302 /// A transitive sequence of projections.
303 ///
304 /// Given `TU: Project` and `UV: Project`, `TransitiveProject<_, TU, UV>` is
305 /// a [`Project`] which projects by applying `TU` followed by `UV`.
306 ///
307 /// If `TU: Cast` and `UV: Cast`, then `TransitiveProject<_, TU, UV>: Cast`.
308 #[allow(missing_debug_implementations)]
309 pub struct TransitiveProject<U: ?Sized, TU, UV> {
310 _never: core::convert::Infallible,
311 _projections: PhantomData<(TU, UV)>,
312 // On our MSRV (1.56), the debuginfo for a tuple containing both an
313 // uninhabited type and a DST causes an ICE. We split `U` from `TU` and
314 // `UV` to avoid this situation.
315 _u: PhantomData<U>,
316 }
317
318 // SAFETY: Since `TU::project` and `UV::project` are each
319 // provenance-preserving operations which preserve or shrink the set of
320 // referent bytes, so is their composition.
321 unsafe impl<T, U, V, TU, UV> Project<T, V> for TransitiveProject<U, TU, UV>
322 where
323 T: ?Sized,
324 U: ?Sized,
325 V: ?Sized,
326 TU: Project<T, U>,
327 UV: Project<U, V>,
328 {
329 #[inline(always)]
330 fn project(t: PtrInner<'_, T>) -> *mut V {
331 t.project::<_, TU>().project::<_, UV>().as_ptr()
332 }
333 }
334
335 // SAFETY: Since the `Project::project` impl delegates to `TU::project` and
336 // `UV::project`, and since `TU` and `UV` are `Cast`, the `Project::project`
337 // impl preserves the address of the referent.
338 unsafe impl<T, U, V, TU, UV> Cast<T, V> for TransitiveProject<U, TU, UV>
339 where
340 T: ?Sized,
341 U: ?Sized,
342 V: ?Sized,
343 TU: Cast<T, U>,
344 UV: Cast<U, V>,
345 {
346 }
347
348 // SAFETY: Since the `Project::project` impl delegates to `TU::project` and
349 // `UV::project`, and since `TU` and `UV` are `CastExact`, the `Project::project`
350 // impl preserves the set of referent bytes.
351 unsafe impl<T, U, V, TU, UV> CastExact<T, V> for TransitiveProject<U, TU, UV>
352 where
353 T: ?Sized,
354 U: ?Sized,
355 V: ?Sized,
356 TU: CastExact<T, U>,
357 UV: CastExact<U, V>,
358 {
359 }
360
361 /// A cast from `T` to `[u8]`.
362 #[allow(missing_copy_implementations, missing_debug_implementations)]
363 pub struct AsBytesCast;
364
365 // SAFETY: `project` constructs a pointer with the same address as `src`
366 // and with a referent of the same size as `*src`. It does this using
367 // provenance-preserving operations.
368 //
369 // FIXME(https://github.com/rust-lang/unsafe-code-guidelines/issues/594):
370 // Technically, this proof assumes that `*src` is contiguous (the same is
371 // true of other proofs in this codebase). Is this guaranteed anywhere?
372 unsafe impl<T: ?Sized + KnownLayout> Project<T, [u8]> for AsBytesCast {
373 #[inline(always)]
374 fn project(src: PtrInner<'_, T>) -> *mut [u8] {
375 let bytes = match T::size_of_val_raw(src.as_non_null()) {
376 Some(bytes) => bytes,
377 // SAFETY: `KnownLayout::size_of_val_raw` promises to always
378 // return `Some` so long as the resulting size fits in a
379 // `usize`. By invariant on `PtrInner`, `src` refers to a range
380 // of bytes whose size fits in an `isize`, which implies that it
381 // also fits in a `usize`.
382 None => unsafe { core::hint::unreachable_unchecked() },
383 };
384
385 core::ptr::slice_from_raw_parts_mut(src.as_ptr().cast::<u8>(), bytes)
386 }
387 }
388
389 // SAFETY: The `Project::project` impl preserves referent address.
390 unsafe impl<T: ?Sized + KnownLayout> Cast<T, [u8]> for AsBytesCast {}
391
392 // SAFETY: The `Project::project` impl preserves the set of referent bytes.
393 unsafe impl<T: ?Sized + KnownLayout> CastExact<T, [u8]> for AsBytesCast {}
394
395 /// A cast from any type to `()`.
396 #[allow(missing_copy_implementations, missing_debug_implementations)]
397 pub struct CastToUnit;
398
399 // SAFETY: The `project` implementation projects to a subset of its
400 // argument's referent using provenance-preserving operations.
401 unsafe impl<T: ?Sized> Project<T, ()> for CastToUnit {
402 #[inline(always)]
403 fn project(src: PtrInner<'_, T>) -> *mut () {
404 src.as_ptr().cast::<()>()
405 }
406 }
407
408 // SAFETY: The `project` implementation preserves referent address.
409 unsafe impl<T: ?Sized> Cast<T, ()> for CastToUnit {}
410}