Refactor K20 to use ioreg!

[bgamari]

No description provided.

[bgamari]

@bharrisau you may be interested in this. It hasn't been tested yet however.

[bharrisau]

Hmm, the brace alignment to make way for the doc comments is disappointing.

[bharrisau]

And there will need to be some thinking in how to handle SIM. It changes between devices with different peripheral loadouts. Might end up having to take an ID and converting it to a register and bit pair.

[bgamari]

@bharrisau I agree concerning the brace alignment issue and was thinking of implementing inner docstrings (e.g. //!) as a way to fix this.

[bgamari]

@bharrisau My only experience with the K20 series is with the MK20DX128. It's possible (likely?) that the SIM block changes in different family members. If you have any insights here I'd love to hear.

[bharrisau]

Better wait for @farcaller, style is his thing ;)

[farcaller]

You lost your cursor :)

[farcaller]

The brace alignment is truly quite a mess, also, "in-line" apidocs are //!, not ///, no? I'd prefer something like

/// Port control register
0x0 => reg32 pcr[32] {
  /// Pull direction select
  0 => ps {
    0 => PULL_DOWN,
    1 => PULL_UP
  }
...

[bharrisau]

If parsing isn't an issue, that matches what we have done elsewhere.

[bgamari]

@farcaller I agree that the brace alignment isn't great. I'll admit that I'm not terribly familiar with this aspect of Rust's docstring syntax, //! sounds like what I had intended to implement. I do worry, however, that placing field docstrings on separate lines is going to greatly bloat the format, essentially doubling the size. Perhaps this would be acceptable?

/// Port control register
0x0 => reg32 pcr[32] {
  0 => ps {                //! Pull direction select
    0 => PULL_DOWN,
    1 => PULL_UP
  }

It will take a bit of parsing acrobatics, but I think it should be doable.

[farcaller]

placing field docstrings on separate lines is going to greatly bloat the format

Same problem as docstrings in struct definitions :-(

Having support for both /// and //! would be nice.

[bharrisau]

If you hadn't done such a good job of implementing the DSL I was going to suggest a syntax that let the compiler handle all the parsing using item_decorators and item_modifiers.

#[zinc_block]
pub struct Foo {
  /// BAR register
  #[offset(0)] bar: Bar
}

#[zinc_register(u32)]
struct Bar {
  /// Pull direction select
  #[bit(0)] ps: bool,
  #[bits(1, 2)] #[ro] baz: BazEnum
}

We could revisit it if the maintenance on the parser gets too much.

[bgamari]

@bharrisau somehow I missed your comment until now. I hadn't known about item decorators until you mentioned them but even now that I do, I still weakly believe that a dedicated parser is the right way to do things. Using Rust syntax here strongly detracts from the readability and verifiability of the code. Especially given how (relatively) simple the parser is, I think it's worth the code.

In other news, I intend on fixing the comment situation (implementing proper inner and outer docstrings) this weekend, if not earlier.

[bharrisau]

Yes, the iroeg parser provides a much much nicer language than doing it in Rust with attributes. It just comes down to the decision between maintaining our parser, or letting Rust handle it. In your PR, the parser was only about half the code anyway the rest was generation of the ioreg stuff.

As I'm not the one maintaining it, I prefer the DSL.

[bgamari]

I quickly worked inner doc comment support into the parser this afternoon and updated the k20 branch. Let me know how this looks. Not that I'm not entirely sure that the use of inner doc comments after non-block items is sane.

[bharrisau]

Reminder to remove all the ioreg changes from this PR.