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