TURN ON WORD WRAP /* Copyright 2003 Chris Cavey This file is part of XID. XID is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. XID is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with XID; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ Introduction XID or XBox Interface Driver allows a PC running Windows 2000/XP to communicate with an XBox Controller through an HID Minidriver. While the XBox controller is close to conforming to the HID specification, it does not export any form of report descriptors. Report descriptors are crucial as they tell the HID class driver how to handle the data streamed by the controller. In order for the XBox controller to work with a WinXp/2000 PC, the HID minidriver must create this report descriptor as well as parse the input data. This task in itself is easy; making a customizable driver that works with games no designed for the native platform (XBOX) of the controller is far from easy. I've spent months trying to ascertain the methods employed by other drivers to accomplish such tasks. In the end I've created and at very least laid plans that utilize a feature with in the HID spec itself to allow for simple custimization of the driver. Lastly, I ask that if any changes are made you submit a copy back to the original webpage. I will attempt to keep download links from all submissions. Not only that, but I'm curious where this project will go. I've lost interest in this project and I have many other things on plate these days, but I still want to see where XID will go. Requirements Requirements for Using Driver Windows XP/2000 Supported XBox Controller ( through vendor/product id ) Requirements for Building Driver Windows XP/2000 Windows 2000 DDK or Winddows XP DDK, XP DDK suggested. These are avaiable from Microsoft for little or no cost. Visual Studio 6.0/.NET with commandline compilation correctly installed Distribution Status Herein is a quite literal breakdown of what has been implemented thus far. -Basic Driver IOCTL KNOWN ISSUES: Problems with startup/shutdown, possibly in power IOCTLs. -HID IOCTL IOCTL_HID_GET_DEVICE_DESCRIPTOR IOCTL_HID_GET_REPORT_DESCRIPTOR IOCTL_HID_READ_REPORT IOCTL_HID_SET_OUTPUT_REPORT IOCTL_HID_GET_DEVICE_ATTRIBUTES IOCTL_HID_SET_FEATURE IOCTL_HID_GET_FEATURE -Dynamic HID Report Descriptors Rather than rely on a single HID report descriptor, I've created a system that can generate and properly parse report descriptors on the fly. On driver load, the system retrieves two important flags from the registry located at [HKEY_LOCAL_MACHINE\SOFTWARE\XID]. See the included xid.reg file for sample entries. Two DWORD regristry values, "genConfig" and "buttonConfig" are retrieved from the registry. If these keys are now present the driver will create failsafe deafults. The "buttonConfig" value determines the status of 16 possible buttons (this does not include axes/slides/pov). The field is a simple bit field with bits 0-1 configuring button 0, bits 2-3 for button 1, etc. In each pair of bits per button, if the least significant bit of the pair is set, the button will be digital. If the most significant bit of the pair is set the button will be analog. If neither bit is set, a button will no be created. Behavior is undefined is both bits are set. "genConfig" determines the status of the axes/sliders/pov. This 32-bit DWORD values is broken into bitfields. The #defines in xidreport.h preceded by an underscore define the flags. Ex. _X_FLAG. Using this information the driver generates a report descriptor fitting the flags from the registry while also retained the information needed to correctly fill and parse raw data. Currently, all controllers must share the same report descriptor ( it is possible to alert this by first plugging in a controller with a given report descriptior configuration, altering the registry values, and plugging in another controller. ) -Dynamic Control Mapping Rather than create a file based interface to read and write dynamic configuration data to the driver, I have implemented a solution within the HID standard using FEATURE reports. Small packets of data can be transfered between a user mode program and the driver using FEATURE reports. I implemented a simple protocol which the interface class wraps (see the XID API). This protocol provides for dynamically mapping a physical control to a virtual control defined by the HID report descriptor. The behavior of some mappings is undefined. Such as the entire POV->Button or Left Stick Axes->Button. Only mappings that make sense and were immediately easy were implemented. -Simple Rumble Using basic HID class functions included with Windows you can set output reports and therefore make the device rumble. The XID interface class has an example of how this is done. Suggested Approaches Here are a few possible customizations and suggestions as to the future of this driver. -Finish algorithm to map ALL controls to any other controls. -When mapping an stick into a button, define a rectangle in the 2d space of the button as the on/off zone of the button. If the button is analog, use the distance from a central point of this hotspot. -Allow for macro combo buttons -Allow for a simply postfix based stack to govern the button mapping, such as "(A + B) / 2". Average the physical A and B buttons and assign to virtual button -Support rumble through DirectX ( 8 and 9 ) -Harvest more vendor/product ID pairs for the INF file -Support the Steel Battiliion controller. -Allow multiple controllers to have distinct report descriptors Build Instructions You must have a DDK installed. Instantiate a DDK commandline using the shortcuts created by the DDK installer. Navigate to the directory containing the source of XID. Simply run "build" to create the driver. The "build" program is part of the DDK and is not some batch/make file. You may have to alter the path in the .inf file to correctly locate and .sys file output by the build process. XID API The setup of classes allows a usermode program to communicate with the driver. Most of the hard parts (controller enumeratation and device control) have been implemented. The code is straight forward and rather obvious. The main.cpp included in the project has simple examples. File Breakdown COPYING - GNU license file LICENSE - GNU license file MAKEFILE - oldhiddescriptor.txt - ... README.txt - this file resource.h - simply include for the resources in the driver Sources - list of all source files used, modify if you add files to the project xid.cpp, xid.h - main driver routines xid.inf - install file xid.rc - resources (version number, author, dates) xidbytestream.cpp, xidbytestream.h - simply class for a stream of bytes xidconfig.cpp, xidconfig.h - manages dynamic configuration data xidcontroller.cpp, xidcontroller.h - interprets physical data from the controller xidioctl.cpp, xidioctl.h - basic HID IOCTL xidreport.cpp, xidreport.h - governs report descriptor creation and report creation xidtypes.h - .... xidusb.cpp, xidusb.h - functions to access raw usb hardware xid.reg - basic registry entries for controller to work XIDAPI/ main.cpp - Example of XIDAPI usage TestUserMode2.sln - .NET solution TestUserMode2.vcproj - .NET prject XIDInterface.cpp, XIDInterface.h - XID inteface class |