No description
  • C 99.3%
  • Makefile 0.7%
Find a file
2026-07-21 02:24:05 +00:00
module Add BlackShark V3 for Xbox PIDs (0a4e headset, 0a55 dongle) 2026-07-20 22:21:00 -04:00
0001-usb-core-add-USB_QUIRK_CONFIG_DESC_READ_255-for-Razer.patch Add BlackShark V3 for Xbox PIDs (0a4e headset, 0a55 dongle) 2026-07-20 22:21:00 -04:00
README.md Add BlackShark V3 for Xbox PIDs (0a4e headset, 0a55 dongle) 2026-07-20 22:21:00 -04:00

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

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.