Architecture Overview

Architecture overview

ASFireWire has a DriverKit FireWire driver extension and a Swift control/installer app. The app installs the extension and displays diagnostics; it does not carry the Core Audio stream. AudioDriverKit publishes audio devices, while the SCSI controller integration exposes SBP-2 targets to the macOS SCSI stack.

Layers and boundaries

Core Audio / HAL
       ↕
AudioDriverKit, audio format/clock/configuration
       ↕
Audio/Wire: content codecs and CIP/IEC 61883/AM824 framing
       ↕  Audio/Ports: framed packets + neutral lifetime-owned contracts
Isoch / Async: opaque packets, OHCI contexts and DMA
       ↕
Bus policy / Hardware MMIO / PCIDriverKit controller access
       ↕
FireWire controller and bus

Transport moves fully framed packets opaquely. It must not parse/build CIP or know Core Audio format semantics. Content framing currently lives under Audio/Wire; CIP also serves non-audio content, so that home is provisional, but it must not move into transport. Audio code must not reach into descriptors, DMA, or MMIO.

The seam must own the lifetime of its buffer views/control contract. The core and audio sides run on separate services/queues: drain dependent work and release views before freeing mappings or detaching hardware. No MMIO may follow detach.

Core subsystems

Area	Responsibility
Hardware, Phy	OHCI registers, hardware access and PHY packet mechanism
Async	Request/response transmit/receive, transaction labels, routing, completion
Isoch and shared DMA primitives	Isochronous contexts, descriptor programs, packet movement
Bus	Reset, Self-ID, topology/generation, CSR, bus roles, IRM and timing policy
ConfigROM and Discovery	Local ROM staging, remote ROM reads/parsing, devices and units
Protocols	AV/C/FCP/CMP, SBP-2 and register/PCR access
SCSIController	HBA and SBP-2 target publication/readiness
Audio	Family protocols, wire codecs, runtime configuration, AudioDriverKit publication
Service, Controller, Scheduling	Composition, lifecycle coordination and scheduled work
Diagnostics and UserClient	Snapshots, metric exports and bounded app/driver interfaces

Startup, reset, and teardown

The root runtime coordinator owns service transitions and admission. Conceptually it establishes controller access, wires services, allocates DMA/contexts, stages the local ROM, arms interrupts/Self-ID, and starts bus discovery. Actual ordering belongs to source and the runtime lifecycle contract, not an independently maintained sequence here.

A bus reset changes generation and invalidates stale routes. Topology/discovery refresh, protocol recovery and audio rebind must use the new route. Planned stop closes new work, quiesces producers/queues and contexts, then releases mappings and hardware. Provider removal can revoke hardware access before ordinary cleanup; teardown must respect that.

The Config ROM pipeline separates build, stage, read, scan, pure parsing, and storage. A generation scan completes once after terminal node states and outstanding requests drain. See the Config ROM subsystem.

Async commands pass through transmit contexts and descriptor construction to OHCI DMA; interrupts and receive parsing route results to transactions matched by labels. Ring wrap padding, last-descriptor status, branches and completion scans are one mechanism: changing one part without the rest can stall all device I/O.

Audio and other device classes

AudioDeviceHost is the shared publication, recovery and teardown shell for DICE, AV/C, MOTU and RME families. Family adapters provide device facts and events, rather than independent copies of the lifecycle. See the host source.

Playback goes from shared Core Audio output buffers through audio content encoding to isochronous transmit. Receive packets are decoded into the input view used by the audio stack. Resolved rate, per-stream geometry and channel maps must agree with HAL formats; channel count alone does not prove socket-to-wire mapping or working sound.

DV capture and audio receive currently share receive context 0 and are mutually exclusive. SBP-2 integrates through the SCSI HBA; scanner/disk functionality remains device-specific hardware evidence. See Device Compatibility for both classes.

Repository map and engineering references

• ASFW/: Swift installer/control app and optional MCP diagnostics.
• ASFWDriver/: C++ driver, protocol families, audio integration and user client.
• tests/ and ASFWTests/: host logic, fixtures and Swift tests.
• The maintainer's isolated AudioDriverKit lab is local-only and intended for a separate project.
• tools/: diagnostics, simulators and development utilities.
• documentation/fixtures/: captured hardware reports and test evidence; implementation contracts live alongside source.
• project.yml: source specification for the committed generated Xcode project.

Use RAII, explicit endianness, centralized hardware constants, compile-time invariants, and host-testable logic. Check DMA barriers and bounded hardware quiesce, and design buffer/timing margins for clock drift and packet loss, not just ideal arithmetic.

Read CONTRIBUTING.md and CLAUDE.md for requirements; Building and Signing for tools; FireWire Fundamentals for background; and Audio Semantics for configuration concepts.