// boards/redboard_redv/src/main.rs

#[no_mangle]
pub unsafe fn main() {
    // only machine mode
    rv32i::configure_trap_handler(rv32i::PermissionMode::Machine);
    ...
    let peripherals = static_init!(E310xDefaultPeripherals, E310xDefaultPeripherals::new()); 

}

pub struct E310xDefaultPeripherals<'a> {
    pub uart0: sifive::uart::Uart<'a>,
    pub gpio_port: crate::gpio::Port<'a>,
    pub prci: sifive::prci::Prci,
    pub pwm0: sifive::pwm::Pwm,
    pub pwm1: sifive::pwm::Pwm,
    pub pwm2: sifive::pwm::Pwm,
    pub rtc: sifive::rtc::Rtc,
    pub watchdog: sifive::watchdog::Watchdog,
}

impl<'a> E310xDefaultPeripherals<'a> {
    pub fn new() -> Self {
        Self {
            uart0: sifive::uart::Uart::new(crate::uart::UART0_BASE, 16_000_000),
            gpio_port: crate::gpio::Port::new(),
            prci: sifive::prci::Prci::new(crate::prci::PRCI_BASE),
            pwm0: sifive::pwm::Pwm::new(crate::pwm::PWM0_BASE),
            pwm1: sifive::pwm::Pwm::new(crate::pwm::PWM1_BASE),
            pwm2: sifive::pwm::Pwm::new(crate::pwm::PWM2_BASE),
            rtc: sifive::rtc::Rtc::new(crate::rtc::RTC_BASE),
            watchdog: sifive::watchdog::Watchdog::new(crate::watchdog::WATCHDOG_BASE),
        }
    }
}

pub struct Port<'a> {
    pins: [GpioPin<'a>; 32],
}

pub struct GpioPin<'a> {
    registers: StaticRef<GpioRegisters>,
    pin: Field<u32, pins::Register>,
    set: FieldValue<u32, pins::Register>,
    clear: FieldValue<u32, pins::Register>,
    client: OptionalCell<&'a dyn hil::gpio::Client>,
}

use tock_registers::registers::{ReadOnly, ReadWrite, WriteOnly};

register_structs! {
    Registers {
        // Control register: read-write
        // The 'Control' parameter constrains this register to only use fields from
        // a certain group (defined below in the bitfields section).
        // “Control”参数将该寄存器限制为仅使用某个组中的字段（定义见下面的bitfields部分）。
        // 偏移   寄存器名  访问方式 寄存器大小  寄存器类型
        (0x000 => cr:    ReadWrite< u8, Control::Register>),

        // Status register: read-only
        (0x001 => s: ReadOnly<u8, Status::Register>),

        // Registers can be bytes, halfwords, or words:
        // 第二个类型参数可以省略，这意味着没有为这些寄存器定义位字段
        (0x002 => byte0: ReadWrite<u8>),
        (0x003 => byte1: ReadWrite<u8>),
        (0x004 => short: ReadWrite<u16>),

        // 寄存器之间的空白必须用填充字段标记，声明如下。此填充的长度由宏自动计算
        (0x006 => _reserved),
        (0x008 => word: ReadWrite<u32>),

        // The type for a register can be anything. Conveniently, you can use an array when there are a bunch of similar registers.
        // 寄存器的类型可以是任何类型。通常当存在一组类似的寄存器时，可以使用数组
        (0x00C => array: [ReadWrite<u32>; 4]),
        (0x01C => ... ),

        // 结构的结尾标记如下, 与结构体大小匹配的@END 标记
        (0x100 => @END),
    }
}

#[repr(C)]
struct Registers {
    // Control register: read-write
    // The 'Control' parameter constrains this register to only use fields from a certain group (defined below in the bitfields section).
    // “Control”参数将该寄存器限制为仅使用某个组中的字段（定义见下面的bitfields部分）。
    cr: ReadWrite<u8, Control::Register>,

    // Status register: read-only
    s: ReadOnly<u8, Status::Register>

    // Registers can be bytes, halfwords, or words:
    byte0: ReadWrite<u8>,
    byte1: ReadWrite<u8>,
    short: ReadWrite<u16>,

    // The padding length was automatically computed as 0x008 - 0x006.
    _reserved: [u8; 2],
    word: ReadWrite<u32>,

    // Arrays are expanded as-is, like any other type.
    array: [ReadWrite<u32>; 4],

    // Etc.
}

register_structs! {
    pub Registers {
        (0x000 => foo: ReadOnly<u32>),
        (0x004 => pub bar: ReadOnly<u32>),
        (0x008 => @END),
    }
}

#[repr(C)]
pub struct Registers {
    foo: ReadOnly<u32>,
    pub bar: ReadOnly<u32>,
}

register_bitfields! [
    // First parameter is the register width. Can be u8, u16, u32, or u64.
    //第一个参数是寄存器宽度。可以是u8、u16、u32或u64。
    u32,

    // Each subsequent parameter is a register abbreviation, its descriptive name, and its associated bitfields. The descriptive name defines this 'group' of bitfields. Only registers defined as ReadWrite<_, Control::Register> can use these bitfields.
    // 每个后续参数都是一个寄存器缩写、描述性名称及其关联的位字段。
    // 描述性名称定义了这组位字段。
    // 只有定义为ReadWrite<_，Control:：Register>的寄存器才能使用这些位字段。
    Control [
        // Bitfields are defined as:
        // 字段定义如下
        // name OFFSET(shift) NUMBITS(num) [ /* optional values */ ]

        // This is a two-bit field which includes bits 4 and 5
        RANGE OFFSET(4) NUMBITS(2) [
            // Each of these defines a name for a value that the bitfield can be written with or matched against. Note that this set is not exclusive-- the field can still be written with arbitrary constants.
            // 其中每一项都定义了一个值的名称，该值可以写入或匹配位字段。
            // 请注意，这个集合不是排他性的——字段仍然可以用任意常量写入
            VeryHigh = 0,
            High = 1,
            Low = 2
        ],

        // A common case is single-bit bitfields, which usually just mean'enable' or 'disable' something.
        // 单字段，仅意味着enable/disable
        EN  OFFSET(3) NUMBITS(1) [],
        INT OFFSET(2) NUMBITS(1) []
    ],

    // Another example:
    // Status register
    Status [
        TXCOMPLETE  OFFSET(0) NUMBITS(1) [],
        TXINTERRUPT OFFSET(1) NUMBITS(1) [],
        RXCOMPLETE  OFFSET(2) NUMBITS(1) [],
        RXINTERRUPT OFFSET(3) NUMBITS(1) [],
        MODE        OFFSET(4) NUMBITS(3) [
            FullDuplex = 0,
            HalfDuplex = 1,
            Loopback = 2,
            Disabled = 3
        ],
        ERRORCOUNT OFFSET(6) NUMBITS(3) []
    ],

    // In a simple case, offset can just be a number, and the number of bits is set to 1:
    // 在一个简单的情况下，偏移量可以只是一个数字，并且位数设置为1：
    InterruptFlags [
        UNDES   10,
        TXEMPTY  9,
        NSSR     8,
        OVRES    3,
        MODF     2,
        TDRE     1,
        RDRF     0
    ]
]

ReadOnly<T: UIntLike, R: RegisterLongName = ()>: Readable
.get() -> T                                    // Get the raw register value
.read(field: Field<T, R>) -> T                 // Read the value of the given field
.read_as_enum<E>(field: Field<T, R>) -> Option<E> // Read value of the given field as a enum member
.is_set(field: Field<T, R>) -> bool            // Check if one or more bits in a field are set
.matches_any(value: FieldValue<T, R>) -> bool  // Check if any specified parts of a field match
.matches_all(value: FieldValue<T, R>) -> bool  // Check if all specified parts of a field match
.extract() -> LocalRegisterCopy<T, R>          // Make local copy of register

WriteOnly<T: UIntLike, R: RegisterLongName = ()>: Writeable
.set(value: T)                                 // Set the raw register value
.write(value: FieldValue<T, R>)                // Write the value of one or more fields,
                                               //  overwriting other fields to zero
ReadWrite<T: UIntLike, R: RegisterLongName = ()>: Readable + Writeable + ReadWriteable
.get() -> T                                    // Get the raw register value
.set(value: T)                                 // Set the raw register value
.read(field: Field<T, R>) -> T                 // Read the value of the given field
.read_as_enum<E>(field: Field<T, R>) -> Option<E> // Read value of the given field as a enum member
.write(value: FieldValue<T, R>)                // Write the value of one or more fields,
                                               //  overwriting other fields to zero
.modify(value: FieldValue<T, R>)               // Write the value of one or more fields,
                                               //  leaving other fields unchanged
.modify_no_read(                               // Write the value of one or more fields,
      original: LocalRegisterCopy<T, R>,       //  leaving other fields unchanged, but pass in
      value: FieldValue<T, R>)                 //  the original value, instead of doing a register read
.is_set(field: Field<T, R>) -> bool            // Check if one or more bits in a field are set
.matches_any(value: FieldValue<T, R>) -> bool  // Check if any specified parts of a field match
.matches_all(value: FieldValue<T, R>) -> bool  // Check if all specified parts of a field match
.extract() -> LocalRegisterCopy<T, R>          // Make local copy of register

Aliased<T: UIntLike, R: RegisterLongName = (), W: RegisterLongName = ()>: Readable + Writeable
.get() -> T                                    // Get the raw register value
.set(value: T)                                 // Set the raw register value
.read(field: Field<T, R>) -> T                 // Read the value of the given field
.read_as_enum<E>(field: Field<T, R>) -> Option<E> // Read value of the given field as a enum member
.write(value: FieldValue<T, W>)                // Write the value of one or more fields,
                                               //  overwriting other fields to zero
.is_set(field: Field<T, R>) -> bool            // Check if one or more bits in a field are set
.matches_any(value: FieldValue<T, R>) -> bool  // Check if any specified parts of a field match
.matches_all(value: FieldValue<T, R>) -> bool  // Check if all specified parts of a field match
.extract() -> LocalRegisterCopy<T, R>          // Make local copy of register

use tock_registers::registers::ReadWrite;

#[repr(C)]
struct Registers {
    // The register name in the struct should be a lowercase version of the register abbreviation, as written in the datasheet:
    // 结构中的寄存器变量名称应为数据表中所述的寄存器缩写的小写版本
    cr: ReadWrite<u8, Control::Register>,
}

register_bitfields! [
    u8,

    // The name should be the long descriptive register name, camelcase, without the word 'register'.
    // 寄存器名(驼峰)，该名称应为长描述性寄存器名称，不含“寄存器”一词。
    Control [
        // The field name should be the capitalized abbreviated field name, as given in the datasheet.
        // 字段名（大写）应为数据表中给出的大写缩写字段名
        RANGE OFFSET(4) NUMBITS(3) [
            // Each of the field values should be camelcase, as descriptive of their value as possible.
            //每个字段值都应该是驼峰，尽可能描述它们的值
            VeryHigh = 0,
            High = 1,
            Low = 2
        ]
    ]
]

pub struct Uart<'a> {
    // 指向静态分配的可变数据（如内存映射的I/O寄存器）的指针。
    registers: StaticRef<UartRegisters>,
    clock_frequency: u32,
    tx_client: OptionalCell<&'a dyn hil::uart::TransmitClient>,
    rx_client: OptionalCell<&'a dyn hil::uart::ReceiveClient>,
    stop_bits: Cell<hil::uart::StopBits>,
    buffer: TakeCell<'static, [u8]>,
    len: Cell<usize>,
    index: Cell<usize>,
}

register_structs! {
    UartRegisters {
        // 偏移   寄存器名(小写)  访问方式 寄存器大小  寄存器类型
        (0x00 => txdata: ReadWrite<u32, TxData::Register>),
        (0x04 => rxdata: ReadWrite<u32, RxData::Register>),
        (0x08 => txctrl: ReadWrite<u32, TxCtrl::Register>),
        (0x0c => rxctrl: ReadWrite<u32, RxCtrl::Register>),
        (0x10 => ie: ReadWrite<u32, Ie::Register>),
        (0x14 => ip: ReadOnly<u32, Ip::Register>),
        (0x18 => div: ReadWrite<u32, Div::Register>),
    }
}

register_bitfields! [u32,

    // 每个后续参数都是一个寄存器缩写、描述性名称及其关联的位字段。
    // 描述性名称定义了这组位字段。
    // 只有定义为ReadWrite<_，Control:：Register>的寄存器才能使用这些位字段。
    TxData [
        // 字段定义如下
        // name OFFSET(shift) NUMBITS(num) [ /* optional values */ ]
        DATA OFFSET(0) NUMBITS(8) [],
        FULL OFFSET(31) NUMBITS(1) [],
    ],

    RxData [
        data OFFSET(0) NUMBITS(8) [],
        empty OFFSET(31) NUMBITS(1) [],
    ],
    TxCtrl [
        txen OFFSET(0) NUMBITS(1) [],
        nstop OFFSET(0) NUMBITS(1) [
            OneStopBit = 0,
            TwoStopBit = 1,
        ],
        txcnt OFFSET(16) NUMBITS(3) [],
        empty OFFSET(31) NUMBITS(1) [],
    ],
    ....
]

pub struct Uart<'a> {
    registers: StaticRef<UartRegisters>,
    clock_frequency: u32,
    tx_client: OptionalCell<&'a dyn hil::uart::TransmitClient>,
    rx_client: OptionalCell<&'a dyn hil::uart::ReceiveClient>,
    stop_bits: Cell<hil::uart::StopBits>,
    buffer: TakeCell<'static, [u8]>,
    len: Cell<usize>,
    index: Cell<usize>,
}

impl<'a> Uart<'a> {
    pub const fn new(base: StaticRef<UartRegisters>, clock_frequency: u32) -> Uart<'a> {
        Uart {
            registers: base,
            clock_frequency: clock_frequency,
            tx_client: OptionalCell::empty(),
            rx_client: OptionalCell::empty(),
            stop_bits: Cell::new(hil::uart::StopBits::One),
            buffer: TakeCell::empty(),
            len: Cell::new(0),
            index: Cell::new(0),
        }
    }
    //...
}

pub struct GpioRegisters {
    /// Pin value.
    value: ReadOnly<u32, pins::Register>,
    /// Pin Input Enable Register
    input_en: ReadWrite<u32, pins::Register>,
    /// Pin Output Enable Register
    output_en: ReadWrite<u32, pins::Register>,
    /// Output Port Value Register
    port: ReadWrite<u32, pins::Register>,
    /// Internal Pull-Up Enable Register
    pullup: ReadWrite<u32, pins::Register>,
    /// Drive Strength Register
    drive: ReadWrite<u32, pins::Register>,
    /// Rise Interrupt Enable Register
    rise_ie: ReadWrite<u32, pins::Register>,
    /// Rise Interrupt Pending Register
    rise_ip: ReadWrite<u32, pins::Register>,
    /// Fall Interrupt Enable Register
    fall_ie: ReadWrite<u32, pins::Register>,
    /// Fall Interrupt Pending Register
    fall_ip: ReadWrite<u32, pins::Register>,
    /// High Interrupt Enable Register
    high_ie: ReadWrite<u32, pins::Register>,
    /// High Interrupt Pending Register
    high_ip: ReadWrite<u32, pins::Register>,
    /// Low Interrupt Enable Register
    low_ie: ReadWrite<u32, pins::Register>,
    /// Low Interrupt Pending Register
    low_ip: ReadWrite<u32, pins::Register>,
    /// HW I/O Function Enable Register
    iof_en: ReadWrite<u32, pins::Register>,
    /// HW I/O Function Select Register
    iof_sel: ReadWrite<u32, pins::Register>,
    /// Output XOR (invert) Register
    out_xor: ReadWrite<u32, pins::Register>,
}