7.1 KiB
Bluetooth adaptation
Complete platform interrupts and DMA and supply the
runtime inputs. QcaBluetooth
runs the Linux btqca.c initialization over a GENI UART and carries H4 bytes to Apple's
bluetoothd through UART.SK. Apple's stack owns scanning, pairing, keys, BLE and audio
profiles.
Use driver build integration to connect the recipe, then run this page's checks.
Sources and interfaces
| Implementation | Source | What to read and implement |
|---|---|---|
| Protocol core | qbt.h | qbt_platform callbacks, qbt_create, qbt_boot, qbt_step, qbt_deadline |
| UART | qbt_geni.h | GENI DMA, IRQ service, drain and quiesce |
| Kernel pipe | qbt_transport.h | UART.SK operations and power requests |
| Board integration | BluetoothProbe.cpp, WcnPower.h | Resources, power order, worker and shared supplies |
| Native stack | native-ios27.md | bluetoothd routing, scanning and capabilities |
1. Collect the hardware inputs
Read these from the target's DTS:
| Input | sheng value |
|---|---|
| UART | QUP2 SE6 at 0x898000, GIC INTID 493 |
| DMA stream | Apps SMMU 0x423 |
| CTS, RTS, TX, RX | GPIO 76, 77, 78, 79 |
BT_EN |
GPIO 81 |
| Wake source | GPIO 79 |
| Serial clock and rate | 51.2 MHz, 16x oversampling, 3.2 Mbaud |
| Firmware | hmtbtfw20.tlv, hmtnv20.bin |
Pin the firmware in firmware/bluetooth/manifest.json and stage it in the device repository:
python3 scripts/stage-bluetooth-firmware.py OUTPUT --source FIRMWARE_QCA_DIRECTORY
The UART needs protocol 2 microcode from the boot firmware. powerOn returns ENXIO when
the engine reports another protocol.
2. Implement the power path
Share the WCN supplies with Wi-Fi through sheng_wcn_power_get and sheng_wcn_power_put.
Each radio holds one vote, and the last owner releases the supplies.
powerOn runs in this order:
- Map the resources and set up 32 KiB of DMA buffers through
smmu_plan_bypassandsmmu_configure_bypass, holdingAppsSmmuLock. - Take the Bluetooth power vote.
- Hold
BT_ENlow for 100 ms, then enable the serial clock. - Check the QUP version and protocol, then prepare the engine.
- Attach the UART interrupt and the wake interrupt.
- Raise
BT_EN, wait 60 ms, then enable the pin pulls. - Call
qbt_geni_start, thenqbt_bootwith the rate and address.
powerOff shuts the controller down, quiesces the engine, lowers BT_EN and releases the vote.
Return the first error so a failed step reaches qbt_transport_power_result.
3. Start the worker
Call sheng_bluetooth_probe from the late platform probe. The worker:
- Fills
qbt_platformand callsqbt_create, thenqbt_transport_init. - Waits for the Data addon, since the firmware reader needs it.
- Moves bytes between
qbt_transportandqbt_transmit, and sleeps until the earlier ofqbt_deadlineandqbt_geni_deadline.
4. Publish the controller
Add the node to the device tree:
bluetooth {
device_type = "bluetooth";
compatible = "qcom,wcn7850-bt";
unixnu,adt-name = "bluetooth";
transport-encoding = <1>;
transport-speed = <3200000>;
status = "okay";
};
Before userland starts, the board sets local-mac-address and /chosen/mac-address-bluetooth0
and registers an IOService named bluetooth with the same properties.
5. Connect the native stack
Set these under payload.runtime in board.toml:
audio_system_plugins = ["BTAudioHALPlugin.driver"]
bluetooth_tool = "scripts/build-bluetooth-userspace.py"
bluetooth_target = "ios27"
The tool stages signed BlueTool, bluetoothd and QcaBTType0.dylib with the firmware.
patches/xnu-12377/sheng-bluetooth-runtime.patch mounts them over /usr/lib and /usr/sbin.
audio_system_plugins keeps the Bluetooth HAL plug-in visible through the audio overlay.
The adapter is locked to one bluetoothd hash. For another OS build, follow
native-ios27.md
and locate its patch sites again.
Pairing keys need the keychain, which needs AppleKeyStoreState.
The board returns /chosen/unique-chip-id through native_aks_device_id.
6. Build and verify
From the workspace root:
python3 UniXNU-<device>/scripts/check-bluetooth-platform.py
python3 UniXNU-<device>/scripts/check-bluetooth-shared.py --tree <resolved-tree>
python3 UniXNU-<device>/scripts/check-wcn-power.py
From the UniXNU checkout, with bluetooth=1 and log-bluetooth=2 in the board's boot
arguments:
./unixnu build kernel payload -D ../UniXNU-<device> --os <profile>
./unixnu bootimg -D ../UniXNU-<device> --os <profile> --dtb <device>.dtb -o boot.img
fastboot boot boot.img
Expected result: after capturing the log, [bluetooth] shows
state=2 error=0 and [bluetooth proc] shows one bluetoothd start. In Settings, turn
Bluetooth on, pair an accessory and play audio. Restart and confirm it reconnects without
pairing again.
For sheng discovery failures, use log-bluetooth=3. The persistent boot log
records [bluetooth hci] rows with timestamps, command bytes, controller replies
and Inquiry results. TX_UART records a complete frame accepted by the UART;
RX_CONTROLLER records a received event. missed and dropped count trace
losses. Keep the accessory in pairing mode while opening Bluetooth Settings,
then capture the log from Recovery. ACL, audio and pairing keys are excluded.
The macOS sheng profile selects QcaBluetooth through the component catalog.
The kernel and runtime use the same device submodule. Build the diagnostic image
with the standard commands:
./unixnu build kernel payload --os macos-27 -D ../UniXNU-sheng --uefi ../uefi-sheng --kernel-arg=log-bluetooth=3
./unixnu bootimg --os macos-27 -D ../UniXNU-sheng --uefi ../uefi-sheng
| Symptom | Check |
|---|---|
| Settings item stays gray | bluetoothd launchd job and the [bluetooth proc] restart count |
[bluetooth uart] shows faults or errors |
Serial clock rate, DMA mapping and pins |
Pairing keys are lost or bluetoothd reports a keychain problem |
AppleKeyStoreState key wrapping |
| Audio stays on the speaker | audio_system_plugins |
Record device results as described in Porting record.
Next step
Continue with USB.