feat: Raspberry Pi 4/400 Bluetooth over mini UART (H4, Broadcom patchram, firmware mailbox BT_ON); move BT stack to Drivers/Bluetooth

docs/raspberry-pi.md

@@ -95,6 +95,9 @@ PL011 on GPIO 14/15: header pins 8 (TX) and 10 (RX), ground on pin 6, 115200
 | Keyboard (built in), USB ports | VL805 xHCI as ACPI `\_SB.SCB0.XHC0` (`PNP0D10`) | `Drivers/USB/Xhci.cpp` platform probe |
 | USB 2 devices (built-in keyboard too) | VIA hub on the VL805's USB 2 root port | `Drivers/USB/Hub.cpp` |
 | Reset, power-off | PSCI | `Arch::Reboot`, `Arch::PowerOff` |
+| Bluetooth (CYW43455 on the 4B, CYW43456 on the 400) | `BCM2EA6` (`\_SB.GDV0.BTH0`) on the mini UART (`BCM2836`) | `Drivers/Bluetooth/Broadcom.cpp`, `Drivers/Serial/BtUart.cpp` |
+| VideoCore firmware mailbox (radio power, clocks, board MAC) | `BCM2849` (`RPIQ`) | `Drivers/Platform/RpiFirmware.cpp` |
+| GPIO pin functions | `BCM2845` (`GPI0`) | `Drivers/Platform/RpiGpio.cpp` |
 
 The VL805 sits behind the BCM2711's PCIe, whose config space is not ECAM
 (the root bridge's `_DSD` says `linux-ecam-quirk-id = "bcm2711"`), so the
@@ -114,18 +117,56 @@ socket, and the Pi 400's internal keyboard (`04d9:0007`), hang off it: a
 keyboard or mouse is always a low/full-speed device behind a high-speed hub,
 reached through that hub's transaction translator.
 
+## Bluetooth
+
+The radio's Bluetooth half speaks HCI over a UART (H4) on GPIO 30-33 (CTS,
+RTS, TXD, RXD); its power switch, `BT_ON`, is line 0 of the VideoCore
+firmware's GPIO expander, reached through the mailbox. The firmware tables
+describe it as `BTH0`, whose `UARTSerialBus` names the UART it uses: with
+the `miniuart-bt` overlay the PL011 is the console, so Bluetooth has the mini
+UART. The kernel refuses to take a UART that is the SPCR console.
+
+At boot the driver probe routes the pins (`ALT5` for the mini UART, `ALT3`
+for the PL011), starts the UART (interrupt driven, 16 KiB receive and
+transmit rings) and the H4 transport under the shared HCI layer. Once the
+root is mounted the idle loop finishes, as for USB adapters:
+
+1. power-cycle the controller through `BT_ON`, HCI Reset at 115200 baud;
+2. Read Local Version: the ROM's LMP subversion picks the patch file,
+   `0:/os/firmware/brcm/BCM4345C0.hcd` (0x6119, 4B) or `BCM4345C5.hcd`
+   (0x6606, 400), shipped unmodified from Raspberry Pi OS's bluez-firmware;
+3. raise both ends to the operating speed (vendor `0xFC18`);
+4. Download Minidriver (`0xFC2E`), then every record of the `.hcd` file
+   (Write RAM, then Launch RAM), as Linux's `btbcm` does;
+5. the patched firmware restarts at 115200: reset, raise the speed again.
+
+The mini UART's FIFO is 8 bytes deep. Its hardware RTS is tried first; if
+the controller answers with it on, the link runs at 921600 baud, otherwise
+at 460800 without flow control (what Raspberry Pi OS uses), and at 115200
+if the UART has no interrupt. The baud rate derives from the VPU core
+clock, so `mk-rpi4-sd.sh` pins it (`core_freq=500`, `core_freq_min=500` in
+`config.txt`), as the overlay's documentation requires. A failed fast
+bring-up is retried entirely at 115200.
+
+The CYW43456 reports a chip-wide default address (`43:45:C5:00:1F:AC`);
+the driver replaces it with the board's Ethernet MAC from the firmware.
+`0:/config/bluetooth.toml` still overrides both (Broadcom `0xFC01`).
+
 ## Not supported yet
 
 - Ethernet (BCM54213 via GENET v5, `BCM6E4E`).
 - SD high-speed mode: the driver transfers by polled PIO at 25 MHz on a
   4-bit bus (multi-block CMD18/CMD25 with Auto CMD12), at most 12.5 MB/s;
   switching the card to 50 MHz (CMD6) would double that.
-- Wi-Fi and Bluetooth (CYW43455 over SDIO/UART).
+- Wi-Fi (the CYW4345x's SDIO half, on the Arasan controller).
 - Audio (HDMI via VideoCore, the 3.5 mm jack via PWM).
 
 ## Status
 
-Everything above is verified on QEMU only, including the Pi-specific path:
+Bluetooth has not run yet: QEMU has no model of the radio, so it is
+untested on any machine.
+
+Everything else above is verified on QEMU only, including the Pi-specific path:
 the firmware's own XHC0 table, retargeted at QEMU's xHCI and loaded with the
 `bcm2711` quirk on QEMU's root bridge, boots to the desktop with non-coherent
 DMA. Real hardware has not been tried yet. The ext2 root on the SD card boots on QEMU (`run-rpi4-sd`); the