1use core::ops::{Deref, DerefMut};
4
5use procmacros::doc_replace;
6
7#[cfg(dma_can_access_psram)]
8use crate::soc::is_valid_psram_address;
9use crate::{
10 dma::{DmaAlignmentError, DmaBufError},
11 soc::{is_uncached_ram_address, is_valid_ram_address},
12};
13
14#[derive(Debug)]
24#[cfg_attr(feature = "defmt", derive(defmt::Format))]
25#[cfg_attr(soc_internal_memory_cached, repr(C, align(64)))] #[cfg_attr(not(soc_internal_memory_cached), repr(C, align(4)))] #[instability::unstable]
28pub struct InternalMemory<T>(T);
29
30impl<T> InternalMemory<T> {
31 #[instability::unstable]
33 pub const fn new(init: T) -> Self {
34 Self(init)
35 }
36
37 #[instability::unstable]
42 pub const fn as_ptr(&self) -> *const T {
43 &raw const self.0
44 }
45
46 #[instability::unstable]
52 pub fn get_mut(&mut self) -> DmaAlignedMut<'_, T> {
53 assert!(is_valid_ram_address(&raw const self.0 as usize));
54 DmaAlignedMut(&mut self.0)
55 }
56
57 #[instability::unstable]
68 pub fn get_ref(&self) -> DmaAlignedRef<'_, T> {
69 assert!(is_valid_ram_address(&raw const self.0 as usize));
70 DmaAlignedRef(&self.0)
71 }
72}
73
74#[cfg(dma_can_access_psram)]
76pub(crate) const PSRAM_CACHE_LINE: usize = cfg_select! {
77 soc_internal_memory_cached => 128,
83 esp32s31 => 64,
84 any(esp32, esp32c5, esp32c61) => 32, _ => crate::soc::CONFIG_DATA_CACHE_LINE_SIZE,
86};
87
88pub(crate) fn region_dma_alignment(addr: usize) -> Option<usize> {
95 if is_uncached_ram_address(addr) {
97 return Some(1);
98 }
99
100 if is_valid_ram_address(addr) {
101 return Some(core::mem::align_of::<InternalMemory<()>>());
102 }
103
104 #[cfg(dma_can_access_psram)]
105 if is_valid_psram_address(addr) {
106 return Some(PSRAM_CACHE_LINE);
107 }
108
109 None
110}
111
112fn validate_dma_alignment(addr: usize, size: usize) -> Result<(), DmaBufError> {
115 if size == 0 {
117 return Ok(());
118 }
119
120 let Some(alignment) = region_dma_alignment(addr) else {
121 return Err(DmaBufError::UnsupportedMemoryRegion);
122 };
123
124 if !size.is_multiple_of(alignment) {
125 return Err(DmaBufError::InvalidAlignment(DmaAlignmentError::Size));
126 }
127 if !addr.is_multiple_of(alignment) {
128 return Err(DmaBufError::InvalidAlignment(DmaAlignmentError::Address));
129 }
130
131 Ok(())
132}
133
134#[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
137pub(crate) fn region_needs_cache_op(addr: usize, size: usize) -> bool {
138 if size == 0 {
140 return false;
141 }
142
143 let mut in_cached_region = false;
144
145 #[cfg(soc_internal_memory_cached)]
146 {
147 in_cached_region |= is_valid_ram_address(addr);
148 }
149 #[cfg(dma_can_access_psram)]
150 {
151 in_cached_region |= is_valid_psram_address(addr);
152 }
153
154 in_cached_region
155}
156
157#[derive(Debug)]
159#[cfg_attr(feature = "defmt", derive(defmt::Format))]
160#[instability::unstable]
161pub struct DmaAlignedMut<'a, T>(&'a mut T)
162where
163 T: ?Sized;
164
165impl<'a, T: ?Sized> DmaAlignedMut<'a, T> {
166 #[doc_replace(
167 "align_req" => {
168 cfg(soc_internal_memory_cached) => "64",
169 _ => "4"
170 },
171 "uncached_note" => {
172 cfg(esp32p4) => "This does not apply to `#[ram(unstable(uncached))]` variables.",
173 _ => ""
174 }
175 )]
176 #[instability::unstable]
182 pub fn new(ptr: &'a mut T) -> Result<Self, DmaBufError> {
183 let addr = ptr as *mut T as *mut () as usize;
184 validate_dma_alignment(addr, core::mem::size_of_val(ptr))?;
185 Ok(Self(ptr))
186 }
187
188 #[instability::unstable]
196 pub const unsafe fn new_unchecked(ptr: &'a mut T) -> Self {
197 Self(ptr)
198 }
199
200 #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
201 fn do_cache_op(&self) -> bool {
202 region_needs_cache_op(
203 self.0 as *const T as *const () as usize,
204 core::mem::size_of_val(self.0),
205 )
206 }
207
208 #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
210 #[instability::unstable]
211 pub fn writeback(&mut self) {
212 if !self.do_cache_op() {
213 return;
214 }
215
216 unsafe {
218 crate::soc::cache_writeback_addr(
219 self.0 as *const T as *const () as u32,
220 core::mem::size_of_val(self.0) as u32,
221 );
222 }
223 }
224
225 #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
227 #[instability::unstable]
228 pub fn invalidate(&self) {
229 if !self.do_cache_op() {
230 return;
231 }
232
233 unsafe {
235 crate::soc::cache_invalidate_addr(
236 self.0 as *const T as *const () as u32,
237 core::mem::size_of_val(self.0) as u32,
238 );
239 }
240 }
241
242 pub fn into_inner(self) -> &'a mut T {
244 self.0
245 }
246
247 pub fn reborrow<'b>(&'b mut self) -> DmaAlignedMut<'b, T> {
249 DmaAlignedMut(self.0)
250 }
251}
252
253impl<'a, T, const N: usize> DmaAlignedMut<'a, [T; N]> {
254 pub fn unsize(self) -> DmaAlignedMut<'a, [T]> {
256 DmaAlignedMut(self.0)
257 }
258}
259
260impl<'a, T: ?Sized> Deref for DmaAlignedMut<'a, T> {
261 type Target = T;
262
263 fn deref(&self) -> &Self::Target {
264 self.0
265 }
266}
267
268impl<'a, T: ?Sized> DerefMut for DmaAlignedMut<'a, T> {
269 fn deref_mut(&mut self) -> &mut Self::Target {
270 self.0
271 }
272}
273
274#[derive(Debug)]
283#[cfg_attr(feature = "defmt", derive(defmt::Format))]
284#[instability::unstable]
285pub struct DmaAlignedRef<'a, T>(&'a T)
286where
287 T: ?Sized;
288
289impl<'a, T: ?Sized> DmaAlignedRef<'a, T> {
290 #[doc_replace(
291 "align_req" => {
292 cfg(soc_internal_memory_cached) => "64",
293 _ => "4"
294 },
295 "uncached_note" => {
296 cfg(esp32p4) => "This does not apply to `#[ram(unstable(uncached))]` values.",
297 _ => ""
298 }
299 )]
300 #[instability::unstable]
306 pub fn new(ptr: &'a T) -> Result<Self, DmaBufError> {
307 let addr = ptr as *const T as *const () as usize;
308 validate_dma_alignment(addr, core::mem::size_of_val(ptr))?;
309 Ok(Self(ptr))
310 }
311
312 #[instability::unstable]
320 pub const unsafe fn new_unchecked(ptr: &'a T) -> Self {
321 Self(ptr)
322 }
323
324 #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
325 fn do_cache_op(&self) -> bool {
326 region_needs_cache_op(
327 self.0 as *const T as *const () as usize,
328 core::mem::size_of_val(self.0),
329 )
330 }
331
332 #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
334 #[instability::unstable]
335 pub fn invalidate(&self) {
336 if !self.do_cache_op() {
337 return;
338 }
339
340 unsafe {
343 crate::soc::cache_invalidate_addr(
344 self.0 as *const T as *const () as u32,
345 core::mem::size_of_val(self.0) as u32,
346 );
347 }
348 }
349
350 #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]
356 #[instability::unstable]
357 pub fn writeback(&self) {
358 if !self.do_cache_op() {
359 return;
360 }
361
362 unsafe {
365 crate::soc::cache_writeback_addr(
366 self.0 as *const T as *const () as u32,
367 core::mem::size_of_val(self.0) as u32,
368 );
369 }
370 }
371
372 pub fn into_inner(self) -> &'a T {
374 self.0
375 }
376}
377
378impl<'a, T: ?Sized> Deref for DmaAlignedRef<'a, T> {
379 type Target = T;
380
381 fn deref(&self) -> &Self::Target {
382 self.0
383 }
384}