rigless 0.1.0

Virtual hardware-in-the-loop runtime: run unmodified firmware on an emulated MCU with every peripheral, chip model and unit of virtual time in Rust, and a CPU core of its own that translates the firmware's instructions to host code
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

// Copyright (c) 2026 Rigless Labs.
// SPDX-License-Identifier: MIT OR Apache-2.0
//! The chip end of an inter-integrated-circuit bus.

use std::any::Any;

use crate::device::DeviceContext;
use crate::snapshot::Store;

/// An integrated circuit on an I²C bus: what a controller, on a part or inside another chip, addresses.
///
/// A transaction is a start carrying an address and a direction, bytes one way, and a stop. A
/// restart is another start without the stop. The controller calls this and never learns what's
/// behind it. A chip implements it and never learns there's a controller. A chip that isn't at the
/// address doesn't acknowledge the start, and the controller reads nothing from it.
///
/// `Any` so a controller with several peers on one bus can hand a board back the concrete chip it
/// hung there, the way [`crate::chip::spi::Peer`] and [`crate::chip::uart::Peer`] already do. A
/// snapshot keeps a chip through its own [`Store`].
pub trait Peer: Store + std::fmt::Debug + Send + Any {
    /// A start condition carrying `address` and whether the controller will read. Returns the
    /// acknowledge.
    fn start(&mut self, address: u8, read: bool, context: &DeviceContext<'_>) -> bool;

    /// One byte from the controller, after a start it acknowledged for a write. Returns the
    /// acknowledge.
    fn write(&mut self, byte: u8, context: &DeviceContext<'_>) -> bool;

    /// One byte to the controller, after a start it acknowledged for a read. `last` is the
    /// controller's not-acknowledge, which says the stop is next.
    fn read(&mut self, last: bool, context: &DeviceContext<'_>) -> u8;

    /// The stop condition.
    fn stop(&mut self, context: &DeviceContext<'_>);

    /// Every byte this peer has been written, oldest first, or nothing where it keeps no log.
    ///
    /// The far end's own record, the same job [`crate::chip::spi::Peer::received`] and
    /// [`crate::chip::uart::Peer::received`] do for their own buses: it is what says a byte reached
    /// the far end, rather than the controller's own belief that it sent one.
    fn received(&self) -> &[u8] {
        &[]
    }
}