joydev: support for Saitek PS1000 gamepad

joydev: support for Saitek PS1000 gamepad

[Andreas Hübner]

[-- Attachment #1: Type: text/plain, Size: 1544 bytes --]

Hello!

I was trying to contact who I think is the maintainer of the joydev
module (vojtech@suze.cz), but had no success. Apologies if this list is
not the right target audience, I would appreciate any hints about who is
currently maintaining the module.
It's also possible, that the issue is not related to joydev module
itself. usb-hid could also be involved.

I'm pasting the contents of the mail I had sent:

---------------------------------------------------------------------------

In the linux kernel documentation you requested information on what
devices this driver currently can't make complete use of.
I have a Saitek PS1000 Gamepad (USB) that has 5 axis and at least 10 buttons,
probably more. (One of the axis is also wired to buttons in the windows
driver.)
The joydev driver does not fully support this device:

Joystick (Jess Technology Co., Ltd. PS1000 Dual AnaloguePad) has 6 axes and 0 buttons. Driver version is 2.1.0.
Testing ... (interrupt to exit)
Axes:  0:     0  1:     0  2:     0  3:     0  4:     0  5:-32767

All the axes work but the sixth does not exist on the device. However,
no button is detected which makes it kind of unusable.

If you need more info or need me to compile, test, debug stuff, just ask.
I also attached the lsusb -vv output.

---------------------------------------------------------------------------

So if anyone has an idea how to deal with the issue, please contact me.
I'm willing to debug this if someone tells me where to dive in or how
the usb input stuff works.


Andreas Hübner

[-- Attachment #2: lsusb.txt --]
[-- Type: text/plain, Size: 1980 bytes --]

Bus 002 Device 002: ID 06a3:0621 Saitek PLC 
Device Descriptor:
  bLength                18
  bDescriptorType         1
  bcdUSB               2.00
  bDeviceClass            0 (Defined at Interface level)
  bDeviceSubClass         0 
  bDeviceProtocol         0 
  bMaxPacketSize0        64
  idVendor           0x06a3 Saitek PLC
  idProduct          0x0621 
  bcdDevice            1.00
  iManufacturer           1 Jess Technology Co., Ltd.
  iProduct                2 PS1000 Dual AnaloguePad
  iSerial                 0 
  bNumConfigurations      1
  Configuration Descriptor:
    bLength                 9
    bDescriptorType         2
    wTotalLength           34
    bNumInterfaces          1
    bConfigurationValue     1
    iConfiguration          0 
    bmAttributes         0x80
      (Bus Powered)
    MaxPower              200mA
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        0
      bAlternateSetting       0
      bNumEndpoints           1
      bInterfaceClass         3 Human Interface Device
      bInterfaceSubClass      0 No Subclass
      bInterfaceProtocol      0 None
      iInterface              0 
        HID Device Descriptor:
          bLength                 9
          bDescriptorType        33
          bcdHID               1.11
          bCountryCode            0 Not supported
          bNumDescriptors         1
          bDescriptorType        34 Report
          wDescriptorLength     137
         Report Descriptors: 
           ** UNAVAILABLE **
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x81  EP 1 IN
        bmAttributes            3
          Transfer Type            Interrupt
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0040  1x 64 bytes
        bInterval              10
Device Status:     0x0000
  (Bus Powered)

Re: joydev: support for Saitek PS1000 gamepad

[simon]

Hi Andreas,
I'm not involved with that bit of code, but here are some hints for you...

> I was trying to contact who I think is the maintainer of the joydev
> module (vojtech@suze.cz), but had no success. Apologies if this list is
> not the right target audience, I would appreciate any hints about who is
> currently maintaining the module.

You are asking in exactly the right place :-)

> It's also possible, that the issue is not related to joydev module
> itself. usb-hid could also be involved.

If the device is a HID device, it is quite possible that the HID
descriptor it is providing is 'wrong' (not properly understood by Linux).
We have to 'correct' these on a number of devices.

If you can post/decode the descriptor that might provide some insight into
the problem.

On newer kernels the descriptor can be found under the '/sys' directory.

For example (a HID gaming wheel I have):
--
simon@ubuntu:/sys/bus/hid/devices/0003:046D:C294.000B$ ls
driver  hidraw  power  range  report_descriptor  subsystem  uevent
simon@ubuntu:/sys/bus/hid/devices/0003:046D:C294.000B$ hexdump -C
report_descriptor
00000000  05 01 09 04 a1 01 a1 02  95 01 75 0a 15 00 26 ff 
|..........u...&.|
00000010  03 35 00 46 ff 03 09 30  81 02 95 0c 75 01 25 01 
|.5.F...0....u.%.|
00000020  45 01 05 09 19 01 29 0c  81 02 95 02 06 00 ff 09 
|E.....).........|
00000030  01 81 02 05 01 09 31 26  ff 00 46 ff 00 95 01 75 
|......1&..F....u|
00000040  08 81 02 25 07 46 3b 01  75 04 65 14 09 39 81 42 
|...%.F;.u.e..9.B|
00000050  75 01 95 04 65 00 06 00  ff 09 01 25 01 45 01 81 
|u...e......%.E..|
00000060  02 95 02 75 08 26 ff 00  46 ff 00 09 02 81 02 c0 
|...u.&..F.......|
00000070  a1 02 26 ff 00 46 ff 00  95 07 75 08 09 03 91 02 
|..&..F....u.....|
00000080  c0 0a ff ff 95 08 b1 02  c0                       |.........|
00000089
--

There are tools to capture and decode the binary block here:
http://digimend.sourceforge.net/

Simon

Re: joydev: support for Saitek PS1000 gamepad

[Andreas Hübner]

[-- Attachment #1: Type: text/plain, Size: 204 bytes --]

Hi Simon,

thanks for your help!

> If you can post/decode the descriptor that might provide some insight into
> the problem.

I've attached the hid report descriptor in binary and spec format.


Andreas

[-- Attachment #2: saitek_ps1000.spec --]
[-- Type: text/plain, Size: 2215 bytes --]

Usage Page (Desktop),               ; Generic desktop controls (01h)
Usage (Gamepad),                    ; Gamepad (05h, application collection)
Collection (Application),
    Usage (Pointer),                ; Pointer (01h, physical collection)
    Collection (Physical),
        Usage Page (Desktop),       ; Generic desktop controls (01h)
        Usage (X),                  ; X (30h, dynamic value)
        Usage (Y),                  ; Y (31h, dynamic value)
        Usage (Z),                  ; Z (32h, dynamic value)
        Usage (Rz),                 ; Rz (35h, dynamic value)
        Usage (Rx),                 ; Rx (33h, dynamic value)
        Usage (Slider),             ; Slider (36h, dynamic value)
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Maximum (255),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Minimum (0),
        Logical Maximum (255),
        Physical Minimum (0),
        Physical Maximum (255),
        Unit,
        Report Size (8),
        Report Count (5),
        Input (Variable),
    End Collection,
    Usage (Hat Switch),             ; Hat switch (39h, dynamic value)
    Logical Minimum (1),
    Logical Maximum (8),
    Physical Minimum (0),
    Physical Maximum (315),
    Unit (Degrees),
    Report Size (4),
    Report Count (1),
    Input (Constant, Variable),
    Usage Page (Button),            ; Button (09h)
    Usage Minimum (01h),
    Usage Maximum (0Dh),
    Logical Minimum (0),
    Logical Maximum (1),
    Report Size (1),
    Report Count (13),
    Input (Constant, Variable),
    Report Count (7),
    Input (Constant),
    Usage Page (LED),               ; LEDs (08h)
    Usage (43h),
    Logical Minimum (0),
    Logical Maximum (255),
    Physical Minimum (0),
    Physical Maximum (255),
    Report Size (8),
    Report Count (4),
    Output (Variable, Volatile),
End Collection

[-- Attachment #3: saitek_ps1000.bin --]
[-- Type: application/octet-stream, Size: 137 bytes --]

Re: Saitek PS1000 gamepad - HID descriptor wonky

[simon]

Hi Andreas,

> I've attached the hid report descriptor in binary and spec format.

As you probably noticed this HID descriptor is a little 'weird'.

First it defines 6 usages
--
        Usage (X),                  ; X (30h, dynamic value)
        Usage (Y),                  ; Y (31h, dynamic value)
        Usage (Z),                  ; Z (32h, dynamic value)
        Usage (Rz),                 ; Rz (35h, dynamic value)
        Usage (Rx),                 ; Rx (33h, dynamic value)
        Usage (Slider),             ; Slider (36h, dynamic value)
--

but then only says they are 5 inputs
--
        Report Count (5),
--

I'm guessing that if you adjust the report count to '6' then your 6th axis
might start working, and possibly the hat-switch and buttons too...

So the next question has to be how committed to your ($15??) game pad are
you, and are you will to go through the pain of building/submitting
patches? It's a great opportunity to put 'kernel dev' on your resume ;-)


I'll have to defer to the other kernel devs....

Q. Is there a way of patching a HID descriptor without writing a driver?


Otherwise you could look at 'drivers/hid/hid-elecom.c' as a template for
your patch.

Good luck, and feel free to ask questions,
Simon.

Re: Saitek PS1000 gamepad - HID descriptor wonky

[Andreas Hübner]

Hi Simon,

> As you probably noticed this HID descriptor is a little 'weird'.
>
> First it defines 6 usages
> [...]
> but then only says they are 5 inputs

Indeed. Actually, the controller only has 5 axes. Two analog sticks (4 axes)
and a throttle that is linked to the trigger buttons. Pressing the left
trigger yields a negative axis value and the right trigger produces
positive values. (I assume it's for controlling the acceleration, etc.)
This axis also has a threshold in the positive and negative range each
triggering a button press.

> So the next question has to be how committed to your ($15??) game pad are
> you, and are you will to go through the pain of building/submitting
> patches? It's a great opportunity to put 'kernel dev' on your resume ;-)

Well, I'm always happy when I can hack some code, so count me in. :)
Usually, the only problem for me is to get a decent setup to start
debugging.

But I guess, I'll have to learn a bit more about HID descriptors before
I can start hacking.

> Otherwise you could look at 'drivers/hid/hid-elecom.c' as a template for
> your patch.

Will take a look at it - thanks!


Andreas

Re: Saitek PS1000 gamepad - HID descriptor wonky

[simon]

>> You have to check the rsize, otherwise you might have problems writing
>> outside the size of the original descriptor.
>
> That's exactly what I've been doing, or did I miss something?

> In fact, I wanted to be absolutely sure and only mess with the descriptor
> when the sizes match.  (*rsize == 137)

Err.. must have been sleepy when I looked over your code. Don't know
whether '>=' is better than '==', all other modules do this and I wonder
whether the kernel can get a larger descriptor block by some mechanism.


> Should already be on the list. And I was able to identify the culprit so
> no need to bother you.
>
> The problem is the following code in hidinput_configure_usage
> (drivers/hid/hid-input.c):
>
> 	if (field->flags & HID_MAIN_ITEM_CONSTANT)
> 		goto ignore;
>
> The buttons and the hat are defined with the constant flag enabled.
> Now I might be reading the spec wrong, but I'm not so sure that we can
> simply skip constant values.

Quite obviously if the buttons change value in the HID stream then they
are not 'CONSTANT', personally I would patch this part of the HID
descriptor so they are just defined as 'input variable'.

> Well, I need to patch the descriptor nevertheless because it defines a
> non-existing sixth axis. Might as well remove the constant flag on the
> buttons and hat. However, other devices might be affected as well, so
> I'd like to get some input on how to deal with the situation.

Not sure why you would think other devices might be affected. Patching the
HID descriptor should be limited to this USBID pair, and even only active
if the device provided matches the template you use to trigger patching.

Some drivers provide a complete/new descriptor where patching is
complicated, although you gain extra hacker-points if you can achieve the
same with a minimal patch :-)

Simon.

Re: Saitek PS1000 gamepad - HID descriptor wonky

[Andreas Hübner]

On Mon, Dec 12, 2011 at 01:49:59PM -0500, simon@mungewell.org wrote:
> Err.. must have been sleepy when I looked over your code. Don't know
> whether '>=' is better than '==', all other modules do this and I wonder
> whether the kernel can get a larger descriptor block by some mechanism.

Well, this would be kind of strange, wouldn't it?
But I can change it to '>=' if it makes you happy. :)


> Quite obviously if the buttons change value in the HID stream then they
> are not 'CONSTANT', personally I would patch this part of the HID
> descriptor so they are just defined as 'input variable'.

While I personally agree with that interpretation, the spec only states
that constant fields can not be written by the host. (I know, this
doesn't make any sense for an input report.)

Somewhere I read that a constant field with no usage assigned to it
should be treated as padding. But in this case, there is a usage
assigned to.
And this is what I'd actually do in hidinput_configure_usage: only goto
ignore if there is no usage associated with the field.

On the other hand, the gamepad example in the HID Usage Tables doesn't
use the constant flag for buttons.


> Not sure why you would think other devices might be affected. Patching the
> HID descriptor should be limited to this USBID pair, and even only active
> if the device provided matches the template you use to trigger patching.

I was worrying that other devices might declare some non-padding input
fields as constants. So if you fix this problem in the generic part
(i. e. hid-input.c) those devices will also start working correctly.


Andreas

Re: Saitek PS1000 gamepad - HID descriptor wonky

[Andreas Hübner]

I'm finally coming back to this after quite some time.

Tried to find more info regarding the issue with the constant bit on those
input reports, but I wasn't able to come up with anything useful.
Windows just seems to ignore it.

Well, it's probably not worth it to spend anymore time on this, so I
prepared a patch that fixes the report descriptor accordingly.

I tried to follow the kernel patch policy, but since this is my first
patch I might have screwed something up. Just let me know.


Andreas

Re: Saitek PS1000 gamepad - HID descriptor wonky

[Andreas Hübner]

Hi Simon!

Let's continue the discussion on the list. I did made some progress
that requires input from the HID maintainers.

> You have to check the rsize, otherwise you might have problems writing
> outside the size of the original descriptor.

That's exactly what I've been doing, or did I miss something?
In fact, I wanted to be absolutely sure and only mess with the descriptor
when the sizes match.  (*rsize == 137)

> Note a D-Pad might be defined as 'Buttons', a 'D-Pad' or as a 'Hat'. You
> need to check out the values change in the HID stream.

It's defined as a 'Hat' with 8 different directions.

> Send me a copy of the original descriptor and I'll have a look.

Should already be on the list. And I was able to identify the culprit so
no need to bother you.

The problem is the following code in hidinput_configure_usage
(drivers/hid/hid-input.c):

	if (field->flags & HID_MAIN_ITEM_CONSTANT)
		goto ignore;

The buttons and the hat are defined with the constant flag enabled.
Now I might be reading the spec wrong, but I'm not so sure that we can
simply skip constant values.
This is the description of the data/constant flag.

    Indicates whether the item is data or a constant
    value. Data indicates the item is defining report
    fields that contain modifiable device data. Constant
    indicates the item is a static read-only field in a
    report and cannot be modified (written) by the
    host.


Well, I need to patch the descriptor nevertheless because it defines a
non-existing sixth axis. Might as well remove the constant flag on the
buttons and hat. However, other devices might be affected as well, so
I'd like to get some input on how to deal with the situation.


Andreas