RUST 实验 - GPIO I2C 控制器（QTest）¶

./rust/hw/i2c/  
├── i2c_core             // i2c通用核心实现  
│   └── src  
│       ├── core.rs  
│       └── lib.rs  
├── i2c_slave            // i2c各种从机外设实现  
│   └── src  
│       ├── at24c02.rs  
│       └── lib.rs  
├── gpio_i2c             // i2c具体控制器实现  
│   └── src  
│       ├── bindings.rs  
│       ├── registers.rs  
│       ├── device.rs  
│       └── lib.rs  

./hw/i2c/Kconfig                    // I2C驱动配置，新增GPIO_I2C编译项，关联Rust实现驱动  
./hw/riscv/Kconfig                  // RISC-V主板配置，GEVICO_G233平台新增GPIO_I2C外设依赖  

./rust/Cargo.toml                   // 顶层workspace添加相应crate  

./rust/hw/i2c/Kconfig               // 添加子项  
./rust/hw/i2c/meson.build           // 添加子项  

./rust/hw/i2c/gpio_i2c/meson.build  // 注意添加bindgen相关  
./rust/hw/i2c/gpio_i2c/Cargo.toml   // 注意依赖相对路径层级  

./rust/hw/i2c/gpio_i2c/wrapper.h        // 专供bindgen解析的适配头，修复工具解析报错并引入标准C头文件  
./rust/hw/i2c/gpio_i2c/src/bindings.rs  // 导入bindgen生成的QEMU的C接口绑定代码，Rust通过其调用C侧接口  

./include/hw/i2c/gpio_i2c.h             // 声明C接口函数符号，供C代码调用Rust实现  
./rust/hw/i2c/gpio_i2c/src/lib.rs       // 导出Rust功能实现，对接C声明接口函数符号  

./include/hw/riscv/g233.h               // 声明项目相关内存映射枚举  
./hw/riscv/g233.c                       // 调用控制器create实现  

// QEMU硬件抽象层  
pub struct GPIOI2CRegisters {}  // 寄存器，存放设备所有寄存器  
pub struct GPIOI2CState {}      // QOM设备模型，存放设备运行状态  
pub struct GPIOI2CClass {}      // QOM设备类，存放设备固定属性  

// 业务特性，强制设备挂载系统总线并规定设备唯一ID  
trait GPIOI2CImpl: SysBusDeviceImpl + IsA<GPIOI2CState> {}  

// QEMU框架适配层  
impl GPIOI2CClass {}                           // 保存设备ID，调用父类初始化  
unsafe impl ObjectType for GPIOI2CState {}     // 绑定实例类对象，设备命名供QEMU使用  
impl GPIOI2CImpl for GPIOI2CState {}           // 定义设备ID  
impl ObjectImpl for GPIOI2CState {}            // 绑定设备完整生命周期函数  
impl DeviceImpl for GPIOI2CState {}            // 启用设备，创建设备硬件资源  
impl ResettablePhasesImpl for GPIOI2CState {}  // 复位回调，虚拟机复位时恢复硬件初始状态  
impl SysBusDeviceImpl for GPIOI2CState {}      // 挂载设备到系统总线，绑定MMIO访问入口  

// QEMU业务接口层  
impl GPIOI2CRegisters {}                       // 实现寄存器读写及复位逻辑  
impl GPIOI2CState {}                           // 实现数据收发工具函数  

// 导出设备创建函数  
pub unsafe extern "C" fn gpio_i2c_create()     // 创建实例化设备，供QEMU的C代码调用  

gpio_i2c_create  
  └> GPIOI2CState::new  
  |    └> GPIOI2CState::init  
  |         └> MemoryRegion::init_io - GPIOI2C_OPS  
  |         └> GPIOI2CRegisters - Default::default()  
  |         └> I2C_Bus::new  
  └> GPIOI2CState::sysbus_realize  
       └> GPIOI2CState::realize -> I2CBus::attach -> AT24C02Slave::new  

qtest_readl  -> GPIOI2C_OPS.read  -> GPIOI2CState::read  -> GPIOI2CRegisters::read  

qtest_writel -> GPIOI2C_OPS.write -> GPIOI2CState::write -> GPIOI2CRegisters::write  
  ┌-----------------------------------------------------------┘  
  └> I2C_Bus::transfer_read  -> AT24C02Slave::recv  
  └> I2C_Bus::transfer_write -> AT24C02Slave::send  

             sys-bus                      i2c-bus  
 risc-v --<----------->-- i2c-master --<----------->-- i2c-slave  
processor                 controller                   peripheral  

   /-SDA-<->- start+[7addr+1rw](tx)+n|ack(rx)+[8data](tx)+n|ack(rx)+stop -<->-SDA-\  
I2C device                                                                    I2C controller  
   \-SCL----- ------            ...12345678...123456789...         ----- -----SCL-/  

pub struct I2CBus {  
    devices: Vec<Box<dyn I2CSlave>>,  // 挂载在总线上的从机列表  
    current_addr: Option<u8>,         // 当前正在通信的从机地址  
    is_recv: bool                     // 本次传输是主机读或主机写的标记  
}  

impl I2CBus {  
    pub fn new             // 创建I2C总线，初始化设备列表及当前寻址地址  
    pub fn device_count    // 统计I2C总线上挂载的从设备数量  
    pub fn is_busy         // 判断总线是否正在传输  

    pub fn attach          // 挂载I2C从机到I2C总线  
    pub fn start_transfer  // 返回开始信号，保存地址，确定主机读写  
    pub fn end_transfer    // 返回结束信号，设置地址为空  
    pub fn send            // 发送数据，调用从机发送函数  
    pub fn recv            // 接收数据，调用从机接收函数  
    pub fn transfer_write  // 封装完整写流程：起始写传输+连续写入字节+结束传输  
    pub fn transfer_read   // 封装完整读流程：起始读传输+连续读取字节+结束传输  
}  

pub struct AT24C02Slave {  
    pub addr: u8,          // 从机设备地址  
    pub regs: [u8; 256],   // EEPROM存储数组  
    pub pointer: u8,       // 存储读写指针  
    pub first_byte: bool,  // 标记首字节  
}  

impl I2CSlave for AT24C02Slave {  
    fn address  // 获取设备地址  
    fn event    // 响应总线事件  
    fn send     // 发送主机数据，并设置存储读写指针  
    fn recv     // 接收主机数据，并设置存储读写指针  
}  

impl GPIOI2CRegisters {  

    pub(self) fn read(&mut self, offset: RegisterOffset) -> u32 {  
    }  

    pub(self) fn write(&mut self, offset: RegisterOffset, value: u32, device: &GPIOI2CState) -> bool {  
        use RegisterOffset::*;  
        match offset {  
            ADDR     => self.addr     = Addr::from(value),  
            DATA     => self.data     = value,  
            CTRL     => {  
                let mut i2c_bus = device.i2c_bus.borrow_mut();  
                let mut ctrl = Ctrl::from(value);  
                match (ctrl.en(), ctrl.start(), ctrl.stop(), ctrl.rw()) {  

            // 使能+起始信号：发起传输，更新总线及寄存器状态  
                    (true, true, false, _) => {  
                        let addr = u32::from(self.addr) as u8;  
                        let ret  = i2c_bus.start_transfer(addr, ctrl.rw());  
                        self.status.set_busy(i2c_bus.is_busy());  
                        self.status.set_ack(ret == 0);  
                        self.status.set_done(true);  
                    },  

            // 使能+停止信号：结束传输，更新总线及寄存器状态  
                    (true, false, true, false) => {  
                        i2c_bus.end_transfer();  
                        self.status.set_busy(i2c_bus.is_busy());  
                        self.status.set_done(true);  
                    },  

            // 使能+无起止+写模式：读寄存器发送数据，更新总线及寄存器状态  
                    (true, false, false, false) => {  
                        let data = self.data as u8;  
                        let ret  = i2c_bus.send(data);  
                        self.status.set_busy(i2c_bus.is_busy());  
                        self.status.set_ack(ret == 0);  
                        self.status.set_done(true);  
                    },  

            // 使能+无起止+读模式：接收数据写寄存器，更新总线及寄存器状态  
                    (true, false, false, true) => {  
                        let data = i2c_bus.recv();  
                        self.data = data as u32;  
                        self.status.set_busy(i2c_bus.is_busy());  
                        self.status.set_done(true);  
                    },  

            // 无效控制组合，不执行任何操作  
                    _ => {},  
                };  
                ctrl.set_start(false);  
                ctrl.set_stop(false);  
                self.ctrl = ctrl  
            },  
            STATUS   => self.status   = Status::from(value),  
            PRESCALE => self.prescale = value,  
        }  
        false  
    }  

}