mock_mmio/

lib.rs

// Copyright 2025 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

//! Support for mocking MMIO regions.
//!
//! This crate provides the type [MockMemoryOps] allowing expectations to be set on accesses to a
//! block of memory. This type is generated by the [mockall] crate - see its documentation for
//! setting expectations.
//!
//! # Usage Example
//! ```
//! use mmio::Mmio;
//! use mockall::predicate::eq;
//! let mut ops = MockMemoryOps::new();
//! // Expect a single load32 call at offset 64, returning the value 0xabcd.
//! ops.expect_load32()
//!     .times(1)
//!     .with(eq(64))
//!     .return_const(0xabcd_u32);
//!
//! let len = 1024;
//! // Create an MMIO region using the given mock ops and of the given size.
//! // The returned region may be split and sent to other threads.
//! let mmio = new_mock_mmio(&ops, len);
//! assert_eq!(mmio.load32(64), 0xabcd_u32);
//! ```
use mmio::MmioSplit;
use mmio::region::{MmioRegion, UnsafeMmio};
use mockall::mock;
use std::ops::Deref;

mock! {
    pub MemoryOps {
        pub fn load8(&self, addr: usize) -> u8;
        pub fn load16(&self, addr: usize) -> u16;
        pub fn load32(&self, addr: usize) -> u32;
        pub fn load64(&self, addr: usize) -> u64;

        pub fn store8(&self, addr: usize, value: u8);
        pub fn store16(&self, addr: usize, value: u16);
        pub fn store32(&self, addr: usize, value: u32);
        pub fn store64(&self, addr: usize, value: u64);

        pub fn write_barrier(&self);
    }
}

/// Create a mock MMIO operation of the given `len` that uses the given mock `ops`.
///
/// The returned MMIO region is splittable and sendable.
pub fn new_mock_mmio<O: Deref<Target = MockMemoryOps> + Clone + Send + Sync>(
    ops: O,
    len: usize,
) -> impl MmioSplit + Send + Sync + use<O> {
    MmioRegion::new(MockMmio { ops, len })
}

#[derive(Clone)]
struct MockMmio<O> {
    ops: O,
    len: usize,
}

impl<O: Deref<Target = MockMemoryOps>> UnsafeMmio for MockMmio<O> {
    fn len(&self) -> usize {
        self.len
    }

    fn align_offset(&self, _align: usize) -> usize {
        0
    }

    unsafe fn load8_unchecked(&self, offset: usize) -> u8 {
        self.ops.load8(offset)
    }

    unsafe fn load16_unchecked(&self, offset: usize) -> u16 {
        self.ops.load16(offset)
    }

    unsafe fn load32_unchecked(&self, offset: usize) -> u32 {
        self.ops.load32(offset)
    }

    unsafe fn load64_unchecked(&self, offset: usize) -> u64 {
        self.ops.load64(offset)
    }

    unsafe fn store8_unchecked(&self, offset: usize, value: u8) {
        self.ops.store8(offset, value)
    }

    unsafe fn store16_unchecked(&self, offset: usize, value: u16) {
        self.ops.store16(offset, value)
    }

    unsafe fn store32_unchecked(&self, offset: usize, value: u32) {
        self.ops.store32(offset, value)
    }

    unsafe fn store64_unchecked(&self, offset: usize, value: u64) {
        self.ops.store64(offset, value)
    }

    fn write_barrier(&self) {
        self.ops.write_barrier();
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use mmio::Mmio;
    use mockall::Sequence;
    use mockall::predicate::eq;

    #[test]
    fn test_mock_ops() {
        let mut ops = MockMemoryOps::new();
        ops.expect_load8().with(eq(0)).return_const(17);

        let mmio = new_mock_mmio(&ops, 1024);
        assert_eq!(mmio.load8(0), 17);
    }

    #[test]
    fn test_sequence_interleaving() {
        // This test defines two concurrent sequences each with 2 operations:
        // - [a1, a2]
        // - [b1, b2]
        //
        // The operations in each sequence must be performed in order, but the sequences may be
        // interleaved. There are 6 possible interleavings:
        //
        // - [a1, a2, b1, b2]
        // - [a1, b1, a2, b2]
        // - [a1, b1, b2, a2]
        // - [b1, a1, a2, b2]
        // - [b1, a1, b2, a2]
        // - [b1, b2, a1, a2]
        enum Op {
            A1,
            A2,
            B1,
            B2,
        }
        for interleaving in [
            [Op::A1, Op::A2, Op::B1, Op::B2],
            [Op::A1, Op::B1, Op::A2, Op::B2],
            [Op::A1, Op::B1, Op::B2, Op::A2],
            [Op::B1, Op::A1, Op::A2, Op::B2],
            [Op::B1, Op::A1, Op::B2, Op::A2],
            [Op::B1, Op::B2, Op::A1, Op::A2],
            // An invalid interleaving. Uncommenting the following line should cause a failure.
            //[Op::A1, Op::B2, Op::A2, Op::B1],
        ] {
            let mut ops = MockMemoryOps::new();

            let mut seq1 = Sequence::new();
            let mut seq2 = Sequence::new();

            ops.expect_load8()
                .times(1)
                .in_sequence(&mut seq1)
                .with(eq(0_usize))
                .return_const(17_u8);
            ops.expect_load8()
                .times(1)
                .in_sequence(&mut seq1)
                .with(eq(1_usize))
                .return_const(36_u8);

            ops.expect_store16()
                .times(1)
                .in_sequence(&mut seq2)
                .with(eq(2_usize), eq(1023_u16))
                .return_const(());
            ops.expect_load16()
                .times(1)
                .in_sequence(&mut seq2)
                .with(eq(2_usize))
                .return_const(1023_u16);

            let mut mmio = new_mock_mmio(&ops, 1024);
            let r1 = mmio.split_off(2);
            let mut r2 = mmio.split_off(2);

            for op in interleaving {
                match op {
                    Op::A1 => assert_eq!(r1.load8(0), 17),
                    Op::A2 => assert_eq!(r1.load8(1), 36),
                    Op::B1 => r2.store16(0, 1023),
                    Op::B2 => assert_eq!(r2.load16(0), 1023),
                }
            }
        }
    }
}