Skip to content

j81: speakers — SmartIO, MCA v1 and MAX98721 on the iPad Air 2 - #192

Merged
henrikklee merged 22 commits into
OrchardLinux:mainfrom
ricktav:j81/audio
Nov 22, 2026
Merged

henrikklee merged 22 commits into
OrchardLinux:mainfrom
ricktav:j81/audio

Conversation

@ricktav

@ricktav ricktav commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

Summary

The iPad Air 2's (J81, A8X / T7001) speakers. With this, both speakers play in stereo, on an installed Omarchy through PipeWire as well: an ALSA card "J81 Speakers" with a UCM profile, so PipeWire offers it as "Built-in Audio Speakers".

The A8X audio path is the one the A9/A10 support already uses (SmartIO DMA → MCA → i2s-switch → amplifiers), but with older versions of each block. This PR adds those versions and the amplifier driver, and describes the speaker link in the device tree.

Changes

  • SmartIO (drivers/soc-apple 0028-0029): the A8/A8X SmartIO runs AppleA7IOP version 1 mailboxes. On V1 the AP has to enable the send FIFO itself; without that, setup fails with -EBUSY.
  • Firmware: devices/j81/firmware.json stages the A8X SmartIO firmware (smartio-from-kernelcache@2).
  • MCA version 1 (drivers/sound 0020-0021): the T7001 register layout, from iOS 15.8's _setIISConfig_v1. The version register carries the version in its upper half. The speaker link runs TDM, 8×16-bit slots in a 256-bit frame, with the bit clock from an AP NCO channel at twice SCLK. As on J71b, output is bounded to -12 dB until there is speaker protection.
  • NCO (drivers/clk 0007, drivers/sound 0025 binding): the T7001 variant (0x1000 channel stride, from iOS's AppleS5L8960XNCO). Its reference is 342857142 Hz, from the live ADT's clock-frequencies.
  • MAX98721 (drivers/sound 0022-0023): a new codec driver. MAX98721 has no public datasheet; every register iOS writes matches the MAX98925 map, so the driver uses that map. It writes the protection values from Apple's speaker-config (limiter, boost, current limit), and turns the amplifier on only while a stream runs.
  • audio-graph-card2 (drivers/sound 0027): a fix for the "multi" link's port references. graph_get_next_multi_ep() drops the reference of the port it is given, and two callers dropped it again. Each deferred probe of a card with a "multi" node took the port's refcount below zero ("refcount_t: addition on 0; use-after-free"). This is not specific to Apple hardware.
  • Device tree (devices/t7001 0012-0016; bindings drivers/sound 0024 i2s-switch syscon, 0026 MCA graph port): I2C1, SmartIO, the i2s-switch, MCA3, the NCO and the two amplifiers, and an audio-graph-card2 card. Everything is described in t7001.dtsi and disabled there, then enabled on t7001-air2. The card has one CPU and two codecs on one TDM link ("semi-multi"); slot 0 is the left speaker (0x31), slot 1 the right (0x34).
  • Config: CONFIG_SND_AUDIO_GRAPH_CARD2=m in both configs.
  • UCM profile (system/defaults/usr/share/alsa/ucm2, conf.d/J81_Speakers and Orchard/ipad-air2): both amplifiers' gain controls start at 0 (muted), and PipeWire doesn't know them by name. Without a profile, the card plays silence. The profile sets both to 22, and PipeWire's software volume applies on top, as on the iPad 6 and 7.
  • J81: audio_output is working, with a note that the headphone jack isn't supported. The j81 entry in tools/catalog/drivers.json comes from this branch's apple-4k kernel. Includes the regenerated matrix and a CHANGELOG line.
  • Docs: docs/j81-audio.md has the hardware table, the status and the test log.

Speaker safety

There is no speaker protection (thermal or excursion model) yet, so:

  • The MCA driver divides every sample by 4 (-12 dB) before it reaches the DMA buffer. The PCM has no mmap access, so no client can bypass this.
  • The amplifier gain control stops at 22 (0x16), the value iOS uses on J81.
  • The amplifiers' own limiter (ALC) is on, with Apple's threshold.

Not included

  • The headphone codec (CS42L81 on SPI1) and the microphones.
  • The amplifiers' interrupts (GPIO 8 and 9) and the "function-alive" GPIO.
  • Speaker protection. Until it exists, the -12 dB bound stays.

Testing

  • iPad Air 2 Wi-Fi (J81, iPad5,3). Host: Asahi Linux on a MacBook Air M2. RAM boots (orchard run) with a probe payload built from this branch's apple-4k kernel.
  • First probe, drivers loaded by hand:
    • Both amplifiers answer at 0x31 and 0x34 (revision 0x80).
    • SmartIO setup failed with -EBUSY until the V1 send-FIFO enable; fixed in this series.
    • The MCA version check is fixed in this series.
  • Final revision, drivers loading on their own:
    • The SmartIO firmware loads, and the card registers with "Left/Right Speaker Volume".
    • dmesg has no refcount warnings; before 0027, three warnings appeared at each deferred probe of the card.
  • Playback:
    • Test tones per channel, both channels together, and a short tune, each heard from the expected speaker (portrait, Home button down: channel 0 left, channel 1 right).
    • During playback, hw_ptr advances at 48000 frames/s with no underruns. MCA3 TX is enabled and the frame running. The NCO runs at 24.576 MHz. The i2s-switch routes MCA3 to pad 3. Both amplifiers have their global enable set and no status flags.
    • After the loudest test (gain 22, -3 dBFS before the driver's -12 dB), the amplifiers' flag registers are clear.
  • Installed Omarchy (orchard launch):
    • Setup: I built the apple-4k platform layer from this branch and installed it with boot-entries sync. That system predates the SmartIO recipe, so I copied in the firmware file the recipe makes (same sha256).
    • The card and its drivers come up at boot, with no refcount warnings.
    • WirePlumber picks up the UCM profile ("Built-in Audio Speakers") and sets both gains to 22.
    • pw-play and a web game in the browser play through the speakers.
    • Not run: a fresh orchard install with the new firmware recipe.
  • Boot: with MCA3 enabled, 4 of 5 early RAM boots froze before any audio driver loaded; the cause is not established. Those boots were before DFU on this iPad had to be entered from Recovery or a running Linux. Entering DFU straight from a running iPadOS fails here with any kernel (palera1n #757). Since then, 5 of 5 boots of this kernel came up: 3 RAM boots and 2 installed-system launches.
  • Checks:
    • kernel/audit-patches.py passes for apple-4k and apple-16k.
    • python -m unittest discover -s tests: everything passes except the 5 tests in test_ram and test_cascadia_loader that also fail on unmodified main on this host.

🤖 Generated with Claude Code

ricktav and others added 20 commits November 20, 2026 09:11
What the iPad Air 2's ADT and 19H422 kernelcache say about its audio path
(SmartIO + MCA v1, two MAX98721 speaker amps on i2c1, CS42L81 on spi1),
what the A9/A10 path already covers, the plan and the speaker-safety rules.
No driver or device change yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The iPad Air 2's audio DMA runs through SmartIO, as on A9 and A10. Its
firmware is the __DATA,__firmware section of AppleT7000SmartIO in the
board's kernelcache (19H422: 493792 bytes, a 32-bit ARM image).

- smartio: accept com.apple.driver.AppleT7000SmartIO.
- devices/j81/firmware.json: read the kernelcache and write
  lib/firmware/apple/t7000-smartio.bin with smartio-from-kernelcache@2.

No driver loads it yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Enable the bus without clients, so the two MAX98721 amplifiers (0x31,
0x34) can be identified from user space before a driver exists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The iPad Air 2's SmartIO is an AppleA7IOP version 1: same firmware
protocol and boot order as the S8000/T8010 (version 2), different
register offsets, no mask mirror and no 0xb84 status. apple-sio-core
gets a per-version register table and apple,t7000-sio (MCA0 and MCA3
endpoints of the J81); S8000 and T8010 program the same registers in the
same order as before. The binding gains the compatible, without a shim
region for it.

Builds as a module for apple-4k. Not run on hardware yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The iPad Air 2's MCAs are mca-version 1, driven in iOS by the same
AppleAE2MCA as the A9/A10 ones through _setIISConfig_v1. The fields keep
their encoding; offsets, the interrupt status/enable pair, the MCLK
divider and the CFG constants differ. The A5 driver (Cascadia
s5l-audio.c, hardware-tested) programs the same values.

s8000-mca gets a per-version register table, translates its interrupt
causes to the version 1 registers, allows a frame longer than its slots
(PAD), and adds apple,t7001-mca with the J81 speaker link (MCA3: provider,
2 channels in 8 slots, 256-bit frame). Version 4 and 5 variants program
the same registers and values as before.

Builds as a module for apple-4k. Not run on hardware yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The iPad Air 2 has two MAX98721 boosted class-D amplifiers on I2C1 (0x31
and 0x34), fed by MCA3 in TDM slots 0 and 1. Their registers follow the
MAX98925 map; the sequence follows iOS 15's AppleMAX98721Amp (19H422):
TDM consumer at 256 BCLKs per frame, limiter, boost and boost current
from the ADT speaker-config record, gain capped at iOS's value and
starting at 0, and the amplifiers enabled only while a stream runs.

A new small driver (max98721.c, reusing max98925.h) rather than an
extension of max98925.c, which needs an MCLK and only handles 32-64
BCLKs per frame. Built as a module in both configs; no device tree
binds it yet.

Not run on hardware yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The A8X NCO is the block of the T8010 variant (iOS: AppleS5L8960XNCO,
the same control bits), with its channels 0x1000 apart instead of
0x4000: iOS falls back to a 0x1000 page when the ADT has no
pmgr-nco-page-size, and the T7001 ADT has none. Add apple,t7001-nco.

The binding patch sits after the sound patch that adds apple,t8010-nco
to the same list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Describe SmartIO, the i2s-switch, MCA3 (the speaker link) and the NCO
in t7001.dtsi, all disabled, with values from Apple's J81 device tree.
Enable SmartIO on the Air 2. The NCO reference rate is not in the IPSW
ADT (iBoot fills it in), so the NCO, MCA3, the amplifiers and the sound
card stay off until it has been read from a running device.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The NCO reference rate comes from a running J81's Apple device tree
(clock-frequencies[10] = 342857142 Hz); with it the NCO, the i2s-switch
and MCA3 are enabled on the Air 2. The amplifiers and the sound card
follow after the read-only probe of the amplifiers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On a J81 the SmartIO firmware booted, but the driver's first reply to its
ready message failed: on AppleA7IOP version 1 the AP enables the send
FIFO itself (it read 0x00020000, disabled). The MCA version register
reads 0x00010002, the version in its upper half. Both fixes are in the
version 1 paths only. The amplifiers answer at 0x31 and 0x34 with
revision 0x80; the docs record the probe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The two MAX98721 amplifiers on I2C1 and an audio-graph-card2 card that
plays to both from MCA3 (one TDM link, slot 0 to 0x31, slot 1 to 0x34),
the graph port in the MCA binding, and CONFIG_SND_AUDIO_GRAPH_CARD2=m.
Not yet played on hardware: with MCA3 enabled, RAM boots of this kernel
freeze early in 4 of 5 attempts (bisected to enabling the MCA3 node; see
docs/j81-audio.md).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…lti refcounts

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The amplifiers' gain controls start at 0 (muted) and PipeWire does not
know them by name, so without a profile the card plays silence. The
profile sets both to 22, the level iOS uses and the most the driver
allows; PipeWire's software volume applies on top.

Tested on a J81 with Omarchy: WirePlumber picks the profile ("Built-in
Audio Speakers") and sets both controls; pw-play is heard.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both speakers play through PipeWire on an installed Omarchy, so
audio_output is working; the headphone jack and the microphones are not
supported yet. drivers.json's j81 entry comes from this branch's
apple-4k kernel, where the MCA driver binds the speaker link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SmartIO on the A8/A8X (AppleA7IOP version 1), MCA version 1 in the S8000 MCA driver, the MAX98721 speaker amplifier driver, the T7001 NCO, the device tree and a UCM profile; both speakers play in stereo. The headphone jack and the microphones are not part of it. Squashed from ricktav's j81/audio (17aa5eb); patch files renumbered to follow main.
@henrikklee
henrikklee marked this pull request as ready for review November 22, 2026 18:06
Patch numbers follow main's, and the changelog, compatibility table and
driver catalog are combined with the other J81 changes. ricktav's patches
are unchanged.
@henrikklee
henrikklee merged commit fa6e850 into OrchardLinux:main Nov 22, 2026
2 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants