Files
UniXNU/docs/porting/bluetooth.md

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:

  1. Map the resources and set up 32 KiB of DMA buffers through smmu_plan_bypass and smmu_configure_bypass, holding AppsSmmuLock.
  2. Take the Bluetooth power vote.
  3. Hold BT_EN low for 100 ms, then enable the serial clock.
  4. Check the QUP version and protocol, then prepare the engine.
  5. Attach the UART interrupt and the wake interrupt.
  6. Raise BT_EN, wait 60 ms, then enable the pin pulls.
  7. Call qbt_geni_start, then qbt_boot with 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:

  1. Fills qbt_platform and calls qbt_create, then qbt_transport_init.
  2. Waits for the Data addon, since the firmware reader needs it.
  3. Moves bytes between qbt_transport and qbt_transmit, and sleeps until the earlier of qbt_deadline and qbt_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.