Introducing Swift MMIO

[ole (Ole Begemann)]

@lorenzofiamingo

Sure

func foo() -> Int { return 0 }
func foo() -> Int? { return 1 }

let f = foo() // Error: Ambiguous use of 'foo'
let f: Int = foo() // 0
let f: Int? = foo() // 1

Sure, but what does this have to do with the RawRepresentable example I posted above?

[lorenzofiamingo]

My fault, sorry. I was misled by this

@ole

In non-generic contexts users will have access to the non-failable init, while in generic contexts only the failable init? will be available (as it should be).

[fumoboy007]

Happy New Year!

@rauhul

Additionally, I think there's some confusion about the functionality exposed by MMIO, which is understandable due to the lack of documentation. Here's a deeper dive into what @Register does and the functionality of the current API:

As someone without MMIO experience, the additional context was very helpful. Thanks!

@rauhul

As demonstrated in the original post, registers provide a modify method to make read-modify-write (RMW) routines easy and "swifty."

Ahhh, I think this is the part I misunderstood in the original post. I didn’t realize that you can only access the properties inside .modify or after calling .read, and I didn’t realize that the @Register struct isn’t the struct that is being accessed!

I guess I should have seen it given that the property in the @RegisterBank struct in the original post is of type Register<CR1> rather than just CR1. That being said, it seems like something that would be easy to miss. In fact…

@rauhul

let isr = CEC_ISR(unsafeAddress: 0x1000)

I think this should be let isr = Register<CEC_ISR>(unsafeAddress: 0x1000), no?

After clearing up this misunderstanding, I think the design overall makes a lot of sense. There a few details that I think could be changed to make it easier to understand and more familiar to Swift developers:

1. Rename @Register to @RegisterDescriptor to make it clear that the struct is not the one you will read from or write to.
2. Swap the projected type and the descriptor type in the property declaration. As mentioned before, it feels more natural to have the projected type be the property type. Also, moving the descriptor type to the macro with a parameter name like generatedDescriptorType helps the user understand that they can change the generated type name to anything they want. (At first, I thought the name had to be a “to uppercase” transformation of the property name.)
3. Add RawRepresentable conformance to the generated Read and Write structs instead of defining a storage property. As @ole pointed out, the initializer can be non-optional and still satisfy the protocol requirement.
4. Perhaps consider eliminating the generated Raw struct and moving the members into the generated Read and Write structs as $-prefixed members. This would avoid having similarly-named raw and rawValue properties in the Read and Write structs.
5. If possible, use an associated type to provide the bit width rather than specifying it in the @RegisterDescriptor macro. The associated type could be constrained to FixedWidthInteger & UnsignedInteger.

After applying these changes to the example in the original post, the code looks a lot clearer to me:

import MMIO

/// An example 32-bit wide register, encompassing three individual bit fields:
/// - "en" (Enable)
/// - "clken" (Clock Enable)
/// - "rst" (Reset)
@RegisterDescriptor
struct CR1 {
  typealias RawValue = UInt32

  @ReadWrite(bits: 0..<1, generatedDescriptorType: EN.self)
  var en: Bool
  @ReadWrite(bits: 1..<2, generatedDescriptorType: CLKEN.self)
  var clken: Bool
  @ReadWrite(bits: 2..<3, generatedDescriptorType: RST.self)
  var rst: Bool
}

@RegisterBank
struct Control {
  @RegisterBank(offset: 0x0)
  var cr1: Register<CR1>
  @RegisterBank(offset: 0x4)
  var cr2: Register<CR2>
}

var control = Control(unsafeAddress: 0x1000)

// Get a reference to the cr1 register in the control bank.
var cr1 = control.cr1

// Perform a read-modify-write of the cr1 register.
cr1.modify { cr1 in
  // Mutate `en` as a Bool.
  cr1.en = true

  // Mutate `clken` as a raw integer.
  cr1.$clken = 0

  // Mutate `rst` using C-style manual bit operations.
  cr1.rawValue |= (1 & CR1.RST.bitMask) << CR1.RST.bitOffset
}

[rauhul (Rauhul Varma)]

These are great ideas, but there may be some more design discussion needed to make them happen; do you mind opening an issue on the swift-mmio repo and continuing the discussion there?

[fumoboy007]

Done!

1. Rename `@Register` to `@RegisterDescriptor` · Issue #69 · apple/swift-mmio · GitHub
2. Existing issue: Register field definitions are confusing due to vacuous types · Issue #33 · apple/swift-mmio · GitHub
3. Add `RawRepresentable` conformance to the generated `Read` and `Write` structs · Issue #70 · apple/swift-mmio · GitHub
4. Merge properties of `Raw` struct into `Read`/`Write` structs · Issue #71 · apple/swift-mmio · GitHub
5. Use an associated type to provide the bit width of a register · Issue #72 · apple/swift-mmio · GitHub

[nikolai.ruhe]

Great work!

Here's some feedback from using Swift MMIO.