|
| 1 | +// SPDX-License-Identifier: MIT OR Apache-2.0 |
| 2 | + |
| 3 | +//! Defines wrapper for a region mapped by PCI Root Bridge I/O protocol. |
| 4 | +
|
| 5 | +use crate::StatusExt; |
| 6 | +use crate::proto::pci::root_bridge::buffer::PciBuffer; |
| 7 | +use core::ffi::c_void; |
| 8 | +use core::fmt::Debug; |
| 9 | +use core::mem::ManuallyDrop; |
| 10 | +use core::ptr; |
| 11 | +use log::{error, trace}; |
| 12 | +use uefi_raw::Status; |
| 13 | +use uefi_raw::protocol::pci::root_bridge::PciRootBridgeIoProtocol; |
| 14 | + |
| 15 | +/// Represents a region of memory mapped and made visible to devices |
| 16 | +/// by PCI Root Bridge I/O protocol. |
| 17 | +/// The region will be unmapped automatically when it is dropped. |
| 18 | +/// |
| 19 | +/// # Lifetime |
| 20 | +/// `'p` is the lifetime for Protocol. |
| 21 | +/// Protocol must be available for the entire lifetime of this struct |
| 22 | +/// as it provides its unmap function. |
| 23 | +/// |
| 24 | +/// # Invariant |
| 25 | +/// Value stored in its internal buffer cannot have a larger alignment requirement than page size, |
| 26 | +/// which is 4096. |
| 27 | +/// |
| 28 | +/// # Safety |
| 29 | +/// Value stored in its internal buffer cannot be larger than the buffer's size, |
| 30 | +/// which is 4096 * `pages` |
| 31 | +#[derive(Debug)] |
| 32 | +pub struct PciMappedRegion<'p: 'r, 'r, T> { |
| 33 | + pub(super) host: &'r PciBuffer<'p, T>, |
| 34 | + /// Bytes size of the mapped region. |
| 35 | + pub(super) length: usize, |
| 36 | + pub(super) device_address: usize, |
| 37 | + pub(super) key: *const c_void, |
| 38 | + pub(super) proto: &'p PciRootBridgeIoProtocol, |
| 39 | +} |
| 40 | + |
| 41 | +/// Represents a region of memory that a PCI device can use. |
| 42 | +/// CPU cannot use address in this struct to deference memory. |
| 43 | +/// This is effectively the same as rust's slice type. |
| 44 | +/// This type only exists to prevent users from accidentally dereferencing it. |
| 45 | +#[derive(Debug, Copy, Clone)] |
| 46 | +pub struct DeviceRegion { |
| 47 | + /// Starting address of the memory region |
| 48 | + pub device_address: usize, |
| 49 | + |
| 50 | + /// Byte length of the memory region. |
| 51 | + pub length: usize, |
| 52 | +} |
| 53 | + |
| 54 | +impl<'p: 'r, 'r, T> PciMappedRegion<'p, 'r, T> { |
| 55 | + /// Returns access to the underlying buffer. |
| 56 | + #[must_use] |
| 57 | + pub const fn host(&'r self) -> &'r PciBuffer<'p, T> { |
| 58 | + self.host |
| 59 | + } |
| 60 | + |
| 61 | + /// Returns mapped address and length of a region. |
| 62 | + /// |
| 63 | + /// # Safety |
| 64 | + /// **Returned address cannot be used to reference memory from CPU!** |
| 65 | + /// **Do not cast it back to pointer or reference** |
| 66 | + #[must_use] |
| 67 | + pub const fn region(&self) -> DeviceRegion { |
| 68 | + DeviceRegion { |
| 69 | + device_address: self.device_address, |
| 70 | + length: self.length, |
| 71 | + } |
| 72 | + } |
| 73 | + |
| 74 | + /// Unmaps underlying memory region. |
| 75 | + /// It is recommended to use this over its Drop implementation, which will only log an error |
| 76 | + /// if unmapping fails. |
| 77 | + pub fn unmap(self) -> crate::Result<PciBuffer<'p, T>> { |
| 78 | + let region = ManuallyDrop::new(self); |
| 79 | + match region.unmap_inner() { |
| 80 | + // SAFETY: |
| 81 | + // This technically creates an alias to its underlying ExclusivePtr value, |
| 82 | + // but we don't do any read/writes through it. |
| 83 | + // And the original is discarded right away. |
| 84 | + Ok(_) => unsafe { Ok(ptr::read(region.host)) }, |
| 85 | + Err(e) => Err(e), |
| 86 | + } |
| 87 | + } |
| 88 | + |
| 89 | + fn unmap_inner(&self) -> crate::Result { |
| 90 | + unsafe { (self.proto.unmap)(self.proto, self.key) }.to_result_with_val(|| { |
| 91 | + let host_start = self.host.base_ptr().addr(); |
| 92 | + let host_end = host_start + self.length; |
| 93 | + let device_start = self.device_address; |
| 94 | + let device_end = device_start + self.length; |
| 95 | + trace!( |
| 96 | + "Region [Host 0x{:X}..0x{:X}] -> [Device 0x{:}..0x{:X}] was unmapped", |
| 97 | + host_start, host_end, device_start, device_end |
| 98 | + ); |
| 99 | + }) |
| 100 | + } |
| 101 | +} |
| 102 | + |
| 103 | +impl<'p: 'r, 'r, T> Drop for PciMappedRegion<'p, 'r, T> { |
| 104 | + fn drop(&mut self) { |
| 105 | + let Err(status) = self.unmap_inner() else { |
| 106 | + return; |
| 107 | + }; |
| 108 | + match status.status() { |
| 109 | + // Effectively unreachable path |
| 110 | + Status::SUCCESS => {} |
| 111 | + |
| 112 | + Status::INVALID_PARAMETER => { |
| 113 | + error!("This region was not mapped using PciRootBridgeIo::map"); |
| 114 | + } |
| 115 | + Status::DEVICE_ERROR => { |
| 116 | + error!("The data was not committed to the target system memory."); |
| 117 | + } |
| 118 | + etc => { |
| 119 | + error!( |
| 120 | + "Unexpected error occurred when unmapping device memory: {:?}", |
| 121 | + etc |
| 122 | + ); |
| 123 | + } |
| 124 | + } |
| 125 | + } |
| 126 | +} |
| 127 | + |
| 128 | +impl DeviceRegion { |
| 129 | + /// Changes length of a given region. |
| 130 | + /// The new region must have a shorter length to ensure |
| 131 | + /// it won't contain invalid memory address. |
| 132 | + #[must_use] |
| 133 | + pub fn with_length(mut self, new_length: usize) -> Self { |
| 134 | + assert!(new_length <= self.length); |
| 135 | + self.length = new_length; |
| 136 | + self |
| 137 | + } |
| 138 | +} |
0 commit comments