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

kernel/alloc/
kbox.rs
