Update of the X-Box USB pad driver and documentation to version 0.0.5.

Documentation/input/xpad.txt

-usb-xpad - Linux USB driver for XBOX HID gamecontrollers
+xpad - Linux USB driver for X-Box gamepads
 
-This is the very first release of a driver for XBOX gamecontrollers.
+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.
+In particular, there is currently NO support for the rumble pack.
+You won't find many ff-aware linux applications anyway.
+
 
 0. Status
 ---------
@@ -14,31 +17,38 @@ The jstest-program from joystick-1.2.15 (jstest-version 2.1.0) reports
 8 axes and 10 buttons.
 
 Alls 8 axes work, though they all have the same range (-32768..32767)
-and the zero-setting is not correct for the triggers.
-9 of the 10 buttons work (my black button does not work, though I can
-see no reason for it not to), all of them are in digital mode, though
-(the six buttons on the right side are "analog" ones).
+and the zero-setting is not correct for the triggers (I don't know if that
+is some limitation of jstest, since the input device setup should be fine. I
+didn't have a look at jstest itself yet).
+
+All of the 10 buttons work (in digital mode). The six buttons on the
+right side (A, B, X, Y, black, white) are said to be "analog" and
+report their values as 8 bit unsigned, not sure what this is good for.
+
+I tested the controller with quake3, and configuration and
+in game functionality were OK. However, I find it rather difficult to
+play first person shooters with a pad. Your mileage may vary.
 
 
 1. USB adapter
 --------------
 
 Before you can actually use the driver, you need to get yourself an
-adapter cable to connect the XBOX-controller to your Linux-Box.
+adapter cable to connect the X-Box controller to your Linux-Box.
 
-Such a cable is pretty easy to build. The Controller itself is a USB device
-(a hub with three ports; two expansion slots and the controller device)
-with the only differnce in a nonstandard connector (5 pins vs. 4 on
+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).
 
-You just need to solder an USB connector onto the cable and keep the
+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
-connectors so there no magic to it. Detailed info on these matters can be found
-on the net.
+connectors so there is no magic to it. Detailed info on these matters
+can be found on the net ([1], [2], [3]).
 
 Thanks to the trip splitter found on the cable you don't even need to cut the
-original cable, you can buy an extension cable and cut that instead. That way,
-you can still use the controller with your XBOX, if you have one ;)
+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
@@ -46,22 +56,26 @@ you can still use the controller with your XBOX, if you have one ;)
 
 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 in InterAct_german.dump.
+There should be an entry like the one at the end [4].
+
+Currently (as of version 0.0.4), the following three devices are included:
+ original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202
+ original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285
+ InterAct PowerPad Pro (Germany), vendor=0x05fd, product=0x107a
 
-Don't worry if the vendor and/or product ID don't match, those are easy to
-add to the driver. You could do it yourself, just add the appropriate line
-into the list after the line
-    '} xpad_device[] = {'
-, but before the line that says
-    '{ 0x0000, 0x0000, "unknown...." }'.
+If you have another controller that is not listed above and is not recognized
+by the driver, please drop me a line with the appropriate info (that is, include
+the name, vendor and product ID, as well as the country where you bought it;
+sending the whole dump out of /proc/bus/usb/devices along would be even better).
 
 In theory, the driver should work with other controllers than mine
-(InterAct PowerPad pro, bought in Germany) just fine, but see for yourself.
+(InterAct PowerPad pro, bought in Germany) just fine, but I cannot test this
+for I only have this one controller.
 
 If you compiled and installed the driver, test the functionality:
-> modprobe usb-xpad
+> modprobe xpad
 > modprobe joydev
-> jstest /dev/input/js0
+> jstest /dev/js0
 
 There should be a single line showing 18 inputs (8 axes, 10 buttons), and
 it's values should change if you move the sticks and push the buttons.
@@ -76,9 +90,27 @@ I have to thank ITO Takayuki for the detailed info on his site
  http://euc.jp/periphs/xbox-controller.ja.html.
  
 His useful info and both the usb-skeleton as well as the iforce input driver
-helped a lot in rapid prototyping the basic functionality.
+(Greg Kroah-Hartmann; Vojtech Pavlik) helped a lot in rapid prototyping
+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.xboxhackz.com/Hackz-Reference.htm
+
+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
+P:  Vendor=05fd ProdID=107a Rev= 1.00
+C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
+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
 
 -- 
 Marko Friedemann <mfr@bmx-chemnitz.de>
-2002-07-02
+2002-07-16

drivers/usb/input/xpad.c

 /*
- * USB XBOX HID Gamecontroller - v0.0.3
+ * X-Box gamepad - v0.0.5
  *
  * Copyright (c) 2002 Marko Friedemann <mfr@bmx-chemnitz.de>
  *
@@ -25,44 +25,46 @@
  *  - the skeleton-driver  drivers/usb/usb-skeleton.c
  *
  * Thanks to:
- *  - ITO Takayuki for providing xpad information on his website
+ *  - ITO Takayuki for providing essential xpad information on his website
  *  - Vojtech Pavlik     - iforce driver / input subsystem
  *  - Greg Kroah-Hartman - usb-skeleton driver
  *
  * TODO:
- *	- get the black button to work
  *  - fine tune axes
- *      - fix "analog" buttons
+ *  - fix "analog" buttons (reported as digital now)
  *  - get rumble working
  *
  * History:
  *
- * 2002-06-27 - 0.0.1 - first version, just said "XBOX HID controller"
+ * 2002-06-27 - 0.0.1 : first version, just said "XBOX HID controller"
  *
- * 2002-07-02 - 0.0.2 - basic working version
- *      all axes and 9 of the 10 buttons work (german InterAct device)
- *      the black button does not work
+ * 2002-07-02 - 0.0.2 : basic working version
+ *  - all axes and 9 of the 10 buttons work (german InterAct device)
+ *  - the black button does not work
  *
+ * 2002-07-14 - 0.0.3 : rework by Vojtech Pavlik
+ *  - indentation fixes
+ *  - usb + input init sequence fixes
+ *
+ * 2002-07-16 - 0.0.4 : minor changes, merge with Vojtech's v0.0.3
+ *  - verified the lack of HID and report descriptors
+ *  - verified that ALL buttons WORK
+ *  - fixed d-pad to axes mapping
+ *
+ * 2002-07-17 - 0.0.5 : simplified d-pad handling
  */
 
 #include <linux/config.h>
 #include <linux/kernel.h>
 #include <linux/input.h>
-#include <linux/sched.h>
-#include <linux/signal.h>
-#include <linux/errno.h>
-#include <linux/poll.h>
 #include <linux/init.h>
 #include <linux/slab.h>
-#include <linux/fcntl.h>
 #include <linux/module.h>
-#include <linux/spinlock.h>
-#include <linux/list.h>
 #include <linux/smp_lock.h>
 #include <linux/devfs_fs_kernel.h>
 #include <linux/usb.h>
 
-#define DRIVER_VERSION "v0.0.3"
+#define DRIVER_VERSION "v0.0.5"
 #define DRIVER_AUTHOR "Marko Friedemann <mfr@bmx-chemnitz.de>"
 #define DRIVER_DESC "X-Box pad driver"
 
@@ -75,13 +77,13 @@ static struct xpad_device {
 } xpad_device[] = {
 	{ 0x045e, 0x0202, "Microsoft X-Box pad (US)" },
 	{ 0x045e, 0x0285, "Microsoft X-Box pad (Japan)" },
-	{ 0x05fd, 0x107a, "InterAct X-Box pad (Germany)" },
+	{ 0x05fd, 0x107a, "InterAct 'PowerPad Pro' X-Box pad (Germany)" },
 	{ 0x0000, 0x0000, "X-Box pad" }
 };
 
 static signed short xpad_btn[] = {
-	BTN_A, BTN_B, BTN_C, BTN_X, BTN_Y, BTN_Z,       /* 6 "analog" buttons */
-	BTN_START, BTN_BACK, BTN_THUMBL, BTN_THUMBR,    /* start/back + stick press */
+	BTN_A, BTN_B, BTN_C, BTN_X, BTN_Y, BTN_Z,	/* "analog" buttons */
+	BTN_START, BTN_BACK, BTN_THUMBL, BTN_THUMBR,	/* start/back/sticks */
 	-1						/* terminating entry */
 };
 
@@ -89,15 +91,10 @@ static signed short xpad_abs[] = {
 	ABS_X, ABS_Y,		/* left stick */
 	ABS_RX, ABS_RY,		/* right stick */
 	ABS_Z, ABS_RZ,		/* triggers left/right */
-	ABS_HAT0X, ABS_HAT0Y,	/* dpad */
+	ABS_HAT0X, ABS_HAT0Y,	/* digital pad */
 	-1			/* terminating entry */
 };
 
-static struct {
-	__s32 x;
-	__s32 y;
-} xpad_hat_to_axis[] = { {0, 0}, {0, -1}, {1, -1}, {1, 0}, {1, 1}, {0, 1}, {-1, 1}, {-1, 0}, {-1, -1} };
-
 static struct usb_device_id xpad_table [] = {
 	{ USB_INTERFACE_INFO('X', 'B', 0) },	/* X-Box USB-IF not approved class */
 	{ }
@@ -113,28 +110,17 @@ struct usb_xpad {
 	unsigned char idata[XPAD_PKT_LEN];	/* input data */
 	
 	char phys[65];				/* physical device path */
-	int open_count;				/* how many times has this been opened */
+	int open_count;				/* reference count */
 };
 
 /*
  *	xpad_process_packet
  *
- *      Completes a request by converting the data into events for the input subsystem.
+ *	Completes a request by converting the data into events for the
+ *	input subsystem.
  *
- *      The used report descriptor given below was taken from ITO Takayukis website:
+ *	The used report descriptor was taken from ITO Takayukis website:
  *	 http://euc.jp/periphs/xbox-controller.ja.html
- *
- * ----------------------------------------------------------------------------------------------------------------
- * |  padding | byte-cnt | dpad sb12 | reserved |   bt A   |   bt B   |   bt X   |   bt Y   | bt black | bt white |
- * | 01234567 | 01234567 | 0123 4567 | 01234567 | 01234567 | 01234567 | 01234567 | 01234567 | 01234567 | 01234567 |
- * |    0     |    1     |     2     |    3     |    4     |    5     |    6     |    7     |    8     |    9     |
- * ----------------------------------------------------------------------------------------------------------------
- *
- * ---------------------------------------------------------------------------------------------------------------
- * |  trig L  |  trig R  |     left stick X    |     left stick Y    |     right stick X   |     right stick Y   |
- * | 01234567 | 01234567 | 01234567 | 01234567 | 01234567 | 01234567 | 01234567 | 01234567 | 01234567 | 01234567 |
- * |    10    |    11    |    12    |    13    |    14    |    15    |    16    |    17    |    18    |    19    |
- * ---------------------------------------------------------------------------------------------------------------
  */
 
 static void xpad_process_packet(struct usb_xpad *xpad, u16 cmd, unsigned char *data)
@@ -154,8 +140,8 @@ static void xpad_process_packet(struct usb_xpad *xpad, u16 cmd, unsigned char *d
 	input_report_abs(dev, ABS_RZ, data[11]);
 	
 	/* digital pad */
-	input_report_abs(dev, ABS_HAT0X, xpad_hat_to_axis[data[2] & 0x0f].x);
-	input_report_abs(dev, ABS_HAT0Y, xpad_hat_to_axis[data[2] & 0x0f].y);
+	input_report_abs(dev, ABS_HAT0X, !!(data[2] & 0x08) - !!(data[2] & 0x04));
+	input_report_abs(dev, ABS_HAT0Y, !!(data[2] & 0x02) - !!(data[2] & 0x01));
 	
 	/* start/back buttons and stick press left/right */
 	input_report_key(dev, BTN_START, (data[2] & 0x10) >> 4);
@@ -234,8 +220,10 @@ static void * xpad_probe(struct usb_device *udev, unsigned int ifnum, const stru
 	
 	ep_irq_in = udev->actconfig->interface[ifnum].altsetting[0].endpoint + 0;
 	
-	FILL_INT_URB(xpad->irq_in, udev, usb_rcvintpipe(udev, ep_irq_in->bEndpointAddress),
-	xpad->idata, XPAD_PKT_LEN, xpad_irq_in, xpad, ep_irq_in->bInterval);
+	FILL_INT_URB(xpad->irq_in, udev,
+		usb_rcvintpipe(udev, ep_irq_in->bEndpointAddress),
+		xpad->idata, XPAD_PKT_LEN, xpad_irq_in, xpad,
+		ep_irq_in->bInterval);
 	
 	xpad->udev = udev;
 	
@@ -267,19 +255,19 @@ static void * xpad_probe(struct usb_device *udev, unsigned int ifnum, const stru
 			case ABS_X:
 			case ABS_Y:
 			case ABS_RX:
-			case ABS_RY:
+			case ABS_RY:	/* the two sticks */
 				xpad->dev.absmax[t] =  32767;
 				xpad->dev.absmin[t] = -32768;
 				xpad->dev.absflat[t] = 128;
 				xpad->dev.absfuzz[t] = 16;
 				break;
 			case ABS_Z:
-			case ABS_RZ:
+			case ABS_RZ:	/* the triggers */
 				xpad->dev.absmax[t] = 255;
 				xpad->dev.absmin[t] = 0;
 				break;
 			case ABS_HAT0X:
-			case ABS_HAT0Y:
+			case ABS_HAT0Y:	/* the d-pad */
 				xpad->dev.absmax[t] =  1;
 				xpad->dev.absmin[t] = -1;
 				break;