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::{
7 KVmalloc,
8 Kmalloc,
9 Vmalloc,
10 VmallocPageIter, //
11};
12
13use super::{
14 AllocError,
15 Allocator,
16 Flags,
17 NumaNode, //
18};
19
20use crate::{
21 fmt,
22 page::AsPageIter,
23 prelude::*,
24 types::ForeignOwnable, //
25};
26
27use core::{
28 alloc::Layout,
29 borrow::{
30 Borrow,
31 BorrowMut, //
32 },
33 marker::PhantomData,
34 mem::{
35 ManuallyDrop,
36 MaybeUninit, //
37 },
38 ops::{
39 Deref,
40 DerefMut, //
41 },
42 ptr::NonNull,
43 result::Result, //
44};
45
46use pin_init::ZeroableOption;
47
48/// The kernel's [`Box`] type -- a heap allocation for a single value of type `T`.
49///
50/// This is the kernel's version of the Rust stdlib's `Box`. There are several differences,
51/// for example no `noalias` attribute is emitted and partially moving out of a `Box` is not
52/// supported. There are also several API differences, e.g. `Box` always requires an [`Allocator`]
53/// implementation to be passed as generic, page [`Flags`] when allocating memory and all functions
54/// that may allocate memory are fallible.
55///
56/// `Box` works with any of the kernel's allocators, e.g. [`Kmalloc`], [`Vmalloc`] or [`KVmalloc`].
57/// There are aliases for `Box` with these allocators ([`KBox`], [`VBox`], [`KVBox`]).
58///
59/// When dropping a [`Box`], the value is also dropped and the heap memory is automatically freed.
60///
61/// # Examples
62///
63/// ```
64/// let b = KBox::<u64>::new(24_u64, GFP_KERNEL)?;
65///
66/// assert_eq!(*b, 24_u64);
67/// # Ok::<(), Error>(())
68/// ```
69///
70/// ```
71/// # use kernel::bindings;
72/// const SIZE: usize = bindings::KMALLOC_MAX_SIZE as usize + 1;
73/// struct Huge([u8; SIZE]);
74///
75/// assert!(KBox::<Huge>::new_uninit(GFP_KERNEL | __GFP_NOWARN).is_err());
76/// ```
77///
78/// ```
79/// # use kernel::bindings;
80/// const SIZE: usize = bindings::KMALLOC_MAX_SIZE as usize + 1;
81/// struct Huge([u8; SIZE]);
82///
83/// assert!(KVBox::<Huge>::new_uninit(GFP_KERNEL).is_ok());
84/// ```
85///
86/// [`Box`]es can also be used to store trait objects by coercing their type:
87///
88/// ```
89/// trait FooTrait {}
90///
91/// struct FooStruct;
92/// impl FooTrait for FooStruct {}
93///
94/// let _ = KBox::new(FooStruct, GFP_KERNEL)? as KBox<dyn FooTrait>;
95/// # Ok::<(), Error>(())
96/// ```
97///
98/// # Invariants
99///
100/// `self.0` is always properly aligned and either points to memory allocated with `A` or, for
101/// zero-sized types, is a dangling, well aligned pointer.
102#[repr(transparent)]
103#[derive(core::marker::CoercePointee)]
104pub struct Box<#[pointee] T: ?Sized, A: Allocator>(NonNull<T>, PhantomData<A>);
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, NumaNode::NO_NODE)?;
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 /// Creates a new zero-initialized `Box<T, A>`.
283 ///
284 /// New memory is allocated with `A` and the [`__GFP_ZERO`] flag. The allocation may fail, in
285 /// which case an error is returned. For ZSTs no memory is allocated.
286 ///
287 /// # Examples
288 ///
289 /// ```
290 /// let b = KBox::<[u8; 128]>::zeroed(GFP_KERNEL)?;
291 /// assert_eq!(*b, [0; 128]);
292 /// # Ok::<(), Error>(())
293 /// ```
294 pub fn zeroed(flags: Flags) -> Result<Self, AllocError>
295 where
296 T: Zeroable,
297 {
298 // SAFETY: `__GFP_ZERO` guarantees the memory is zeroed; `T: Zeroable` guarantees that
299 // all-zeroes is a valid bit pattern for `T`.
300 Ok(unsafe { Self::new_uninit(flags | __GFP_ZERO)?.assume_init() })
301 }
302
303 /// Constructs a new `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then `x` will be
304 /// pinned in memory and can't be moved.
305 #[inline]
306 pub fn pin(x: T, flags: Flags) -> Result<Pin<Box<T, A>>, AllocError>
307 where
308 A: 'static,
309 {
310 Ok(Self::new(x, flags)?.into())
311 }
312
313 /// Construct a pinned slice of elements `Pin<Box<[T], A>>`.
314 ///
315 /// This is a convenient means for creation of e.g. slices of structrures containing spinlocks
316 /// or mutexes.
317 ///
318 /// # Examples
319 ///
320 /// ```
321 /// use kernel::sync::{
322 /// new_spinlock,
323 /// SpinLock, //
324 /// };
325 ///
326 /// struct Inner {
327 /// a: u32,
328 /// b: u32,
329 /// }
330 ///
331 /// #[pin_data]
332 /// struct Example {
333 /// c: u32,
334 /// #[pin]
335 /// d: SpinLock<Inner>,
336 /// }
337 ///
338 /// impl Example {
339 /// fn new() -> impl PinInit<Self, Error> {
340 /// try_pin_init!(Self {
341 /// c: 10,
342 /// d <- new_spinlock!(Inner { a: 20, b: 30 }),
343 /// })
344 /// }
345 /// }
346 ///
347 /// // Allocate a boxed slice of 10 `Example`s.
348 /// let s = KBox::pin_slice(
349 /// | _i | Example::new(),
350 /// 10,
351 /// GFP_KERNEL
352 /// )?;
353 ///
354 /// assert_eq!(s[5].c, 10);
355 /// assert_eq!(s[3].d.lock().a, 20);
356 /// # Ok::<(), Error>(())
357 /// ```
358 pub fn pin_slice<Func, Item, E>(
359 mut init: Func,
360 len: usize,
361 flags: Flags,
362 ) -> Result<Pin<Box<[T], A>>, E>
363 where
364 Func: FnMut(usize) -> Item,
365 Item: PinInit<T, E>,
366 E: From<AllocError>,
367 {
368 let mut buffer = super::Vec::<T, A>::with_capacity(len, flags)?;
369 for i in 0..len {
370 let ptr = buffer.spare_capacity_mut().as_mut_ptr().cast();
371 // SAFETY:
372 // - `ptr` is a valid pointer to uninitialized memory.
373 // - `ptr` is not used if an error is returned.
374 // - `ptr` won't be moved until it is dropped, i.e. it is pinned.
375 unsafe { init(i).__pinned_init(ptr)? };
376
377 // SAFETY:
378 // - `i + 1 <= len`, hence we don't exceed the capacity, due to the call to
379 // `with_capacity()` above.
380 // - The new value at index buffer.len() + 1 is the only element being added here, and
381 // it has been initialized above by `init(i).__pinned_init(ptr)`.
382 unsafe { buffer.inc_len(1) };
383 }
384
385 let (ptr, _, _) = buffer.into_raw_parts();
386 let slice = core::ptr::slice_from_raw_parts_mut(ptr, len);
387
388 // SAFETY: `slice` points to an allocation allocated with `A` (`buffer`) and holds a valid
389 // `[T]`.
390 Ok(Pin::from(unsafe { Box::from_raw(slice) }))
391 }
392
393 /// Convert a [`Box<T,A>`] to a [`Pin<Box<T,A>>`]. If `T` does not implement
394 /// [`Unpin`], then `x` will be pinned in memory and can't be moved.
395 pub fn into_pin(this: Self) -> Pin<Self> {
396 this.into()
397 }
398
399 /// Forgets the contents (does not run the destructor), but keeps the allocation.
400 fn forget_contents(this: Self) -> Box<MaybeUninit<T>, A> {
401 let ptr = Self::into_raw(this);
402
403 // SAFETY: `ptr` is valid, because it came from `Box::into_raw`.
404 unsafe { Box::from_raw(ptr.cast()) }
405 }
406
407 /// Drops the contents, but keeps the allocation.
408 ///
409 /// # Examples
410 ///
411 /// ```
412 /// let value = KBox::new([0; 32], GFP_KERNEL)?;
413 /// assert_eq!(*value, [0; 32]);
414 /// let value = KBox::drop_contents(value);
415 /// // Now we can re-use `value`:
416 /// let value = KBox::write(value, [1; 32]);
417 /// assert_eq!(*value, [1; 32]);
418 /// # Ok::<(), Error>(())
419 /// ```
420 pub fn drop_contents(this: Self) -> Box<MaybeUninit<T>, A> {
421 let ptr = this.0.as_ptr();
422
423 // SAFETY: `ptr` is valid, because it came from `this`. After this call we never access the
424 // value stored in `this` again.
425 unsafe { core::ptr::drop_in_place(ptr) };
426
427 Self::forget_contents(this)
428 }
429
430 /// Moves the `Box`'s value out of the `Box` and consumes the `Box`.
431 pub fn into_inner(b: Self) -> T {
432 // SAFETY: By the type invariant `&*b` is valid for `read`.
433 let value = unsafe { core::ptr::read(&*b) };
434 let _ = Self::forget_contents(b);
435 value
436 }
437}
438
439impl<T, A> From<Box<T, A>> for Pin<Box<T, A>>
440where
441 T: ?Sized,
442 A: Allocator,
443{
444 /// Converts a `Box<T, A>` into a `Pin<Box<T, A>>`. If `T` does not implement [`Unpin`], then
445 /// `*b` will be pinned in memory and can't be moved.
446 ///
447 /// This moves `b` into `Pin` without moving `*b` or allocating and copying any memory.
448 fn from(b: Box<T, A>) -> Self {
449 // SAFETY: The value wrapped inside a `Pin<Box<T, A>>` cannot be moved or replaced as long
450 // as `T` does not implement `Unpin`.
451 unsafe { Pin::new_unchecked(b) }
452 }
453}
454
455impl<T, A> InPlaceWrite<T> for Box<MaybeUninit<T>, A>
456where
457 A: Allocator + 'static,
458{
459 type Initialized = Box<T, A>;
460
461 fn write_init<E>(mut self, init: impl Init<T, E>) -> Result<Self::Initialized, E> {
462 let slot = self.as_mut_ptr();
463 // SAFETY: When init errors/panics, slot will get deallocated but not dropped,
464 // slot is valid.
465 unsafe { init.__init(slot)? };
466 // SAFETY: All fields have been initialized.
467 Ok(unsafe { Box::assume_init(self) })
468 }
469
470 fn write_pin_init<E>(mut self, init: impl PinInit<T, E>) -> Result<Pin<Self::Initialized>, E> {
471 let slot = self.as_mut_ptr();
472 // SAFETY: When init errors/panics, slot will get deallocated but not dropped,
473 // slot is valid and will not be moved, because we pin it later.
474 unsafe { init.__pinned_init(slot)? };
475 // SAFETY: All fields have been initialized.
476 Ok(unsafe { Box::assume_init(self) }.into())
477 }
478}
479
480impl<T, A> InPlaceInit<T> for Box<T, A>
481where
482 A: Allocator + 'static,
483{
484 type PinnedSelf = Pin<Self>;
485
486 #[inline]
487 fn try_pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Pin<Self>, E>
488 where
489 E: From<AllocError>,
490 {
491 Box::<_, A>::new_uninit(flags)?.write_pin_init(init)
492 }
493
494 #[inline]
495 fn try_init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E>
496 where
497 E: From<AllocError>,
498 {
499 Box::<_, A>::new_uninit(flags)?.write_init(init)
500 }
501}
502
503// SAFETY: The pointer returned by `into_foreign` comes from a well aligned
504// pointer to `T` allocated by `A`.
505unsafe impl<T: 'static, A> ForeignOwnable for Box<T, A>
506where
507 A: Allocator,
508{
509 const FOREIGN_ALIGN: usize = if core::mem::align_of::<T>() < A::MIN_ALIGN {
510 A::MIN_ALIGN
511 } else {
512 core::mem::align_of::<T>()
513 };
514
515 type Borrowed<'a> = &'a T;
516 type BorrowedMut<'a> = &'a mut T;
517
518 fn into_foreign(self) -> *mut c_void {
519 Box::into_raw(self).cast()
520 }
521
522 unsafe fn from_foreign(ptr: *mut c_void) -> Self {
523 // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
524 // call to `Self::into_foreign`.
525 unsafe { Box::from_raw(ptr.cast()) }
526 }
527
528 unsafe fn borrow<'a>(ptr: *mut c_void) -> &'a T {
529 // SAFETY: The safety requirements of this method ensure that the object remains alive and
530 // immutable for the duration of 'a.
531 unsafe { &*ptr.cast() }
532 }
533
534 unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> &'a mut T {
535 let ptr = ptr.cast();
536 // SAFETY: The safety requirements of this method ensure that the pointer is valid and that
537 // nothing else will access the value for the duration of 'a.
538 unsafe { &mut *ptr }
539 }
540}
541
542// SAFETY: The pointer returned by `into_foreign` comes from a well aligned
543// pointer to `T` allocated by `A`.
544unsafe impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>>
545where
546 A: Allocator,
547{
548 const FOREIGN_ALIGN: usize = <Box<T, A> as ForeignOwnable>::FOREIGN_ALIGN;
549 type Borrowed<'a> = Pin<&'a T>;
550 type BorrowedMut<'a> = Pin<&'a mut T>;
551
552 fn into_foreign(self) -> *mut c_void {
553 // SAFETY: We are still treating the box as pinned.
554 Box::into_raw(unsafe { Pin::into_inner_unchecked(self) }).cast()
555 }
556
557 unsafe fn from_foreign(ptr: *mut c_void) -> Self {
558 // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
559 // call to `Self::into_foreign`.
560 unsafe { Pin::new_unchecked(Box::from_raw(ptr.cast())) }
561 }
562
563 unsafe fn borrow<'a>(ptr: *mut c_void) -> Pin<&'a T> {
564 // SAFETY: The safety requirements for this function ensure that the object is still alive,
565 // so it is safe to dereference the raw pointer.
566 // The safety requirements of `from_foreign` also ensure that the object remains alive for
567 // the lifetime of the returned value.
568 let r = unsafe { &*ptr.cast() };
569
570 // SAFETY: This pointer originates from a `Pin<Box<T>>`.
571 unsafe { Pin::new_unchecked(r) }
572 }
573
574 unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> Pin<&'a mut T> {
575 let ptr = ptr.cast();
576 // SAFETY: The safety requirements for this function ensure that the object is still alive,
577 // so it is safe to dereference the raw pointer.
578 // The safety requirements of `from_foreign` also ensure that the object remains alive for
579 // the lifetime of the returned value.
580 let r = unsafe { &mut *ptr };
581
582 // SAFETY: This pointer originates from a `Pin<Box<T>>`.
583 unsafe { Pin::new_unchecked(r) }
584 }
585}
586
587impl<T, A> Deref for Box<T, A>
588where
589 T: ?Sized,
590 A: Allocator,
591{
592 type Target = T;
593
594 fn deref(&self) -> &T {
595 // SAFETY: `self.0` is always properly aligned, dereferenceable and points to an initialized
596 // instance of `T`.
597 unsafe { self.0.as_ref() }
598 }
599}
600
601impl<T, A> DerefMut for Box<T, A>
602where
603 T: ?Sized,
604 A: Allocator,
605{
606 fn deref_mut(&mut self) -> &mut T {
607 // SAFETY: `self.0` is always properly aligned, dereferenceable and points to an initialized
608 // instance of `T`.
609 unsafe { self.0.as_mut() }
610 }
611}
612
613/// # Examples
614///
615/// ```
616/// # use core::borrow::Borrow;
617/// struct Foo<B: Borrow<u32>>(B);
618///
619/// // Owned instance.
620/// let owned = Foo(1);
621///
622/// // Owned instance using `KBox`.
623/// let owned_kbox = Foo(KBox::new(1, GFP_KERNEL)?);
624///
625/// let i = 1;
626/// // Borrowed from `i`.
627/// let borrowed = Foo(&i);
628/// # Ok::<(), Error>(())
629/// ```
630impl<T, A> Borrow<T> for Box<T, A>
631where
632 T: ?Sized,
633 A: Allocator,
634{
635 fn borrow(&self) -> &T {
636 self.deref()
637 }
638}
639
640/// # Examples
641///
642/// ```
643/// # use core::borrow::BorrowMut;
644/// struct Foo<B: BorrowMut<u32>>(B);
645///
646/// // Owned instance.
647/// let owned = Foo(1);
648///
649/// // Owned instance using `KBox`.
650/// let owned_kbox = Foo(KBox::new(1, GFP_KERNEL)?);
651///
652/// let mut i = 1;
653/// // Borrowed from `i`.
654/// let borrowed = Foo(&mut i);
655/// # Ok::<(), Error>(())
656/// ```
657impl<T, A> BorrowMut<T> for Box<T, A>
658where
659 T: ?Sized,
660 A: Allocator,
661{
662 fn borrow_mut(&mut self) -> &mut T {
663 self.deref_mut()
664 }
665}
666
667impl<T, A> fmt::Display for Box<T, A>
668where
669 T: ?Sized + fmt::Display,
670 A: Allocator,
671{
672 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
673 <T as fmt::Display>::fmt(&**self, f)
674 }
675}
676
677impl<T, A> fmt::Debug for Box<T, A>
678where
679 T: ?Sized + fmt::Debug,
680 A: Allocator,
681{
682 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
683 <T as fmt::Debug>::fmt(&**self, f)
684 }
685}
686
687impl<T, A> Drop for Box<T, A>
688where
689 T: ?Sized,
690 A: Allocator,
691{
692 fn drop(&mut self) {
693 let layout = Layout::for_value::<T>(self);
694
695 // SAFETY: The pointer in `self.0` is guaranteed to be valid by the type invariant.
696 unsafe { core::ptr::drop_in_place::<T>(self.deref_mut()) };
697
698 // SAFETY:
699 // - `self.0` was previously allocated with `A`.
700 // - `layout` is equal to the `Layout´ `self.0` was allocated with.
701 unsafe { A::free(self.0.cast(), layout) };
702 }
703}
704
705/// # Examples
706///
707/// ```
708/// use kernel::{
709/// alloc::allocator::VmallocPageIter,
710/// page::{
711/// AsPageIter,
712/// PAGE_SIZE, //
713/// }, //
714/// };
715///
716/// let mut vbox = VBox::new((), GFP_KERNEL)?;
717///
718/// assert!(vbox.page_iter().next().is_none());
719///
720/// let mut vbox = VBox::<[u8; PAGE_SIZE]>::new_uninit(GFP_KERNEL)?;
721///
722/// let page = vbox.page_iter().next().expect("At least one page should be available.\n");
723///
724/// // SAFETY: There is no concurrent read or write to the same page.
725/// unsafe { page.fill_zero_raw(0, PAGE_SIZE)? };
726/// # Ok::<(), Error>(())
727/// ```
728impl<T> AsPageIter for VBox<T> {
729 type Iter<'a>
730 = VmallocPageIter<'a>
731 where
732 T: 'a;
733
734 fn page_iter(&mut self) -> Self::Iter<'_> {
735 let ptr = self.0.cast();
736 let size = core::mem::size_of::<T>();
737
738 // SAFETY:
739 // - `ptr` is a valid pointer to the beginning of a `Vmalloc` allocation.
740 // - `ptr` is guaranteed to be valid for the lifetime of `'a`.
741 // - `size` is the size of the `Vmalloc` allocation `ptr` points to.
742 unsafe { VmallocPageIter::new(ptr, size) }
743 }
744}