| 1 |
// SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
//! Implementation of [`Box`]. |
| 4 |
|
| 5 |
#[allow(unused_imports)] // Used in doc comments. |
| 6 |
use super::allocator::{KVmalloc, Kmalloc, Vmalloc, VmallocPageIter}; |
| 7 |
use super::{AllocError, Allocator, Flags, NumaNode}; |
| 8 |
use core::alloc::Layout; |
| 9 |
use core::borrow::{Borrow, BorrowMut}; |
| 10 |
use core::marker::PhantomData; |
| 11 |
use core::mem::ManuallyDrop; |
| 12 |
use core::mem::MaybeUninit; |
| 13 |
use core::ops::{Deref, DerefMut}; |
| 14 |
use core::pin::Pin; |
| 15 |
use core::ptr::NonNull; |
| 16 |
use core::result::Result; |
| 17 |
|
| 18 |
use crate::ffi::c_void; |
| 19 |
use crate::fmt; |
| 20 |
use crate::init::InPlaceInit; |
| 21 |
use crate::page::AsPageIter; |
| 22 |
use crate::types::ForeignOwnable; |
| 23 |
use pin_init::{InPlaceWrite, Init, PinInit, ZeroableOption}; |
| 24 |
|
| 25 |
/// The kernel's [`Box`] type -- a heap allocation for a single value of type `T`. |
| 26 |
/// |
| 27 |
/// This is the kernel's version of the Rust stdlib's `Box`. There are several differences, |
| 28 |
/// for example no `noalias` attribute is emitted and partially moving out of a `Box` is not |
| 29 |
/// supported. There are also several API differences, e.g. `Box` always requires an [`Allocator`] |
| 30 |
/// implementation to be passed as generic, page [`Flags`] when allocating memory and all functions |
| 31 |
/// that may allocate memory are fallible. |
| 32 |
/// |
| 33 |
/// `Box` works with any of the kernel's allocators, e.g. [`Kmalloc`], [`Vmalloc`] or [`KVmalloc`]. |
| 34 |
/// There are aliases for `Box` with these allocators ([`KBox`], [`VBox`], [`KVBox`]). |
| 35 |
/// |
| 36 |
/// When dropping a [`Box`], the value is also dropped and the heap memory is automatically freed. |
| 37 |
/// |
| 38 |
/// # Examples |
| 39 |
/// |
| 40 |
/// ``` |
| 41 |
/// let b = KBox::<u64>::new(24_u64, GFP_KERNEL)?; |
| 42 |
/// |
| 43 |
/// assert_eq!(*b, 24_u64); |
| 44 |
/// # Ok::<(), Error>(()) |
| 45 |
/// ``` |
| 46 |
/// |
| 47 |
/// ``` |
| 48 |
/// # use kernel::bindings; |
| 49 |
/// const SIZE: usize = bindings::KMALLOC_MAX_SIZE as usize + 1; |
| 50 |
/// struct Huge([u8; SIZE]); |
| 51 |
/// |
| 52 |
/// assert!(KBox::<Huge>::new_uninit(GFP_KERNEL | __GFP_NOWARN).is_err()); |
| 53 |
/// ``` |
| 54 |
/// |
| 55 |
/// ``` |
| 56 |
/// # use kernel::bindings; |
| 57 |
/// const SIZE: usize = bindings::KMALLOC_MAX_SIZE as usize + 1; |
| 58 |
/// struct Huge([u8; SIZE]); |
| 59 |
/// |
| 60 |
/// assert!(KVBox::<Huge>::new_uninit(GFP_KERNEL).is_ok()); |
| 61 |
/// ``` |
| 62 |
/// |
| 63 |
/// [`Box`]es can also be used to store trait objects by coercing their type: |
| 64 |
/// |
| 65 |
/// ``` |
| 66 |
/// trait FooTrait {} |
| 67 |
/// |
| 68 |
/// struct FooStruct; |
| 69 |
/// impl FooTrait for FooStruct {} |
| 70 |
/// |
| 71 |
/// let _ = KBox::new(FooStruct, GFP_KERNEL)? as KBox<dyn FooTrait>; |
| 72 |
/// # Ok::<(), Error>(()) |
| 73 |
/// ``` |
| 74 |
/// |
| 75 |
/// # Invariants |
| 76 |
/// |
| 77 |
/// `self.0` is always properly aligned and either points to memory allocated with `A` or, for |
| 78 |
/// zero-sized types, is a dangling, well aligned pointer. |
| 79 |
#[repr(transparent)] |
| 80 |
#[cfg_attr(CONFIG_RUSTC_HAS_COERCE_POINTEE, derive(core::marker::CoercePointee))] |
| 81 |
pub struct Box<#[cfg_attr(CONFIG_RUSTC_HAS_COERCE_POINTEE, pointee)] T: ?Sized, A: Allocator>( |
| 82 |
NonNull<T>, |
| 83 |
PhantomData<A>, |
| 84 |
); |
| 85 |
|
| 86 |
// This is to allow coercion from `Box<T, A>` to `Box<U, A>` if `T` can be converted to the |
| 87 |
// dynamically-sized type (DST) `U`. |
| 88 |
#[cfg(not(CONFIG_RUSTC_HAS_COERCE_POINTEE))] |
| 89 |
impl<T, U, A> core::ops::CoerceUnsized<Box<U, A>> for Box<T, A> |
| 90 |
where |
| 91 |
T: ?Sized + core::marker::Unsize<U>, |
| 92 |
U: ?Sized, |
| 93 |
A: Allocator, |
| 94 |
{ |
| 95 |
} |
| 96 |
|
| 97 |
// This is to allow `Box<U, A>` to be dispatched on when `Box<T, A>` can be coerced into `Box<U, |
| 98 |
// A>`. |
| 99 |
#[cfg(not(CONFIG_RUSTC_HAS_COERCE_POINTEE))] |
| 100 |
impl<T, U, A> core::ops::DispatchFromDyn<Box<U, A>> for Box<T, A> |
| 101 |
where |
| 102 |
T: ?Sized + core::marker::Unsize<U>, |
| 103 |
U: ?Sized, |
| 104 |
A: Allocator, |
| 105 |
{ |
| 106 |
} |
| 107 |
|
| 108 |
/// Type alias for [`Box`] with a [`Kmalloc`] allocator. |
| 109 |
/// |
| 110 |
/// # Examples |
| 111 |
/// |
| 112 |
/// ``` |
| 113 |
/// let b = KBox::new(24_u64, GFP_KERNEL)?; |
| 114 |
/// |
| 115 |
/// assert_eq!(*b, 24_u64); |
| 116 |
/// # Ok::<(), Error>(()) |
| 117 |
/// ``` |
| 118 |
pub type KBox<T> = Box<T, super::allocator::Kmalloc>; |
| 119 |
|
| 120 |
/// Type alias for [`Box`] with a [`Vmalloc`] allocator. |
| 121 |
/// |
| 122 |
/// # Examples |
| 123 |
/// |
| 124 |
/// ``` |
| 125 |
/// let b = VBox::new(24_u64, GFP_KERNEL)?; |
| 126 |
/// |
| 127 |
/// assert_eq!(*b, 24_u64); |
| 128 |
/// # Ok::<(), Error>(()) |
| 129 |
/// ``` |
| 130 |
pub type VBox<T> = Box<T, super::allocator::Vmalloc>; |
| 131 |
|
| 132 |
/// Type alias for [`Box`] with a [`KVmalloc`] allocator. |
| 133 |
/// |
| 134 |
/// # Examples |
| 135 |
/// |
| 136 |
/// ``` |
| 137 |
/// let b = KVBox::new(24_u64, GFP_KERNEL)?; |
| 138 |
/// |
| 139 |
/// assert_eq!(*b, 24_u64); |
| 140 |
/// # Ok::<(), Error>(()) |
| 141 |
/// ``` |
| 142 |
pub type KVBox<T> = Box<T, super::allocator::KVmalloc>; |
| 143 |
|
| 144 |
// SAFETY: All zeros is equivalent to `None` (option layout optimization guarantee: |
| 145 |
// <https://doc.rust-lang.org/stable/std/option/index.html#representation>). |
| 146 |
unsafe impl<T, A: Allocator> ZeroableOption for Box<T, A> {} |
| 147 |
|
| 148 |
// SAFETY: `Box` is `Send` if `T` is `Send` because the `Box` owns a `T`. |
| 149 |
unsafe impl<T, A> Send for Box<T, A> |
| 150 |
where |
| 151 |
T: Send + ?Sized, |
| 152 |
A: Allocator, |
| 153 |
{ |
| 154 |
} |
| 155 |
|
| 156 |
// SAFETY: `Box` is `Sync` if `T` is `Sync` because the `Box` owns a `T`. |
| 157 |
unsafe impl<T, A> Sync for Box<T, A> |
| 158 |
where |
| 159 |
T: Sync + ?Sized, |
| 160 |
A: Allocator, |
| 161 |
{ |
| 162 |
} |
| 163 |
|
| 164 |
impl<T, A> Box<T, A> |
| 165 |
where |
| 166 |
T: ?Sized, |
| 167 |
A: Allocator, |
| 168 |
{ |
| 169 |
/// Creates a new `Box<T, A>` from a raw pointer. |
| 170 |
/// |
| 171 |
/// # Safety |
| 172 |
/// |
| 173 |
/// For non-ZSTs, `raw` must point at an allocation allocated with `A` that is sufficiently |
| 174 |
/// aligned for and holds a valid `T`. The caller passes ownership of the allocation to the |
| 175 |
/// `Box`. |
| 176 |
/// |
| 177 |
/// For ZSTs, `raw` must be a dangling, well aligned pointer. |
| 178 |
#[inline] |
| 179 |
pub const unsafe fn from_raw(raw: *mut T) -> Self { |
| 180 |
// INVARIANT: Validity of `raw` is guaranteed by the safety preconditions of this function. |
| 181 |
// SAFETY: By the safety preconditions of this function, `raw` is not a NULL pointer. |
| 182 |
Self(unsafe { NonNull::new_unchecked(raw) }, PhantomData) |
| 183 |
} |
| 184 |
|
| 185 |
/// Consumes the `Box<T, A>` and returns a raw pointer. |
| 186 |
/// |
| 187 |
/// This will not run the destructor of `T` and for non-ZSTs the allocation will stay alive |
| 188 |
/// indefinitely. Use [`Box::from_raw`] to recover the [`Box`], drop the value and free the |
| 189 |
/// allocation, if any. |
| 190 |
/// |
| 191 |
/// # Examples |
| 192 |
/// |
| 193 |
/// ``` |
| 194 |
/// let x = KBox::new(24, GFP_KERNEL)?; |
| 195 |
/// let ptr = KBox::into_raw(x); |
| 196 |
/// // SAFETY: `ptr` comes from a previous call to `KBox::into_raw`. |
| 197 |
/// let x = unsafe { KBox::from_raw(ptr) }; |
| 198 |
/// |
| 199 |
/// assert_eq!(*x, 24); |
| 200 |
/// # Ok::<(), Error>(()) |
| 201 |
/// ``` |
| 202 |
#[inline] |
| 203 |
pub fn into_raw(b: Self) -> *mut T { |
| 204 |
ManuallyDrop::new(b).0.as_ptr() |
| 205 |
} |
| 206 |
|
| 207 |
/// Consumes and leaks the `Box<T, A>` and returns a mutable reference. |
| 208 |
/// |
| 209 |
/// See [`Box::into_raw`] for more details. |
| 210 |
#[inline] |
| 211 |
pub fn leak<'a>(b: Self) -> &'a mut T { |
| 212 |
// SAFETY: `Box::into_raw` always returns a properly aligned and dereferenceable pointer |
| 213 |
// which points to an initialized instance of `T`. |
| 214 |
unsafe { &mut *Box::into_raw(b) } |
| 215 |
} |
| 216 |
} |
| 217 |
|
| 218 |
impl<T, A> Box<MaybeUninit<T>, A> |
| 219 |
where |
| 220 |
A: Allocator, |
| 221 |
{ |
| 222 |
/// Converts a `Box<MaybeUninit<T>, A>` to a `Box<T, A>`. |
| 223 |
/// |
| 224 |
/// It is undefined behavior to call this function while the value inside of `b` is not yet |
| 225 |
/// fully initialized. |
| 226 |
/// |
| 227 |
/// # Safety |
| 228 |
/// |
| 229 |
/// Callers must ensure that the value inside of `b` is in an initialized state. |
| 230 |
pub unsafe fn assume_init(self) -> Box<T, A> { |
| 231 |
let raw = Self::into_raw(self); |
| 232 |
|
| 233 |
// SAFETY: `raw` comes from a previous call to `Box::into_raw`. By the safety requirements |
| 234 |
// of this function, the value inside the `Box` is in an initialized state. Hence, it is |
| 235 |
// safe to reconstruct the `Box` as `Box<T, A>`. |
| 236 |
unsafe { Box::from_raw(raw.cast()) } |
| 237 |
} |
| 238 |
|
| 239 |
/// Writes the value and converts to `Box<T, A>`. |
| 240 |
pub fn write(mut self, value: T) -> Box<T, A> { |
| 241 |
(*self).write(value); |
| 242 |
|
| 243 |
// SAFETY: We've just initialized `b`'s value. |
| 244 |
unsafe { self.assume_init() } |
| 245 |
} |
| 246 |
} |
| 247 |
|
| 248 |
impl<T, A> Box<T, A> |
| 249 |
where |
| 250 |
A: Allocator, |
| 251 |
{ |
| 252 |
/// Creates a new `Box<T, A>` and initializes its contents with `x`. |
| 253 |
/// |
| 254 |
/// New memory is allocated with `A`. The allocation may fail, in which case an error is |
| 255 |
/// returned. For ZSTs no memory is allocated. |
| 256 |
pub fn new(x: T, flags: Flags) -> Result<Self, AllocError> { |
| 257 |
let b = Self::new_uninit(flags)?; |
| 258 |
Ok(Box::write(b, x)) |
| 259 |
} |
| 260 |
|
| 261 |
/// Creates a new `Box<T, A>` with uninitialized contents. |
| 262 |
/// |
| 263 |
/// New memory is allocated with `A`. The allocation may fail, in which case an error is |
| 264 |
/// returned. For ZSTs no memory is allocated. |
| 265 |
/// |
| 266 |
/// # Examples |
| 267 |
/// |
| 268 |
/// ``` |
| 269 |
/// let b = KBox::<u64>::new_uninit(GFP_KERNEL)?; |
| 270 |
/// let b = KBox::write(b, 24); |
| 271 |
/// |
| 272 |
/// assert_eq!(*b, 24_u64); |
| 273 |
/// # Ok::<(), Error>(()) |
| 274 |
/// ``` |
| 275 |
pub fn new_uninit(flags: Flags) -> Result<Box<MaybeUninit<T>, A>, AllocError> { |
| 276 |
let layout = Layout::new::<MaybeUninit<T>>(); |
| 277 |
let ptr = A::alloc(layout, flags, NumaNode::NO_NODE)?; |
| 278 |
|
| 279 |
// INVARIANT: `ptr` is either a dangling pointer or points to memory allocated with `A`, |
| 280 |
// which is sufficient in size and alignment for storing a `T`. |
| 281 |
Ok(Box(ptr.cast(), PhantomData)) |
| 282 |
} |
| 283 |
|
| 284 |
/// Constructs a new `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then `x` will be |
| 285 |
/// pinned in memory and can't be moved. |
| 286 |
#[inline] |
| 287 |
pub fn pin(x: T, flags: Flags) -> Result<Pin<Box<T, A>>, AllocError> |
| 288 |
where |
| 289 |
A: 'static, |
| 290 |
{ |
| 291 |
Ok(Self::new(x, flags)?.into()) |
| 292 |
} |
| 293 |
|
| 294 |
/// Construct a pinned slice of elements `Pin<Box<[T], A>>`. |
| 295 |
/// |
| 296 |
/// This is a convenient means for creation of e.g. slices of structrures containing spinlocks |
| 297 |
/// or mutexes. |
| 298 |
/// |
| 299 |
/// # Examples |
| 300 |
/// |
| 301 |
/// ``` |
| 302 |
/// use kernel::sync::{new_spinlock, SpinLock}; |
| 303 |
/// |
| 304 |
/// struct Inner { |
| 305 |
/// a: u32, |
| 306 |
/// b: u32, |
| 307 |
/// } |
| 308 |
/// |
| 309 |
/// #[pin_data] |
| 310 |
/// struct Example { |
| 311 |
/// c: u32, |
| 312 |
/// #[pin] |
| 313 |
/// d: SpinLock<Inner>, |
| 314 |
/// } |
| 315 |
/// |
| 316 |
/// impl Example { |
| 317 |
/// fn new() -> impl PinInit<Self, Error> { |
| 318 |
/// try_pin_init!(Self { |
| 319 |
/// c: 10, |
| 320 |
/// d <- new_spinlock!(Inner { a: 20, b: 30 }), |
| 321 |
/// }) |
| 322 |
/// } |
| 323 |
/// } |
| 324 |
/// |
| 325 |
/// // Allocate a boxed slice of 10 `Example`s. |
| 326 |
/// let s = KBox::pin_slice( |
| 327 |
/// | _i | Example::new(), |
| 328 |
/// 10, |
| 329 |
/// GFP_KERNEL |
| 330 |
/// )?; |
| 331 |
/// |
| 332 |
/// assert_eq!(s[5].c, 10); |
| 333 |
/// assert_eq!(s[3].d.lock().a, 20); |
| 334 |
/// # Ok::<(), Error>(()) |
| 335 |
/// ``` |
| 336 |
pub fn pin_slice<Func, Item, E>( |
| 337 |
mut init: Func, |
| 338 |
len: usize, |
| 339 |
flags: Flags, |
| 340 |
) -> Result<Pin<Box<[T], A>>, E> |
| 341 |
where |
| 342 |
Func: FnMut(usize) -> Item, |
| 343 |
Item: PinInit<T, E>, |
| 344 |
E: From<AllocError>, |
| 345 |
{ |
| 346 |
let mut buffer = super::Vec::<T, A>::with_capacity(len, flags)?; |
| 347 |
for i in 0..len { |
| 348 |
let ptr = buffer.spare_capacity_mut().as_mut_ptr().cast(); |
| 349 |
// SAFETY: |
| 350 |
// - `ptr` is a valid pointer to uninitialized memory. |
| 351 |
// - `ptr` is not used if an error is returned. |
| 352 |
// - `ptr` won't be moved until it is dropped, i.e. it is pinned. |
| 353 |
unsafe { init(i).__pinned_init(ptr)? }; |
| 354 |
|
| 355 |
// SAFETY: |
| 356 |
// - `i + 1 <= len`, hence we don't exceed the capacity, due to the call to |
| 357 |
// `with_capacity()` above. |
| 358 |
// - The new value at index buffer.len() + 1 is the only element being added here, and |
| 359 |
// it has been initialized above by `init(i).__pinned_init(ptr)`. |
| 360 |
unsafe { buffer.inc_len(1) }; |
| 361 |
} |
| 362 |
|
| 363 |
let (ptr, _, _) = buffer.into_raw_parts(); |
| 364 |
let slice = core::ptr::slice_from_raw_parts_mut(ptr, len); |
| 365 |
|
| 366 |
// SAFETY: `slice` points to an allocation allocated with `A` (`buffer`) and holds a valid |
| 367 |
// `[T]`. |
| 368 |
Ok(Pin::from(unsafe { Box::from_raw(slice) })) |
| 369 |
} |
| 370 |
|
| 371 |
/// Convert a [`Box<T,A>`] to a [`Pin<Box<T,A>>`]. If `T` does not implement |
| 372 |
/// [`Unpin`], then `x` will be pinned in memory and can't be moved. |
| 373 |
pub fn into_pin(this: Self) -> Pin<Self> { |
| 374 |
this.into() |
| 375 |
} |
| 376 |
|
| 377 |
/// Forgets the contents (does not run the destructor), but keeps the allocation. |
| 378 |
fn forget_contents(this: Self) -> Box<MaybeUninit<T>, A> { |
| 379 |
let ptr = Self::into_raw(this); |
| 380 |
|
| 381 |
// SAFETY: `ptr` is valid, because it came from `Box::into_raw`. |
| 382 |
unsafe { Box::from_raw(ptr.cast()) } |
| 383 |
} |
| 384 |
|
| 385 |
/// Drops the contents, but keeps the allocation. |
| 386 |
/// |
| 387 |
/// # Examples |
| 388 |
/// |
| 389 |
/// ``` |
| 390 |
/// let value = KBox::new([0; 32], GFP_KERNEL)?; |
| 391 |
/// assert_eq!(*value, [0; 32]); |
| 392 |
/// let value = KBox::drop_contents(value); |
| 393 |
/// // Now we can re-use `value`: |
| 394 |
/// let value = KBox::write(value, [1; 32]); |
| 395 |
/// assert_eq!(*value, [1; 32]); |
| 396 |
/// # Ok::<(), Error>(()) |
| 397 |
/// ``` |
| 398 |
pub fn drop_contents(this: Self) -> Box<MaybeUninit<T>, A> { |
| 399 |
let ptr = this.0.as_ptr(); |
| 400 |
|
| 401 |
// SAFETY: `ptr` is valid, because it came from `this`. After this call we never access the |
| 402 |
// value stored in `this` again. |
| 403 |
unsafe { core::ptr::drop_in_place(ptr) }; |
| 404 |
|
| 405 |
Self::forget_contents(this) |
| 406 |
} |
| 407 |
|
| 408 |
/// Moves the `Box`'s value out of the `Box` and consumes the `Box`. |
| 409 |
pub fn into_inner(b: Self) -> T { |
| 410 |
// SAFETY: By the type invariant `&*b` is valid for `read`. |
| 411 |
let value = unsafe { core::ptr::read(&*b) }; |
| 412 |
let _ = Self::forget_contents(b); |
| 413 |
value |
| 414 |
} |
| 415 |
} |
| 416 |
|
| 417 |
impl<T, A> From<Box<T, A>> for Pin<Box<T, A>> |
| 418 |
where |
| 419 |
T: ?Sized, |
| 420 |
A: Allocator, |
| 421 |
{ |
| 422 |
/// Converts a `Box<T, A>` into a `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then |
| 423 |
/// `*b` will be pinned in memory and can't be moved. |
| 424 |
/// |
| 425 |
/// This moves `b` into `Pin` without moving `*b` or allocating and copying any memory. |
| 426 |
fn from(b: Box<T, A>) -> Self { |
| 427 |
// SAFETY: The value wrapped inside a `Pin<Box<T, A>>` cannot be moved or replaced as long |
| 428 |
// as `T` does not implement `Unpin`. |
| 429 |
unsafe { Pin::new_unchecked(b) } |
| 430 |
} |
| 431 |
} |
| 432 |
|
| 433 |
impl<T, A> InPlaceWrite<T> for Box<MaybeUninit<T>, A> |
| 434 |
where |
| 435 |
A: Allocator + 'static, |
| 436 |
{ |
| 437 |
type Initialized = Box<T, A>; |
| 438 |
|
| 439 |
fn write_init<E>(mut self, init: impl Init<T, E>) -> Result<Self::Initialized, E> { |
| 440 |
let slot = self.as_mut_ptr(); |
| 441 |
// SAFETY: When init errors/panics, slot will get deallocated but not dropped, |
| 442 |
// slot is valid. |
| 443 |
unsafe { init.__init(slot)? }; |
| 444 |
// SAFETY: All fields have been initialized. |
| 445 |
Ok(unsafe { Box::assume_init(self) }) |
| 446 |
} |
| 447 |
|
| 448 |
fn write_pin_init<E>(mut self, init: impl PinInit<T, E>) -> Result<Pin<Self::Initialized>, E> { |
| 449 |
let slot = self.as_mut_ptr(); |
| 450 |
// SAFETY: When init errors/panics, slot will get deallocated but not dropped, |
| 451 |
// slot is valid and will not be moved, because we pin it later. |
| 452 |
unsafe { init.__pinned_init(slot)? }; |
| 453 |
// SAFETY: All fields have been initialized. |
| 454 |
Ok(unsafe { Box::assume_init(self) }.into()) |
| 455 |
} |
| 456 |
} |
| 457 |
|
| 458 |
impl<T, A> InPlaceInit<T> for Box<T, A> |
| 459 |
where |
| 460 |
A: Allocator + 'static, |
| 461 |
{ |
| 462 |
type PinnedSelf = Pin<Self>; |
| 463 |
|
| 464 |
#[inline] |
| 465 |
fn try_pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Pin<Self>, E> |
| 466 |
where |
| 467 |
E: From<AllocError>, |
| 468 |
{ |
| 469 |
Box::<_, A>::new_uninit(flags)?.write_pin_init(init) |
| 470 |
} |
| 471 |
|
| 472 |
#[inline] |
| 473 |
fn try_init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E> |
| 474 |
where |
| 475 |
E: From<AllocError>, |
| 476 |
{ |
| 477 |
Box::<_, A>::new_uninit(flags)?.write_init(init) |
| 478 |
} |
| 479 |
} |
| 480 |
|
| 481 |
// SAFETY: The pointer returned by `into_foreign` comes from a well aligned |
| 482 |
// pointer to `T` allocated by `A`. |
| 483 |
unsafe impl<T: 'static, A> ForeignOwnable for Box<T, A> |
| 484 |
where |
| 485 |
A: Allocator, |
| 486 |
{ |
| 487 |
const FOREIGN_ALIGN: usize = if core::mem::align_of::<T>() < A::MIN_ALIGN { |
| 488 |
A::MIN_ALIGN |
| 489 |
} else { |
| 490 |
core::mem::align_of::<T>() |
| 491 |
}; |
| 492 |
|
| 493 |
type Borrowed<'a> = &'a T; |
| 494 |
type BorrowedMut<'a> = &'a mut T; |
| 495 |
|
| 496 |
fn into_foreign(self) -> *mut c_void { |
| 497 |
Box::into_raw(self).cast() |
| 498 |
} |
| 499 |
|
| 500 |
unsafe fn from_foreign(ptr: *mut c_void) -> Self { |
| 501 |
// SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous |
| 502 |
// call to `Self::into_foreign`. |
| 503 |
unsafe { Box::from_raw(ptr.cast()) } |
| 504 |
} |
| 505 |
|
| 506 |
unsafe fn borrow<'a>(ptr: *mut c_void) -> &'a T { |
| 507 |
// SAFETY: The safety requirements of this method ensure that the object remains alive and |
| 508 |
// immutable for the duration of 'a. |
| 509 |
unsafe { &*ptr.cast() } |
| 510 |
} |
| 511 |
|
| 512 |
unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> &'a mut T { |
| 513 |
let ptr = ptr.cast(); |
| 514 |
// SAFETY: The safety requirements of this method ensure that the pointer is valid and that |
| 515 |
// nothing else will access the value for the duration of 'a. |
| 516 |
unsafe { &mut *ptr } |
| 517 |
} |
| 518 |
} |
| 519 |
|
| 520 |
// SAFETY: The pointer returned by `into_foreign` comes from a well aligned |
| 521 |
// pointer to `T` allocated by `A`. |
| 522 |
unsafe impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>> |
| 523 |
where |
| 524 |
A: Allocator, |
| 525 |
{ |
| 526 |
const FOREIGN_ALIGN: usize = <Box<T, A> as ForeignOwnable>::FOREIGN_ALIGN; |
| 527 |
type Borrowed<'a> = Pin<&'a T>; |
| 528 |
type BorrowedMut<'a> = Pin<&'a mut T>; |
| 529 |
|
| 530 |
fn into_foreign(self) -> *mut c_void { |
| 531 |
// SAFETY: We are still treating the box as pinned. |
| 532 |
Box::into_raw(unsafe { Pin::into_inner_unchecked(self) }).cast() |
| 533 |
} |
| 534 |
|
| 535 |
unsafe fn from_foreign(ptr: *mut c_void) -> Self { |
| 536 |
// SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous |
| 537 |
// call to `Self::into_foreign`. |
| 538 |
unsafe { Pin::new_unchecked(Box::from_raw(ptr.cast())) } |
| 539 |
} |
| 540 |
|
| 541 |
unsafe fn borrow<'a>(ptr: *mut c_void) -> Pin<&'a T> { |
| 542 |
// SAFETY: The safety requirements for this function ensure that the object is still alive, |
| 543 |
// so it is safe to dereference the raw pointer. |
| 544 |
// The safety requirements of `from_foreign` also ensure that the object remains alive for |
| 545 |
// the lifetime of the returned value. |
| 546 |
let r = unsafe { &*ptr.cast() }; |
| 547 |
|
| 548 |
// SAFETY: This pointer originates from a `Pin<Box<T>>`. |
| 549 |
unsafe { Pin::new_unchecked(r) } |
| 550 |
} |
| 551 |
|
| 552 |
unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> Pin<&'a mut T> { |
| 553 |
let ptr = ptr.cast(); |
| 554 |
// SAFETY: The safety requirements for this function ensure that the object is still alive, |
| 555 |
// so it is safe to dereference the raw pointer. |
| 556 |
// The safety requirements of `from_foreign` also ensure that the object remains alive for |
| 557 |
// the lifetime of the returned value. |
| 558 |
let r = unsafe { &mut *ptr }; |
| 559 |
|
| 560 |
// SAFETY: This pointer originates from a `Pin<Box<T>>`. |
| 561 |
unsafe { Pin::new_unchecked(r) } |
| 562 |
} |
| 563 |
} |
| 564 |
|
| 565 |
impl<T, A> Deref for Box<T, A> |
| 566 |
where |
| 567 |
T: ?Sized, |
| 568 |
A: Allocator, |
| 569 |
{ |
| 570 |
type Target = T; |
| 571 |
|
| 572 |
fn deref(&self) -> &T { |
| 573 |
// SAFETY: `self.0` is always properly aligned, dereferenceable and points to an initialized |
| 574 |
// instance of `T`. |
| 575 |
unsafe { self.0.as_ref() } |
| 576 |
} |
| 577 |
} |
| 578 |
|
| 579 |
impl<T, A> DerefMut for Box<T, A> |
| 580 |
where |
| 581 |
T: ?Sized, |
| 582 |
A: Allocator, |
| 583 |
{ |
| 584 |
fn deref_mut(&mut self) -> &mut T { |
| 585 |
// SAFETY: `self.0` is always properly aligned, dereferenceable and points to an initialized |
| 586 |
// instance of `T`. |
| 587 |
unsafe { self.0.as_mut() } |
| 588 |
} |
| 589 |
} |
| 590 |
|
| 591 |
/// # Examples |
| 592 |
/// |
| 593 |
/// ``` |
| 594 |
/// # use core::borrow::Borrow; |
| 595 |
/// # use kernel::alloc::KBox; |
| 596 |
/// struct Foo<B: Borrow<u32>>(B); |
| 597 |
/// |
| 598 |
/// // Owned instance. |
| 599 |
/// let owned = Foo(1); |
| 600 |
/// |
| 601 |
/// // Owned instance using `KBox`. |
| 602 |
/// let owned_kbox = Foo(KBox::new(1, GFP_KERNEL)?); |
| 603 |
/// |
| 604 |
/// let i = 1; |
| 605 |
/// // Borrowed from `i`. |
| 606 |
/// let borrowed = Foo(&i); |
| 607 |
/// # Ok::<(), Error>(()) |
| 608 |
/// ``` |
| 609 |
impl<T, A> Borrow<T> for Box<T, A> |
| 610 |
where |
| 611 |
T: ?Sized, |
| 612 |
A: Allocator, |
| 613 |
{ |
| 614 |
fn borrow(&self) -> &T { |
| 615 |
self.deref() |
| 616 |
} |
| 617 |
} |
| 618 |
|
| 619 |
/// # Examples |
| 620 |
/// |
| 621 |
/// ``` |
| 622 |
/// # use core::borrow::BorrowMut; |
| 623 |
/// # use kernel::alloc::KBox; |
| 624 |
/// struct Foo<B: BorrowMut<u32>>(B); |
| 625 |
/// |
| 626 |
/// // Owned instance. |
| 627 |
/// let owned = Foo(1); |
| 628 |
/// |
| 629 |
/// // Owned instance using `KBox`. |
| 630 |
/// let owned_kbox = Foo(KBox::new(1, GFP_KERNEL)?); |
| 631 |
/// |
| 632 |
/// let mut i = 1; |
| 633 |
/// // Borrowed from `i`. |
| 634 |
/// let borrowed = Foo(&mut i); |
| 635 |
/// # Ok::<(), Error>(()) |
| 636 |
/// ``` |
| 637 |
impl<T, A> BorrowMut<T> for Box<T, A> |
| 638 |
where |
| 639 |
T: ?Sized, |
| 640 |
A: Allocator, |
| 641 |
{ |
| 642 |
fn borrow_mut(&mut self) -> &mut T { |
| 643 |
self.deref_mut() |
| 644 |
} |
| 645 |
} |
| 646 |
|
| 647 |
impl<T, A> fmt::Display for Box<T, A> |
| 648 |
where |
| 649 |
T: ?Sized + fmt::Display, |
| 650 |
A: Allocator, |
| 651 |
{ |
| 652 |
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 653 |
<T as fmt::Display>::fmt(&**self, f) |
| 654 |
} |
| 655 |
} |
| 656 |
|
| 657 |
impl<T, A> fmt::Debug for Box<T, A> |
| 658 |
where |
| 659 |
T: ?Sized + fmt::Debug, |
| 660 |
A: Allocator, |
| 661 |
{ |
| 662 |
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 663 |
<T as fmt::Debug>::fmt(&**self, f) |
| 664 |
} |
| 665 |
} |
| 666 |
|
| 667 |
impl<T, A> Drop for Box<T, A> |
| 668 |
where |
| 669 |
T: ?Sized, |
| 670 |
A: Allocator, |
| 671 |
{ |
| 672 |
fn drop(&mut self) { |
| 673 |
let layout = Layout::for_value::<T>(self); |
| 674 |
|
| 675 |
// SAFETY: The pointer in `self.0` is guaranteed to be valid by the type invariant. |
| 676 |
unsafe { core::ptr::drop_in_place::<T>(self.deref_mut()) }; |
| 677 |
|
| 678 |
// SAFETY: |
| 679 |
// - `self.0` was previously allocated with `A`. |
| 680 |
// - `layout` is equal to the `Layout´ `self.0` was allocated with. |
| 681 |
unsafe { A::free(self.0.cast(), layout) }; |
| 682 |
} |
| 683 |
} |
| 684 |
|
| 685 |
/// # Examples |
| 686 |
/// |
| 687 |
/// ``` |
| 688 |
/// # use kernel::prelude::*; |
| 689 |
/// use kernel::alloc::allocator::VmallocPageIter; |
| 690 |
/// use kernel::page::{AsPageIter, PAGE_SIZE}; |
| 691 |
/// |
| 692 |
/// let mut vbox = VBox::new((), GFP_KERNEL)?; |
| 693 |
/// |
| 694 |
/// assert!(vbox.page_iter().next().is_none()); |
| 695 |
/// |
| 696 |
/// let mut vbox = VBox::<[u8; PAGE_SIZE]>::new_uninit(GFP_KERNEL)?; |
| 697 |
/// |
| 698 |
/// let page = vbox.page_iter().next().expect("At least one page should be available.\n"); |
| 699 |
/// |
| 700 |
/// // SAFETY: There is no concurrent read or write to the same page. |
| 701 |
/// unsafe { page.fill_zero_raw(0, PAGE_SIZE)? }; |
| 702 |
/// # Ok::<(), Error>(()) |
| 703 |
/// ``` |
| 704 |
impl<T> AsPageIter for VBox<T> { |
| 705 |
type Iter<'a> |
| 706 |
= VmallocPageIter<'a> |
| 707 |
where |
| 708 |
T: 'a; |
| 709 |
|
| 710 |
fn page_iter(&mut self) -> Self::Iter<'_> { |
| 711 |
let ptr = self.0.cast(); |
| 712 |
let size = core::mem::size_of::<T>(); |
| 713 |
|
| 714 |
// SAFETY: |
| 715 |
// - `ptr` is a valid pointer to the beginning of a `Vmalloc` allocation. |
| 716 |
// - `ptr` is guaranteed to be valid for the lifetime of `'a`. |
| 717 |
// - `size` is the size of the `Vmalloc` allocation `ptr` points to. |
| 718 |
unsafe { VmallocPageIter::new(ptr, size) } |
| 719 |
} |
| 720 |
} |