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

kernel/alloc/
kbox.rs
