Can you include an example output?

Also, the relevant doc is probably just the readme for the crate.

Example: I'm using the example shown in the crate itself

tock_registers::register_bitfields! [u32,
    Control [
        RANGE OFFSET(4) NUMBITS(2) [
            VeryHigh = 0,
            High = 1,
            Low = 2
        ],
        EN  OFFSET(3) NUMBITS(1) [],
        INT OFFSET(2) NUMBITS(1) []
    ],
    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) []
    ],
    InterruptFlags [
        UNDES   10,
        TXEMPTY  9,
        NSSR     8,
        OVRES    3,
        MODF     2,
        TDRE     1,
        RDRF     0
    ]
];

fn main() {
    let control = LocalRegisterCopy::<u32, Control::Register>::new(0x0);
    let status = LocalRegisterCopy::<u32, Status::Register>::new(0x0);
    let flags = LocalRegisterCopy::<u32, InterruptFlags::Register>::new(0xFF);

    println!("control = {:?}", control);
    println!("status = {:?}", status);
    println!("flags = {:?}", flags);
}

With the feature debug_registers it will output

control = Control { RANGE: VeryHigh, EN: false, INT: false }
status = Status { TXCOMPLETE: false, TXINTERRUPT: false, RXCOMPLETE: false, RXINTERRUPT: false, MODE: FullDuplex, ERRORCOUNT: 0 }
flags = InterruptFlags { UNDES: false, TXEMPTY: false, NSSR: false, OVRES: true, MODF: true, TDRE: true, RDRF: true }

Here we are using boolean for 1 bit fields, enums are printed correctly, and if the value is not 1 bit and not enum it is printed as a number

Without this feature it will just output normal

control = 0
status = 0
flags = 255

I put this specifically in LocalRegisterCopy only so that we don't issue multiple reads to the register which may cause unwanted behavior.

Thank you for this contribution. In general, we're somewhat hesitant to add compilation features to crates in the Tock ecosystem -- they are not easily testable in CI (in particular, all permutations of features), and also not fine grained. Given that many crates rely on the tock-registers crate, any single such reverse-dependency enabling this feature will cause it to be enabled globally, for all users of tock-registers. I think that the proposed feature is very useful, but it has the potential to increase flash size, possibly exceeding a board's flash space if enabled globally, for all debugged registers.

Another way to selectively add such more verbose debugging output could be a wrapper type, such as (with the trait named RegisterDebugInfo):

trait RegisterDebugInfo {
    // methods to query the required debug information

    fn debug<'a>(&'a self) -> RegisterDebug<'a, Self> {
        RegisterDebug(self)
    }
}

pub struct RegisterDebug<'a, R: RegisterDebugInfo>(&'a R); 

impl<'a, R: RegisterDebugInfo> fmt::Debug for RegisterDebug<'a, R> { ... }

This would allow us to avoid conditional compilation, while not generating any additional code if this infrastructure is not used.

Another improvement could be to avoid the use of macros to both parse and format our custom register_bitfields definitions, and to represent the various register fields through proper Rust types, accessible & discoverable through this RegisterDebug trait. Retrieving this information might require extending the code & interfaces we generate in the main register_bitfields macro though.

Thanks @lschuermann , these are really nice ideas for optimization and reducing code.

I'll work on it.

Hello @lschuermann , I have implemented a new way to use debug.

It's called with reg.debug::<Register::Debug>().
This way we can opt in debugging easily, and all other registers will be ignored.

There are some stuff we can discuss.

• We can make something like RegisterLongName that contain the details of the debug info that would return it instead of having to provide it manually in the debug function.
  I was trying to add a type field into RegisterLongName, but its implemented for () by default which made things more difficult, probably a new trait would be best here if we choose to.
• For the parsing, I don't think we can expand on the bitmask macro sadly since we are processing registers as a whole and not fields.

Let me know what you think.

Thanks

I'm thinking of removing the Debug struct and instead implement the RegisterDebugInfo in the Register itself, this will provide less code and better interface. But I'm not sure if this will result in more code getting added to the flash even if we didn't call debug()

I'm thinking of removing the Debug struct and instead implement the RegisterDebugInfo in the Register itself, this will provide less code and better interface. But I'm not sure if this will result in more code getting added to the flash even if we didn't call debug()

I think that's a good idea. If those functions are not used, they shouldn't have any runtime overheads (flash or RAM). One exception has historically been when you convert such a type into a trait object, which will generate a vtable that then holds references to these methods. If this is still an issue it needs to be solved upstream with the Rust compiler, and we can work around it by simply avoiding conversions into trait objects.

I was also thinking about removing the feature-flag entirely. As long as we actively have to call debug(), and there is no overhead to this infrastructure otherwise, it's fine to always include it.

@Amjad50 I spent some good amount of time to look through all the code, and this is pretty awesome. The idea to build a sequence of types in the macro and then recurse through them, taking two mutable closures with you, is very clever. It took me quite some time to really understand why all of this works.

In hopes to improve on that a bit, I took the liberty to push a commit to this PR:

• It improves documentation. In particular, it attempts to clearly communicate guarantees offered by the various APIs introduced, such as in the FieldValueEnumSeq (né EnumDebug) or RegisterDebugInfo trait. This should make it a little easier to understand what's going on.

• It fixes a minor issue where the Debuggable trait description in the interfaces module documentation was misplaced.

• It introduces a proper field value enum type sequence trait (FieldValueEnumSeq), which has a cons FieldValueEnumCons and nil FieldValueEnumNil constructor. While tuples offer a more compact way to represent the same, they are incredibly hard to read with many levels of nesting, and don't offer type uniqueness. Now when something goes wrong, we have a slightly more clear output (in the form of FieldValueEnumCons<u38, Uart::ENABLE::Value, FieldValueEnumNil>).

  Also, this new type sequence uses cons and nil constructors, versus a cons / last style sequence. This happens to be closer to constructs found in other functional languages and avoid special-casing the empty-sequence case.

• Adds a small test + demo of the .debug() method to the fields module doc-comment.

Let me know whether these changes look good to you.

Thanks @lschuermann, these are really nice additions and improvements.
I feel sorry for making it hard to understand. Thanks for the fixes and documentation.
I like the new way of recursing into a nil better than doing it in pairs.

Beside the above small comment, I think the new changes are very good.

Updated!

Error: fatal: unable to access 'https://github.com/tock/tock/': Could not resolve host: github.com
Error: The process '/usr/local/bin/git' failed with exit code 128

Seems to have been a fluke with GitHub's Mac runner.