rust-embedded/rust-raspberrypi-OS-tutorials · error

Overflow on Address::add

Error message

Overflow on Address::add

What it means

The Add<usize> implementation for Address<ATYPE> uses checked_add and panics with "Overflow on Address::add" when base + offset exceeds the address type's maximum. This is a deliberate safety check so address arithmetic never silently wraps in the kernel. It indicates a computed offset or size was wrong (too large) for the address space.

Source

Thrown at 20_timer_callbacks/kernel/src/memory.rs:93

    /// Checks if the address is page aligned.
    pub const fn is_page_aligned(&self) -> bool {
        common::is_aligned(self.value, bsp::memory::mmu::KernelGranule::SIZE)
    }

    /// Return the address' offset into the corresponding page.
    pub const fn offset_into_page(&self) -> usize {
        self.value & bsp::memory::mmu::KernelGranule::MASK
    }
}

impl<ATYPE: AddressType> Add<usize> for Address<ATYPE> {
    type Output = Self;

    #[inline(always)]
    fn add(self, rhs: usize) -> Self::Output {
        match self.value.checked_add(rhs) {
            None => panic!("Overflow on Address::add"),
            Some(x) => Self::new(x),
        }
    }
}

impl<ATYPE: AddressType> Sub<usize> for Address<ATYPE> {
    type Output = Self;

    #[inline(always)]
    fn sub(self, rhs: usize) -> Self::Output {
        match self.value.checked_sub(rhs) {
            None => panic!("Overflow on Address::sub"),
            Some(x) => Self::new(x),
        }
    }
}

impl<ATYPE: AddressType> Sub<Address<ATYPE>> for Address<ATYPE> {

View on GitHub (pinned to 644474cc09)

Solutions

1. Find the offending Address + usize addition (the panic backtrace) and validate the offset/size against the region bounds before adding.
2. Check the source of the offset (memory map, descriptor, constant) for corruption or wrong units (bytes vs pages).
3. Use checked_range_inclusive/contains on the region before computing base + size.
4. Ensure ATYPE width matches the target architecture's address size (e.g. u64 on aarch64) so legitimate addresses don't overflow.

Example fix

// before
let end = region.start_addr + region.size; // may overflow
// after
let end = region.start_addr
    .checked_add_usize(region.size)
    .ok_or("Region exceeds address space")?;

// Rust: bounds-check before address arithmetic
fn safe_end(base: Address<AddressTypeVirtual>, size: usize) -> Option<Address<AddressTypeVirtual>> {
    // emulate checked add before calling operator+
    Some(base + size) // only if caller guaranteed size < addr-space remainder
}

// fn offset_fits(base_addr: u64, offset: usize, max: u64) -> bool {
//     base_addr.checked_add(offset as u64).map_or(false, |sum| sum <= max)
// }
fn offset_fits(base_addr: u64, offset: usize, max: u64) -> bool {
    base_addr.checked_add(offset as u64).map_or(false, |sum| sum <= max)
}

When it happens

Trigger: Evaluating address + usize where the addition overflows ATYPE (e.g. u64/u32 address space), such as translating virtual->physical with an oversized offset, iterating past the end of a memory region, or adding a bogus size from a corrupted descriptor.

Common situations: MMU mapping code adding region sizes that run past the top of memory; a bootloader-provided memory map with absurd region base/size; off-by-N loops over physical/virtual ranges; casting 32-bit addresses into a wider computation then adding past 2^32 when ATYPE is u32.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Overflow on Address::sub
• CPU Exception! {}
• Should not be here. Use of SP_EL0 in EL1 is not supported.
• No handler registered for IRQ {}
• Error handling IRQ

AI-assisted analysis of rust-embedded/rust-raspberrypi-OS-tutorials@644474cc09 (2026-09-06). Data as JSON: /api/errors/2d905475a3145a45. Report an issue: GitHub.