1 // SPDX-License-Identifier: GPL-2.0 2 3 use super::Vmalloc; 4 use crate::page; 5 use core::marker::PhantomData; 6 use core::ptr::NonNull; 7 8 /// An [`Iterator`] of [`page::BorrowedPage`] items owned by a [`Vmalloc`] allocation. 9 /// 10 /// # Guarantees 11 /// 12 /// The pages iterated by the [`Iterator`] appear in the order as they are mapped in the CPU's 13 /// virtual address space ascendingly. 14 /// 15 /// # Invariants 16 /// 17 /// - `buf` is a valid and [`page::PAGE_SIZE`] aligned pointer into a [`Vmalloc`] allocation. 18 /// - `size` is the number of bytes from `buf` until the end of the [`Vmalloc`] allocation `buf` 19 /// points to. 20 pub struct VmallocPageIter<'a> { 21 /// The base address of the [`Vmalloc`] buffer. 22 buf: NonNull<u8>, 23 /// The size of the buffer pointed to by `buf` in bytes. 24 size: usize, 25 /// The current page index of the [`Iterator`]. 26 index: usize, 27 _p: PhantomData<page::BorrowedPage<'a>>, 28 } 29 30 impl<'a> Iterator for VmallocPageIter<'a> { 31 type Item = page::BorrowedPage<'a>; 32 33 fn next(&mut self) -> Option<Self::Item> { 34 let offset = self.index.checked_mul(page::PAGE_SIZE)?; 35 36 // Even though `self.size()` may be smaller than `Self::page_count() * page::PAGE_SIZE`, it 37 // is always a number between `(Self::page_count() - 1) * page::PAGE_SIZE` and 38 // `Self::page_count() * page::PAGE_SIZE`, hence the check below is sufficient. 39 if offset < self.size() { 40 self.index += 1; 41 } else { 42 return None; 43 } 44 45 // SAFETY: `offset` is in the interval `[0, (self.page_count() - 1) * page::PAGE_SIZE]`, 46 // hence the resulting pointer is guaranteed to be within the same allocation. 47 let ptr = unsafe { self.buf.add(offset) }; 48 49 // SAFETY: 50 // - `ptr` is a valid pointer to a `Vmalloc` allocation. 51 // - `ptr` is valid for the duration of `'a`. 52 Some(unsafe { Vmalloc::to_page(ptr) }) 53 } 54 55 fn size_hint(&self) -> (usize, Option<usize>) { 56 let remaining = self.page_count().saturating_sub(self.index); 57 58 (remaining, Some(remaining)) 59 } 60 } 61 62 impl<'a> VmallocPageIter<'a> { 63 /// Creates a new [`VmallocPageIter`] instance. 64 /// 65 /// # Safety 66 /// 67 /// - `buf` must be a [`page::PAGE_SIZE`] aligned pointer into a [`Vmalloc`] allocation. 68 /// - `buf` must be valid for at least the lifetime of `'a`. 69 /// - `size` must be the number of bytes from `buf` until the end of the [`Vmalloc`] allocation 70 /// `buf` points to. 71 pub unsafe fn new(buf: NonNull<u8>, size: usize) -> Self { 72 // INVARIANT: By the safety requirements, `buf` is a valid and `page::PAGE_SIZE` aligned 73 // pointer into a [`Vmalloc`] allocation. 74 Self { 75 buf, 76 size, 77 index: 0, 78 _p: PhantomData, 79 } 80 } 81 82 /// Returns the size of the backing [`Vmalloc`] allocation in bytes. 83 /// 84 /// Note that this is the size the [`Vmalloc`] allocation has been allocated with. Hence, this 85 /// number may be smaller than `[`Self::page_count`] * [`page::PAGE_SIZE`]`. 86 #[inline] 87 pub fn size(&self) -> usize { 88 self.size 89 } 90 91 /// Returns the number of pages owned by the backing [`Vmalloc`] allocation. 92 #[inline] 93 pub fn page_count(&self) -> usize { 94 self.size().div_ceil(page::PAGE_SIZE) 95 } 96 } 97