[PATCH 1/1] Input: xpad - update docs to reflect current state

[PATCH 1/1] Input: xpad - update docs to reflect current state

[Daniel Dressler]

The last time this documentation was accurate was
just over 8 years ago. In this time we've added
support for two new generations of Xbox console
controllers and dozens of third-party controllers.

This patch unifies terminology and makes it explicit
which model of controller a sentence refers to.

It also expands certain sections to address the latest
versions of Xbox controllers.

Thus this documentation should now be useful to
end users and not contain out-right untruths.

Signed-off-by: Daniel Dressler <danieru.dressler@gmail.com>
---
 Documentation/input/xpad.txt  | 123 ++++++++++++++++++++++++++++--------------
 drivers/input/joystick/xpad.c |   4 +-
 2 files changed, 85 insertions(+), 42 deletions(-)

diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.txt
index 7cc9a43..d1b23f2 100644
--- a/Documentation/input/xpad.txt
+++ b/Documentation/input/xpad.txt
@@ -1,18 +1,22 @@
-xpad - Linux USB driver for X-Box gamepads
+xpad - Linux USB driver for Xbox compatible controllers
 
-This is the very first release of a driver for X-Box gamepads.
-Basically, this was hacked away in just a few hours, so don't expect
-miracles.
+This driver exposes all first-party and third-party Xbox compatible
+controllers. It has a long history and has enjoyed considerable usage
+as Window's xinput library caused most PC games to focus on Xbox
+controller compatibility.
 
-In particular, there is currently NO support for the rumble pack.
-You won't find many ff-aware linux applications anyway.
+Due to backwards compatibility all buttons are reported as digital.
+This only effects Original Xbox controllers. All later controller models
+have only digital face buttons.
+
+Rumble is supported on some models of Xbox 360 controllers but not of
+Original Xbox controllers nor on Xbox One controllers. As of writing
+the Xbox One's rumble protocol has not been reverse engineered but in
+the future could be supported.
 
 
 0. Notes
 --------
-
-Driver updated for kernel 2.6.17.11. (Based on a patch for 2.6.11.4.)
-
 The number of buttons/axes reported varies based on 3 things:
 - if you are using a known controller
 - if you are using a known dance pad
@@ -20,12 +24,16 @@ The number of buttons/axes reported varies based on 3 things:
   module configuration for "Map D-PAD to buttons rather than axes for unknown
   pads" (module option dpad_to_buttons)
 
-If you set dpad_to_buttons to 0 and you are using an unknown device (one
-not listed below), the driver will map the directional pad to axes (X/Y),
-if you said N it will map the d-pad to buttons, which is needed for dance
-style games to function correctly.  The default is Y.
+If you set dpad_to_buttons to N and you are using an unknown device
+the driver will map the directional pad to axes (X/Y).
+If you said Y it will map the d-pad to buttons, which is needed for dance
+style games to function correctly. The default is Y.
+
+dpad_to_buttons has no effect for known pads. A erroneous commit message
+claimed dpad_to_buttons could be used to force behavior on known devices.
+This is not true. Both dpad_to_buttons and triggers_to_buttons only affect
+unknown controllers.
 
-dpad_to_buttons has no effect for known pads.
 
 0.1 Normal Controllers
 ----------------------
@@ -80,17 +88,29 @@ to the list of supported devices, ensuring that it will work out of the
 box in the future.
 
 
-1. USB adapter
+1. USB adapters
 --------------
+All generations of Xbox controllers speak USB over the wire.
+- Original Xbox controllers use a proprietary connector and require adapters.
+- Wireless Xbox 360 controllers require a 'Xbox 360 Wireless Gaming Receiver
+  for Windows'
+- Wired Xbox 360 controllers use standard USB connectors.
+- Xbox One controllers can be wireless but speak Wi-Fi Direct and are not
+  yet supported.
+- Xbox One controllers can be wired and use standard Micro-USB connectors.
+
 
-Before you can actually use the driver, you need to get yourself an
-adapter cable to connect the X-Box controller to your Linux-Box. You
-can buy these online fairly cheap, or build your own.
+
+1.1 Original Xbox USB adapters
+--------------
+Using this driver with an Original Xbox controller requires an
+adapter cable to break out the proprietary connector's pins to USB.
+You can buy these online fairly cheap, or build your own.
 
 Such a cable is pretty easy to build. The Controller itself is a USB
 compound device (a hub with three ports for two expansion slots and
 the controller device) with the only difference in a nonstandard connector
-(5 pins vs. 4 on standard USB connector).
+(5 pins vs. 4 on standard USB 1.0 connectors).
 
 You just need to solder a USB connector onto the cable and keep the
 yellow wire unconnected. The other pins have the same order on both
@@ -102,26 +122,41 @@ original one. You can buy an extension cable and cut that instead. That way,
 you can still use the controller with your X-Box, if you have one ;)
 
 
+
 2. Driver Installation
 ----------------------
 
-Once you have the adapter cable and the controller is connected, you need
-to load your USB subsystem and should cat /proc/bus/usb/devices.
-There should be an entry like the one at the end [4].
+Once you have the adapter cable, if needed, and the controller connected
+the xpad module should be auto loaded. To confirm you can cat
+/proc/bus/usb/devices. There should be an entry like the one at the end [4].
+
+
 
-Currently (as of version 0.0.6), the following devices are included:
- original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202
- smaller  Microsoft XBOX controller (US), vendor=0x045e, product=0x0289
+3. Supported Controllers
+------------------------
+For a full list of supported controllers and associated vendor and product
+IDs see the xpad_device[] array[6].
+
+As of the historic version 0.0.6 (2006-10-10) the following devices
+were supported:
+ original Microsoft XBOX controller (US),    vendor=0x045e, product=0x0202
+ smaller  Microsoft XBOX controller (US),    vendor=0x045e, product=0x0289
  original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285
- InterAct PowerPad Pro (Germany), vendor=0x05fd, product=0x107a
- RedOctane Xbox Dance Pad (US), vendor=0x0c12, product=0x8809
+ InterAct PowerPad Pro (Germany),            vendor=0x05fd, product=0x107a
+ RedOctane Xbox Dance Pad (US),              vendor=0x0c12, product=0x8809
+
+Unrecognized models of Xbox controllers should function as Generic
+Xbox controllers. Unrecognized Dance Pad controllers require setting
+the module option 'dpad_to_buttons'.
+
+If you have an unrecognized controller please see 0.3 - Unknown Controllers
 
-The driver should work with xbox pads not listed above as well, however
-you will need to do something extra for dance pads to work.
 
-If you have a controller not listed above, see 0.3 - Unknown Controllers
+4. Manual Testing
+-----------------
+To test this driver's functionality you may use 'jstest'.
 
-If you compiled and installed the driver, test the functionality:
+For example:
 > modprobe xpad
 > modprobe joydev
 > jstest /dev/js0
@@ -134,7 +169,8 @@ show 20 inputs (6 axes, 14 buttons).
 It works? Voila, you're done ;)
 
 
-3. Thanks
+
+5. Thanks
 ---------
 
 I have to thank ITO Takayuki for the detailed info on his site
@@ -145,14 +181,14 @@ His useful info and both the usb-skeleton as well as the iforce input driver
 the basic functionality.
 
 
-4. References
--------------
 
-1. http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
-2. http://xpad.xbox-scene.com/
-3. http://www.markosweb.com/www/xboxhackz.com/ 
+6. References
+-------------
 
-4. /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany):
+[1]: http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
+[2]: http://xpad.xbox-scene.com/
+[3]: http://www.markosweb.com/www/xboxhackz.com/
+[4]: /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany):
 
 T:  Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#=  5 Spd=12  MxCh= 0
 D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs=  1
@@ -162,7 +198,7 @@ I:  If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none)
 E:  Ad=81(I) Atr=03(Int.) MxPS=  32 Ivl= 10ms
 E:  Ad=02(O) Atr=03(Int.) MxPS=  32 Ivl= 10ms
 
-5. /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US):
+[5]: /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US):
 
 T:  Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12  MxCh= 0
 D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
@@ -173,7 +209,12 @@ I:  If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad
 E:  Ad=82(I) Atr=03(Int.) MxPS=  32 Ivl=4ms
 E:  Ad=02(O) Atr=03(Int.) MxPS=  32 Ivl=4ms
 
--- 
+[6]: http://lxr.free-electrons.com/ident?i=xpad_device
+
+
+
+7. Historic Edits
+-----------------
 Marko Friedemann <mfr@bmx-chemnitz.de>
 2002-07-16
  - original doc
@@ -181,3 +222,5 @@ Marko Friedemann <mfr@bmx-chemnitz.de>
 Dominic Cerquetti <binary1230@yahoo.com>
 2005-03-19
  - added stuff for dance pads, new d-pad->axes mappings
+
+Later changes may be viewed with 'git log Documentation/input/xpad.txt'
diff --git a/drivers/input/joystick/xpad.c b/drivers/input/joystick/xpad.c
index 2ed7905..7e2e047 100644
--- a/drivers/input/joystick/xpad.c
+++ b/drivers/input/joystick/xpad.c
@@ -40,8 +40,8 @@
  *
  * TODO:
  *  - fine tune axes (especially trigger axes)
- *  - fix "analog" buttons (reported as digital now)
- *  - get rumble working
+ *  - add original xbox rumble pack support
+ *  - add xbox one rumble support
  *  - need USB IDs for other dance pads
  *
  * History:
-- 
2.1.0

[PATCH 1/1] Input: xpad - update docs to reflect current state

[Daniel Dressler]

The last time this documentation was accurate was
just over 8 years ago. In this time we've added
support for two new generations of Xbox console
controllers and dozens of third-party controllers.

This patch unifies terminology and makes it explicit
which model of controller a sentence refers to.

It also expands certain sections to address the latest
versions of Xbox controllers.

Thus this documentation should now be useful to
end users and not contain out-right untruths.

Signed-off-by: Daniel Dressler <danieru.dressler@gmail.com>
---
 Documentation/input/xpad.txt  | 123 ++++++++++++++++++++++++++++--------------
 drivers/input/joystick/xpad.c |   4 +-
 2 files changed, 85 insertions(+), 42 deletions(-)

diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.txt
index 7cc9a43..d1b23f2 100644
--- a/Documentation/input/xpad.txt
+++ b/Documentation/input/xpad.txt
@@ -1,18 +1,22 @@
-xpad - Linux USB driver for X-Box gamepads
+xpad - Linux USB driver for Xbox compatible controllers
 
-This is the very first release of a driver for X-Box gamepads.
-Basically, this was hacked away in just a few hours, so don't expect
-miracles.
+This driver exposes all first-party and third-party Xbox compatible
+controllers. It has a long history and has enjoyed considerable usage
+as Window's xinput library caused most PC games to focus on Xbox
+controller compatibility.
 
-In particular, there is currently NO support for the rumble pack.
-You won't find many ff-aware linux applications anyway.
+Due to backwards compatibility all buttons are reported as digital.
+This only effects Original Xbox controllers. All later controller models
+have only digital face buttons.
+
+Rumble is supported on some models of Xbox 360 controllers but not of
+Original Xbox controllers nor on Xbox One controllers. As of writing
+the Xbox One's rumble protocol has not been reverse engineered but in
+the future could be supported.
 
 
 0. Notes
 --------
-
-Driver updated for kernel 2.6.17.11. (Based on a patch for 2.6.11.4.)
-
 The number of buttons/axes reported varies based on 3 things:
 - if you are using a known controller
 - if you are using a known dance pad
@@ -20,12 +24,16 @@ The number of buttons/axes reported varies based on 3 things:
   module configuration for "Map D-PAD to buttons rather than axes for unknown
   pads" (module option dpad_to_buttons)
 
-If you set dpad_to_buttons to 0 and you are using an unknown device (one
-not listed below), the driver will map the directional pad to axes (X/Y),
-if you said N it will map the d-pad to buttons, which is needed for dance
-style games to function correctly.  The default is Y.
+If you set dpad_to_buttons to N and you are using an unknown device
+the driver will map the directional pad to axes (X/Y).
+If you said Y it will map the d-pad to buttons, which is needed for dance
+style games to function correctly. The default is Y.
+
+dpad_to_buttons has no effect for known pads. A erroneous commit message
+claimed dpad_to_buttons could be used to force behavior on known devices.
+This is not true. Both dpad_to_buttons and triggers_to_buttons only affect
+unknown controllers.
 
-dpad_to_buttons has no effect for known pads.
 
 0.1 Normal Controllers
 ----------------------
@@ -80,17 +88,29 @@ to the list of supported devices, ensuring that it will work out of the
 box in the future.
 
 
-1. USB adapter
+1. USB adapters
 --------------
+All generations of Xbox controllers speak USB over the wire.
+- Original Xbox controllers use a proprietary connector and require adapters.
+- Wireless Xbox 360 controllers require a 'Xbox 360 Wireless Gaming Receiver
+  for Windows'
+- Wired Xbox 360 controllers use standard USB connectors.
+- Xbox One controllers can be wireless but speak Wi-Fi Direct and are not
+  yet supported.
+- Xbox One controllers can be wired and use standard Micro-USB connectors.
+
 
-Before you can actually use the driver, you need to get yourself an
-adapter cable to connect the X-Box controller to your Linux-Box. You
-can buy these online fairly cheap, or build your own.
+
+1.1 Original Xbox USB adapters
+--------------
+Using this driver with an Original Xbox controller requires an
+adapter cable to break out the proprietary connector's pins to USB.
+You can buy these online fairly cheap, or build your own.
 
 Such a cable is pretty easy to build. The Controller itself is a USB
 compound device (a hub with three ports for two expansion slots and
 the controller device) with the only difference in a nonstandard connector
-(5 pins vs. 4 on standard USB connector).
+(5 pins vs. 4 on standard USB 1.0 connectors).
 
 You just need to solder a USB connector onto the cable and keep the
 yellow wire unconnected. The other pins have the same order on both
@@ -102,26 +122,41 @@ original one. You can buy an extension cable and cut that instead. That way,
 you can still use the controller with your X-Box, if you have one ;)
 
 
+
 2. Driver Installation
 ----------------------
 
-Once you have the adapter cable and the controller is connected, you need
-to load your USB subsystem and should cat /proc/bus/usb/devices.
-There should be an entry like the one at the end [4].
+Once you have the adapter cable, if needed, and the controller connected
+the xpad module should be auto loaded. To confirm you can cat
+/proc/bus/usb/devices. There should be an entry like the one at the end [4].
+
+
 
-Currently (as of version 0.0.6), the following devices are included:
- original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202
- smaller  Microsoft XBOX controller (US), vendor=0x045e, product=0x0289
+3. Supported Controllers
+------------------------
+For a full list of supported controllers and associated vendor and product
+IDs see the xpad_device[] array[6].
+
+As of the historic version 0.0.6 (2006-10-10) the following devices
+were supported:
+ original Microsoft XBOX controller (US),    vendor=0x045e, product=0x0202
+ smaller  Microsoft XBOX controller (US),    vendor=0x045e, product=0x0289
  original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285
- InterAct PowerPad Pro (Germany), vendor=0x05fd, product=0x107a
- RedOctane Xbox Dance Pad (US), vendor=0x0c12, product=0x8809
+ InterAct PowerPad Pro (Germany),            vendor=0x05fd, product=0x107a
+ RedOctane Xbox Dance Pad (US),              vendor=0x0c12, product=0x8809
+
+Unrecognized models of Xbox controllers should function as Generic
+Xbox controllers. Unrecognized Dance Pad controllers require setting
+the module option 'dpad_to_buttons'.
+
+If you have an unrecognized controller please see 0.3 - Unknown Controllers
 
-The driver should work with xbox pads not listed above as well, however
-you will need to do something extra for dance pads to work.
 
-If you have a controller not listed above, see 0.3 - Unknown Controllers
+4. Manual Testing
+-----------------
+To test this driver's functionality you may use 'jstest'.
 
-If you compiled and installed the driver, test the functionality:
+For example:
 > modprobe xpad
 > modprobe joydev
 > jstest /dev/js0
@@ -134,7 +169,8 @@ show 20 inputs (6 axes, 14 buttons).
 It works? Voila, you're done ;)
 
 
-3. Thanks
+
+5. Thanks
 ---------
 
 I have to thank ITO Takayuki for the detailed info on his site
@@ -145,14 +181,14 @@ His useful info and both the usb-skeleton as well as the iforce input driver
 the basic functionality.
 
 
-4. References
--------------
 
-1. http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
-2. http://xpad.xbox-scene.com/
-3. http://www.markosweb.com/www/xboxhackz.com/ 
+6. References
+-------------
 
-4. /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany):
+[1]: http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
+[2]: http://xpad.xbox-scene.com/
+[3]: http://www.markosweb.com/www/xboxhackz.com/
+[4]: /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany):
 
 T:  Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#=  5 Spd=12  MxCh= 0
 D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs=  1
@@ -162,7 +198,7 @@ I:  If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none)
 E:  Ad=81(I) Atr=03(Int.) MxPS=  32 Ivl= 10ms
 E:  Ad=02(O) Atr=03(Int.) MxPS=  32 Ivl= 10ms
 
-5. /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US):
+[5]: /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US):
 
 T:  Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12  MxCh= 0
 D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
@@ -173,7 +209,12 @@ I:  If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad
 E:  Ad=82(I) Atr=03(Int.) MxPS=  32 Ivl=4ms
 E:  Ad=02(O) Atr=03(Int.) MxPS=  32 Ivl=4ms
 
--- 
+[6]: http://lxr.free-electrons.com/ident?i=xpad_device
+
+
+
+7. Historic Edits
+-----------------
 Marko Friedemann <mfr@bmx-chemnitz.de>
 2002-07-16
  - original doc
@@ -181,3 +222,5 @@ Marko Friedemann <mfr@bmx-chemnitz.de>
 Dominic Cerquetti <binary1230@yahoo.com>
 2005-03-19
  - added stuff for dance pads, new d-pad->axes mappings
+
+Later changes may be viewed with 'git log Documentation/input/xpad.txt'
diff --git a/drivers/input/joystick/xpad.c b/drivers/input/joystick/xpad.c
index 2ed7905..7e2e047 100644
--- a/drivers/input/joystick/xpad.c
+++ b/drivers/input/joystick/xpad.c
@@ -40,8 +40,8 @@
  *
  * TODO:
  *  - fine tune axes (especially trigger axes)
- *  - fix "analog" buttons (reported as digital now)
- *  - get rumble working
+ *  - add original xbox rumble pack support
+ *  - add xbox one rumble support
  *  - need USB IDs for other dance pads
  *
  * History:
-- 
2.1.0

Re: [PATCH 1/1] Input: xpad - update docs to reflect current state

[Jonathan Corbet]

On Mon,  3 Nov 2014 17:53:06 +0900
Daniel Dressler <danieru.dressler@gmail.com> wrote:

> The last time this documentation was accurate was
> just over 8 years ago. In this time we've added
> support for two new generations of Xbox console
> controllers and dozens of third-party controllers.
> 
> This patch unifies terminology and makes it explicit
> which model of controller a sentence refers to.

So this seems like a useful update, and I was looking at pulling it into
the docs tree.  But this hunk:

> diff --git a/drivers/input/joystick/xpad.c b/drivers/input/joystick/xpad.c
> index 2ed7905..7e2e047 100644
> --- a/drivers/input/joystick/xpad.c
> +++ b/drivers/input/joystick/xpad.c
> @@ -40,8 +40,8 @@
>   *
>   * TODO:
>   *  - fine tune axes (especially trigger axes)
> - *  - fix "analog" buttons (reported as digital now)
> - *  - get rumble working
> + *  - add original xbox rumble pack support
> + *  - add xbox one rumble support
>   *  - need USB IDs for other dance pads
>   *
>   * History:

Seems like a different change that shouldn't be mixed up with the doc
update.  Send me a version without that change and, in the absence
of complaints, I'll apply it.

Thanks,

jon

Re: [PATCH 1/1] Input: xpad - update docs to reflect current state

[Jonathan Corbet]

On Mon,  3 Nov 2014 17:53:06 +0900
Daniel Dressler <danieru.dressler@gmail.com> wrote:

> The last time this documentation was accurate was
> just over 8 years ago. In this time we've added
> support for two new generations of Xbox console
> controllers and dozens of third-party controllers.
> 
> This patch unifies terminology and makes it explicit
> which model of controller a sentence refers to.

So this seems like a useful update, and I was looking at pulling it into
the docs tree.  But this hunk:

> diff --git a/drivers/input/joystick/xpad.c b/drivers/input/joystick/xpad.c
> index 2ed7905..7e2e047 100644
> --- a/drivers/input/joystick/xpad.c
> +++ b/drivers/input/joystick/xpad.c
> @@ -40,8 +40,8 @@
>   *
>   * TODO:
>   *  - fine tune axes (especially trigger axes)
> - *  - fix "analog" buttons (reported as digital now)
> - *  - get rumble working
> + *  - add original xbox rumble pack support
> + *  - add xbox one rumble support
>   *  - need USB IDs for other dance pads
>   *
>   * History:

Seems like a different change that shouldn't be mixed up with the doc
update.  Send me a version without that change and, in the absence
of complaints, I'll apply it.

Thanks,

jon

Re: [PATCH 1/1] Input: xpad - update docs to reflect current state

[Daniel Dressler]

Thanks Jon

I've sent a second version of the patch without the TODO list edits.


Now I would like to ask about a backwards compact issue related to this driver.

Eons ago in patch 99de0912b [0] when support for the wireless 360
controllers were added the decision was made to map their Dpad to the
discrete buttons.

There is reasonable justification for this behavior since the Dpad has
never functioned like an analog stick on Xbox hardware.

Except support for wired 360 controllers had been added a year earlier
and used the opposite behavior. In fact the wireless 360 controllers
are the only controllers which use the dpad_to_button behavior.

Original Xbox, wired Xbox 360, and all Xbox One controllers all expose
the dpad as a set of axises.

This has caused pain for downstream developers. It means two
controllers  have wildly different behavior. Many developers have just
ignored the issue or suggested users unload xpand and use the userland
replacement. Even Arch's wiki suggests such [1]. Which to be honest is
all one can do. The xpad driver does not expose the information
developers need to even incorporate a workaround without nasty hacks.

As a downstream developer I've been bitten by this twice. The first
time I didn't even know that wired vs wireless made a difference and I
was disturbed to learn the truth.

So here is what I want to hear opinions on: should the wireless 360's
dpad be exposed as both axises _and_ buttons?

[0]: https://github.com/torvalds/linux/commit/99de0912b when t
[1]: https://wiki.archlinux.org/index.php/joystick#Xbox_360_controllers

Daniel

2014-11-08 3:48 GMT+09:00 Jonathan Corbet <corbet@lwn.net>:
> On Mon,  3 Nov 2014 17:53:06 +0900
> Daniel Dressler <danieru.dressler@gmail.com> wrote:
>
>> The last time this documentation was accurate was
>> just over 8 years ago. In this time we've added
>> support for two new generations of Xbox console
>> controllers and dozens of third-party controllers.
>>
>> This patch unifies terminology and makes it explicit
>> which model of controller a sentence refers to.
>
> So this seems like a useful update, and I was looking at pulling it into
> the docs tree.  But this hunk:
>
>> diff --git a/drivers/input/joystick/xpad.c b/drivers/input/joystick/xpad.c
>> index 2ed7905..7e2e047 100644
>> --- a/drivers/input/joystick/xpad.c
>> +++ b/drivers/input/joystick/xpad.c
>> @@ -40,8 +40,8 @@
>>   *
>>   * TODO:
>>   *  - fine tune axes (especially trigger axes)
>> - *  - fix "analog" buttons (reported as digital now)
>> - *  - get rumble working
>> + *  - add original xbox rumble pack support
>> + *  - add xbox one rumble support
>>   *  - need USB IDs for other dance pads
>>   *
>>   * History:
>
> Seems like a different change that shouldn't be mixed up with the doc
> update.  Send me a version without that change and, in the absence
> of complaints, I'll apply it.
>
> Thanks,
>
> jon

Re: [PATCH 1/1] Input: xpad - update docs to reflect current state

[Thomaz de Oliveira dos Reis]

I totally agree that the behavior should be exactly the same in all
XBOX gamepads. But In my opinion this should be mapped as axis only,
since mapping for both could make a confusion in some games.

If you need the axis to be buttons, you can set as a option while
loading the module.




2014-11-10 6:06 GMT-02:00 Daniel Dressler <danieru.dressler@gmail.com>:
> Thanks Jon
>
> I've sent a second version of the patch without the TODO list edits.
>
>
> Now I would like to ask about a backwards compact issue related to this driver.
>
> Eons ago in patch 99de0912b [0] when support for the wireless 360
> controllers were added the decision was made to map their Dpad to the
> discrete buttons.
>
> There is reasonable justification for this behavior since the Dpad has
> never functioned like an analog stick on Xbox hardware.
>
> Except support for wired 360 controllers had been added a year earlier
> and used the opposite behavior. In fact the wireless 360 controllers
> are the only controllers which use the dpad_to_button behavior.
>
> Original Xbox, wired Xbox 360, and all Xbox One controllers all expose
> the dpad as a set of axises.
>
> This has caused pain for downstream developers. It means two
> controllers  have wildly different behavior. Many developers have just
> ignored the issue or suggested users unload xpand and use the userland
> replacement. Even Arch's wiki suggests such [1]. Which to be honest is
> all one can do. The xpad driver does not expose the information
> developers need to even incorporate a workaround without nasty hacks.
>
> As a downstream developer I've been bitten by this twice. The first
> time I didn't even know that wired vs wireless made a difference and I
> was disturbed to learn the truth.
>
> So here is what I want to hear opinions on: should the wireless 360's
> dpad be exposed as both axises _and_ buttons?
>
> [0]: https://github.com/torvalds/linux/commit/99de0912b when t
> [1]: https://wiki.archlinux.org/index.php/joystick#Xbox_360_controllers
>
> Daniel
>
> 2014-11-08 3:48 GMT+09:00 Jonathan Corbet <corbet@lwn.net>:
>> On Mon,  3 Nov 2014 17:53:06 +0900
>> Daniel Dressler <danieru.dressler@gmail.com> wrote:
>>
>>> The last time this documentation was accurate was
>>> just over 8 years ago. In this time we've added
>>> support for two new generations of Xbox console
>>> controllers and dozens of third-party controllers.
>>>
>>> This patch unifies terminology and makes it explicit
>>> which model of controller a sentence refers to.
>>
>> So this seems like a useful update, and I was looking at pulling it into
>> the docs tree.  But this hunk:
>>
>>> diff --git a/drivers/input/joystick/xpad.c b/drivers/input/joystick/xpad.c
>>> index 2ed7905..7e2e047 100644
>>> --- a/drivers/input/joystick/xpad.c
>>> +++ b/drivers/input/joystick/xpad.c
>>> @@ -40,8 +40,8 @@
>>>   *
>>>   * TODO:
>>>   *  - fine tune axes (especially trigger axes)
>>> - *  - fix "analog" buttons (reported as digital now)
>>> - *  - get rumble working
>>> + *  - add original xbox rumble pack support
>>> + *  - add xbox one rumble support
>>>   *  - need USB IDs for other dance pads
>>>   *
>>>   * History:
>>
>> Seems like a different change that shouldn't be mixed up with the doc
>> update.  Send me a version without that change and, in the absence
>> of complaints, I'll apply it.
>>
>> Thanks,
>>
>> jon

Re: [PATCH 1/1] Input: xpad - update docs to reflect current state

[Daniel Dressler]

I'd love to make all controllers report as axises but doing so _will_
break stuff downstream. Not least of which being every game which uses
SDL2's controller configs:
https://github.com/gabomdq/SDL_GameControllerDB/blob/master/gamecontrollerdb.txt

Which is just about every-single major commercial proprietary game
which has been ported to linux in the past 2 years.

Now it should also be clear that adding extra axises will not break
those games. The SDL2 library should just ignore those axises.

Also, the module option "dpad_to_buttons" will only operate on unknown
devices. Users cannot use it to return to old behavior so we have to
get this right.

Daniel

2014-11-10 20:47 GMT+09:00 Thomaz de Oliveira dos Reis <thor27@gmail.com>:
> I totally agree that the behavior should be exactly the same in all
> XBOX gamepads. But In my opinion this should be mapped as axis only,
> since mapping for both could make a confusion in some games.
>
> If you need the axis to be buttons, you can set as a option while
> loading the module.
>
>
>
>
> 2014-11-10 6:06 GMT-02:00 Daniel Dressler <danieru.dressler@gmail.com>:
>> Thanks Jon
>>
>> I've sent a second version of the patch without the TODO list edits.
>>
>>
>> Now I would like to ask about a backwards compact issue related to this driver.
>>
>> Eons ago in patch 99de0912b [0] when support for the wireless 360
>> controllers were added the decision was made to map their Dpad to the
>> discrete buttons.
>>
>> There is reasonable justification for this behavior since the Dpad has
>> never functioned like an analog stick on Xbox hardware.
>>
>> Except support for wired 360 controllers had been added a year earlier
>> and used the opposite behavior. In fact the wireless 360 controllers
>> are the only controllers which use the dpad_to_button behavior.
>>
>> Original Xbox, wired Xbox 360, and all Xbox One controllers all expose
>> the dpad as a set of axises.
>>
>> This has caused pain for downstream developers. It means two
>> controllers  have wildly different behavior. Many developers have just
>> ignored the issue or suggested users unload xpand and use the userland
>> replacement. Even Arch's wiki suggests such [1]. Which to be honest is
>> all one can do. The xpad driver does not expose the information
>> developers need to even incorporate a workaround without nasty hacks.
>>
>> As a downstream developer I've been bitten by this twice. The first
>> time I didn't even know that wired vs wireless made a difference and I
>> was disturbed to learn the truth.
>>
>> So here is what I want to hear opinions on: should the wireless 360's
>> dpad be exposed as both axises _and_ buttons?
>>
>> [0]: https://github.com/torvalds/linux/commit/99de0912b when t
>> [1]: https://wiki.archlinux.org/index.php/joystick#Xbox_360_controllers
>>
>> Daniel
>>
>> 2014-11-08 3:48 GMT+09:00 Jonathan Corbet <corbet@lwn.net>:
>>> On Mon,  3 Nov 2014 17:53:06 +0900
>>> Daniel Dressler <danieru.dressler@gmail.com> wrote:
>>>
>>>> The last time this documentation was accurate was
>>>> just over 8 years ago. In this time we've added
>>>> support for two new generations of Xbox console
>>>> controllers and dozens of third-party controllers.
>>>>
>>>> This patch unifies terminology and makes it explicit
>>>> which model of controller a sentence refers to.
>>>
>>> So this seems like a useful update, and I was looking at pulling it into
>>> the docs tree.  But this hunk:
>>>
>>>> diff --git a/drivers/input/joystick/xpad.c b/drivers/input/joystick/xpad.c
>>>> index 2ed7905..7e2e047 100644
>>>> --- a/drivers/input/joystick/xpad.c
>>>> +++ b/drivers/input/joystick/xpad.c
>>>> @@ -40,8 +40,8 @@
>>>>   *
>>>>   * TODO:
>>>>   *  - fine tune axes (especially trigger axes)
>>>> - *  - fix "analog" buttons (reported as digital now)
>>>> - *  - get rumble working
>>>> + *  - add original xbox rumble pack support
>>>> + *  - add xbox one rumble support
>>>>   *  - need USB IDs for other dance pads
>>>>   *
>>>>   * History:
>>>
>>> Seems like a different change that shouldn't be mixed up with the doc
>>> update.  Send me a version without that change and, in the absence
>>> of complaints, I'll apply it.
>>>
>>> Thanks,
>>>
>>> jon

Re: [PATCH 1/1] Input: xpad - update docs to reflect current state

[Thomaz de Oliveira dos Reis]

Ok, I got your point... So having both looks like the best option to me.

2014-11-10 10:15 GMT-02:00 Daniel Dressler <danieru.dressler@gmail.com>:
> I'd love to make all controllers report as axises but doing so _will_
> break stuff downstream. Not least of which being every game which uses
> SDL2's controller configs:
> https://github.com/gabomdq/SDL_GameControllerDB/blob/master/gamecontrollerdb.txt
>
> Which is just about every-single major commercial proprietary game
> which has been ported to linux in the past 2 years.
>
> Now it should also be clear that adding extra axises will not break
> those games. The SDL2 library should just ignore those axises.
>
> Also, the module option "dpad_to_buttons" will only operate on unknown
> devices. Users cannot use it to return to old behavior so we have to
> get this right.
>
> Daniel
>
> 2014-11-10 20:47 GMT+09:00 Thomaz de Oliveira dos Reis <thor27@gmail.com>:
>> I totally agree that the behavior should be exactly the same in all
>> XBOX gamepads. But In my opinion this should be mapped as axis only,
>> since mapping for both could make a confusion in some games.
>>
>> If you need the axis to be buttons, you can set as a option while
>> loading the module.
>>
>>
>>
>>
>> 2014-11-10 6:06 GMT-02:00 Daniel Dressler <danieru.dressler@gmail.com>:
>>> Thanks Jon
>>>
>>> I've sent a second version of the patch without the TODO list edits.
>>>
>>>
>>> Now I would like to ask about a backwards compact issue related to this driver.
>>>
>>> Eons ago in patch 99de0912b [0] when support for the wireless 360
>>> controllers were added the decision was made to map their Dpad to the
>>> discrete buttons.
>>>
>>> There is reasonable justification for this behavior since the Dpad has
>>> never functioned like an analog stick on Xbox hardware.
>>>
>>> Except support for wired 360 controllers had been added a year earlier
>>> and used the opposite behavior. In fact the wireless 360 controllers
>>> are the only controllers which use the dpad_to_button behavior.
>>>
>>> Original Xbox, wired Xbox 360, and all Xbox One controllers all expose
>>> the dpad as a set of axises.
>>>
>>> This has caused pain for downstream developers. It means two
>>> controllers  have wildly different behavior. Many developers have just
>>> ignored the issue or suggested users unload xpand and use the userland
>>> replacement. Even Arch's wiki suggests such [1]. Which to be honest is
>>> all one can do. The xpad driver does not expose the information
>>> developers need to even incorporate a workaround without nasty hacks.
>>>
>>> As a downstream developer I've been bitten by this twice. The first
>>> time I didn't even know that wired vs wireless made a difference and I
>>> was disturbed to learn the truth.
>>>
>>> So here is what I want to hear opinions on: should the wireless 360's
>>> dpad be exposed as both axises _and_ buttons?
>>>
>>> [0]: https://github.com/torvalds/linux/commit/99de0912b when t
>>> [1]: https://wiki.archlinux.org/index.php/joystick#Xbox_360_controllers
>>>
>>> Daniel
>>>
>>> 2014-11-08 3:48 GMT+09:00 Jonathan Corbet <corbet@lwn.net>:
>>>> On Mon,  3 Nov 2014 17:53:06 +0900
>>>> Daniel Dressler <danieru.dressler@gmail.com> wrote:
>>>>
>>>>> The last time this documentation was accurate was
>>>>> just over 8 years ago. In this time we've added
>>>>> support for two new generations of Xbox console
>>>>> controllers and dozens of third-party controllers.
>>>>>
>>>>> This patch unifies terminology and makes it explicit
>>>>> which model of controller a sentence refers to.
>>>>
>>>> So this seems like a useful update, and I was looking at pulling it into
>>>> the docs tree.  But this hunk:
>>>>
>>>>> diff --git a/drivers/input/joystick/xpad.c b/drivers/input/joystick/xpad.c
>>>>> index 2ed7905..7e2e047 100644
>>>>> --- a/drivers/input/joystick/xpad.c
>>>>> +++ b/drivers/input/joystick/xpad.c
>>>>> @@ -40,8 +40,8 @@
>>>>>   *
>>>>>   * TODO:
>>>>>   *  - fine tune axes (especially trigger axes)
>>>>> - *  - fix "analog" buttons (reported as digital now)
>>>>> - *  - get rumble working
>>>>> + *  - add original xbox rumble pack support
>>>>> + *  - add xbox one rumble support
>>>>>   *  - need USB IDs for other dance pads
>>>>>   *
>>>>>   * History:
>>>>
>>>> Seems like a different change that shouldn't be mixed up with the doc
>>>> update.  Send me a version without that change and, in the absence
>>>> of complaints, I'll apply it.
>>>>
>>>> Thanks,
>>>>
>>>> jon