| blob | 9ce414361c2c6dd8eea09b11041f6c307cbc7864 |
1 // SPDX-License-Identifier: GPL-2.0
3 //! Implementation of [`Box`].
5 #[allow(unused_imports)] // Used in doc comments.
6 use super::allocator::{KVmalloc, Kmalloc, Vmalloc};
7 use super::{AllocError, Allocator, Flags};
8 use core::alloc::Layout;
9 use core::fmt;
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;
18 use crate::init::{InPlaceInit, InPlaceWrite, Init, PinInit};
19 use crate::types::ForeignOwnable;
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)]
64 pub struct Box<T: ?Sized, A: Allocator>(NonNull<T>, PhantomData<A>);
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 /// ```
76 pub type KBox<T> = Box<T, super::allocator::Kmalloc>;
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 /// ```
88 pub type VBox<T> = Box<T, super::allocator::Vmalloc>;
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 /// ```
100 pub type KVBox<T> = Box<T, super::allocator::KVmalloc>;
102 // SAFETY: `Box` is `Send` if `T` is `Send` because the `Box` owns a `T`.
103 unsafe impl<T, A> Send for Box<T, A>
104 where
105 T: Send + ?Sized,
106 A: Allocator,
107 {
108 }
110 // SAFETY: `Box` is `Sync` if `T` is `Sync` because the `Box` owns a `T`.
111 unsafe impl<T, A> Sync for Box<T, A>
112 where
113 T: Sync + ?Sized,
114 A: Allocator,
115 {
116 }
118 impl<T, A> Box<T, A>
119 where
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 }
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 }
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 }
172 impl<T, A> Box<MaybeUninit<T>, A>
173 where
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);
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 }
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);
197 // SAFETY: We've just initialized `b`'s value.
198 unsafe { self.assume_init() }
199 }
200 }
202 impl<T, A> Box<T, A>
203 where
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 }
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)?;
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 }
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 }
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);
252 // SAFETY: `ptr` is valid, because it came from `Box::into_raw`.
253 unsafe { Box::from_raw(ptr.cast()) }
254 }
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();
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) };
276 Self::forget_contents(this)
277 }
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 }
288 impl<T, A> From<Box<T, A>> for Pin<Box<T, A>>
289 where
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 }
304 impl<T, A> InPlaceWrite<T> for Box<MaybeUninit<T>, A>
305 where
306 A: Allocator + 'static,
307 {
308 type Initialized = Box<T, A>;
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 }
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 }
329 impl<T, A> InPlaceInit<T> for Box<T, A>
330 where
331 A: Allocator + 'static,
332 {
333 type PinnedSelf = Pin<Self>;
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 }
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 }
352 impl<T: 'static, A> ForeignOwnable for Box<T, A>
353 where
354 A: Allocator,
355 {
356 type Borrowed<'a> = &'a T;
358 fn into_foreign(self) -> *const crate::ffi::c_void {
359 Box::into_raw(self) as _
360 }
362 unsafe fn from_foreign(ptr: *const crate::ffi::c_void) -> Self {
363 // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
364 // call to `Self::into_foreign`.
365 unsafe { Box::from_raw(ptr as _) }
366 }
368 unsafe fn borrow<'a>(ptr: *const crate::ffi::c_void) -> &'a T {
369 // SAFETY: The safety requirements of this method ensure that the object remains alive and
370 // immutable for the duration of 'a.
371 unsafe { &*ptr.cast() }
372 }
373 }
375 impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>>
376 where
377 A: Allocator,
378 {
379 type Borrowed<'a> = Pin<&'a T>;
381 fn into_foreign(self) -> *const crate::ffi::c_void {
382 // SAFETY: We are still treating the box as pinned.
383 Box::into_raw(unsafe { Pin::into_inner_unchecked(self) }) as _
384 }
386 unsafe fn from_foreign(ptr: *const crate::ffi::c_void) -> Self {
387 // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
388 // call to `Self::into_foreign`.
389 unsafe { Pin::new_unchecked(Box::from_raw(ptr as _)) }
390 }
392 unsafe fn borrow<'a>(ptr: *const crate::ffi::c_void) -> Pin<&'a T> {
393 // SAFETY: The safety requirements for this function ensure that the object is still alive,
394 // so it is safe to dereference the raw pointer.
395 // The safety requirements of `from_foreign` also ensure that the object remains alive for
396 // the lifetime of the returned value.
397 let r = unsafe { &*ptr.cast() };
399 // SAFETY: This pointer originates from a `Pin<Box<T>>`.
400 unsafe { Pin::new_unchecked(r) }
401 }
402 }
404 impl<T, A> Deref for Box<T, A>
405 where
406 T: ?Sized,
407 A: Allocator,
408 {
409 type Target = T;
411 fn deref(&self) -> &T {
412 // SAFETY: `self.0` is always properly aligned, dereferenceable and points to an initialized
413 // instance of `T`.
414 unsafe { self.0.as_ref() }
415 }
416 }
418 impl<T, A> DerefMut for Box<T, A>
419 where
420 T: ?Sized,
421 A: Allocator,
422 {
423 fn deref_mut(&mut self) -> &mut T {
424 // SAFETY: `self.0` is always properly aligned, dereferenceable and points to an initialized
425 // instance of `T`.
426 unsafe { self.0.as_mut() }
427 }
428 }
430 impl<T, A> fmt::Debug for Box<T, A>
431 where
432 T: ?Sized + fmt::Debug,
433 A: Allocator,
434 {
435 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
436 fmt::Debug::fmt(&**self, f)
437 }
438 }
440 impl<T, A> Drop for Box<T, A>
441 where
442 T: ?Sized,
443 A: Allocator,
444 {
445 fn drop(&mut self) {
446 let layout = Layout::for_value::<T>(self);
448 // SAFETY: The pointer in `self.0` is guaranteed to be valid by the type invariant.
449 unsafe { core::ptr::drop_in_place::<T>(self.deref_mut()) };
451 // SAFETY:
452 // - `self.0` was previously allocated with `A`.
453 // - `layout` is equal to the `Layout´ `self.0` was allocated with.
454 unsafe { A::free(self.0.cast(), layout) };
455 }
456 }