SDL support of Share button and Paddles?

[slouken]

Version of xpadneo

hid-xpadneo-v0.9-137-g13dd267

Controller Model

• Xbox One S controller
• Xbox Elite 2 controller
• Xbox Series X|S controller
• Other:

Connection mode

• Bluetooth connection
• USB cable (not yet supported)
• Xbox Dongle connection (not yet supported)

Describe your feature reqeust

• I'd like to see support for a specific model
• I'd like to see support for a specific hardware feature
• I'd like to see support for a specific software feature

Is your feature request related to a problem? Please describe.
SDL just added tentative support for automatically detecting the paddles for the Xbox Elite 2 controller, and could do the same for the Share button, but currently has no way of detecting whether the connected controller has these features.
libsdl-org/SDL@b0677f4

I also noticed that the Share button gets sent as a keyboard key and doesn't generate the KEY_RECORD that I would have expected from the evdev description.

Describe the solution you'd like
It would be ideal if the real VID/PID of the controller were available, as well as EVIOCGBIT() reporting the actual buttons available.

It would also be nice if there were a way to report the Share button, but I understand that you're converting it to a keystroke for compatibility with other software. FWIW, Steam binds the Share button to screenshot by default, so you wouldn't be missing any functionality there and would make it possible for users to bind the button to other in-game functionality if you reported it as a controller button instead of a keyboard key.

If changes to xpadneo would benefit from code changes in SDL, feel free to create an issue or PR at the SDL repo and I'll be happy to discuss them.

[smcv]

If this driver's mapping of evdev capabilities is not the same as in-kernel drivers, then it would be very useful to have evemu-describe output for each supported device as a reference, similar to what's on libsdl-org/SDL#7814 - that will let SDL's unit tests for gamepad detection/classification look at simulated xpadneo controllers without needing to have actual physical hardware, making it less likely that using SDL and xpadneo together will regress.

Similarly, if xpadneo presents its supported devices as HID controllers, it would be very useful to have a hex-dump of the HID descriptor (usually od -t x1 /sys/class/input/eventXX/device/device/report_descriptor) as a reference. SDL doesn't yet use HID descriptors as input to its classification of devices, but it could in future.

If these details are likely to change with future versions of xpadneo, then please mention the version number of xpadneo when generating them.

[smcv]

libsdl-org/SDL#7801 (comment) explains how to get that information and why SDL would benefit from having it.

[kakra]

@slouken Thanks for reaching out to me. Yes, the aspects you mention are there for historic reasons (mostly, to make jsdev software happy), and during v0.10 to v0.11 I want to eliminate these problems. The user-space stack has evolved enough that there is no need for work-arounds. jsdev compatibility will be ignored, jscal can be used to remap things (which breaks Chrome, btw).

This includes:

• proper HID reports with native PID/VID (to become compatible with SDL and Steam Input)
• a remapping tool with support for Xbox Elite 2 native profile support
• a udev helper to save and restore settings from a sysfs interface (storing profiles for non-native profile models)
• RGB support for the Guide button (still need to make up my mind about this)
• maybe a GUI tool for remapping and storing profiles inside the controller (for supported models)
• allow switching the Guide button between shift mode operation and native function button (currently shift mode)

I also had a chat with Proton devs who told me there's native HID parsing support in Proton now, so everything should settle around proper HID support. We could in theory craft our own HID descriptor.

Without the extra features, xpadneo no longer provides any benefits over the in-kernel drivers (except we work around the rumble crash properly which ff-memless cannot do natively). So one step forward would be to submit patches to the kernel to request fixed time intervals from ff-memless (I'm currently working on that).

@smcv You mention that we expose the paddles as BTN_TRIGGERHAPPY. This is because the evdev button range of BTN_GAMEPAD is too small to fit all the inputs of the controller, and evdev devices are not allowed to bleed into the other ranges. There are a few hard-coded exceptions in the kernel which either leave it to user-space, or work around it in a similar way by shifting key codes to a different range. The reasoning behind this is: If a devices has a BTN_GAMEPAD, it's a gamepad. If it has BTN_JOYSTICK, it's a joystick. This is how it's meant for user-space to detect the type of device as far as I understand it. So if we bleed out of our range, we would bleed into BTN_DIGI which could make user-space to detect our device as a digitizer/pen. Technically, we could move two paddles to BTN_C and BTN_Z, there are controllers out there which have only two paddles (which are dead in Xbox mode but available in Switch mode). But that would completely mess up how SDL or Steam Input would handle the buttons. [1]

Thus, implementations using evdev should be prepared to handle sparse keymaps.

MS decided to not use sparse keymaps with the HID-mode of the controller, instead it ships with blind buttons in the keymap (BTN_C and friends). This was probably done to properly map buttons to evdev symbols on Android which wouldn't get updated drivers for all the Android devices out there. xpadneo went another route and actually made the bitmap sparse, but this confused some software while it fixed other software (except Chrome which uses evdev to detect mappings but then uses jsdev to read the device and counts positions), until SDL added support which also didn't respect sparse bitmaps by not looking at the actual evdev symbols, it suddenly broke a lot of games. We mostly fixed this by patching the HID descriptor and disable hidraw access but still had a few games that would rotate the last three buttons (because BTN_MODE is technically in the wrong position in the Linux bitmaps). That's why I also excluded that Guide button, later the Share button, too, and mapped those differently.

Mapping to F12 is just a stop-gap solution until we have native PID/VID and custom mappings in place.

So yes, xpadneo is working towards fixing that. But anyone who is not depending on special xpadneo features should really use the in-kernel drivers. That's what Steam Input expects, that's what SDL expects.

Until then, I would appreciate if our GUID 050003f05e0400008e02000030110000 would not be included into controllerdb because it just does not work properly with the report parser of SDL (the parser ignores evdev symbols and HID descriptors, and thus cannot handle sparse keymaps).

I'd be happy to support efforts in SDL to use evdev natively for most devices instead of using controllerdb (or at least have a controllerdb line which would say "use evdev"). With proper evdev symbol matching in place, most of the controllerdb entries should become obsolete. I don't think that HID parsing is the way forward (the kernel already does it and creates the evdev symbol mapping). While hidraw is nice to support devices without native kernel driver, evdev should probably be preferred if a native kernel driver is available - tho, I'm not sure how to detect that. Maybe by looking if hid-generic is used, and only then use hidraw if ACLs allow?

Looking forward to a solution which makes SDL, evdev, jsdev (optional), some emulators, and Steam Input happy. :-)

[1]: This is why the BTN_TRIGGER_HAPPY range has been introduced: To support game input devices which have more buttons than the joystick/gamepad ranges support. It's anecdotal: Because there was no space for additional joystick bits, and "joy" means "happy", a newly named bitmap range was placed at the end.

[kakra]

as well as EVIOCGBIT() reporting the actual buttons available.

@slouken Didn't know of that. I'll look into it, maybe we can fast-forward to better support that way.

Do you have an example of how to properly use it from user-space?

[slouken]

SDL's auto-mapping based on evdev capability bits has improved quite a bit, and at least for Xbox controllers I think will be able to replace the mapping database.

Here is how SDL gets the bits and figures out the mapping based on capabilities:
https://github.com/libsdl-org/SDL/blob/2c3717881f3500ae73ece85bffb70dd868535dbf/src/joystick/linux/SDL_sysjoystick.c#L943
https://github.com/libsdl-org/SDL/blob/2c3717881f3500ae73ece85bffb70dd868535dbf/src/joystick/linux/SDL_sysjoystick.c#L1726
https://github.com/libsdl-org/SDL/blob/2c3717881f3500ae73ece85bffb70dd868535dbf/src/joystick/linux/SDL_sysjoystick.c#L2083

[kakra]

So from this, I'm guessing that it should return a bitmap of physically existing buttons (or rather, buttons that are able to generate events through the driver):
https://github.com/libsdl-org/SDL/blob/2c3717881f3500ae73ece85bffb70dd868535dbf/src/joystick/linux/SDL_sysjoystick.c#LL956C1-L959C71

Feel free to find me on our Discord channel.

[kakra]

@slouken Regarding:
https://github.com/libsdl-org/SDL/blob/2c3717881f3500ae73ece85bffb70dd868535dbf/src/joystick/linux/SDL_sysjoystick.c#LL2090C8-L2090C92

You can still see the original PID/VID when looking at the hidraw device from which the evdev device derives:

# realpath /sys/class/input/event24/device
/sys/devices/virtual/misc/uhid/0005:045E:0B22.001A/input/input32

# grep '^' /sys/devices/virtual/misc/uhid/0005:045E:0B22.001A/input/input32/id/*
id/bustype:0005
id/product:028e
id/vendor:045e
id/version:1130

# realpath /sys/class/hidraw/hidraw17
/sys/devices/virtual/misc/uhid/0005:045E:0B22.001A/hidraw/hidraw17

# "0B22" in the sysfs path vs "028e" in the id path

[kakra]

@slouken https://github.com/libsdl-org/SDL/blob/2c3717881f3500ae73ece85bffb70dd868535dbf/src/joystick/linux/SDL_sysjoystick.c#L2083

Yes, because these additional buttons would bleed out of the BTN_GAMEPAD range. xpadneo tries to put buttons at fixed locations on the bitmap [1], so the paddles will stay at their event code, and other buttons map to their actual symbol name.

If it helps, you can detect the driver from the sysfs path:

# realpath /sys/devices/virtual/misc/uhid/0005:045E:0B22.001C/driver
/sys/bus/hid/drivers/xpadneo

[1]: This code is problematic with that idea:
https://github.com/libsdl-org/SDL/blob/2c3717881f3500ae73ece85bffb70dd868535dbf/src/joystick/linux/SDL_sysjoystick.c#L2102

Future xpadneo will move BTN_SHARE and other non-standard buttons to the start of the BTN_TRIGGER_HAPPY range.

Following the standard of Linux input, you can expect the controller to have paddles, if BTN_TRIGGER_HAPPY37 is set (in a later version of xpadneo at least).

[kakra]

I think it may be time for an official kernel patch to add alias names to trigger happy, something like #define BTN_PADDLE_TOPRIGHT BTN_TRIGGER_HAPPY1 or something similar. We're clearly seeing a trend towards more or less de-facto standards for additional gamepad buttons.

[kakra]

@slouken That above commit should fix the bitmap for you. Only controllers having paddles will report the bits set now. I'll backport that to v0.9 if needed.

[kakra]

[1]: This code is problematic with that idea

@slouken I think I'll also expose the position of the profile button and trigger ranges. So this may end up in trigger happy, too. Your code should really not count the bits all across the trigger happy range but instead assume fixed positions. xpadneo may support gamepads in the future with only two paddles (I have such a model here for testing).

[slouken]

The 6.x kernel puts the paddles at BTN_TRIGGER_HAPPY5 - BTN_TRIGGER_HAPPY8, maybe that should be used instead?

[kakra]

The 6.x kernel puts the paddles at BTN_TRIGGER_HAPPY5 - BTN_TRIGGER_HAPPY8, maybe that should be used instead?

Oh then yes, will do. Do you know what happy 1 to 4 is used for then?

[slouken]

I have no idea. :)
I just verified that the 6.1 kernel uses KEY_RECORD for the Share button, and that works well. I'm going to go ahead and update the SDL code to look for those symbols, assuming that future xpadneo versions will use those as well?

[slouken]

I went ahead and made that change in libsdl-org/SDL@db1d4d3.

[slouken]

BTN_TRIGGER_HAPPY1 - BTN_TRIGGER_HAPPY4 are the D-PAD buttons when they're reported as buttons instead of a hat:
https://github.com/torvalds/linux/blob/15adb51c04ccfcf58ac3eec7464a2768fe175fcc/drivers/input/joystick/xpad.c#L760

[kakra]

I have no idea. :)

But I have: This actually followed a discussion I had with the xpad author, and I suggested to move that to the happy bits instead of bleeding out in the gamepad range. But I suggested to leave some space for additional future buttons (e.g., Share). Now it follows the d-pad directly.

[kakra]

I went ahead and made that change in libsdl-org/SDL@db1d4d3.

See my comments on that commit, the devil is in the details. ;-)

[kakra]

I just verified that the 6.1 kernel uses KEY_RECORD for the Share button, and that works well. I'm going to go ahead and update the SDL code to look for those symbols, assuming that future xpadneo versions will use those as well?

I had KEY_RECORD but it never worked because user-space isn't prepared to see the consumer device range on regular input devices (rather on remote controls). And then, this bit is not allowed on a gamepad device.

The original controller firmware for XBE2 had that on a sub device (consumer control), currently it may show up on the gamepad device but it doesn't work there except user-space explicitly looks for it. So yes, SDL2 could support this but it's really not the way it should be. I find no code that explicitly uses that code so it probably comes from a broken HID device descriptor if it appears in the gamepad application of the descriptor.

[slouken]

It looks like KEY_RECORD is being explicitly used for this purpose:
https://github.com/torvalds/linux/blob/15adb51c04ccfcf58ac3eec7464a2768fe175fcc/drivers/input/joystick/xpad.c#L1891

[kakra]

Yes, but that code should probably not have gone into the kernel then. I found no way to bind KEY_RECORD in the desktop, neither in KDE shortcuts/hotkeys nor in Steam. It is just ignored because it doesn't belong there. It's a consumer control key as far as I could figure out. Documentation about the purpose of each event code is quite sparse.

Maybe xpad should be fixed to report it as BTN_TRIGGER_HAPPY<nextfreenumber>, and then SDL2 and xpadneo can follow?

[slouken]

Possibly. It does function in SDL, and by virtue of that will work in Steam.

We'll need to continue supporting it because of the long line of 6.x kernels that report that key, but we can certainly add a new one if it gets changed in the future.

[kakra]

Okay, I'll do some tests and update my README then. Which version of SDL2 will have the new paddle detection so I can reference that in the README?

[slouken]

2.28 is about to be released with the new paddle support.

[kakra]

@slouken Okay I found you mentioned 2.28 in the other linked issue report. I'll use that and add a tag line to close this report then, unless it isn't fixed for you. Is that okay for you?

I'd like to defer resolving the KEY_RECORD issue until after xpadneo v0.10 because that branch currently still uses sub devices.

[kakra]

Yes please! The capabilities bitmaps are the key thing for recognising what a gamepad or other evdev input device is, and what it can do. Wherever possible, evdev input consumers like SDL need to be able to assume that a button appears in the bitmap if and only if it physically exists on the device and can generate events.

This was partially a bug which is fixed now: The capability bitmap is filled properly now, except I need to look into KEY_RECORD.

[smcv]

I'm referring the standard of interpreting a single set bit as assuming we see some kind of device, like in "if it has BTN_GAMEPAD, it is a gamepad".

I believe that convention is only meant to apply to rather broad device categories, namely joysticks and gamepads (which are implicitly assumed to have at least one button). The rest of the bitfield is capability discovery - now that we know we're looking at a gamepad, does it have a TL button or a clickable left thumbstick or whatever? - which only really works if the button has a well-known conventional purpose, and device drivers follow it.

To be able to do that, it would be really, really useful to have full evemu-describe output for the devices that xpadneo supports.

Is there an open issue where I can report that data?

Not at the moment, please could you open one? I hope @slouken won't mind us using https://github.com/libsdl-org/SDL/issues for this. One issue for the whole batch (which we can close when the test data has been added), with one comment per physical device, is probably a good way to organise them.

[slouken]

I hope @slouken won't mind us using https://github.com/libsdl-org/SDL/issues for this. One issue for the whole batch (which we can close when the test data has been added), with one comment per physical device, is probably a good way to organise them.

Sure, that would be fine. Thanks!