swift-mmio

0.0.1

Define and operate on type safe MMIO
apple/swift-mmio

What's New

Swift MMIO 0.0.1

2023-11-17T20:43:21Z

Swift MMIO initial release.

Additions

  • Introduces @RegisterBank and @RegisterBank(offset:) macros, enabling you
    to define register groups directly in Swift code. [#2]
  • Introduces @Register macro and bit field macros (@Reserved, @ReadWrite,
    @ReadOnly, @WriteOnly) for declaring registers composed of bit fields. Bit
    field macros take a range parameter which describes the subset of bits they
    reference (e.g., @ReadWrite(bits: 3..<7)). [#4]
  • Enhances bit field macros to support discontiguous bit fields. They now accept
    a variadic list of bit ranges and automatically handle scattering/gathering
    from the relevant bits (e.g., @ReadWrite(bits: 3..<7, 10..<12)). [#10]
  • Enhances bit field macros with type projections via a new as: parameter.
    Projections allow you to operation on bit fields using strong types instead of
    raw integers (e.g. @ReadWrite(bits: 3..<7, as: A.self)) [#27]
  • Enhances registers with support for interposing reads and writes when
    compiling with FEATURE_INTERPOSABLE. You can use interposers to unit test
    drivers. This feature is enabled when building with the
    SWIFT_MMIO_FEATURE_INTERPOSABLE environment variable defined. [#31]

The 0.0.1 release includes contributions from @rauhul. Thank you!

Swift MMIO

Swift MMIO is an open source package for defining and operating on memory mapped IO directly in Swift.

Sample Usage

Swift MMIO makes it easy to define registers directly in Swift source code and manipulate them in a safe and ergonomic manner.

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

@Register(bitWidth: 32)
struct CR1 {
  @ReadWrite(bits: 12..<13, as: Bool.self)
  var en: EN
}

let control = Control(unsafeAddress: 0x1000)
control.cr1.modify { $0.en = true }

Using Swift MMIO in your project

Swift MMIO supports use with the Swift Package Manager. First, add the Swift MMIO repository to your Package's dependencies:

.package(url: "https://github.com/apple/swift-mmio.git", from: "0.0.1"),

Important: This project follows semantic versioning. While still in major version 0, source-stability is only guaranteed within minor versions (e.g. between 0.0.3 and 0.0.4). If you want to guard against potentially source-breaking package updates, you can specify your package dependency using .upToNextMinor(from: "0.0.1") as the requirement.:

.package(url: "https://github.com/apple/swift-mmio.git", .upToNextMinor(from: "0.0.1")),

Second, add the MMIO library to your targets' dependencies:

.target(
  name: "DeviceRegisters",
  dependencies: [
    .product(name: "MMIO", package: "swift-mmio")
  ]),

Finally, import MMIO in your Swift source code.

Documentation

For guides, articles, and API documentation see the Package's documentation on the Web or in Xcode.

Contributing to Swift MMIO

Code of Conduct

Like all Swift.org projects, we would like the Swift MMIO project to foster a diverse and friendly community. We expect contributors to adhere to the Swift.org Code of Conduct. A copy of this document is available in this repository.

Contact information

The current code owner of this package is Rauhul Varma (@rauhul). You can contact him on the Swift forums.

In case of moderation issues, you can also directly contact a member of the Swift Core Team.

Description

  • Swift Tools 5.9.0
View More Packages from this Author

Dependencies

Last updated: Wed Dec 06 2023 10:29:17 GMT-1000 (Hawaii-Aleutian Standard Time)