axdma/
lib.rs

1//! [ArceOS](https://github.com/arceos-org/arceos) global DMA allocator.
2
3#![no_std]
4
5extern crate alloc;
6
7mod dma;
8
9use core::{alloc::Layout, ptr::NonNull};
10
11use allocator::AllocResult;
12use memory_addr::PhysAddr;
13
14use self::dma::ALLOCATOR;
15
16/// Converts a physical address to a bus address.
17///
18/// It assumes that there is a linear mapping with the offset
19/// [`axconfig::plat::PHYS_BUS_OFFSET`], that maps all the physical memory
20/// to the virtual space at the address plus the offset. So we have
21/// `baddr = paddr + PHYS_BUS_OFFSET`.
22#[inline]
23pub const fn phys_to_bus(paddr: PhysAddr) -> BusAddr {
24    BusAddr::new((paddr.as_usize() + axconfig::plat::PHYS_BUS_OFFSET) as u64)
25}
26
27/// Allocates **coherent** memory that meets Direct Memory Access (DMA)
28/// requirements.
29///
30/// This function allocates a block of memory through the global allocator. The
31/// memory pages must be contiguous, undivided, and have consistent read and
32/// write access.
33///
34/// - `layout`: The memory layout, which describes the size and alignment
35///   requirements of the requested memory.
36///
37/// Returns an [`DMAInfo`] structure containing details about the allocated
38/// memory, such as the starting address and size. If it's not possible to
39/// allocate memory meeting the criteria, returns [`None`].
40///
41/// # Safety
42///
43/// This function is unsafe because it directly interacts with the global
44/// allocator, which can potentially cause memory leaks or other issues if not
45/// used correctly.
46pub unsafe fn alloc_coherent(layout: Layout) -> AllocResult<DMAInfo> {
47    ALLOCATOR.lock().alloc_coherent(layout)
48}
49
50/// Frees coherent memory previously allocated.
51///
52/// This function releases the memory block that was previously allocated and
53/// marked as coherent. It ensures proper deallocation and management of resources
54/// associated with the memory block.
55///
56/// - `dma_info`: An instance of [`DMAInfo`] containing the details of the memory
57///   block to be freed, such as its starting address and size.
58///
59/// # Safety
60///
61/// This function is unsafe because it directly interacts with the global allocator,
62/// which can potentially cause memory leaks or other issues if not used correctly.
63pub unsafe fn dealloc_coherent(dma: DMAInfo, layout: Layout) {
64    ALLOCATOR.lock().dealloc_coherent(dma, layout)
65}
66
67/// A bus memory address.
68///
69/// It's a wrapper type around an [`u64`].
70#[repr(transparent)]
71#[derive(Copy, Clone, Default, Ord, PartialOrd, Eq, PartialEq)]
72pub struct BusAddr(u64);
73
74impl BusAddr {
75    /// Converts an [`u64`] to a physical address.
76    pub const fn new(addr: u64) -> Self {
77        Self(addr)
78    }
79
80    /// Converts the address to an [`u64`].
81    pub const fn as_u64(self) -> u64 {
82        self.0
83    }
84}
85
86impl From<u64> for BusAddr {
87    fn from(value: u64) -> Self {
88        Self::new(value)
89    }
90}
91
92impl core::fmt::Debug for BusAddr {
93    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
94        f.debug_tuple("BusAddr")
95            .field(&format_args!("{:#X}", self.0))
96            .finish()
97    }
98}
99
100/// Represents information related to a DMA operation.
101#[derive(Debug, Clone, Copy)]
102pub struct DMAInfo {
103    /// The address at which the CPU accesses this memory region. This address
104    /// is a virtual memory address used by the CPU to access memory.
105    pub cpu_addr: NonNull<u8>,
106    /// Represents the physical address of this memory region on the bus. The DMA
107    /// controller uses this address to directly access memory.
108    pub bus_addr: BusAddr,
109}
axdma/lib.rs

axdma/
lib.rs
