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