- C 99.3%
- Makefile 0.7%
| module | ||
| 0001-usb-core-add-USB_QUIRK_CONFIG_DESC_READ_255-for-Razer.patch | ||
| README.md | ||
Razer BlackShark V3 family — Linux fix (USB config-descriptor quirk)
The Razer BlackShark V3 headsets enumerate on Linux and play audio, but their vendor command channel is dead: no battery level, no EQ, no sidetone — every Synapse-protocol command is silently ignored. On Windows the same devices work fully.
Covered product IDs (all vendor 1532):
| Model | Wired / headset | Wireless dongle |
|---|---|---|
| BlackShark V3 | 0579 |
057a |
| BlackShark V3 Pro | 0576 |
0577 |
| BlackShark V3 for Xbox | 0a4e |
0a55 |
The trigger was isolated and confirmed on the V3 Pro dongle (0577); the other
three are the same family, wired and wireless, expected to share the firmware
behavior and quirked on that basis.
Root cause
The dongle fingerprints its host during the first USB enumeration after power-on,
keyed on a single detail: the wLength of the host's first
GET_DESCRIPTOR(CONFIGURATION) request.
| First config read | Result |
|---|---|
| 255 bytes (what Windows requests) | vendor channel enabled — battery, EQ, everything works |
| 9 bytes (header-only, what Linux requests) | vendor channel disabled for the entire power session |
Both requests are perfectly spec-compliant — the device just truncates the reply to
wLength — but the firmware was evidently only validated against the larger Windows
request. The decision latches at first enumeration and cannot be undone without
cutting power: USB resets, re-enumerations, and byte-exact replays of complete Windows
control sessions were all verified not to recover the device. (The V3 family includes an
Xbox variant, so host fingerprinting appears to be intentional; Linux is collateral.)
The trigger was isolated by single-variable bisection on otherwise unmodified kernels: with only the first read widened to 255 bytes, the vendor channel comes up enabled on a cold plug with no interface drivers bound at all (bare kernel enumeration); without it, never.
Two ways to apply the fix
1. DKMS module (module/) — recommended for now
A tiny kprobe module that widens the first config-descriptor read to 255 bytes for the six BlackShark V3 IDs only. It touches nothing else, adds no measurable overhead (the hook fires only during enumeration), and auto-rebuilds on every kernel update via DKMS — so a kernel upgrade never reverts it.
sudo cp -r module /usr/src/razer-cfg255-1.0
sudo dkms add razer-cfg255/1.0
sudo dkms install razer-cfg255/1.0
sudo modprobe razer-cfg255
echo razer-cfg255 | sudo tee /etc/modules-load.d/razer-cfg255.conf # load at boot
Then unplug and replug the device. dmesg shows
razer-cfg255: widened first config read for 1532:xxxx and the headset arms.
2. Kernel patch (0001-*.patch) — the upstream fix
A proper usbcore device quirk (USB_QUIRK_CONFIG_DESC_READ_255) plus table entries
for all six IDs (1532:0576/0577/0579/057a/0a4e/0a55). This is the permanent, distro-wide fix —
intended for submission to linux-usb@vger.kernel.org once the initial single-device
version has landed.
cd /path/to/linux
git am /path/to/0001-usb-core-add-USB_QUIRK_CONFIG_DESC_READ_255-for-Razer.patch
Based on and git am-clean against gregkh usb-next (also applies to mainline).
Passes checkpatch.pl --strict with 0 errors — the single advisory ("has stable@,
perhaps needs Fixes:") is expected: there is no commit to blame, this is a device
quirk, which is an allowed stable category on its own. Compile-verified
(config.o/quirks.o) with both gcc and clang. The runtime letter r is documented
in Documentation/admin-guide/kernel-parameters.txt as part of the patch.
Runtime test without rebuilding (on any kernel that already carries the quirk): the
quirk is exposed as flag letter r, so you can apply it to this or a suspected sibling
device via a boot/module parameter:
usbcore.quirks=1532:0576:r,1532:0577:r,1532:0579:r,1532:057a:r,1532:0a4e:r,1532:0a55:r
Status
- Module: verified arming a cold V3 Pro dongle (
0577) on a stock kernel, bare enumeration only. The other five IDs (0576/0579/057a/0a4e/0a55) are same-family additions, not yet individually confirmed. Note the for-Xbox pair (0a4e/0a55) may enumerate via a different descriptor path, so the trigger is not guaranteed to apply there. - Patch:
git am-clean against mainline, checkpatch-clean. Held for submission until the initial single-device (0577) patch has landed upstream.
License
GPL-2.0, matching the Linux kernel.