1 // SPDX-License-Identifier: GPL-2.0 2 3 //! Implementation of the kernel's memory allocation infrastructure. 4 5 pub mod allocator; 6 pub mod kbox; 7 pub mod kvec; 8 pub mod layout; 9 10 pub use self::kbox::Box; 11 pub use self::kbox::KBox; 12 pub use self::kbox::KVBox; 13 pub use self::kbox::VBox; 14 15 pub use self::kvec::IntoIter; 16 pub use self::kvec::KVVec; 17 pub use self::kvec::KVec; 18 pub use self::kvec::VVec; 19 pub use self::kvec::Vec; 20 21 /// Indicates an allocation error. 22 #[derive(Copy, Clone, PartialEq, Eq, Debug)] 23 pub struct AllocError; 24 use core::{alloc::Layout, ptr::NonNull}; 25 26 /// Flags to be used when allocating memory. 27 /// 28 /// They can be combined with the operators `|`, `&`, and `!`. 29 /// 30 /// Values can be used from the [`flags`] module. 31 #[derive(Clone, Copy, PartialEq)] 32 pub struct Flags(u32); 33 34 impl Flags { 35 /// Get the raw representation of this flag. 36 pub(crate) fn as_raw(self) -> u32 { 37 self.0 38 } 39 40 /// Check whether `flags` is contained in `self`. 41 pub fn contains(self, flags: Flags) -> bool { 42 (self & flags) == flags 43 } 44 } 45 46 impl core::ops::BitOr for Flags { 47 type Output = Self; 48 fn bitor(self, rhs: Self) -> Self::Output { 49 Self(self.0 | rhs.0) 50 } 51 } 52 53 impl core::ops::BitAnd for Flags { 54 type Output = Self; 55 fn bitand(self, rhs: Self) -> Self::Output { 56 Self(self.0 & rhs.0) 57 } 58 } 59 60 impl core::ops::Not for Flags { 61 type Output = Self; 62 fn not(self) -> Self::Output { 63 Self(!self.0) 64 } 65 } 66 67 /// Allocation flags. 68 /// 69 /// These are meant to be used in functions that can allocate memory. 70 pub mod flags { 71 use super::Flags; 72 73 /// Zeroes out the allocated memory. 74 /// 75 /// This is normally or'd with other flags. 76 pub const __GFP_ZERO: Flags = Flags(bindings::__GFP_ZERO); 77 78 /// Allow the allocation to be in high memory. 79 /// 80 /// Allocations in high memory may not be mapped into the kernel's address space, so this can't 81 /// be used with `kmalloc` and other similar methods. 82 /// 83 /// This is normally or'd with other flags. 84 pub const __GFP_HIGHMEM: Flags = Flags(bindings::__GFP_HIGHMEM); 85 86 /// Users can not sleep and need the allocation to succeed. 87 /// 88 /// A lower watermark is applied to allow access to "atomic reserves". The current 89 /// implementation doesn't support NMI and few other strict non-preemptive contexts (e.g. 90 /// `raw_spin_lock`). The same applies to [`GFP_NOWAIT`]. 91 pub const GFP_ATOMIC: Flags = Flags(bindings::GFP_ATOMIC); 92 93 /// Typical for kernel-internal allocations. The caller requires `ZONE_NORMAL` or a lower zone 94 /// for direct access but can direct reclaim. 95 pub const GFP_KERNEL: Flags = Flags(bindings::GFP_KERNEL); 96 97 /// The same as [`GFP_KERNEL`], except the allocation is accounted to kmemcg. 98 pub const GFP_KERNEL_ACCOUNT: Flags = Flags(bindings::GFP_KERNEL_ACCOUNT); 99 100 /// For kernel allocations that should not stall for direct reclaim, start physical IO or 101 /// use any filesystem callback. It is very likely to fail to allocate memory, even for very 102 /// small allocations. 103 pub const GFP_NOWAIT: Flags = Flags(bindings::GFP_NOWAIT); 104 105 /// Suppresses allocation failure reports. 106 /// 107 /// This is normally or'd with other flags. 108 pub const __GFP_NOWARN: Flags = Flags(bindings::__GFP_NOWARN); 109 } 110 111 /// The kernel's [`Allocator`] trait. 112 /// 113 /// An implementation of [`Allocator`] can allocate, re-allocate and free memory buffers described 114 /// via [`Layout`]. 115 /// 116 /// [`Allocator`] is designed to be implemented as a ZST; [`Allocator`] functions do not operate on 117 /// an object instance. 118 /// 119 /// In order to be able to support `#[derive(CoercePointee)]` later on, we need to avoid a design 120 /// that requires an `Allocator` to be instantiated, hence its functions must not contain any kind 121 /// of `self` parameter. 122 /// 123 /// # Safety 124 /// 125 /// - A memory allocation returned from an allocator must remain valid until it is explicitly freed. 126 /// 127 /// - Any pointer to a valid memory allocation must be valid to be passed to any other [`Allocator`] 128 /// function of the same type. 129 /// 130 /// - Implementers must ensure that all trait functions abide by the guarantees documented in the 131 /// `# Guarantees` sections. 132 pub unsafe trait Allocator { 133 /// The minimum alignment satisfied by all allocations from this allocator. 134 /// 135 /// # Guarantees 136 /// 137 /// Any pointer allocated by this allocator is guaranteed to be aligned to `MIN_ALIGN` even if 138 /// the requested layout has a smaller alignment. 139 const MIN_ALIGN: usize; 140 141 /// Allocate memory based on `layout` and `flags`. 142 /// 143 /// On success, returns a buffer represented as `NonNull<[u8]>` that satisfies the layout 144 /// constraints (i.e. minimum size and alignment as specified by `layout`). 145 /// 146 /// This function is equivalent to `realloc` when called with `None`. 147 /// 148 /// # Guarantees 149 /// 150 /// When the return value is `Ok(ptr)`, then `ptr` is 151 /// - valid for reads and writes for `layout.size()` bytes, until it is passed to 152 /// [`Allocator::free`] or [`Allocator::realloc`], 153 /// - aligned to `layout.align()`, 154 /// 155 /// Additionally, `Flags` are honored as documented in 156 /// <https://docs.kernel.org/core-api/mm-api.html#mm-api-gfp-flags>. 157 fn alloc(layout: Layout, flags: Flags) -> Result<NonNull<[u8]>, AllocError> { 158 // SAFETY: Passing `None` to `realloc` is valid by its safety requirements and asks for a 159 // new memory allocation. 160 unsafe { Self::realloc(None, layout, Layout::new::<()>(), flags) } 161 } 162 163 /// Re-allocate an existing memory allocation to satisfy the requested `layout`. 164 /// 165 /// If the requested size is zero, `realloc` behaves equivalent to `free`. 166 /// 167 /// If the requested size is larger than the size of the existing allocation, a successful call 168 /// to `realloc` guarantees that the new or grown buffer has at least `Layout::size` bytes, but 169 /// may also be larger. 170 /// 171 /// If the requested size is smaller than the size of the existing allocation, `realloc` may or 172 /// may not shrink the buffer; this is implementation specific to the allocator. 173 /// 174 /// On allocation failure, the existing buffer, if any, remains valid. 175 /// 176 /// The buffer is represented as `NonNull<[u8]>`. 177 /// 178 /// # Safety 179 /// 180 /// - If `ptr == Some(p)`, then `p` must point to an existing and valid memory allocation 181 /// created by this [`Allocator`]; if `old_layout` is zero-sized `p` does not need to be a 182 /// pointer returned by this [`Allocator`]. 183 /// - `ptr` is allowed to be `None`; in this case a new memory allocation is created and 184 /// `old_layout` is ignored. 185 /// - `old_layout` must match the `Layout` the allocation has been created with. 186 /// 187 /// # Guarantees 188 /// 189 /// This function has the same guarantees as [`Allocator::alloc`]. When `ptr == Some(p)`, then 190 /// it additionally guarantees that: 191 /// - the contents of the memory pointed to by `p` are preserved up to the lesser of the new 192 /// and old size, i.e. `ret_ptr[0..min(layout.size(), old_layout.size())] == 193 /// p[0..min(layout.size(), old_layout.size())]`. 194 /// - when the return value is `Err(AllocError)`, then `ptr` is still valid. 195 unsafe fn realloc( 196 ptr: Option<NonNull<u8>>, 197 layout: Layout, 198 old_layout: Layout, 199 flags: Flags, 200 ) -> Result<NonNull<[u8]>, AllocError>; 201 202 /// Free an existing memory allocation. 203 /// 204 /// # Safety 205 /// 206 /// - `ptr` must point to an existing and valid memory allocation created by this [`Allocator`]; 207 /// if `old_layout` is zero-sized `p` does not need to be a pointer returned by this 208 /// [`Allocator`]. 209 /// - `layout` must match the `Layout` the allocation has been created with. 210 /// - The memory allocation at `ptr` must never again be read from or written to. 211 unsafe fn free(ptr: NonNull<u8>, layout: Layout) { 212 // SAFETY: The caller guarantees that `ptr` points at a valid allocation created by this 213 // allocator. We are passing a `Layout` with the smallest possible alignment, so it is 214 // smaller than or equal to the alignment previously used with this allocation. 215 let _ = unsafe { Self::realloc(Some(ptr), Layout::new::<()>(), layout, Flags(0)) }; 216 } 217 } 218 219 /// Returns a properly aligned dangling pointer from the given `layout`. 220 pub(crate) fn dangling_from_layout(layout: Layout) -> NonNull<u8> { 221 let ptr = layout.align() as *mut u8; 222 223 // SAFETY: `layout.align()` (and hence `ptr`) is guaranteed to be non-zero. 224 unsafe { NonNull::new_unchecked(ptr) } 225 } 226