kernel/alloc/
kbox.rs

1// SPDX-License-Identifier: GPL-2.0
2
3//! Implementation of [`Box`].
4
5#[allow(unused_imports)] // Used in doc comments.
6use super::allocator::{KVmalloc, Kmalloc, Vmalloc};
7use super::{AllocError, Allocator, Flags};
8use core::alloc::Layout;
9use core::fmt;
10use core::marker::PhantomData;
11use core::mem::ManuallyDrop;
12use core::mem::MaybeUninit;
13use core::ops::{Deref, DerefMut};
14use core::pin::Pin;
15use core::ptr::NonNull;
16use core::result::Result;
17
18use crate::init::{InPlaceInit, InPlaceWrite, Init, PinInit};
19use crate::types::ForeignOwnable;
20
21/// The kernel's [`Box`] type -- a heap allocation for a single value of type `T`.
22///
23/// This is the kernel's version of the Rust stdlib's `Box`. There are several differences,
24/// for example no `noalias` attribute is emitted and partially moving out of a `Box` is not
25/// supported. There are also several API differences, e.g. `Box` always requires an [`Allocator`]
26/// implementation to be passed as generic, page [`Flags`] when allocating memory and all functions
27/// that may allocate memory are fallible.
28///
29/// `Box` works with any of the kernel's allocators, e.g. [`Kmalloc`], [`Vmalloc`] or [`KVmalloc`].
30/// There are aliases for `Box` with these allocators ([`KBox`], [`VBox`], [`KVBox`]).
31///
32/// When dropping a [`Box`], the value is also dropped and the heap memory is automatically freed.
33///
34/// # Examples
35///
36/// ```
37/// let b = KBox::<u64>::new(24_u64, GFP_KERNEL)?;
38///
39/// assert_eq!(*b, 24_u64);
40/// # Ok::<(), Error>(())
41/// ```
42///
43/// ```
44/// # use kernel::bindings;
45/// const SIZE: usize = bindings::KMALLOC_MAX_SIZE as usize + 1;
46/// struct Huge([u8; SIZE]);
47///
48/// assert!(KBox::<Huge>::new_uninit(GFP_KERNEL | __GFP_NOWARN).is_err());
49/// ```
50///
51/// ```
52/// # use kernel::bindings;
53/// const SIZE: usize = bindings::KMALLOC_MAX_SIZE as usize + 1;
54/// struct Huge([u8; SIZE]);
55///
56/// assert!(KVBox::<Huge>::new_uninit(GFP_KERNEL).is_ok());
57/// ```
58///
59/// # Invariants
60///
61/// `self.0` is always properly aligned and either points to memory allocated with `A` or, for
62/// zero-sized types, is a dangling, well aligned pointer.
63#[repr(transparent)]
64pub struct Box<T: ?Sized, A: Allocator>(NonNull<T>, PhantomData<A>);
65
66/// Type alias for [`Box`] with a [`Kmalloc`] allocator.
67///
68/// # Examples
69///
70/// ```
71/// let b = KBox::new(24_u64, GFP_KERNEL)?;
72///
73/// assert_eq!(*b, 24_u64);
74/// # Ok::<(), Error>(())
75/// ```
76pub type KBox<T> = Box<T, super::allocator::Kmalloc>;
77
78/// Type alias for [`Box`] with a [`Vmalloc`] allocator.
79///
80/// # Examples
81///
82/// ```
83/// let b = VBox::new(24_u64, GFP_KERNEL)?;
84///
85/// assert_eq!(*b, 24_u64);
86/// # Ok::<(), Error>(())
87/// ```
88pub type VBox<T> = Box<T, super::allocator::Vmalloc>;
89
90/// Type alias for [`Box`] with a [`KVmalloc`] allocator.
91///
92/// # Examples
93///
94/// ```
95/// let b = KVBox::new(24_u64, GFP_KERNEL)?;
96///
97/// assert_eq!(*b, 24_u64);
98/// # Ok::<(), Error>(())
99/// ```
100pub type KVBox<T> = Box<T, super::allocator::KVmalloc>;
101
102// SAFETY: `Box` is `Send` if `T` is `Send` because the `Box` owns a `T`.
103unsafe impl<T, A> Send for Box<T, A>
104where
105    T: Send + ?Sized,
106    A: Allocator,
107{
108}
109
110// SAFETY: `Box` is `Sync` if `T` is `Sync` because the `Box` owns a `T`.
111unsafe impl<T, A> Sync for Box<T, A>
112where
113    T: Sync + ?Sized,
114    A: Allocator,
115{
116}
117
118impl<T, A> Box<T, A>
119where
120    T: ?Sized,
121    A: Allocator,
122{
123    /// Creates a new `Box<T, A>` from a raw pointer.
124    ///
125    /// # Safety
126    ///
127    /// For non-ZSTs, `raw` must point at an allocation allocated with `A` that is sufficiently
128    /// aligned for and holds a valid `T`. The caller passes ownership of the allocation to the
129    /// `Box`.
130    ///
131    /// For ZSTs, `raw` must be a dangling, well aligned pointer.
132    #[inline]
133    pub const unsafe fn from_raw(raw: *mut T) -> Self {
134        // INVARIANT: Validity of `raw` is guaranteed by the safety preconditions of this function.
135        // SAFETY: By the safety preconditions of this function, `raw` is not a NULL pointer.
136        Self(unsafe { NonNull::new_unchecked(raw) }, PhantomData)
137    }
138
139    /// Consumes the `Box<T, A>` and returns a raw pointer.
140    ///
141    /// This will not run the destructor of `T` and for non-ZSTs the allocation will stay alive
142    /// indefinitely. Use [`Box::from_raw`] to recover the [`Box`], drop the value and free the
143    /// allocation, if any.
144    ///
145    /// # Examples
146    ///
147    /// ```
148    /// let x = KBox::new(24, GFP_KERNEL)?;
149    /// let ptr = KBox::into_raw(x);
150    /// // SAFETY: `ptr` comes from a previous call to `KBox::into_raw`.
151    /// let x = unsafe { KBox::from_raw(ptr) };
152    ///
153    /// assert_eq!(*x, 24);
154    /// # Ok::<(), Error>(())
155    /// ```
156    #[inline]
157    pub fn into_raw(b: Self) -> *mut T {
158        ManuallyDrop::new(b).0.as_ptr()
159    }
160
161    /// Consumes and leaks the `Box<T, A>` and returns a mutable reference.
162    ///
163    /// See [`Box::into_raw`] for more details.
164    #[inline]
165    pub fn leak<'a>(b: Self) -> &'a mut T {
166        // SAFETY: `Box::into_raw` always returns a properly aligned and dereferenceable pointer
167        // which points to an initialized instance of `T`.
168        unsafe { &mut *Box::into_raw(b) }
169    }
170}
171
172impl<T, A> Box<MaybeUninit<T>, A>
173where
174    A: Allocator,
175{
176    /// Converts a `Box<MaybeUninit<T>, A>` to a `Box<T, A>`.
177    ///
178    /// It is undefined behavior to call this function while the value inside of `b` is not yet
179    /// fully initialized.
180    ///
181    /// # Safety
182    ///
183    /// Callers must ensure that the value inside of `b` is in an initialized state.
184    pub unsafe fn assume_init(self) -> Box<T, A> {
185        let raw = Self::into_raw(self);
186
187        // SAFETY: `raw` comes from a previous call to `Box::into_raw`. By the safety requirements
188        // of this function, the value inside the `Box` is in an initialized state. Hence, it is
189        // safe to reconstruct the `Box` as `Box<T, A>`.
190        unsafe { Box::from_raw(raw.cast()) }
191    }
192
193    /// Writes the value and converts to `Box<T, A>`.
194    pub fn write(mut self, value: T) -> Box<T, A> {
195        (*self).write(value);
196
197        // SAFETY: We've just initialized `b`'s value.
198        unsafe { self.assume_init() }
199    }
200}
201
202impl<T, A> Box<T, A>
203where
204    A: Allocator,
205{
206    /// Creates a new `Box<T, A>` and initializes its contents with `x`.
207    ///
208    /// New memory is allocated with `A`. The allocation may fail, in which case an error is
209    /// returned. For ZSTs no memory is allocated.
210    pub fn new(x: T, flags: Flags) -> Result<Self, AllocError> {
211        let b = Self::new_uninit(flags)?;
212        Ok(Box::write(b, x))
213    }
214
215    /// Creates a new `Box<T, A>` with uninitialized contents.
216    ///
217    /// New memory is allocated with `A`. The allocation may fail, in which case an error is
218    /// returned. For ZSTs no memory is allocated.
219    ///
220    /// # Examples
221    ///
222    /// ```
223    /// let b = KBox::<u64>::new_uninit(GFP_KERNEL)?;
224    /// let b = KBox::write(b, 24);
225    ///
226    /// assert_eq!(*b, 24_u64);
227    /// # Ok::<(), Error>(())
228    /// ```
229    pub fn new_uninit(flags: Flags) -> Result<Box<MaybeUninit<T>, A>, AllocError> {
230        let layout = Layout::new::<MaybeUninit<T>>();
231        let ptr = A::alloc(layout, flags)?;
232
233        // INVARIANT: `ptr` is either a dangling pointer or points to memory allocated with `A`,
234        // which is sufficient in size and alignment for storing a `T`.
235        Ok(Box(ptr.cast(), PhantomData))
236    }
237
238    /// Constructs a new `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then `x` will be
239    /// pinned in memory and can't be moved.
240    #[inline]
241    pub fn pin(x: T, flags: Flags) -> Result<Pin<Box<T, A>>, AllocError>
242    where
243        A: 'static,
244    {
245        Ok(Self::new(x, flags)?.into())
246    }
247
248    /// Forgets the contents (does not run the destructor), but keeps the allocation.
249    fn forget_contents(this: Self) -> Box<MaybeUninit<T>, A> {
250        let ptr = Self::into_raw(this);
251
252        // SAFETY: `ptr` is valid, because it came from `Box::into_raw`.
253        unsafe { Box::from_raw(ptr.cast()) }
254    }
255
256    /// Drops the contents, but keeps the allocation.
257    ///
258    /// # Examples
259    ///
260    /// ```
261    /// let value = KBox::new([0; 32], GFP_KERNEL)?;
262    /// assert_eq!(*value, [0; 32]);
263    /// let value = KBox::drop_contents(value);
264    /// // Now we can re-use `value`:
265    /// let value = KBox::write(value, [1; 32]);
266    /// assert_eq!(*value, [1; 32]);
267    /// # Ok::<(), Error>(())
268    /// ```
269    pub fn drop_contents(this: Self) -> Box<MaybeUninit<T>, A> {
270        let ptr = this.0.as_ptr();
271
272        // SAFETY: `ptr` is valid, because it came from `this`. After this call we never access the
273        // value stored in `this` again.
274        unsafe { core::ptr::drop_in_place(ptr) };
275
276        Self::forget_contents(this)
277    }
278
279    /// Moves the `Box`'s value out of the `Box` and consumes the `Box`.
280    pub fn into_inner(b: Self) -> T {
281        // SAFETY: By the type invariant `&*b` is valid for `read`.
282        let value = unsafe { core::ptr::read(&*b) };
283        let _ = Self::forget_contents(b);
284        value
285    }
286}
287
288impl<T, A> From<Box<T, A>> for Pin<Box<T, A>>
289where
290    T: ?Sized,
291    A: Allocator,
292{
293    /// Converts a `Box<T, A>` into a `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then
294    /// `*b` will be pinned in memory and can't be moved.
295    ///
296    /// This moves `b` into `Pin` without moving `*b` or allocating and copying any memory.
297    fn from(b: Box<T, A>) -> Self {
298        // SAFETY: The value wrapped inside a `Pin<Box<T, A>>` cannot be moved or replaced as long
299        // as `T` does not implement `Unpin`.
300        unsafe { Pin::new_unchecked(b) }
301    }
302}
303
304impl<T, A> InPlaceWrite<T> for Box<MaybeUninit<T>, A>
305where
306    A: Allocator + 'static,
307{
308    type Initialized = Box<T, A>;
309
310    fn write_init<E>(mut self, init: impl Init<T, E>) -> Result<Self::Initialized, E> {
311        let slot = self.as_mut_ptr();
312        // SAFETY: When init errors/panics, slot will get deallocated but not dropped,
313        // slot is valid.
314        unsafe { init.__init(slot)? };
315        // SAFETY: All fields have been initialized.
316        Ok(unsafe { Box::assume_init(self) })
317    }
318
319    fn write_pin_init<E>(mut self, init: impl PinInit<T, E>) -> Result<Pin<Self::Initialized>, E> {
320        let slot = self.as_mut_ptr();
321        // SAFETY: When init errors/panics, slot will get deallocated but not dropped,
322        // slot is valid and will not be moved, because we pin it later.
323        unsafe { init.__pinned_init(slot)? };
324        // SAFETY: All fields have been initialized.
325        Ok(unsafe { Box::assume_init(self) }.into())
326    }
327}
328
329impl<T, A> InPlaceInit<T> for Box<T, A>
330where
331    A: Allocator + 'static,
332{
333    type PinnedSelf = Pin<Self>;
334
335    #[inline]
336    fn try_pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Pin<Self>, E>
337    where
338        E: From<AllocError>,
339    {
340        Box::<_, A>::new_uninit(flags)?.write_pin_init(init)
341    }
342
343    #[inline]
344    fn try_init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E>
345    where
346        E: From<AllocError>,
347    {
348        Box::<_, A>::new_uninit(flags)?.write_init(init)
349    }
350}
351
352impl<T: 'static, A> ForeignOwnable for Box<T, A>
353where
354    A: Allocator,
355{
356    type Borrowed<'a> = &'a T;
357    type BorrowedMut<'a> = &'a mut T;
358
359    fn into_foreign(self) -> *mut crate::ffi::c_void {
360        Box::into_raw(self).cast()
361    }
362
363    unsafe fn from_foreign(ptr: *mut crate::ffi::c_void) -> Self {
364        // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
365        // call to `Self::into_foreign`.
366        unsafe { Box::from_raw(ptr.cast()) }
367    }
368
369    unsafe fn borrow<'a>(ptr: *mut crate::ffi::c_void) -> &'a T {
370        // SAFETY: The safety requirements of this method ensure that the object remains alive and
371        // immutable for the duration of 'a.
372        unsafe { &*ptr.cast() }
373    }
374
375    unsafe fn borrow_mut<'a>(ptr: *mut crate::ffi::c_void) -> &'a mut T {
376        let ptr = ptr.cast();
377        // SAFETY: The safety requirements of this method ensure that the pointer is valid and that
378        // nothing else will access the value for the duration of 'a.
379        unsafe { &mut *ptr }
380    }
381}
382
383impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>>
384where
385    A: Allocator,
386{
387    type Borrowed<'a> = Pin<&'a T>;
388    type BorrowedMut<'a> = Pin<&'a mut T>;
389
390    fn into_foreign(self) -> *mut crate::ffi::c_void {
391        // SAFETY: We are still treating the box as pinned.
392        Box::into_raw(unsafe { Pin::into_inner_unchecked(self) }).cast()
393    }
394
395    unsafe fn from_foreign(ptr: *mut crate::ffi::c_void) -> Self {
396        // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
397        // call to `Self::into_foreign`.
398        unsafe { Pin::new_unchecked(Box::from_raw(ptr.cast())) }
399    }
400
401    unsafe fn borrow<'a>(ptr: *mut crate::ffi::c_void) -> Pin<&'a T> {
402        // SAFETY: The safety requirements for this function ensure that the object is still alive,
403        // so it is safe to dereference the raw pointer.
404        // The safety requirements of `from_foreign` also ensure that the object remains alive for
405        // the lifetime of the returned value.
406        let r = unsafe { &*ptr.cast() };
407
408        // SAFETY: This pointer originates from a `Pin<Box<T>>`.
409        unsafe { Pin::new_unchecked(r) }
410    }
411
412    unsafe fn borrow_mut<'a>(ptr: *mut crate::ffi::c_void) -> Pin<&'a mut T> {
413        let ptr = ptr.cast();
414        // SAFETY: The safety requirements for this function ensure that the object is still alive,
415        // so it is safe to dereference the raw pointer.
416        // The safety requirements of `from_foreign` also ensure that the object remains alive for
417        // the lifetime of the returned value.
418        let r = unsafe { &mut *ptr };
419
420        // SAFETY: This pointer originates from a `Pin<Box<T>>`.
421        unsafe { Pin::new_unchecked(r) }
422    }
423}
424
425impl<T, A> Deref for Box<T, A>
426where
427    T: ?Sized,
428    A: Allocator,
429{
430    type Target = T;
431
432    fn deref(&self) -> &T {
433        // SAFETY: `self.0` is always properly aligned, dereferenceable and points to an initialized
434        // instance of `T`.
435        unsafe { self.0.as_ref() }
436    }
437}
438
439impl<T, A> DerefMut for Box<T, A>
440where
441    T: ?Sized,
442    A: Allocator,
443{
444    fn deref_mut(&mut self) -> &mut T {
445        // SAFETY: `self.0` is always properly aligned, dereferenceable and points to an initialized
446        // instance of `T`.
447        unsafe { self.0.as_mut() }
448    }
449}
450
451impl<T, A> fmt::Display for Box<T, A>
452where
453    T: ?Sized + fmt::Display,
454    A: Allocator,
455{
456    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
457        <T as fmt::Display>::fmt(&**self, f)
458    }
459}
460
461impl<T, A> fmt::Debug for Box<T, A>
462where
463    T: ?Sized + fmt::Debug,
464    A: Allocator,
465{
466    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
467        <T as fmt::Debug>::fmt(&**self, f)
468    }
469}
470
471impl<T, A> Drop for Box<T, A>
472where
473    T: ?Sized,
474    A: Allocator,
475{
476    fn drop(&mut self) {
477        let layout = Layout::for_value::<T>(self);
478
479        // SAFETY: The pointer in `self.0` is guaranteed to be valid by the type invariant.
480        unsafe { core::ptr::drop_in_place::<T>(self.deref_mut()) };
481
482        // SAFETY:
483        // - `self.0` was previously allocated with `A`.
484        // - `layout` is equal to the `Layout´ `self.0` was allocated with.
485        unsafe { A::free(self.0.cast(), layout) };
486    }
487}