Documenting vendor specific HCI commands on macOS about docs HOT 4 OPEN

Hi all,

I did a bit of reverse engineering to find more commands 🎉

On startup, bluetoothd checks which Broadcom chip the device has and then creates a list of supported vendor-specific commands. That means, depending on the Broadcom chip, there might be different vendor-specific features available. My reverse engineering here is based on an iPhone 13 mini SRD on iOS 16.3 as well as an M1 MacBook on macOS 13.4.1. Apple could ask Broadcom to add more features any time, and these could be added on both ends, *OS and the Broadcom firmware, just through a software update. Yet, in my experience, these vendor-specific commands tend to be very stable across versions, and if a new feature is added, they would add new commands rather than repurposing old command IDs.

Internally, bluetoothd has a list of commands mapped to names. However, the command IDs used there have a different numbering scheme than HCI. So far, I haven't found the part that does the translation between the two. Luckily, I was able to dynamically print the command names with Frida before the HCI packets are composed, allowing me to map the most relevant HCI commands to names.

Here are the results:

0xfc57 BD_VSC_WRITE_HI_PRIO_CONN (macOS) / BD_VSC_HI_PRIO_CONN (iOS name)

0xfce2
    0x00    BD_VSC_OLYMPIC_NUM_CMPLT_PKT_THRESH
    0x04    BD_VSC_OLYMPIC_SET_HI_PRIO_RSSI
    0x0b    BD_VSC_OLYMPIC_CHANGE_LE_SETTINGS                   // attempted on M1 but only supported on iOS
    0x15    BD_VSC_OLYMPIC_ANTENNA_PREF_B
    0x19    BD_VSC_OLYMPIC_A2DP_ACL_SIMULTANEOUS
    0x1c    BD_VSC_OLYMPIC_SET_MIN_AFH_LE_CHANNELS
    0x1e    BD_VSC_OLYMPIC_ADV_DUPLICATE_FILTER_BYPASS_CONFIG   // attempted on M1 but only supported on iOS
    0x26    BD_VSC_OLYMPIC_SET_SAR_LOCATION
    0x2a    BD_VSC_ENABLE_HOST_WAKE_REPORT
    0x2c    BD_VSC_OLYMPIC_SET_EXT_SCAN_LIMITS                  // attempted on M1 but only supported on iOS
    0x2d    BD_VSC_OLYMPIC_GET_EXT_ADV_DROPPED
    0x31    BD_VSC_OLYMPIC_SET_EXT_SCAN_BUFFERS                 // attempted on M1 but only supported on iOS
    0x36    BT_VSC_OLYMPIC_SET_RETAIN_LE_SCAN_DUPLICATES_ON_START  // attempted on M1 but only supported on iOS
    0x3a    BD_VSC_ENABLE_POWER_TAG

0xfce9
    0x01    BD_VSC_LE_META_ENA_FEATURES
    0x02    BD_VSC_LE_META_ADD_IRK_TO_LIST
    0x03    BD_VSC_LE_META_REMV_IRK_FROM_LIST
    0x05    BD_VSC_LE_META_ADV_PCF_FEATURE_SEL
    0x07    BD_VSC_LE_META_ADV_PCF_SERVICE_UUID // on macOS
    0x1e    BD_VSC_LE_META_RESET_ADV_MATCHING_RULES
    0x20    BD_VSC_LE_META_RESET_ZONE_MONITOR_FEAT
    0x50    BD_VSC_LE_META_ADV_PCF_SERVICE_UUID // on iOS
    0x35    BD_VSC_LE_META_CONFIG_ADV_MATCHING_ADDRESS_LIST
    0x37    BD_VSC_LE_META_ADD_ADV_MATCHING_RULE_ENHANCED

0xfd02  BD_VSC_ENA_WBS

0xfd03  BD_VSC_SET_VS_EVENT_MASK

0xfd1c 
    0x51    BD_VSC_ENABLE_DISABLE_FW_LOG_STREAMING

0xfd47  BD_VSC_ENABLE_EXTENDED_DUPLICATE_FILTER

0xfd48  ?? used but no name

0xfd5c  BD_VSC_REMOTE_AP_WRITE_LOCAL_STATE

0xfd7f  BD_VSC_LTE_VSC

0xfdea  BD_VSC_ENABLE_LMP_ROUTING_THROUGH_VSE

0xfdf2  BD_VSC_BEAMFORMING_MRC_CONTROL   // Beamforming MRC Global control Enable

0xfdfd  BD_VSC_HDR_CONTROL      // attempted on M1 but only supported on iOS

0xfddd  BD_VSC_OLYMPIC_ENHANCED_LINK_QUAL_STATS

0xfe00  BD_VSC_PHY_STATISTIC

0xfe06  BD_VSC_CENTRAL_SKIP_SNIFF_MODE

0xfe2c
    0x03    BD_VSC_MATCHTABLE_CONFIG
    0x04    BD_VSC_MATCHTABLE_PARAMS
    0x07    BD_VSC_ADVBUFMATCH_CONTROL

0xfe29  BD_VSC_OP_POWER_LDO_DURING_SLEEP

0xfe2d  BD_VSC_HP_BF

0xfe3c  BD_VSC_DUP_FILTER_REPORT_ENABLE

0xfe49  BD_VSC_SET_BTSC_PAGE_SCAN

0xfe65  BD_VSC_OP_HID_HIGH_PRIORITY_ACL_CONN

0xfe6e  BD_VSC_SCO_BUFFER_SIZE_CONTROL

0xfff2  BD_VSC_BTCLK_SENSORC_TIMESYNC   // attempted on M1 but only supported on iOS

These were commands I observed when enabling/disabling Bluetooth, connecting AirPods, a Bose headset, tethering with an iPhone, Apple Magic Keyboard and Magic Trackpad.

It might be worth to invest more time on static reversing of bluetoothd, as the full command list is much larger. Also, as bluetoothd composes all those HCI packets, the binary even contains information about what the values inside these packets could mean!

In case anyone wants to reproduce this with different peripherals or log Bluetooth packets along with system log messages to get more insights into what functionality these packets might implement, here are the scripts I used: asahi-bt-hooks.zip

from docs.

Status update:

• 0x057 Write_High_Priority_Connection we definitely want, this is well documented and also used by android: https://github.com/LineageOS/android_system_bt/blob/lineage-19.1/stack/l2cap/l2c_utils.cc#L2246

• with the help of https://github.com/seemoo-lab/internalblue/blob/master/internalblue/hci.py and https://github.com/hughbe/macOS-iOS-headers/blob/master/macOS/Frameworks/IOBluetooth.framework/BroadcomHostController.h a lot of the requests can be deciphered

  • 0x0e2 is just called Olympic in the firmware. Judging from a few version strings found on the internet Olympic might be the codename broadcom uses for firmware they make for apple
  • 0x0e9, 0x147, 0x148, 0x14a, 0x14b, 0x14d, 0x14e are indeed LE Advertising related and not interesting for us
  • 0x11c is DBFW, possible stands for "debug firmware", configuring firmware coredumps and debugging related things
  • 0x1f2 still no clue
  • 0x1dd is EnhancedLinkQuelityStats: First two bytes is the connection handle, then a byte where the last 3 bits set btStatEnable, coexStatEnable, diversityStatEnable (not sure about the order here), and the last byte sets the update interval in seconds
  • 0x205, 0x22d, and 0x206: still don't know

• this document by Broadcom/Cypress on improving performance with the BlueZ stack is also quite interesting, it lists a few improvements that landed in the android fork of BlueZ but never landed upstream.

  • "Configuring bluetooth low-power mode" don't think we need to do this, macOS sends no such command, and the output of Read_Sleepmode_Param command suggests some things are already set by default. Might still be interesting to try Read_Sleepmode_Param on macOS and check if more things are enabled.
  • The "Automatic Flush timeout" of 200ms is also something I've seen macOS apply when starting audio streams, so we probably want that too
  • "Rate limiting of filling buffers" not sure whether that landed in upstream BlueZ, would have to investigate, definitely looks interesting
  • "Prioritizing of A2DP streams" this is the Write_High_Priority_Connection vendor command discussed earlier.

from docs.

Edit: I just realised 2-3 more commands being used when suspending the M1 and logging for a longer time, so I added these to the list above, such as BD_VSC_REMOTE_AP_WRITE_LOCAL_STATE.

from docs.

Took me a while to get back to this, thanks a lot for all the reverse engineering work Jiska, it's quite crazy how many Apple-specific features this firmware has..

I've opened an issue with BlueZ to figure out how we can integrate those vendor specific commands: bluez/bluez#722

from docs.