ax_memory_addr/
addr.rs

1use core::cmp::Ord;
2
3/// A trait for memory address types.
4///
5/// Memory address types here include both physical and virtual addresses, as
6/// well as any other similar types like guest physical addresses in a
7/// hypervisor.
8///
9/// This trait is automatically implemented for any type that is `Copy`,
10/// `From<usize>`, `Into<usize>`, and `Ord`, providing a set of utility methods
11/// for address alignment and arithmetic.
12pub trait MemoryAddr:
13    // The address type should be trivially copyable. This implies `Clone`.
14    Copy
15    // The address type should be convertible to and from `usize`.
16    + From<usize>
17    + Into<usize>
18    // The address type should be comparable.
19    + Ord
20{
21    // No required methods for now. Following are some utility methods.
22
23    //
24    // This section contains utility methods for address alignment.
25    //
26
27    /// Aligns the address downwards to the given alignment.
28    #[inline]
29    #[must_use = "this returns a new address, without modifying the original"]
30    fn align_down<U>(self, align: U) -> Self
31    where
32        U: Into<usize>,
33    {
34        Self::from(crate::align_down(self.into(), align.into()))
35    }
36
37    /// Aligns the address upwards to the given alignment.
38    #[inline]
39    #[must_use = "this returns a new address, without modifying the original"]
40    fn align_up<U>(self, align: U) -> Self
41    where
42        U: Into<usize>,
43    {
44        Self::from(crate::align_up(self.into(), align.into()))
45    }
46
47    /// Returns the offset of the address within the given alignment.
48    #[inline]
49    #[must_use = "this function has no side effects, so it can be removed if the return value is not used"]
50    fn align_offset<U>(self, align: U) -> usize
51    where
52        U: Into<usize>,
53    {
54        crate::align_offset(self.into(), align.into())
55    }
56
57    /// Checks whether the address has the demanded alignment.
58    #[inline]
59    #[must_use = "this function has no side effects, so it can be removed if the return value is not used"]
60    fn is_aligned<U>(self, align: U) -> bool
61    where
62        U: Into<usize>,
63    {
64        crate::is_aligned(self.into(), align.into())
65    }
66
67    /// Aligns the address downwards to 4096 (bytes).
68    #[inline]
69    #[must_use = "this returns a new address, without modifying the original"]
70    fn align_down_4k(self) -> Self {
71        Self::from(crate::align_down(self.into(), crate::PAGE_SIZE_4K))
72    }
73
74    /// Aligns the address upwards to 4096 (bytes).
75    #[inline]
76    #[must_use = "this returns a new address, without modifying the original"]
77    fn align_up_4k(self) -> Self {
78        Self::from(crate::align_up(self.into(), crate::PAGE_SIZE_4K))
79    }
80
81    /// Returns the offset of the address within a 4K-sized page.
82    #[inline]
83    #[must_use = "this function has no side effects, so it can be removed if the return value is not used"]
84    fn align_offset_4k(self) -> usize {
85        crate::align_offset(self.into(), crate::PAGE_SIZE_4K)
86    }
87
88    /// Checks whether the address is 4K-aligned.
89    #[inline]
90    #[must_use = "this function has no side effects, so it can be removed if the return value is not used"]
91    fn is_aligned_4k(self) -> bool {
92        crate::is_aligned(self.into(), crate::PAGE_SIZE_4K)
93    }
94
95    //
96    // This section contains utility methods for address arithmetic.
97    //
98
99    /// Adds a given offset to the address to get a new address.
100    /// 
101    /// # Panics
102    /// 
103    /// Panics if the result overflows.
104    #[inline]
105    #[must_use = "this returns a new address, without modifying the original"]
106    fn offset(self, offset: isize) -> Self {
107        // todo: use `strict_add_signed` when it's stable.
108        Self::from(usize::checked_add_signed(self.into(), offset).expect("overflow in `MemoryAddr::offset`"))
109    }
110
111    /// Adds a given offset to the address to get a new address.
112    /// 
113    /// Unlike `offset`, this method always wraps around on overflow.
114    #[inline]
115    #[must_use = "this returns a new address, without modifying the original"]
116    fn wrapping_offset(self, offset: isize) -> Self {
117        Self::from(usize::wrapping_add_signed(self.into(), offset))
118    }
119
120    /// Gets the distance between two addresses.
121    /// 
122    /// # Panics
123    /// 
124    /// Panics if the result is not representable by `isize`.
125    #[inline]
126    #[must_use = "this function has no side effects, so it can be removed if the return value is not used"]
127    fn offset_from(self, base: Self) -> isize {
128        let result = usize::wrapping_sub(self.into(), base.into()) as isize;
129        if (result > 0) ^ (base < self) {
130            // The result has overflowed.
131            panic!("overflow in `MemoryAddr::offset_from`");
132        } else {
133            result
134        }
135    }
136
137    /// Adds a given **unsigned** offset to the address to get a new address.
138    /// 
139    /// This method is similar to `offset`, but it takes an unsigned offset.
140    /// 
141    /// # Panics
142    /// 
143    /// Panics if the result overflows.
144    #[inline]
145    #[must_use = "this returns a new address, without modifying the original"]
146    fn add(self, rhs: usize) -> Self {
147        Self::from(usize::checked_add(self.into(), rhs).expect("overflow in `MemoryAddr::add`"))
148    }
149
150    /// Adds a given **unsigned** offset to the address to get a new address.
151    /// 
152    /// Unlike `add`, this method always wraps around on overflow.
153    #[inline]
154    #[must_use = "this returns a new address, without modifying the original"]
155    fn wrapping_add(self, rhs: usize) -> Self {
156        Self::from(usize::wrapping_add(self.into(), rhs))
157    }
158
159    /// Adds a given **unsigned** offset to the address to get a new address.
160    /// 
161    /// Unlike `add`, this method returns a tuple of the new address and a boolean indicating
162    /// whether the addition has overflowed.
163    #[inline]
164    #[must_use = "this returns a new address, without modifying the original"]
165    fn overflowing_add(self, rhs: usize) -> (Self, bool) {
166        let (result, overflow) = self.into().overflowing_add(rhs);
167        (Self::from(result), overflow)
168    }
169
170    /// Adds a given **unsigned** offset to the address to get a new address.
171    /// 
172    /// Unlike `add`, this method returns `None` on overflow.
173    #[inline]
174    #[must_use = "this returns a new address, without modifying the original"]
175    fn checked_add(self, rhs: usize) -> Option<Self> {
176        usize::checked_add(self.into(), rhs).map(Self::from)
177    }
178
179    /// Subtracts a given **unsigned** offset from the address to get a new address.
180    /// 
181    /// This method is similar to `offset(-rhs)`, but it takes an unsigned offset. 
182    /// 
183    /// # Panics
184    /// 
185    /// Panics if the result overflows.
186    #[inline]
187    #[must_use = "this returns a new address, without modifying the original"]
188    fn sub(self, rhs: usize) -> Self {
189        Self::from(usize::checked_sub(self.into(), rhs).expect("overflow in `MemoryAddr::sub`"))
190    }
191
192    /// Subtracts a given **unsigned** offset from the address to get a new address.
193    /// 
194    /// Unlike `sub`, this method always wraps around on overflowed.
195    #[inline]
196    #[must_use = "this returns a new address, without modifying the original"]
197    fn wrapping_sub(self, rhs: usize) -> Self {
198        Self::from(usize::wrapping_sub(self.into(), rhs))
199    }
200
201    /// Subtracts a given **unsigned** offset from the address to get a new address.
202    /// 
203    /// Unlike `sub`, this method returns a tuple of the new address and a boolean indicating
204    /// whether the subtraction has overflowed.
205    #[inline]
206    #[must_use = "this returns a new address, without modifying the original"]
207    fn overflowing_sub(self, rhs: usize) -> (Self, bool) {
208        let (result, overflow) = self.into().overflowing_sub(rhs);
209        (Self::from(result), overflow)
210    }
211
212    /// Subtracts a given **unsigned** offset from the address to get a new address.
213    /// 
214    /// Unlike `sub`, this method returns `None` on overflow.
215    #[inline]
216    #[must_use = "this returns a new address, without modifying the original"]
217    fn checked_sub(self, rhs: usize) -> Option<Self> {
218        usize::checked_sub(self.into(), rhs).map(Self::from)
219    }
220
221    /// Subtracts another address from the address to get the offset between them.
222    /// 
223    /// # Panics
224    /// 
225    /// Panics if the result overflows.
226    #[inline]
227    #[must_use = "this function has no side effects, so it can be removed if the return value is not used"]
228    fn sub_addr(self, rhs: Self) -> usize {
229        usize::checked_sub(self.into(), rhs.into()).expect("overflow in `MemoryAddr::sub_addr`")
230    }
231
232    /// Subtracts another address from the address to get the offset between them.
233    /// 
234    /// Unlike `sub_addr`, this method always wraps around on overflow.
235    #[inline]
236    #[must_use = "this function has no side effects, so it can be removed if the return value is not used"]
237    fn wrapping_sub_addr(self, rhs: Self) -> usize {
238        usize::wrapping_sub(self.into(), rhs.into())
239    }
240
241    /// Subtracts another address from the address to get the offset between them.
242    /// 
243    /// Unlike `sub_addr`, this method returns a tuple of the offset and a boolean indicating
244    /// whether the subtraction has overflowed.
245    #[inline]
246    #[must_use = "this function has no side effects, so it can be removed if the return value is not used"]
247    fn overflowing_sub_addr(self, rhs: Self) -> (usize, bool) {
248        usize::overflowing_sub(self.into(), rhs.into())
249    }
250
251    /// Subtracts another address from the address to get the offset between them.
252    /// 
253    /// Unlike `sub_addr`, this method returns `None` on overflow.
254    #[inline]
255    #[must_use = "this function has no side effects, so it can be removed if the return value is not used"]
256    fn checked_sub_addr(self, rhs: Self) -> Option<usize> {
257        usize::checked_sub(self.into(), rhs.into())
258    }
259}
260
261/// Implement the `MemoryAddr` trait for any type that is `Copy`, `From<usize>`,
262/// `Into<usize>`, and `Ord`.
263impl<T> MemoryAddr for T where T: Copy + From<usize> + Into<usize> + Ord {}
264
265/// Creates a new address type by wrapping an `usize`.
266///
267/// For each `$vis type $name;`, this macro generates the following items:
268/// - Definition of the new address type `$name`, which contains a single
269///   private unnamed field of type `usize`.
270/// - Default implementations (i.e. derived implementations) for the following
271///   traits:
272///   - `Copy`, `Clone`,
273///   - `Default`,
274///   - `Ord`, `PartialOrd`, `Eq`, and `PartialEq`.
275/// - Implementations for the following traits:
276///   - `From<usize>`, `Into<usize>` (by implementing `From<$name> for usize`),
277///   - `Add<usize>`, `AddAssign<usize>`, `Sub<usize>`, `SubAssign<usize>`, and
278///   - `Sub<$name>`.
279/// - Two `const` methods to convert between the address type and `usize`:
280///   - `from_usize`, which converts an `usize` to the address type, and
281///   - `as_usize`, which converts the address type to an `usize`.
282///
283/// # Example
284///
285/// ```
286/// use ax_memory_addr::{MemoryAddr, def_usize_addr};
287///
288/// def_usize_addr! {
289///     /// A example address type.
290///     #[derive(Debug)]
291///     pub type ExampleAddr;
292/// }
293///
294/// # fn main() {
295/// const EXAMPLE: ExampleAddr = ExampleAddr::from_usize(0x1234);
296/// const EXAMPLE_USIZE: usize = EXAMPLE.as_usize();
297/// assert_eq!(EXAMPLE_USIZE, 0x1234);
298/// assert_eq!(
299///     EXAMPLE.align_down(0x10usize),
300///     ExampleAddr::from_usize(0x1230)
301/// );
302/// assert_eq!(EXAMPLE.align_up_4k(), ExampleAddr::from_usize(0x2000));
303/// # }
304/// ```
305#[macro_export]
306macro_rules! def_usize_addr {
307    (
308        $(#[$meta:meta])*
309        $vis:vis type $name:ident;
310
311        $($tt:tt)*
312    ) => {
313        #[repr(transparent)]
314        #[derive(Copy, Clone, Default, Ord, PartialOrd, Eq, PartialEq)]
315        $(#[$meta])*
316        pub struct $name(usize);
317
318        impl $name {
319            #[doc = concat!("Converts an `usize` to an [`", stringify!($name), "`].")]
320            #[inline]
321            pub const fn from_usize(addr: usize) -> Self {
322                Self(addr)
323            }
324
325            #[doc = concat!("Converts an [`", stringify!($name), "`] to an `usize`.")]
326            #[inline]
327            pub const fn as_usize(self) -> usize {
328                self.0
329            }
330        }
331
332        impl From<usize> for $name {
333            #[inline]
334            fn from(addr: usize) -> Self {
335                Self(addr)
336            }
337        }
338
339        impl From<$name> for usize {
340            #[inline]
341            fn from(addr: $name) -> usize {
342                addr.0
343            }
344        }
345
346        impl core::ops::Add<usize> for $name {
347            type Output = Self;
348            #[inline]
349            fn add(self, rhs: usize) -> Self {
350                Self(self.0 + rhs)
351            }
352        }
353
354        impl core::ops::AddAssign<usize> for $name {
355            #[inline]
356            fn add_assign(&mut self, rhs: usize) {
357                self.0 += rhs;
358            }
359        }
360
361        impl core::ops::Sub<usize> for $name {
362            type Output = Self;
363            #[inline]
364            fn sub(self, rhs: usize) -> Self {
365                Self(self.0 - rhs)
366            }
367        }
368
369        impl core::ops::SubAssign<usize> for $name {
370            #[inline]
371            fn sub_assign(&mut self, rhs: usize) {
372                self.0 -= rhs;
373            }
374        }
375
376        impl core::ops::Sub<$name> for $name {
377            type Output = usize;
378            #[inline]
379            fn sub(self, rhs: $name) -> usize {
380                self.0 - rhs.0
381            }
382        }
383
384        $crate::def_usize_addr!($($tt)*);
385    };
386    () => {};
387}
388
389/// Creates implementations for the [`Debug`](core::fmt::Debug),
390/// [`LowerHex`](core::fmt::LowerHex), and [`UpperHex`](core::fmt::UpperHex)
391/// traits for the given address types defined by the [`def_usize_addr`].
392///
393/// For each `$name = $format;`, this macro generates the following items:
394/// - An implementation of [`core::fmt::Debug`] for the address type `$name`,
395///   which formats the address with `format_args!($format,
396///   format_args!("{:#x}", self.0))`,
397/// - An implementation of [`core::fmt::LowerHex`] for the address type `$name`,
398///   which formats the address in the same way as [`core::fmt::Debug`],
399/// - An implementation of [`core::fmt::UpperHex`] for the address type `$name`,
400///   which formats the address with `format_args!($format,
401///   format_args!("{:#X}", self.0))`.
402///
403/// # Example
404///
405/// ```
406/// use ax_memory_addr::{PhysAddr, VirtAddr, def_usize_addr, def_usize_addr_formatter};
407///
408/// def_usize_addr! {
409///     /// An example address type.
410///     pub type ExampleAddr;
411/// }
412///
413/// def_usize_addr_formatter! {
414///     ExampleAddr = "EA:{}";
415/// }
416///
417/// # fn main() {
418/// assert_eq!(format!("{:?}", PhysAddr::from(0x1abc)), "PA:0x1abc");
419/// assert_eq!(format!("{:x}", VirtAddr::from(0x1abc)), "VA:0x1abc");
420/// assert_eq!(format!("{:X}", ExampleAddr::from(0x1abc)), "EA:0x1ABC");
421/// # }
422/// ```
423#[macro_export]
424macro_rules! def_usize_addr_formatter {
425    (
426        $name:ident = $format:literal;
427
428        $($tt:tt)*
429    ) => {
430        impl core::fmt::Debug for $name {
431            fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
432                f.write_fmt(format_args!($format, format_args!("{:#x}", self.0)))
433            }
434        }
435
436        impl core::fmt::LowerHex for $name {
437            fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
438                f.write_fmt(format_args!($format, format_args!("{:#x}", self.0)))
439            }
440        }
441
442        impl core::fmt::UpperHex for $name {
443            fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
444                f.write_fmt(format_args!($format, format_args!("{:#X}", self.0)))
445            }
446        }
447
448        $crate::def_usize_addr_formatter!($($tt)*);
449    };
450    () => {};
451}
452
453def_usize_addr! {
454    /// A physical memory address.
455    pub type PhysAddr;
456
457    /// A virtual memory address.
458    pub type VirtAddr;
459}
460
461def_usize_addr_formatter! {
462    PhysAddr = "PA:{}";
463    VirtAddr = "VA:{}";
464}
465
466impl VirtAddr {
467    /// Creates a new virtual address from a raw pointer.
468    #[inline]
469    pub fn from_ptr_of<T>(ptr: *const T) -> Self {
470        Self(ptr as usize)
471    }
472
473    /// Creates a new virtual address from a mutable raw pointer.
474    #[inline]
475    pub fn from_mut_ptr_of<T>(ptr: *mut T) -> Self {
476        Self(ptr as usize)
477    }
478
479    /// Converts the virtual address to a raw pointer.
480    #[inline]
481    pub const fn as_ptr(self) -> *const u8 {
482        self.0 as *const u8
483    }
484
485    /// Converts the virtual address to a raw pointer of a specific type.
486    #[inline]
487    pub const fn as_ptr_of<T>(self) -> *const T {
488        self.0 as *const T
489    }
490
491    /// Converts the virtual address to a mutable raw pointer.
492    #[inline]
493    pub const fn as_mut_ptr(self) -> *mut u8 {
494        self.0 as *mut u8
495    }
496
497    /// Converts the virtual address to a mutable raw pointer of a specific
498    /// type.
499    #[inline]
500    pub const fn as_mut_ptr_of<T>(self) -> *mut T {
501        self.0 as *mut T
502    }
503}
504
505/// Alias for [`PhysAddr::from_usize`].
506#[macro_export]
507macro_rules! pa {
508    ($addr:expr) => {
509        $crate::PhysAddr::from_usize($addr)
510    };
511}
512
513/// Alias for [`VirtAddr::from_usize`].
514#[macro_export]
515macro_rules! va {
516    ($addr:expr) => {
517        $crate::VirtAddr::from_usize($addr)
518    };
519}
520
521#[cfg(test)]
522mod test {
523
524    use super::*;
525
526    def_usize_addr! {
527        /// An example address type.
528        pub type ExampleAddr;
529        /// Another example address type.
530        pub type AnotherAddr;
531    }
532
533    def_usize_addr_formatter! {
534        ExampleAddr = "EA:{}";
535        AnotherAddr = "AA:{}";
536    }
537
538    #[test]
539    pub fn test_alignment() {
540        let alignment = 0x1000usize;
541        let base = alignment * 2;
542        let offset = 0x123usize;
543        let addr = ExampleAddr::from_usize(base + offset);
544
545        assert_eq!(addr.align_down(alignment), ExampleAddr::from_usize(base));
546        assert_eq!(
547            addr.align_up(alignment),
548            ExampleAddr::from_usize(base + alignment)
549        );
550        assert_eq!(addr.align_offset(alignment), offset);
551        assert!(!addr.is_aligned(alignment));
552        assert!(ExampleAddr::from_usize(base).is_aligned(alignment));
553        assert_eq!(
554            ExampleAddr::from_usize(base).align_up(alignment),
555            ExampleAddr::from_usize(base)
556        );
557    }
558
559    #[test]
560    pub fn test_addr_wrapping_arithmetic() {
561        let base = usize::MAX - 0x100usize;
562        let offset = 0x200usize;
563        let with_offset = base.wrapping_add(offset);
564
565        let addr = ExampleAddr::from_usize(base);
566        let offset_addr = ExampleAddr::from_usize(with_offset);
567
568        assert_eq!(addr.wrapping_offset(offset as isize), offset_addr);
569        assert_eq!(offset_addr.wrapping_offset(-(offset as isize)), addr);
570        assert_eq!(addr.wrapping_add(offset), offset_addr);
571        assert_eq!(offset_addr.wrapping_sub(offset), addr);
572        assert_eq!(offset_addr.wrapping_sub_addr(addr), offset);
573    }
574
575    #[test]
576    pub fn test_addr_checked_arithmetic() {
577        let low_addr = ExampleAddr::from_usize(0x100usize);
578        let high_addr = ExampleAddr::from_usize(usize::MAX - 0x100usize);
579        let small_offset = 0x50usize;
580        let large_offset = 0x200usize;
581
582        assert_eq!(
583            low_addr.checked_sub(small_offset),
584            Some(low_addr.wrapping_sub(small_offset))
585        );
586        assert_eq!(low_addr.checked_sub(large_offset), None);
587        assert_eq!(
588            high_addr.checked_add(small_offset),
589            Some(high_addr.wrapping_add(small_offset))
590        );
591        assert_eq!(high_addr.checked_add(large_offset), None);
592
593        assert_eq!(
594            high_addr.checked_sub_addr(low_addr),
595            Some(usize::MAX - 0x200usize)
596        );
597        assert_eq!(low_addr.checked_sub_addr(high_addr), None);
598    }
599
600    #[test]
601    pub fn test_addr_overflowing_arithmetic() {
602        let low_addr = ExampleAddr::from_usize(0x100usize);
603        let high_addr = ExampleAddr::from_usize(usize::MAX - 0x100usize);
604        let small_offset = 0x50usize;
605        let large_offset = 0x200usize;
606
607        assert_eq!(
608            low_addr.overflowing_sub(small_offset),
609            (low_addr.wrapping_sub(small_offset), false)
610        );
611        assert_eq!(
612            low_addr.overflowing_sub(large_offset),
613            (low_addr.wrapping_sub(large_offset), true)
614        );
615        assert_eq!(
616            high_addr.overflowing_add(small_offset),
617            (high_addr.wrapping_add(small_offset), false)
618        );
619        assert_eq!(
620            high_addr.overflowing_add(large_offset),
621            (high_addr.wrapping_add(large_offset), true)
622        );
623        assert_eq!(
624            high_addr.overflowing_sub_addr(low_addr),
625            (high_addr.wrapping_sub_addr(low_addr), false)
626        );
627        assert_eq!(
628            low_addr.overflowing_sub_addr(high_addr),
629            (low_addr.wrapping_sub_addr(high_addr), true)
630        );
631    }
632
633    #[test]
634    #[should_panic]
635    pub fn test_addr_offset_overflow() {
636        let addr = ExampleAddr::from_usize(usize::MAX);
637        let _ = addr.offset(1);
638    }
639
640    #[test]
641    #[should_panic]
642    pub fn test_addr_offset_from_overflow() {
643        let addr = ExampleAddr::from_usize(usize::MAX);
644        let _ = addr.offset_from(ExampleAddr::from_usize(0));
645    }
646
647    #[test]
648    #[should_panic]
649    pub fn test_addr_offset_from_underflow() {
650        let addr = ExampleAddr::from_usize(0);
651        let _ = addr.offset_from(ExampleAddr::from_usize(usize::MAX));
652    }
653
654    #[test]
655    #[should_panic]
656    pub fn test_addr_add_overflow() {
657        let addr = ExampleAddr::from_usize(usize::MAX);
658        let _ = addr.add(1);
659    }
660
661    #[test]
662    #[should_panic]
663    pub fn test_addr_sub_underflow() {
664        let addr = ExampleAddr::from_usize(0);
665        let _ = addr.sub(1);
666    }
667
668    #[test]
669    #[should_panic]
670    pub fn test_addr_sub_addr_overflow() {
671        let addr = ExampleAddr::from_usize(0);
672        let _ = addr.sub_addr(ExampleAddr::from_usize(1));
673    }
674}
ax_memory_addr/addr.rs

ax_memory_addr/
addr.rs
