Add initial support for discontiguous bit fields (#10)

Updates the bit field macros 'bits' argument to accept a list of bit
ranges. The register macro uses this information to generate a bit field
descriptor type conforming to either ContiguousBitField or
DiscontiguousBitField. The public api for users remains unchanged.

This commit doesn't introduce any diagnostics for overlapping bit fields
within a discontiguous bit fields. A future commit will include those
diagnostics as well as additional diagnostics for overlapping bit fields
across fields in a register.

In the future the implementation of bit field descriptors could be
improved. At a high level we would introduce a BitField protocol with
two requirements: least significant bit and most significant bit. We
would then extend FixedWidthInteger with a subscript taking a variadic
list of these fields. This change would allow us to remove the
distinction between contiguous and discontiguous bit fields. In order to
make this change we need variadic pack iteration to land and we need to
be able to use variadic packs without using runtime metadata.

Author: rauhul

Package.swift

@@ -20,6 +20,8 @@ let package = Package(
   ],
   targets: [
     .target(name: "MMIO", dependencies: ["MMIOMacros", "MMIOVolatile"]),
+    .testTarget(name: "MMIOTests", dependencies: ["MMIO"]),
+
     .macro(
       name: "MMIOMacros",
       dependencies: [
@@ -38,5 +40,6 @@ let package = Package(
         .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
         .product(name: "SwiftSyntaxMacrosTestSupport", package: "swift-syntax"),
       ]),
+
     .target(name: "MMIOVolatile"),
   ])

Sources/MMIO/BitField.swift

@@ -9,18 +9,128 @@
 //
 //===----------------------------------------------------------------------===//
 
-public typealias BitFieldStorage = FixedWidthInteger & UnsignedInteger
+// Explore bit field refactor:
+// * requires variadic pack iteration
+// * requires no metadata-less variadic packs
+// - protocol BitField with (least|most) significant bit requirements
+// - FixedWidthInteger.subscript[(variadic T: BitField)] -> Storage
+
+extension FixedWidthInteger {
+  @inline(__always)
+  static func bitRangeWithinBounds(bits bitRange: Range<Int>) -> Bool {
+    bitRange.lowerBound >= 0 && bitRange.upperBound <= Self.bitWidth
+  }
+
+  subscript(bits bitRange: Range<Int>) -> Self {
+    @inline(__always) get {
+      precondition(Self.bitRangeWithinBounds(bits: bitRange))
+      let bitWidth = bitRange.upperBound - bitRange.lowerBound
+      let bitMask: Self = 1 << bitWidth &- 1
+      return (self >> bitRange.lowerBound) & bitMask
+    }
+
+    @inline(__always) set {
+      precondition(Self.bitRangeWithinBounds(bits: bitRange))
+      let bitWidth = bitRange.upperBound - bitRange.lowerBound
+      let bitMask: Self = 1 << bitWidth &- 1
+      self &= ~(bitMask << bitRange.lowerBound)
+      self |= (newValue & bitMask) << bitRange.lowerBound
+    }
+  }
+}
+
+extension FixedWidthInteger {
+  static func bitRangesCoalesced(bits bitRanges: [Range<Int>]) -> Bool {
+    let bitRanges = bitRanges.sorted { $0.lowerBound < $1.lowerBound }
+    var lowerBound = -1
+    for bitRange in bitRanges {
+      // Specifically ensure that the bit ranges dont overlap, e.g. the
+      // following ranges are not valid: 0..<1, 0..<2. This is to ensure ranges
+      // are coalesced before iterating reduce the number of mask and shift
+      // operations needed.
+      guard lowerBound <= bitRange.lowerBound else { return false }
+      lowerBound = bitRange.upperBound
+    }
+    return true
+  }
+
+  subscript(bits bitRanges: [Range<Int>]) -> Self {
+    @inline(__always) get {
+      precondition(Self.bitRangesCoalesced(bits: bitRanges))
+
+      var currentShift = 0
+      var value: Self = 0
+      for bitRange in bitRanges {
+        let valueSlice = self[bits: bitRange]
+        value |= valueSlice << currentShift
+        let bitWidth = bitRange.upperBound - bitRange.lowerBound
+        currentShift += bitWidth
+      }
+      return value
+    }
+
+    @inline(__always) set {
+      precondition(Self.bitRangesCoalesced(bits: bitRanges))
+
+      var newValue = newValue
+      for bitRange in bitRanges {
+        self[bits: bitRange] = newValue
+        let bitWidth = bitRange.upperBound - bitRange.lowerBound
+        newValue >>= bitWidth
+      }
+    }
+  }
+}
 
 public protocol BitField {
-  associatedtype RawStorage: BitFieldStorage
+  associatedtype Storage: FixedWidthInteger & UnsignedInteger
+
+  static func insert(_ value: Storage, into storage: inout Storage)
+  static func extract(from storage: Storage) -> Storage
+}
+
+public protocol ContiguousBitField: BitField {
   static var bitRange: Range<Int> { get }
   static var bitWidth: Int { get }
   static var bitOffset: Int { get }
-  static var bitMask: RawStorage { get }
+  static var bitMask: Storage { get }
+}
+
+extension ContiguousBitField {
+  public static var bitWidth: Int {
+    Self.bitRange.upperBound - Self.bitRange.lowerBound
+  }
+  public static var bitOffset: Int { Self.bitRange.lowerBound }
+  public static var bitMask: Storage { (1 << Self.bitWidth) &- 1 }
+}
+
+extension ContiguousBitField {
+  // FIXME: value.bitWidth <= Self.bitWidth <= Storage.bitWidth
+  @inline(__always)
+  public static func insert(_ value: Storage, into storage: inout Storage) {
+    storage[bits: Self.bitRange] = value
+  }
+
+  @inline(__always)
+  public static func extract(from storage: Storage) -> Storage {
+    storage[bits: Self.bitRange]
+  }
 }
 
-extension BitField {
-  public static var bitWidth: Int { self.bitRange.count }
-  public static var bitOffset: Int { self.bitRange.lowerBound }
-  public static var bitMask: RawStorage { (1 << self.bitWidth) - 1 }
+public protocol DiscontiguousBitField: BitField {
+  /// - Precondition: Bit bitRanges must not overlap and must be sorted by from
+  /// lowest to highest bit index
+  static var bitRanges: [Range<Int>] { get }
+}
+
+extension DiscontiguousBitField {
+  @inline(__always)
+  public static func insert(_ value: Storage, into storage: inout Storage) {
+    storage[bits: Self.bitRanges] = value
+  }
+
+  @inline(__always)
+  public static func extract(from storage: Storage) -> Storage {
+    storage[bits: Self.bitRanges]
+  }
 }

Sources/MMIO/Extensions/FixedWidthInteger.swift

@@ -16,7 +16,7 @@ import MMIOVolatile
 /// The set of types which conform to this protocol restricts the the set of
 /// volatile operations available on the platform. As such, user code must
 /// _never_ conform new types to this protocol.
-public protocol MMIOVolatileStorage: BitFieldStorage {
+public protocol MMIOVolatileStorage: FixedWidthInteger & UnsignedInteger {
   /// Loads an instance of `self` from the address pointed to by pointer.
   static func load(from pointer: UnsafePointer<Self>) -> Self
   /// Stores an instance of `self` to the address pointed to by pointer.

Sources/MMIO/MMIOVolatileStorage.swift

@@ -0,0 +1,56 @@
+//===----------------------------------------------------------*- swift -*-===//
+//
+// This source file is part of the Swift MMIO open source project
+//
+// Copyright (c) 2023 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
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftSyntax
+
+struct BitFieldDescription {
+  var accessLevel: AccessLevel?
+  var bitWidth: Int
+  var type: any BitFieldMacro.Type
+  var fieldName: IdentifierPatternSyntax
+  var fieldType: TypeSyntax
+  var bitRanges: [Range<Int>]
+  var bitRangeExpressions: [ExprSyntax]
+  var projectedType: Int?
+}
+
+extension BitFieldDescription {
+  func validate() throws {
+    // FIXME: Validate bit range overlap
+  }
+
+  func declarations() -> [DeclSyntax] {
+    switch bitRangeExpressions.count {
+    case 0:
+      preconditionFailure()
+    case 1:
+      let bitRange = self.bitRangeExpressions[0]
+      return [
+        """
+        \(self.accessLevel)enum \(self.fieldType): ContiguousBitField {
+          \(self.accessLevel)typealias Storage = UInt\(raw: self.bitWidth)
+          \(self.accessLevel)static let bitRange = \(bitRange)
+        }
+        """
+      ]
+    default:
+      let bitRanges = ArrayExprSyntax(expressions: self.bitRangeExpressions)
+      return [
+        """
+        \(self.accessLevel)enum \(self.fieldType): DiscontiguousBitField {
+          \(self.accessLevel)typealias Storage = UInt\(raw: self.bitWidth)
+          \(self.accessLevel)static let bitRange = \(bitRanges)
+        }
+        """
+      ]
+    }
+  }
+}

Sources/MMIOMacros/Macros/BitFieldDescription.swift

@@ -15,21 +15,15 @@ import SwiftSyntaxBuilder
 import SwiftSyntaxMacroExpansion
 import SwiftSyntaxMacros
 
-struct BitField {
-  var type: any BitFieldMacro.Type
-  var fieldName: IdentifierPatternSyntax
-  var fieldType: TypeSyntax
-  var bitRange: Range<Int>
-  var projectedType: Int?
-}
-
-// @BaseName(bits: 0..<1, 3..<4, as: Bool.self)
+// @BaseName(bits: 3..<4, 0..<1, as: Bool.self)
 protocol BitFieldMacro: MMIOAccessorMacro, ParsableMacro {
   static var isReadable: Bool { get }
   static var isWriteable: Bool { get }
   static var isSymmetric: Bool { get }
 
-  var bitRange: Range<Int> { get }
+  var bitRanges: [Range<Int>] { get }
+  var bitRangeExpressions: [ExprSyntax] { get }
+
   var projectedType: Int? { get }
 }
 
@@ -130,7 +124,8 @@ struct ReservedMacro: BitFieldMacro, Sendable {
   static let isSymmetric = true
 
   @Argument(label: "bits")
-  var bitRange: Range<Int>
+  var bitRanges: [Range<Int>]
+  var bitRangeExpressions: [ExprSyntax] { self.$bitRanges }
 
   var projectedType: Int?
 
@@ -141,7 +136,7 @@ struct ReservedMacro: BitFieldMacro, Sendable {
   ) throws {
     switch label {
     case "bits":
-      try self._bitRange.update(from: expression, in: context)
+      try self._bitRanges.update(from: expression, in: context)
     default:
       fatalError()
     }
@@ -156,7 +151,8 @@ struct ReadWriteMacro: BitFieldMacro, Sendable {
   static let isSymmetric = true
 
   @Argument(label: "bits")
-  var bitRange: Range<Int>
+  var bitRanges: [Range<Int>]
+  var bitRangeExpressions: [ExprSyntax] { self.$bitRanges }
 
   @Argument(label: "as")
   var projectedType: Int?
@@ -168,7 +164,7 @@ struct ReadWriteMacro: BitFieldMacro, Sendable {
   ) throws {
     switch label {
     case "bits":
-      try self._bitRange.update(from: expression, in: context)
+      try self._bitRanges.update(from: expression, in: context)
     case "as":
       try self._projectedType.update(from: expression, in: context)
     default:
@@ -185,7 +181,8 @@ struct ReadOnlyMacro: BitFieldMacro, Sendable {
   static let isSymmetric = false
 
   @Argument(label: "bits")
-  var bitRange: Range<Int>
+  var bitRanges: [Range<Int>]
+  var bitRangeExpressions: [ExprSyntax] { self.$bitRanges }
 
   @Argument(label: "as")
   var projectedType: Int?
@@ -197,7 +194,7 @@ struct ReadOnlyMacro: BitFieldMacro, Sendable {
   ) throws {
     switch label {
     case "bits":
-      try self._bitRange.update(from: expression, in: context)
+      try self._bitRanges.update(from: expression, in: context)
     case "as":
       try self._projectedType.update(from: expression, in: context)
     default:
@@ -214,7 +211,8 @@ struct WriteOnlyMacro: BitFieldMacro, Sendable {
   static let isSymmetric = false
 
   @Argument(label: "bits")
-  var bitRange: Range<Int>
+  var bitRanges: [Range<Int>]
+  var bitRangeExpressions: [ExprSyntax] { self.$bitRanges }
 
   @Argument(label: "as")
   var projectedType: Int?
@@ -226,7 +224,7 @@ struct WriteOnlyMacro: BitFieldMacro, Sendable {
   ) throws {
     switch label {
     case "bits":
-      try self._bitRange.update(from: expression, in: context)
+      try self._bitRanges.update(from: expression, in: context)
     case "as":
       try self._projectedType.update(from: expression, in: context)
     default: