Bluetooth: btrtl: Add firmware format v3 support
PATCH v6 1/1 Bluetooth: btrtl: Add firmware format v3 support
Realtek has introduced a new Bluetooth firmware image format, firmware format v3. This is a Realtek-internal specification; the format differences from v2 are documented inline in this patch.
This patch extends the btrtl driver to recognize and parse the new v3 file format, including:
- New signature string and image ID definitions
- Extension of btrtl_device_info to store v3-specific metadata
- Logic to extract and load firmware data out of v3 images
- Maintains compatibility with the existing v2 firmware format
The RTL8922D is the first IC to use firmware format v3. The firmware image (rtl8922du_fw.bin) payload is approximately 267 KB (0x40a7c bytes), and on a typical boot the full sequence from rtl_load_file() to rtl_finalize_download() completing takes average ~483 ms.
The following is RTL8922D log as expected fw format v3 output:
[ 1.945295] Bluetooth: btrtl_read_chip_id() hci0: RTL: chip_id status=0x00 id=0x3e [ 1.945547] Bluetooth: btrtl_initialize() hci0: RTL: examining hci_ver=0e hci_rev=000d lmp_ver=0e lmp_subver=8922 [ 1.945789] Bluetooth: rtl_read_rom_version() hci0: RTL: rom_version status=0 version=0 [ 1.946034] Bluetooth: btrtl_initialize() hci0: RTL: btrtl_initialize: key id 0 [ 1.946038] Bluetooth: rtl_load_file() hci0: RTL: loading rtl_bt/rtl8922du_fw.bin [ 1.950522] Bluetooth: rtl_load_file() hci0: RTL: loading rtl_bt/rtl8922du_config.bin [ 1.950837] Bluetooth: rtlbt_parse_firmware_v3() hci0: RTL: key id 0 [ 1.950844] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image (f000:00), chip id 62, cut 0x01, len 0000c704 [ 1.950862] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image version: c5900782 [ 1.950865] Bluetooth: rtlbt_parse_config() hci0: RTL: config file: rtl_bt/rtl8922du_config_f000.bin [ 1.950882] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image (f002:00), chip id 62, cut 0x01, len 00034378 [ 1.950922] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image version: 2b84a8b2 [ 1.950925] Bluetooth: rtlbt_parse_config() hci0: RTL: config file: rtl_bt/rtl8922du_config_f002.bin [ 1.951157] Bluetooth: rtlbt_parse_config() hci0: RTL: config file: rtl_bt/rtl8922du_config_f002.bin found [ 1.951164] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image (f000:00), chip id 62, cut 0x01, len 0000c704 [ 1.951169] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: skip image, key_id mismatch (1, 0) [ 1.951177] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image (f002:00), chip id 62, cut 0x01, len 00034378 [ 1.951179] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: skip image, key_id mismatch (1, 0) [ 1.951181] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image (f000:00), chip id 62, cut 0x01, len 0000c704 [ 1.951184] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: skip image, key_id mismatch (2, 0) [ 1.951185] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image (f002:00), chip id 62, cut 0x01, len 00034378 [ 1.951187] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: skip image, key_id mismatch (2, 0) [ 1.951189] Bluetooth: rtlbt_parse_firmware_v3() hci0: RTL: image payload total len: 0x00040a7c [ 2.429887] Bluetooth: rtl_finalize_download() hci0: RTL: Watchdog reset status 00 [ 2.430162] Bluetooth: rtl_finalize_download() hci0: RTL: fw version 0x2b84a8b2
---
V5 -> V6:
- Add missing parentheses around the entire is_v3_fw() macro expression to avoid incorrect evaluation with the logical NOT operator on legacy firmware types
- Add NULL check on ic_info->cfg_name before use in rtlbt_parse_config() to avoid NULL pointer dereference when a crafted firmware specifies FW_TYPE_V3_2 on legacy chips without configuration
- Add bounds check to reject patch_image_len < 4 before reading the image version, preventing an out-of-bounds read
- Propagate the return value of rtlbt_parse_config() and abort parsing on failure instead of silently continuing without the required configuration
- Fix a race condition in rtl_check_download_state() by setting the REALTEK_DOWNLOADING flag before issuing the check-download command, instead of after, to avoid missing the completion event
- Split v3 firmware parse/download logic into new btrtl_enh.c to keep btrtl.c size manageable
V4 -> V5:
- Add independent support for RTL8922D section
- Introduce macros to improve code readability
- Document firmware format v3 and its differences
- Align implementation with reviewer feedback
V3 -> V4:
- Rework skb->data access and add clarifying comments
- Fix latent issues
V2 -> V3:
- Address coccinelle warning
V1 -> V2:
- Add missing symbols
- Resolve build warnings
---
--- drivers/bluetooth/Makefile | 2 +- drivers/bluetooth/btrtl.c | 217 ++++++--- drivers/bluetooth/btrtl.h | 109 ++++- drivers/bluetooth/btrtl_enh.c | 809 ++++++++++++++++++++++++++++++++++ drivers/bluetooth/btusb.c | 3 + 5 files changed, 1081 insertions(+), 59 deletions(-) create mode 100644 drivers/bluetooth/btrtl_enh.c
drivers/bluetooth/Makefile +1 -1
@@ -22,7 +22,7 @@ obj-$(CONFIG_BT_MTKSDIO) += btmtksdio.o obj-$(CONFIG_BT_MTKUART) += btmtkuart.o obj-$(CONFIG_BT_QCOMSMD) += btqcomsmd.o obj-$(CONFIG_BT_BCM) += btbcm.o -obj-$(CONFIG_BT_RTL) += btrtl.o +obj-$(CONFIG_BT_RTL) += btrtl_enh.o btrtl.o obj-$(CONFIG_BT_QCA) += btqca.o obj-$(CONFIG_BT_MTK) += btmtk.o
drivers/bluetooth/btrtl.c +160 -57
431 lines not on this page · raw message
drivers/bluetooth/btrtl.h +108 -1
142 lines not on this page · raw message
drivers/bluetooth/btrtl_enh.c new file +809 -0
809 lines not on this page · raw message
drivers/bluetooth/btusb.c +3 -0
@@ -2825,6 +2825,9 @@ static int btusb_recv_event_realtek(struct hci_dev *hdev, struct sk_buff *skb)return 0 ; } +if (skb->data[0 ] ==HCI_VENDOR_PKT ) +return btrtl_recv_event (hdev, skb); +return hci_recv_frame (hdev, skb); }
Signature · 1 line
2.34.1
This is automated email and please do not reply to this email!
Dear submitter,
Thank you for submitting the patches to the linux bluetooth mailing list. This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=1145861
---Test result---
Test Summary:
CheckPatch FAIL 2.47 seconds VerifyFixes PASS 0.14 seconds VerifySignedoff PASS 0.13 seconds GitLint FAIL 0.34 seconds SubjectPrefix PASS 0.13 seconds BuildKernel PASS 26.44 seconds CheckAllWarning PASS 28.92 seconds CheckSparse PASS 27.17 seconds BuildKernel32 PASS 25.47 seconds CheckKernelLLVM SKIP 0.00 seconds TestRunnerSetup PASS 468.27 seconds IncrementalBuild PASS 24.61 seconds
Details
##############################
Test: CheckPatch - FAIL
Desc: Run checkpatch.pl script
Output:
[v6] Bluetooth: btrtl: Add firmware format v3 support
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating? #803:
new file mode 100644
total: 0 errors, 1 warnings, 1399 lines checked
NOTE: For some of the reported defects, checkpatch may be able to
mechanically convert to the typical style using --fix or --fix-inplace.
/github/workspace/src/patch/14749594.patch has style problems, please review.
NOTE: Ignored message types: UNKNOWN_COMMIT_ID
NOTE: If any of the errors are false positives, please report
them to the maintainer, see CHECKPATCH in MAINTAINERS.
##############################
Test: GitLint - FAIL
Desc: Run gitlint
Output:
[v6] Bluetooth: btrtl: Add firmware format v3 support
21: B1 Line exceeds max length (85>80): "[ 1.945295] Bluetooth: btrtl_read_chip_id() hci0: RTL: chip_id status=0x00 id=0x3e"
22: B1 Line exceeds max length (116>80): "[ 1.945547] Bluetooth: btrtl_initialize() hci0: RTL: examining hci_ver=0e hci_rev=000d lmp_ver=0e lmp_subver=8922"
23: B1 Line exceeds max length (90>80): "[ 1.945789] Bluetooth: rtl_read_rom_version() hci0: RTL: rom_version status=0 version=0" 24: B1 Line exceeds max length (82>80): "[ 1.946034] Bluetooth: btrtl_initialize() hci0: RTL: btrtl_initialize: key id 0" 25: B1 Line exceeds max length (84>80): "[ 1.946038] Bluetooth: rtl_load_file() hci0: RTL: loading rtl_bt/rtl8922du_fw.bin" 26: B1 Line exceeds max length (88>80): "[ 1.950522] Bluetooth: rtl_load_file() hci0: RTL: loading rtl_bt/rtl8922du_config.bin"
28: B1 Line exceeds max length (113>80): "[ 1.950844] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image (f000:00), chip id 62, cut 0x01, len 0000c704"
29: B1 Line exceeds max length (85>80): "[ 1.950862] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image version: c5900782"
30: B1 Line exceeds max length (103>80): "[ 1.950865] Bluetooth: rtlbt_parse_config() hci0: RTL: config file: rtl_bt/rtl8922du_config_f000.bin"
31: B1 Line exceeds max length (113>80): "[ 1.950882] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image (f002:00), chip id 62, cut 0x01, len 00034378"
32: B1 Line exceeds max length (85>80): "[ 1.950922] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image version: 2b84a8b2"
33: B1 Line exceeds max length (103>80): "[ 1.950925] Bluetooth: rtlbt_parse_config() hci0: RTL: config file: rtl_bt/rtl8922du_config_f002.bin" 34: B1 Line exceeds max length (109>80): "[ 1.951157] Bluetooth: rtlbt_parse_config() hci0: RTL: config file: rtl_bt/rtl8922du_config_f002.bin found" 35: B1 Line exceeds max length (113>80): "[ 1.951164] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image (f000:00), chip id 62, cut 0x01, len 0000c704"
36: B1 Line exceeds max length (96>80): "[ 1.951169] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: skip image, key_id mismatch (1, 0)"
37: B1 Line exceeds max length (113>80): "[ 1.951177] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image (f002:00), chip id 62, cut 0x01, len 00034378"
38: B1 Line exceeds max length (96>80): "[ 1.951179] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: skip image, key_id mismatch (1, 0)"
39: B1 Line exceeds max length (113>80): "[ 1.951181] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image (f000:00), chip id 62, cut 0x01, len 0000c704"
40: B1 Line exceeds max length (96>80): "[ 1.951184] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: skip image, key_id mismatch (2, 0)"
41: B1 Line exceeds max length (113>80): "[ 1.951185] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: image (f002:00), chip id 62, cut 0x01, len 00034378"
42: B1 Line exceeds max length (96>80): "[ 1.951187] Bluetooth: rtlbt_parse_section_v3() hci0: RTL: skip image, key_id mismatch (2, 0)" 43: B1 Line exceeds max length (98>80): "[ 1.951189] Bluetooth: rtlbt_parse_firmware_v3() hci0: RTL: image payload total len: 0x00040a7c" 44: B1 Line exceeds max length (85>80): "[ 2.429887] Bluetooth: rtl_finalize_download() hci0: RTL: Watchdog reset status 00" 45: B1 Line exceeds max length (82>80): "[ 2.430162] Bluetooth: rtl_finalize_download() hci0: RTL: fw version 0x2b84a8b2"
##############################
Test: CheckKernelLLVM - SKIP
Desc: Build kernel with LLVM + context analysis
Output:
Clang not found
https://github.com/bluez/bluetooth-next/pull/579
---
Regards,
Linux Bluetooth
Dan Carpenter
build botBCC: [email protected] CC: [email protected] In-Reply-To: <[email protected]> References: <[email protected]> TO: Hilda Wu…
BCC: [email protected]
CC: [email protected]
In-Reply-To: <[email protected]>
References: <[email protected]>
TO: Hilda Wu <[email protected]>
TO: [email protected]
CC: [email protected]
CC: [email protected]
CC: [email protected]
CC: [email protected]
CC: [email protected]
CC: [email protected]
CC: [email protected]
CC: [email protected]
Hi Hilda,
kernel test robot noticed the following build warnings:
[auto build test WARNING on bluetooth/master]
[also build test WARNING on bluetooth-next/master linus/master v7.2 next-20260820] [If your patch is applied to the wrong git tree, kindly drop us a note. And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]
url: https://github.com/intel-lab-lkp/linux/commits/Hilda-Wu/Bluetooth-btrtl-Add-firmware-format-v3-support/20260814-145920 base: https://git.kernel.org/pub/scm/linux/kernel/git/bluetooth/bluetooth.git master patch link: https://lore.kernel.org/r/20260814065920.413487-1-hildawu%40realtek.com patch subject: [PATCH v6] Bluetooth: btrtl: Add firmware format v3 support
:::::: branch date: 27 hours ago
:::::: commit date: 27 hours ago
config: x86_64-randconfig-161 (https://download.01.org/0day-ci/archive/20260822/[email protected]/config)
compiler: gcc-14 (Debian 14.2.0-19) 14.2.0
smatch: v0.5.0-9187-g5189e3fb
If you fix the issue in a separate patch/commit (i.e. not just a new version of the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <[email protected]> | Reported-by: Dan Carpenter <[email protected]> | Closes: https://lore.kernel.org/r/[email protected]/
New smatch warnings:drivers/bluetooth/btrtl.c:1106 btrtl_free() warn: variable dereferenced before check 'btrtl_dev' (see line 1098)
Old smatch warnings:drivers/bluetooth/btrtl.c:1326 btrtl_initialize() warn: passing zero to 'ERR_PTR'
vim +/btrtl_dev +1106 drivers/bluetooth/btrtl.c
c0123cb6c4c7fc2 Vasily Khoruzhick 2023-03-07 1093
26503ad25de8c7c Martin Blumenstingl 2018-08-02 1094 void btrtl_free(struct btrtl_device_info *btrtl_dev)
26503ad25de8c7c Martin Blumenstingl 2018-08-02 1095 {
9a24ce5e29b15c4 Max Chou 2023-04-17 1096 struct rtl_subsection *entry, *tmp;
9a24ce5e29b15c4 Max Chou 2023-04-17 1097
268d3636dfb2225 Alice Mikityanska 2020-01-24 @1098 kvfree(btrtl_dev->fw_data);
268d3636dfb2225 Alice Mikityanska 2020-01-24 1099 kvfree(btrtl_dev->cfg_data);
9a24ce5e29b15c4 Max Chou 2023-04-17 1100
9a24ce5e29b15c4 Max Chou 2023-04-17 1101 list_for_each_entry_safe(entry, tmp, &btrtl_dev->patch_subsecs, list) {
9a24ce5e29b15c4 Max Chou 2023-04-17 1102 list_del(&entry->list);
9a24ce5e29b15c4 Max Chou 2023-04-17 1103 kfree(entry);
9a24ce5e29b15c4 Max Chou 2023-04-17 1104 }
9a24ce5e29b15c4 Max Chou 2023-04-17 1105
8e4d5e1dbe2345c Hilda Wu 2026-08-14 @1106 if (btrtl_dev) {
8e4d5e1dbe2345c Hilda Wu 2026-08-14 1107 struct btrtl_enh_ops *ops = symbol_get(rtl_enh_ops);
8e4d5e1dbe2345c Hilda Wu 2026-08-14 1108
8e4d5e1dbe2345c Hilda Wu 2026-08-14 1109 if (ops) {
8e4d5e1dbe2345c Hilda Wu 2026-08-14 1110 if (ops->free_patch_images)
8e4d5e1dbe2345c Hilda Wu 2026-08-14 1111 ops->free_patch_images(btrtl_dev);
8e4d5e1dbe2345c Hilda Wu 2026-08-14 1112 symbol_put(rtl_enh_ops);
8e4d5e1dbe2345c Hilda Wu 2026-08-14 1113 }
8e4d5e1dbe2345c Hilda Wu 2026-08-14 1114 }
8e4d5e1dbe2345c Hilda Wu 2026-08-14 1115
26503ad25de8c7c Martin Blumenstingl 2018-08-02 1116 kfree(btrtl_dev);
26503ad25de8c7c Martin Blumenstingl 2018-08-02 1117 }
26503ad25de8c7c Martin Blumenstingl 2018-08-02 1118 EXPORT_SYMBOL_GPL(btrtl_free);
26503ad25de8c7c Martin Blumenstingl 2018-08-02 1119 --
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki