From 5734360a8699c8b7f77de0a8c62c9170861127fa Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Thu, 25 Jun 2026 16:29:47 +1000 Subject: [PATCH] Restrict the EXTRAKEY_ENABLE System Control HID usage range. (#26295) --- docs/config_options.md | 4 ++++ tmk_core/protocol/usb_descriptor.c | 8 ++++---- tmk_core/protocol/usb_descriptor_common.h | 16 +++++++++++++++ tmk_core/protocol/vusb/vusb.c | 24 +++++++++++------------ 4 files changed, 36 insertions(+), 16 deletions(-) diff --git a/docs/config_options.md b/docs/config_options.md index 95cc89eaa7e..fa18b4c7d16 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -340,6 +340,10 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define SPLIT_TRANSACTION_IDS_USER .....` * Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](features/split_keyboard#custom-data-sync) for more information. +* `#define SYSTEM_CONTROL_USAGE_MINIMUM 0x0081` +* `#define SYSTEM_CONTROL_USAGE_MAXIMUM 0x008F` + * Sets the usage range reported by the System Control collection that `EXTRAKEY_ENABLE` adds. The default range covers the System Control usages QMK can send and stops below the Generic Desktop D-pad usages (`0x90` and up). Raising the maximum into that range makes some hosts detect the keyboard as a gamepad, so only widen it if you need the extra usages and know your host handles them. The minimum must not be greater than the maximum. + # The `rules.mk` File This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features. diff --git a/tmk_core/protocol/usb_descriptor.c b/tmk_core/protocol/usb_descriptor.c index 53316d56ed1..f83f3c6b660 100644 --- a/tmk_core/protocol/usb_descriptor.c +++ b/tmk_core/protocol/usb_descriptor.c @@ -371,10 +371,10 @@ const USB_Descriptor_HIDReport_Datatype_t PROGMEM SharedReport[] = { HID_RI_USAGE(8, 0x80), // System Control HID_RI_COLLECTION(8, 0x01), // Application HID_RI_REPORT_ID(8, REPORT_ID_SYSTEM), - HID_RI_USAGE_MINIMUM(8, 0x01), // Pointer - HID_RI_USAGE_MAXIMUM(16, 0x00B7), // System Display LCD Autoscale - HID_RI_LOGICAL_MINIMUM(8, 0x01), - HID_RI_LOGICAL_MAXIMUM(16, 0x00B7), + HID_RI_USAGE_MINIMUM(16, SYSTEM_CONTROL_USAGE_MINIMUM), + HID_RI_USAGE_MAXIMUM(16, SYSTEM_CONTROL_USAGE_MAXIMUM), + HID_RI_LOGICAL_MINIMUM(16, SYSTEM_CONTROL_USAGE_MINIMUM), + HID_RI_LOGICAL_MAXIMUM(16, SYSTEM_CONTROL_USAGE_MAXIMUM), HID_RI_REPORT_COUNT(8, 1), HID_RI_REPORT_SIZE(8, 16), HID_RI_INPUT(8, HID_IOF_DATA | HID_IOF_ARRAY | HID_IOF_ABSOLUTE), diff --git a/tmk_core/protocol/usb_descriptor_common.h b/tmk_core/protocol/usb_descriptor_common.h index a1dba288ba3..75ca84328c4 100644 --- a/tmk_core/protocol/usb_descriptor_common.h +++ b/tmk_core/protocol/usb_descriptor_common.h @@ -16,12 +16,28 @@ #pragma once +#include "compiler_support.h" + // Prefix string literal with L for descriptors #define USBCONCAT(a, b) a##b #define USBSTR(s) USBCONCAT(L, s) #define HID_VALUE_16(v) ((uint8_t)(v & 0xFF)), ((uint8_t)(v >> 8)) +///////////////////// +// System Control usage range +// +// Keep this below the Generic Desktop D-pad usages (0x90 and up). If the range +// reaches them, hosts like Steam see the D-pad and treat the keyboard as a gamepad. + +#ifndef SYSTEM_CONTROL_USAGE_MINIMUM +# define SYSTEM_CONTROL_USAGE_MINIMUM 0x0081 // System Power Down +#endif +#ifndef SYSTEM_CONTROL_USAGE_MAXIMUM +# define SYSTEM_CONTROL_USAGE_MAXIMUM 0x008F // System Warm Restart +#endif +STATIC_ASSERT(SYSTEM_CONTROL_USAGE_MINIMUM <= SYSTEM_CONTROL_USAGE_MAXIMUM, "SYSTEM_CONTROL_USAGE_MINIMUM must not be greater than SYSTEM_CONTROL_USAGE_MAXIMUM"); + ///////////////////// // RAW Usage page and ID configuration diff --git a/tmk_core/protocol/vusb/vusb.c b/tmk_core/protocol/vusb/vusb.c index 727b8799dcc..7e8bc65eedf 100644 --- a/tmk_core/protocol/vusb/vusb.c +++ b/tmk_core/protocol/vusb/vusb.c @@ -602,18 +602,18 @@ const PROGMEM uchar shared_hid_report[] = { #ifdef EXTRAKEY_ENABLE // Extrakeys report descriptor - 0x05, 0x01, // Usage Page (Generic Desktop) - 0x09, 0x80, // Usage (System Control) - 0xA1, 0x01, // Collection (Application) - 0x85, REPORT_ID_SYSTEM, // Report ID - 0x19, 0x01, // Usage Minimum (Pointer) - 0x2A, 0xB7, 0x00, // Usage Maximum (System Display LCD Autoscale) - 0x15, 0x01, // Logical Minimum - 0x26, 0xB7, 0x00, // Logical Maximum - 0x95, 0x01, // Report Count (1) - 0x75, 0x10, // Report Size (16) - 0x81, 0x00, // Input (Data, Array, Absolute) - 0xC0, // End Collection + 0x05, 0x01, // Usage Page (Generic Desktop) + 0x09, 0x80, // Usage (System Control) + 0xA1, 0x01, // Collection (Application) + 0x85, REPORT_ID_SYSTEM, // Report ID + 0x1A, HID_VALUE_16(SYSTEM_CONTROL_USAGE_MINIMUM), // Usage Minimum + 0x2A, HID_VALUE_16(SYSTEM_CONTROL_USAGE_MAXIMUM), // Usage Maximum + 0x16, HID_VALUE_16(SYSTEM_CONTROL_USAGE_MINIMUM), // Logical Minimum + 0x26, HID_VALUE_16(SYSTEM_CONTROL_USAGE_MAXIMUM), // Logical Maximum + 0x95, 0x01, // Report Count (1) + 0x75, 0x10, // Report Size (16) + 0x81, 0x00, // Input (Data, Array, Absolute) + 0xC0, // End Collection 0x05, 0x0C, // Usage Page (Consumer) 0x09, 0x01, // Usage (Consumer Control)