projects/linux·blob master · refs

758 lines · 21.8 KiB

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 { pin_init::raw_try_init(ptr, init(i))? };
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 `raw_try_init(ptr, i)`.
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 #[inline]
462 fn write_init<E>(mut self, init: impl Init<T, E>) -> Result<Self::Initialized, E> {
463 let slot = self.as_mut_ptr();
464 // SAFETY: When init errors/panics, slot will get deallocated but not dropped,
465 // slot is valid.
466 unsafe { pin_init::raw_try_init(slot, init)? };
467 // SAFETY: All fields have been initialized.
468 Ok(unsafe { Box::assume_init(self) })
469 }
470
471 #[inline]
472 fn write_pin_init<E>(mut self, init: impl PinInit<T, E>) -> Result<Pin<Self::Initialized>, E> {
473 let slot = self.as_mut_ptr();
474 // SAFETY: When init errors/panics, slot will get deallocated but not dropped,
475 // slot is valid and will not be moved, because we pin it later.
476 unsafe { pin_init::raw_try_init(slot, init)? };
477 // SAFETY: All fields have been initialized.
478 Ok(unsafe { Box::assume_init(self) }.into())
479 }
480}
481
482impl<T, A> InPlaceInit<T> for Box<T, A>
483where
484 A: Allocator + 'static,
485{
486 type PinnedSelf = Pin<Self>;
487
488 #[inline]
489 fn try_pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Pin<Self>, E>
490 where
491 E: From<AllocError>,
492 {
493 Box::<_, A>::new_uninit(flags)?.write_pin_init(init)
494 }
495
496 #[inline]
497 fn try_init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E>
498 where
499 E: From<AllocError>,
500 {
501 Box::<_, A>::new_uninit(flags)?.write_init(init)
502 }
503}
504
505// SAFETY: The pointer returned by `into_foreign` comes from a well aligned
506// pointer to `T` allocated by `A`.
507unsafe impl<T, A> ForeignOwnable for Box<T, A>
508where
509 A: Allocator,
510{
511 const FOREIGN_ALIGN: usize = if core::mem::align_of::<T>() < A::MIN_ALIGN {
512 A::MIN_ALIGN
513 } else {
514 core::mem::align_of::<T>()
515 };
516
517 type Borrowed<'a>
518 = &'a T
519 where
520 Self: 'a;
521 type BorrowedMut<'a>
522 = &'a mut T
523 where
524 Self: 'a;
525
526 fn into_foreign(self) -> *mut c_void {
527 Box::into_raw(self).cast()
528 }
529
530 unsafe fn from_foreign(ptr: *mut c_void) -> Self {
531 // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
532 // call to `Self::into_foreign`.
533 unsafe { Box::from_raw(ptr.cast()) }
534 }
535
536 unsafe fn borrow<'a>(ptr: *mut c_void) -> &'a T {
537 // SAFETY: The safety requirements of this method ensure that the object remains alive and
538 // immutable for the duration of 'a.
539 unsafe { &*ptr.cast() }
540 }
541
542 unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> &'a mut T {
543 let ptr = ptr.cast();
544 // SAFETY: The safety requirements of this method ensure that the pointer is valid and that
545 // nothing else will access the value for the duration of 'a.
546 unsafe { &mut *ptr }
547 }
548}
549
550// SAFETY: The pointer returned by `into_foreign` comes from a well aligned
551// pointer to `T` allocated by `A`.
552unsafe impl<T, A> ForeignOwnable for Pin<Box<T, A>>
553where
554 A: Allocator,
555{
556 const FOREIGN_ALIGN: usize = <Box<T, A> as ForeignOwnable>::FOREIGN_ALIGN;
557 type Borrowed<'a>
558 = Pin<&'a T>
559 where
560 Self: 'a;
561 type BorrowedMut<'a>
562 = Pin<&'a mut T>
563 where
564 Self: 'a;
565
566 fn into_foreign(self) -> *mut c_void {
567 // SAFETY: We are still treating the box as pinned.
568 Box::into_raw(unsafe { Pin::into_inner_unchecked(self) }).cast()
569 }
570
571 unsafe fn from_foreign(ptr: *mut c_void) -> Self {
572 // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
573 // call to `Self::into_foreign`.
574 unsafe { Pin::new_unchecked(Box::from_raw(ptr.cast())) }
575 }
576
577 unsafe fn borrow<'a>(ptr: *mut c_void) -> Pin<&'a T> {
578 // SAFETY: The safety requirements for this function ensure that the object is still alive,
579 // so it is safe to dereference the raw pointer.
580 // The safety requirements of `from_foreign` also ensure that the object remains alive for
581 // the lifetime of the returned value.
582 let r = unsafe { &*ptr.cast() };
583
584 // SAFETY: This pointer originates from a `Pin<Box<T>>`.
585 unsafe { Pin::new_unchecked(r) }
586 }
587
588 unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> Pin<&'a mut T> {
589 let ptr = ptr.cast();
590 // SAFETY: The safety requirements for this function ensure that the object is still alive,
591 // so it is safe to dereference the raw pointer.
592 // The safety requirements of `from_foreign` also ensure that the object remains alive for
593 // the lifetime of the returned value.
594 let r = unsafe { &mut *ptr };
595
596 // SAFETY: This pointer originates from a `Pin<Box<T>>`.
597 unsafe { Pin::new_unchecked(r) }
598 }
599}
600
601impl<T, A> Deref for Box<T, A>
602where
603 T: ?Sized,
604 A: Allocator,
605{
606 type Target = T;
607
608 fn deref(&self) -> &T {
609 // SAFETY: `self.0` is always properly aligned, dereferenceable and points to an initialized
610 // instance of `T`.
611 unsafe { self.0.as_ref() }
612 }
613}
614
615impl<T, A> DerefMut for Box<T, A>
616where
617 T: ?Sized,
618 A: Allocator,
619{
620 fn deref_mut(&mut self) -> &mut T {
621 // SAFETY: `self.0` is always properly aligned, dereferenceable and points to an initialized
622 // instance of `T`.
623 unsafe { self.0.as_mut() }
624 }
625}
626
627/// # Examples
628///
629/// ```
630/// # use core::borrow::Borrow;
631/// struct Foo<B: Borrow<u32>>(B);
632///
633/// // Owned instance.
634/// let owned = Foo(1);
635///
636/// // Owned instance using `KBox`.
637/// let owned_kbox = Foo(KBox::new(1, GFP_KERNEL)?);
638///
639/// let i = 1;
640/// // Borrowed from `i`.
641/// let borrowed = Foo(&i);
642/// # Ok::<(), Error>(())
643/// ```
644impl<T, A> Borrow<T> for Box<T, A>
645where
646 T: ?Sized,
647 A: Allocator,
648{
649 fn borrow(&self) -> &T {
650 self.deref()
651 }
652}
653
654/// # Examples
655///
656/// ```
657/// # use core::borrow::BorrowMut;
658/// struct Foo<B: BorrowMut<u32>>(B);
659///
660/// // Owned instance.
661/// let owned = Foo(1);
662///
663/// // Owned instance using `KBox`.
664/// let owned_kbox = Foo(KBox::new(1, GFP_KERNEL)?);
665///
666/// let mut i = 1;
667/// // Borrowed from `i`.
668/// let borrowed = Foo(&mut i);
669/// # Ok::<(), Error>(())
670/// ```
671impl<T, A> BorrowMut<T> for Box<T, A>
672where
673 T: ?Sized,
674 A: Allocator,
675{
676 fn borrow_mut(&mut self) -> &mut T {
677 self.deref_mut()
678 }
679}
680
681impl<T, A> fmt::Display for Box<T, A>
682where
683 T: ?Sized + fmt::Display,
684 A: Allocator,
685{
686 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
687 <T as fmt::Display>::fmt(&**self, f)
688 }
689}
690
691impl<T, A> fmt::Debug for Box<T, A>
692where
693 T: ?Sized + fmt::Debug,
694 A: Allocator,
695{
696 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
697 <T as fmt::Debug>::fmt(&**self, f)
698 }
699}
700
701impl<T, A> Drop for Box<T, A>
702where
703 T: ?Sized,
704 A: Allocator,
705{
706 fn drop(&mut self) {
707 let layout = Layout::for_value::<T>(self);
708
709 // SAFETY: The pointer in `self.0` is guaranteed to be valid by the type invariant.
710 unsafe { core::ptr::drop_in_place::<T>(self.deref_mut()) };
711
712 // SAFETY:
713 // - `self.0` was previously allocated with `A`.
714 // - `layout` is equal to the `Layout´ `self.0` was allocated with.
715 unsafe { A::free(self.0.cast(), layout) };
716 }
717}
718
719/// # Examples
720///
721/// ```
722/// use kernel::{
723/// alloc::allocator::VmallocPageIter,
724/// page::{
725/// AsPageIter,
726/// PAGE_SIZE, //
727/// }, //
728/// };
729///
730/// let mut vbox = VBox::new((), GFP_KERNEL)?;
731///
732/// assert!(vbox.page_iter().next().is_none());
733///
734/// let mut vbox = VBox::<[u8; PAGE_SIZE]>::new_uninit(GFP_KERNEL)?;
735///
736/// let page = vbox.page_iter().next().expect("At least one page should be available.\n");
737///
738/// // SAFETY: There is no concurrent read or write to the same page.
739/// unsafe { page.fill_zero_raw(0, PAGE_SIZE)? };
740/// # Ok::<(), Error>(())
741/// ```
742impl<T> AsPageIter for VBox<T> {
743 type Iter<'a>
744 = VmallocPageIter<'a>
745 where
746 T: 'a;
747
748 fn page_iter(&mut self) -> Self::Iter<'_> {
749 let ptr = self.0.cast();
750 let size = core::mem::size_of::<T>();
751
752 // SAFETY:
753 // - `ptr` is a valid pointer to the beginning of a `Vmalloc` allocation.
754 // - `ptr` is guaranteed to be valid for the lifetime of `'a`.
755 // - `size` is the size of the `Vmalloc` allocation `ptr` points to.
756 unsafe { VmallocPageIter::new(ptr, size) }
757 }
758}