Update SVD2Swift to generate RegisterArrays (#116)

Updates `SVD2Swift` to automatically generate `RegisterArrays` for
dimensioned SVD instances (excluding fields) instead of N instances
being generated as peers suffixed by an index.

Introduces `RegisterProtocol` to standardize the API for register types
needed for `RegisterArray` to work with both `@RegisterBlocks` and
`Registers`.

Updates the XML decoding library and macro implementation to handle
decoding optional `@XMLInlineElement` properties and Updates the SVD
model structures, such as `SVDCluster`, to make `dimensionElement`
optional with non-optional child properties.

Consolidates the `@XMLAttribute` and `@XMLInlineElement` macro
implementations.

Sources/MMIO/MMIOMacros.swift

@@ -11,6 +11,7 @@
 
 // RegisterBlock macros
 @attached(member, names: named(unsafeAddress), named(init), named(interposer))
+@attached(extension, conformances: RegisterProtocol)
 public macro RegisterBlock() =
  #externalMacro(module: "MMIOMacros", type: "RegisterBlockMacro")
 

Sources/MMIO/Register.swift

@@ -11,7 +11,7 @@
 
 /// A container type referencing of a region of memory whose layout is defined
 /// by another type.
-public struct Register<Value> where Value: RegisterValue {
+public struct Register<Value>: RegisterProtocol where Value: RegisterValue {
  public var unsafeAddress: UInt
 
  #if FEATURE_INTERPOSABLE

Sources/MMIO/RegisterArray.swift

@@ -11,7 +11,7 @@
 
 /// A container type referencing of a region of memory whose layout is defined
 /// by another type.
-public struct RegisterArray<Value> where Value: RegisterValue {
+public struct RegisterArray<Value> {
  public var unsafeAddress: UInt
  public var stride: UInt
  public var count: UInt
@@ -20,27 +20,6 @@ public struct RegisterArray<Value> where Value: RegisterValue {
  public var interposer: (any MMIOInterposer)?
  #endif
 
- @inlinable @inline(__always)
- static func preconditionAligned(unsafeAddress: UInt, stride: UInt) {
- let alignment = MemoryLayout<Value.Raw.Storage>.alignment
- #if $Embedded
- // FIXME: Embedded doesn't have static interpolated strings yet
- precondition(
- unsafeAddress.isMultiple(of: UInt(alignment)),
- "Misaligned address")
- precondition(
- stride.isMultiple(of: UInt(alignment)),
- "Misaligned stride")
- #else
- precondition(
- unsafeAddress.isMultiple(of: UInt(alignment)),
- "Misaligned address '\(unsafeAddress)' for data of type '\(Value.self)'")
- precondition(
- stride.isMultiple(of: UInt(alignment)),
- "Misaligned stride '\(unsafeAddress)' for data of type '\(Value.self)'")
- #endif
- }
-
  #if FEATURE_INTERPOSABLE
  @inlinable @inline(__always)
  public init(
@@ -49,7 +28,6 @@ public struct RegisterArray<Value> where Value: RegisterValue {
  count: UInt,
  interposer: (any MMIOInterposer)?
  ) {
- Self.preconditionAligned(unsafeAddress: unsafeAddress, stride: stride)
  self.unsafeAddress = unsafeAddress
  self.stride = stride
  self.count = count
@@ -62,17 +40,16 @@ public struct RegisterArray<Value> where Value: RegisterValue {
  stride: UInt,
  count: UInt
  ) {
- Self.preconditionAligned(unsafeAddress: unsafeAddress, stride: stride)
  self.unsafeAddress = unsafeAddress
  self.stride = stride
  self.count = count
  }
  #endif
 }
 
-extension RegisterArray {
+extension RegisterArray where Value: RegisterValue {
  @inlinable @inline(__always)
- subscript<Index>(
+ public subscript<Index>(
  _ index: Index
  ) -> Register<Value> where Index: BinaryInteger {
  #if $Embedded
@@ -95,3 +72,29 @@ extension RegisterArray {
  #endif
  }
 }
+
+extension RegisterArray where Value: RegisterProtocol {
+ @inlinable @inline(__always)
+ public subscript<Index>(
+ _ index: Index
+ ) -> Value where Index: BinaryInteger {
+ #if $Embedded
+ // FIXME: Embedded doesn't have static interpolated strings yet
+ precondition(
+ 0 <= index && index < self.count,
+ "Index out of bounds")
+ #else
+ precondition(
+ 0 <= index && index < self.count,
+ "Index '\(index)' out of bounds '0..<\(self.count)'")
+ #endif
+ let index = UInt(index)
+ #if FEATURE_INTERPOSABLE
+ return .init(
+ unsafeAddress: self.unsafeAddress + (index * self.stride),
+ interposer: self.interposer)
+ #else
+ return .init(unsafeAddress: self.unsafeAddress + (index * self.stride))
+ #endif
+ }
+}

Sources/MMIO/RegisterProtocol.swift

@@ -0,0 +1,20 @@
+//===----------------------------------------------------------*- swift -*-===//
+//
+// This source file is part of the Swift MMIO open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+// This only exists because RegisterBlock is not a concrete type, ideally
+// RegisterBlock and Register would both be the same Register type
+public protocol RegisterProtocol {
+ #if FEATURE_INTERPOSABLE
+ init(unsafeAddress: UInt, interposer: (any MMIOInterposer)?)
+ #else
+ init(unsafeAddress: UInt)
+ #endif
+}

Sources/MMIOMacros/Macros/RegisterBlockMacro.swift

@@ -95,3 +95,24 @@ extension RegisterBlockMacro: MMIOMemberMacro {
  ]
  }
 }
+
+extension RegisterBlockMacro: MMIOExtensionMacro {
+ static var extensionMacroSuppressParsingDiagnostics: Bool { true }
+
+ func expansion(
+ of node: AttributeSyntax,
+ attachedTo declaration: some DeclGroupSyntax,
+ providingExtensionsOf type: some TypeSyntaxProtocol,
+ conformingTo protocols: [TypeSyntax],
+ in context: MacroContext<Self, some MacroExpansionContext>
+ ) throws -> [ExtensionDeclSyntax] {
+ // Avoid duplicating diagnostics produced by `MemberMacro` conformance.
+ // Only create extension when applied to struct decls.
+ guard declaration.is(StructDeclSyntax.self) else { return [] }
+
+ let `extension`: DeclSyntax =
+ "extension \(type.trimmed): RegisterProtocol {}"
+
+ return [try `extension`.requireAs(ExtensionDeclSyntax.self, context)]
+ }
+}

Sources/SVD/Macros/SVDMacros.swift

@@ -11,12 +11,12 @@
 
 @attached(peer)
 macro XMLAttribute() =
- #externalMacro(module: "SVDMacros", type: "XMLAttributeMacro")
+ #externalMacro(module: "SVDMacros", type: "XMLMarkerMacro")
 
 @attached(extension, names: named(init(_:)), conformances: XMLElementInitializable)
 macro XMLElement() =
  #externalMacro(module: "SVDMacros", type: "XMLElementMacro")
 
 @attached(peer)
 macro XMLInlineElement() =
- #externalMacro(module: "SVDMacros", type: "XMLInlineElementMacro")
+ #externalMacro(module: "SVDMacros", type: "XMLMarkerMacro")

Sources/SVD/Macros/XMLElement.swift

@@ -22,7 +22,30 @@ enum Errors: Error, @unchecked Sendable {
  case unknownElement(XMLElement)
 }
 
-// XMLElement.child(element) -> T
+// Support for @XMLElement properties
+// where: @XMLInlineElement & XMLElementInitializable
+extension XMLElement {
+ func decode<T>(
+ _: T.Type = T.self
+ ) throws -> T where T: XMLElementInitializable {
+ try self
+ .decode(T?.self)
+ .unwrap()
+ }
+
+ func decode<T>(
+ _: T?.Type = T?.self
+ ) throws -> T? where T: XMLElementInitializable {
+ do {
+ return try T.init(self)
+ } catch Errors.missingValue {
+ return nil
+ }
+ }
+}
+
+// Support for @XMLElement properties
+// where: implied @XMLChild & XMLElementInitializable
 extension XMLElement {
  func decode<T>(
  _: T.Type = T.self,
@@ -64,7 +87,8 @@ extension XMLElement {
  }
 }
 
-// XMLElement.child(node) -> T
+// Support for @XMLElement properties
+// where: implied @XMLChild & XMLNodeInitializable
 extension XMLElement {
  func decode<T>(
  _: T.Type = T.self,
@@ -86,7 +110,8 @@ extension XMLElement {
  }
 }
 
-// XMLElement.attribute(node) -> T
+// Support for @XMLElement properties
+// where: @XMLAttribute & XMLNodeInitializable
 extension XMLElement {
  func decode<T>(
  _: T.Type = T.self,

Sources/SVD/Models/SVDCluster.swift

@@ -48,7 +48,7 @@ public struct SVDCluster {
  /// consecutive array elements and a comma separated list of strings used to
  /// identify each element in the array.
  @XMLInlineElement
- public var dimensionElement: SVDDimensionElement = .init()
+ public var dimensionElement: SVDDimensionElement?
  /// String to identify the cluster. Cluster names are required to be unique
  /// within the scope of a peripheral. A list of cluster names can be build
  /// using the placeholder `%s`. Use the placeholder `[%s]` at the end of the

Sources/SVD/Models/SVDDimensionElement.swift

@@ -18,10 +18,11 @@ import FoundationXML
 @XMLElement
 public struct SVDDimensionElement {
  /// Define the number of elements in an array.
- public var dim: UInt64?
+ public var dim: UInt64
  /// Specify the address increment, in Bytes, between two neighboring array
  /// members in the address map.
- public var dimIncrement: UInt64?
+ public var dimIncrement: UInt64
+ // FIXME: this should be `DimIndexType?`
  /// Do not define on peripheral level. By default, `<dimIndex>` is an
  /// integer value starting at 0.
  public var dimIndex: String?

Sources/SVD/Models/SVDField.swift

@@ -45,7 +45,7 @@ public struct SVDField {
  /// consecutive array elements and a comma separated list of strings used to
  /// identify each element in the array.
  @XMLInlineElement
- public var dimensionElement: SVDDimensionElement = .init()
+ public var dimensionElement: SVDDimensionElement?
  /// Name string used to identify the field. Field names must be unique
  /// within a register.
  public var name: String

Sources/SVD/Models/SVDPeripheral.swift

@@ -31,7 +31,7 @@ public struct SVDPeripheral {
  /// consecutive array elements and a comma separated list of strings used to
  /// identify each element in the array.
  @XMLInlineElement
- public var dimensionElement: SVDDimensionElement = .init()
+ public var dimensionElement: SVDDimensionElement?
  /// The string identifies the peripheral. Peripheral names are required to
  /// be unique for a device. The name needs to be an ANSI C identifier to
  /// generate the header file. You can use the placeholder [%s] to create

Sources/SVD/Models/SVDRegister.swift

@@ -35,7 +35,7 @@ public struct SVDRegister {
  /// consecutive array elements and a comma separated list of strings used to
  /// identify each element in the array.
  @XMLInlineElement
- public var dimensionElement: SVDDimensionElement = .init()
+ public var dimensionElement: SVDDimensionElement?
  /// String to identify the register. Register names are required to be
  /// unique within the scope of a peripheral. You can use the placeholder
  /// `%s`, which is replaced by the dimIndex substring. Use the placeholder