Library providing basis for low level registers access This crate re-exports macros refined in ral-macro, so this is the only library needed to be defined in dependencies

Code generator

Refer to ral-gen crate documentation for code generation guidelines

DSL and produced result

Internally generates register description backed by ral

use ral::register;

register! {
    use crate_name::types::CustomType; // Use expressions for custom types used in field declarations

    #[access = "read-write"] // Optional register wide access specifier
    #[doc = "Register description"] // Optional register description
    reg0 { // Register name
        offset: 0x8, // Register offset in enclosing peripheral
        value_size: 32, // Register size, expected values are 8, 16, 32 or 64
        reset_mask: 0xFFFFFFFF, // Reset mask
        reset_value: 0x0, // Reset value
        fields: { // Optional fields
            #[doc = "Bits 16:31 - Read-only u16 field"] // Each field can have a description
            #[access = "read-only"] // Access specifier
            field5[16:16] as u16, // Field specification `<name>[<offset>:<width>] as <type>`

            #[doc = "Bits 14:15 - Write-only field"]
            #[access = "write-only"] // Only setters will be generated
            field4[14:2] as u8, // Default supported types are `u8`, `u16`, `u32` and `u64`

            #[doc = "Bits 11:13 - Read-only field"]
            #[access = "read-only"] // Only getters will be generated
            field3[11:3] as u8,

            #[doc = "Bit 10 - Boolean field"]
            #[access = "read-write"] // `read-write` is a default access specifier
            field2[10:1] as bool, // `bool` fields are also supported by default

            #[doc = "Bits 8:9 - Enum field"]
            #[access = "read-write"] // Both getters and setters will be generated
            field1[8:2] as CustomType, // Custom types are supported with limitations

            #[doc = "Bits 0:7 - Read-write by default long field"]
            field0[0:8] as u8
        }
    }
}

Above register definition will be transformed into following code

// Required uses section
use core::sync::atomic::AtomicPtr;
use core::convert::TryFrom;
use ral::{borrow_register, init_register, return_register, value_read, value_write, R, ReadableRegister, Register, VolatileCell, WritableRegister};
use crate_name::types::CustomType;
const REGISTER: AtomicPtr<VolatileCell<<Reg0 as Register>::ValueType>> = AtomicPtr::new(
    (super::BASE_ADDRESS /* Enclosing peripheral/cluster base address */ + 0x00 /* offset */) as *mut VolatileCell<<Reg0 as Register>::ValueType>,
);
///Register description
pub fn reg0() -> Option<Reg0> {
    borrow_register(&REGISTER).map(Reg0)
}
pub struct Reg0(R<u32, Reg0>);
impl Drop for Reg0 {
    fn drop(&mut self) {
        let Reg0(register) = self;
        return_register(&REGISTER, register);
    }
}
impl Register for Reg0 {
    type RegisterType = Self;
    type ValueType = u32;
    const RESET_MASK: Self::ValueType = 0xFFFF_FFFF;
    const RESET_VALUE: Self::ValueType = 0x1234_0000;
}
impl ReadableRegister for Reg0 { // Will be added if register wide access allows read
    fn get_bits(&self) -> Self::ValueType {
        self.0.get_bits()
    }

    fn read(&mut self) -> &mut Self::RegisterType {
        self.0.read();
        self
    }
}
impl WritableRegister for Reg0 { // Will be added if register wide access allows write
    fn set_bits(&mut self, bits: Self::ValueType) -> &mut Self::RegisterType {
        self.0.set_bits(bits);
        self
    }
    fn reset(&mut self) -> &mut Self::RegisterType {
        self.set_bits(Self::RESET_VALUE)
    }
    fn write(&mut self) -> &mut Self::RegisterType {
        self.0.write();
        self
    }
}
impl Reg0 { // Will be added if any fields specified
    ///Bits 16:31 - Read-only u16 field
    #[inline]
    pub fn get_field5(&self) -> u16 {
        value_read!(self, 0x0000FFFFu32, 16) as u16
        // Will further expand into
        // ((self.0.get_bits() >> 16) & 0x0000FFFFu32) as u16
    }
    ///Bits 14:15 - Write-only field
    #[inline]
    pub fn set_field4(&mut self, value: u8) -> &mut Self {
        value_write!(self, 0x00000003u32, 14, value as <Self as Register>::ValueType);
        // Will further expand into
        // self.0.set_bits(
        //     (self.0.get_bits() & !(0x00000003u32 << 14))
        //         | ((value as <Self as Register>::ValueType & 0x00000003u32) << 14),
        // );
        self
    }
    ///Bits 11:13 - Read-only field
    #[inline]
    pub fn get_field3(&self) -> u8 {
        value_read!(self, 0x00000007u32, 11) as u8
        // Will further expand into
        // ((self.0.get_bits() >> 11) & 0x00000007u32) as u8
    }
    ///Bit 10 - Boolean field
    #[inline]
    pub fn is_field2_set(&self) -> bool {
        value_read!(self, 0x00000001u32, 10) == 1
        // Will further expand into
        // ((self.0.get_bits() >> 10) & 0x00000001u32) == 1
    }
    ///Bit 10 - Boolean field
    #[inline]
    pub fn set_field2_value(&mut self, value: bool) -> &mut Self {
        value_write!(self, 0x00000001u32, 10, value as <Self as Register>::ValueType);
        // Will further expand into
        // self.0.set_bits(
        //     (self.0.get_bits() & !(0x00000001u32 << 10))
        //         | ((value as <Self as Register>::ValueType & 0x00000001u32) << 10),
        // );
        self
    }
    ///Bit 10 - Boolean field
    #[inline]
    pub fn set_field2(&mut self) -> &mut Self {
        self.set_field2_value(true)
    }
    ///Bit 10 - Boolean field
    #[inline]
    pub fn unset_field2(&mut self) -> &mut Self {
        self.set_field2_value(false)
    }
    ///Bits 8:9 - Enum field
    #[inline]
    pub fn get_field1(
        &self,
    ) -> Result<CustomType, <CustomType as TryFrom<<Self as Register>::ValueType>>::Error> {
        <CustomType as TryFrom<<Self as Register>::ValueType>>::try_from(value_read!(self, 0x00000003u32, 8))
        // Will further expand into
        // <CustomType as TryFrom<<Self as Register>::ValueType>>::try_from(
        //     (self.0.get_bits() >> 8) & 0x00000003u32,
        // )
    }
    ///Bits 8:9 - Enum field
    #[inline]
    pub fn set_field1(
        &mut self,
        value: CustomType,
    ) -> Result<&mut Self, <<Self as Register>::ValueType as TryFrom<CustomType>>::Error>
    {
        value_write!(self, 0x00000003u32, 8, <<Self as Register>::ValueType as TryFrom<#ty>>::try_from(value)?);
        // Will further expand into
        // self.0.set_bits(
        //     (self.0.get_bits() & !(0x00000003u32 << 8))
        //         | ((<<Self as Register>::ValueType as TryFrom<CustomType>>::try_from(value)?
        //             & 0x00000003u32) << 8),
        // );
        Ok(self)
    }
    ///Bits 0:7 - Read-write by default long field
    #[inline]
    pub fn get_field0(&self) -> u8 {
        value_read!(self, 0x000000FFu32, 0) as u8
        // Will further expand into
        // ((self.0.get_bits() >> 0) & 0x000000FFu32) as u8
    }
    ///Bits 0:7 - Read-write by default long field
    #[inline]
    pub fn set_field0(&mut self, value: u8) -> &mut Self {
        value_write!(self, 0x000000FFu32, 0, value as <Self as Register>::ValueType);
        // Will further expand into
        // self.0.set_bits(
        //     (self.0.get_bits() & !(0x000000FFu32 << 0))
        //         | ((value as <Self as Register>::ValueType & 0x000000FFu32) << 0),
        // );
        self
    }
}

Proposed modules structure

Enclosing peripheral module can look like this

#![doc = "Peripheral description"]

mod reg0;
pub use reg0::*;

const BASE_ADDRESS: usize = 0x0000_0000; // Should be actual peripheral base address

Peripherals module should look like this

pub mod peripheral;

And finally lib.rs should look like this

#![doc = "Device description"]

pub mod peripherals;

So the recommended module hierarchy is

src/
├── lib.rs
└── peripherals/
    ├── mod.rs
    └── peripheral/
        ├── mod.rs
        ├── reg0.rs
        ├── reg1.rs
        └── cluster/
            ├── mod.rs
            ├── reg2.rs
            ├── reg3.rs
            └── reg4.rs

The layout also includes optional cluster module, which can look like this

#![doc = "Cluster description"]

mod reg2;
pub use reg2::*;
mod reg3;
pub use reg3::*;
mod reg4;
pub use reg4::*;

const BASE_ADDRESS: usize = super::BASE_ADDRESS + 0x40; // Enclosing peripheral/cluster base address plus offset

Requirenments to custom types

For read access you must implement TryFrom<u32> for CustomType or From<u32> for CustomType if your register is 32-bit For write access you have to implement TryFrom<CustomType> for u32 or From<CustomType> for u32 respectively

How to use resulting library

use device_crate::peripherals::peripheral;

let mut reg0 = peripheral::reg0()
        .unwrap() // Borrow the register
        .read(); // Load current data stored in register
let field3 = reg0.get_field3(); // Read `u8` field

let field2 = reg0.is_field2_set(); // Read `bool` field
let field1: CustomType = reg0.get_field1().unwrap(); // Read field represented by `CustomType`
reg0
    .set_field0(if field2 {
        reg0.get_field5() as u8
    } else {
        0
    }) // Set `u8` field
    .unset_field2() // Unset `bool` field
    .set_field4(field3 + 10) // Set 'u8' field
    .set_field1(if field1 == Two { One } else { Three }).unwrap() // Set `CustomType` field
    .write(); // Finally write result to hardware register