HID USB FX2 Sample

- -

HIDUSBFX2

- -

Summary

- -

The -HIDUSBFX2 sample demonstrates how to write a HID minidriver by using the -Microsoft Windows Driver Foundation (WDF). The sample also demonstrates how to map -a non-HID USB device to a HID device. The minidriver is written for the OSR -USB-FX2 Learning Kit. This device is not HID-compliant and the sample exposes -the device as a HID device.

- -

Background -Information

- -

A -HID USB device provides a HID descriptor (through an interface descriptor) that -identifies the device as HID-compliant and enables the system-supplied HID -minidriver (hidusb.sys) and the HID class -driver to load, parse the HID descriptor, and enumerate child HID -device stacks. The system provides strong support for HID devices, so you do -not typically have to write a HID minidriver. However, there are cases in -which you might need to write your own HID minidriver (for example, if it is -difficult to make desired changes to HID-compliant device firmware or if you -need to make a non-HID compliant device a HID device without updating the -firmware).

- -

Overview -of the Device

- -

You -can view the specification for the device in the Using the OSR USB FX-2 Learning Kit document.

- -

The -device is loosely based on the development board that is supplied with the -Cypress EZ-USB FX2 Development Kit (CY3681) and contains one interface -and three endpoints (Interrupt IN, Bulk Out, and Bulk IN). The firmware supports -vendor commands to query or set the LED bar graph display, 7-segment LED -display, and query toggle switch states.

- -

The -interrupt endpoint sends an 8-bit value that represents the state of the -switches. This value is sent on startup, resume from suspend, and whenever the -switch pack setting changes. The firmware does not de-bounce the switch pack. -One switch change can cause multiple bytes to be sent. The bits are in the -reverse order of the labels on the pack (for example, bit 0x80 is labeled -1 on the pack). Bulk endpoints are configured for loopback.

- -

Overview of the -Driver Stack

- - - -

Kernel-Mode -Driver Framework (KMDF) does not support HID minidrivers natively because -the HID architecture requires that the HID class driver (hidclass.sys) own the driver dispatch table for -HID minidrivers. This requirement conflicts with KMDF’s -requirement that it own the driver dispatch table in order to handle -Plug and Play (PnP), power, and I/O requests correctly.

- -

You -can resolve this ownership conflict by using a driver stack that consists of a -minimal WDM driver (also called a shim driver) as function driver and a -complete KMDF driver as lower filter driver. The shim driver registers with the -HID class (so hidclass.sys owns its dispatch -table) and forwards all of the requests to the lower filter driver. The -lower filter driver (KMDF owns the dispatch table) processes all of the -requests.

- -

The -WDK provides code for both of the drivers. The shim driver code is located -in the src\hid\hidmapper\kmdf folder (the driver binary is named hidkmdf.sys), and the lower filter driver code is -located in the src\hid\hidusbfx2\sys folder (the binary is named hidusbfx2.sys). The shim driver is a minimal WDM driver -and you can reuse it without any modification. Remember to rename the -shim driver binary when you reuse it, to avoid a name conflict. Also, note that -shim driver is an inbox driver on Windows 7 and later operating systems (mshidkmdf.sys). INF file for this sample contains a -specific section that allows using the inbox shim driver on Windows 7 and later -OS.

- -

Mapping -non-HID USB device to HID

- -

When the -HID class driver queries the minidriver, the minidriver returns a hard-coded -report descriptor that enables the HID class driver to create child -devices as described by the report descriptor. The report descriptor -has three top-level application collections:

- -

Consumer Control
System Control
Vendor-defined

- -

The -HID class driver creates a driver stack for each top-level collection. The operating -system opens the Consumer Control and System Control collections. These -collections have input buttons and obtain data from the interrupt endpoint of -the USB device. The vendor-defined collection exposes a feature button to -control the 7-segment display and bar graph display. Any client application can -open the vendor-defined collection to send feature requests.

- -

Switch -Pack Mapping

- -

The -switch pack on the USB device is mapped as hot keys that are commonly found on -modern keyboards. This mapping is possible by exposing the switch pack as -two system-supported collections: Consumer Control and System Control. The -Consumer Control collection provides a mapping for some application-launch and -application-action keys, as shown in the following table. The System -Control collection provides a mapping for the power sleep function.

- -

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

- Switch -	- 1 -	- 2 -	- 3 -	- 4 -	- 5 -	- 6 -	- 7 -	- 8 -
- Mapping -	- Sleep -	- Calculator -	- Mail -	- Favorites -	- Refresh -	- Forward -	- Back -	- Browser -

- -

Segment -Display and Bar Graph Mapping

- -

Segment -display and Bar Graph are mapped as HID feature controls that can be -manipulated by using HidD_SetFeature() api from a user mode application. The -feature controls are mapped as Vendor-defined Usage Page 0xff00 with Usage ID -from 1 to 18. Hidclient.exe, a GUI application available in WDK, can also be -used to do this. See following sections for more information.

- -

The -segment display and bar graph are mapped as HID feature controls that you -can manipulate by using the HidD_SetFeature function from a user-mode -application. The feature controls are mapped as vendor-defined usage page -0xff00 with a usage ID from 1-18. You can also use Hidclient.exe, an application that is available in the -WDK, to manipulate the segment display and bar graph. For more -information about this mapping, see the following two tables.

- -

Segment Display -Mapping

- -

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

- Usage - ID -	- 1 -	- 2 -	- 3 -	- 4 -	- 5 -	- 6 -	- 7 -	- 8 -
- Mapping -	- Display 1 -	- Display 2 -	- Display 3 -	- Display 4 -	- Display 5 -	- Display 6 -	- Display 7 -	- Display 8 -

- -

Bar Graph Mapping

- -

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

Usage - ID

Mapping

LED 1 ON

LED 2

LED 3

LED 4

LED 5

LED 6

LED 7

LED 8

All LEDS ON

All LEDS OFF

- -

Support -for Selective Suspend

- -

The -HID class driver provides support for selective suspend. The minidriver -participates in this feature by handling HID class IOCTLs appropriately. To -enable the selective suspend feature for your device, you need to add a -“SelectiveSuspend” = 1 value in the registry in the device hardware key through -the INF file. For an example, see the hidusbfx2.inf file.

- -

Installing -the Sample

- -

If -you adapt this driver for your device, update the INF file to match the hardware -ID (VID, PID) and the device description text to match your test board/device.

- -

To -start installing the sample, you must:

- -

Build the driver and copy the - following files to a folder on your hard drive:

hidusbfx2.inf -
Hidusbfx2.sys -
Hidkmdf.sys - (build <WDK ROOT>/src/hid/hidmapper/kmdf folder for this)
The WDF - coinstaller from the <WDK - ROOT>\redist\wdf\<platform> folder.

Plug in the device and do the - following, depending on the operating system that you are using:

On Windows 7 - and later operating systems:

Launch Device Manager by executing - command devmgmt.msc in a command window, or from Hardware and Sound program - group in Control Panel.
Select OSR - USB-FX2 device from Other Devices category - and click Update - Driver Software… from right-click - menu.
Select Browse my computer for software and provide the location - of the driver files.
Select Install this driver software - anyway when the Windows - Security dialog box appears.
After the - driver is installed, you should see the device in Device Manager under - "Human Interface Devices".

On Windows - Vista and Windows Server 2008:

In the Found New Hardware dialog - box, select Locate - and install driver software (recommended).
Select Don't search online. -
Select I don't have the disc. Show - me other options.
Select Browse my computer for driver - software (advanced).
Enter the - location of the driver files, and select Install this driver software anyway when - the Windows - Security dialog box appears. After the driver is - installed, you should see the device in Device Manager under "Human - Interface Devices".

On Windows - Server 2003 and Windows XP:

In the Found New Hardware Wizard dialog - box, select Install - from a list of specific location (Advanced).
Select Search the best driver in - these locations, select Include this location in the search path, - and then specify the target media or the directory where the INF and SYS - files are copied. The system will scan the directory and pick up the - matching INF file and start the installation.
When you - receive a Hardware - Installation Warning dialog box that states that your - driver has not passed Windows Logo Testing, click Continue Anyway. - The system will copy the driver and INF file, load the driver, and start - the device.
When you see - the Completing the - Found New Hardware Wizard page, click Finish. The - installation is complete. You should be able to see the device in Device - Manager under "Human Interface Devices".

On Windows - 2000:

In the Found New Hardware Wizard - dialog box, click Next. -
Select Display a list of known - drivers for this device, and then click Next.
Select Other Devices, - and then click Next. -
Click Have Disk, - specify the target media or the directory where the INF and SYS files - are copied, and then click Okay. -
In the Manufacturer section, - select Vendor - Name, and the click Next.
Click Next, and - then click Finish - in the Completing - the Add/Remove Hardware Wizard page.

- -

Testing

- -

Testing Switches

- -

Toggle switch number 8 on the device - board to the on position (toggle down) to open a Web browser.
Toggle switch number 2 on the device - board to the on position (toggle down) to start the calculator - application.

- -

Testing Bar Graph -and 7-Segment Display

- -

Start the hidclient.exe GUI application from the WDK. - The application source code is located in the <WDK Root>\src\hid\hclient folder, and - you need to build it by using the appropriate build environment.
From the HID Device to examine menu, select - the device that contains “UsagePage 0ff00, Usage 01” as a substring.
Click Modify Features. The Feature Data dialog box opens.
Click Modify Features. The Modify features dialog box opens.
In the input box, type 7 and click Send to Device. You should see number 7 - appear in the 7-segment display.
Type any number from 1-8, and you will - see the respective number displayed in the 7-segment display.
Type any number from (and - including) 9-17, and you will see one of the LEDs on the bar graph turn - on. For mapping information, see the earlier table.

- -

Report -Descriptor

- -

-// Consumer control collection

- -

-0x05,0x0C, -// USAGE_PAGE (Consumer Page)

- -

-0x09,0x01, -// USAGE (Consumer Control Usage 0x01)

- -

-0xA1,0x01, -// COLLECTION (Application)

- -

-0x85,0x01, -// REPORT_ID

- -

-0x0A, 0x23, 0x02, // USAGE (Usage Browser)

- -

-0x0A, 0x24, 0x02, // USAGE (Usage AC Back)

- -

-0x0A, 0x25, 0x02, // USAGE (Usage AC Forward)

- -

-0x0A, 0x27, 0x02, // USAGE (Usage AC Refresh)

- -

-0x0A, 0x2A, 0x02, // USAGE (Usage AC BookMarks)

- -

-0x0A, 0x8A, 0x01, // USAGE (Usage AL Mail)

- -

-0x0A, 0x92, 0x01, // USAGE (Usage AL Calculator )

- -

-0x15, 0x00, -// LOGICAL_MINIMUM(0)

- -

-0x25, 0x01, -// LOGICAL_MAXIMUM(1)

- -

-0x75, 0x01, -// REPORT_SIZE

- -

-0x95, 0x07, -// REPORT_COUNT

- -

-0x81, 0x02, -// INPUT (Data, Variable,Abs)

- -

-0x75, 0x01, -// REPORT_SIZE

- -

-0x95, 0x01, -// REPORT_COUNT

- -

-0x81, 0x07, -// INPUT (const)

- -

-0xC0, -// END_COLLECTION

- -

-// system control collection

- -

-0x05, 0x01, - // Usage Page (Generic Desktop)

- -

-0x09, 0x80, - // Usage (System Control)

- -

-0xA1, 0x01, // -Collection (Application)

- -

-0x85, 0x02, - // Report ID

- -

-0x95, 0x07, - // Report Count

- -

-0x81, 0x07, - // Input (Constant)

- -

-0x09, 0x82, - // Usage (System Sleep)

- -

-0x95, 0x01, - // Report Count (2)

- -

-0x81, 0x06, -// Input (Data, Variable, Relative, Preferred)

- -

-0xC0, -// End Collection

- -

-// Feature collection

- -

-0x06,0x00, 0xFF, // USAGE_PAGE (Vender Defined Usage Page)

- -

-0x09,0x01, // -USAGE (Vendor Usage 0x01)

- -

-0xA1,0x01, // -COLLECTION (Application)

- -

-0x85,0x03, // -Report ID

- -

-0x19,0x01, - // USAGE MINIMUM

- -

-0x29,0x20, - // USAGE MAXIMUM

- -

-0x15,0x00, - // LOGICAL_MINIMUM(1)

- -

-0x26,0xff, 0x00, // LOGICAL_MAXIMUM(255)

- -

-0x75,0x08, - // REPORT_SIZE

- -

-0x95,0x01, - // REPORT_COUNT

- -

-0xB1,0x00, - // Feature (Data,Ary,Abs)

- -

-0xC0 -// END_COLLECTION

- -

CODE -TOUR

- -

This section includes a file manifest of all the files -in the src\hid\hidusbfx2 directory and src\hid\hidmapper\kmdf directory..

- -

File Manifest

- -

src\hid\hidmapper\kmdf

- -

Files Description

- -

hidkmdf.c Contains code for -driver entry and dispatch.

- -

Sources WDK sources file.

- -

Makefile WDK build environment -makefile.

- -

hidkmdf.rc Resource file for -the driver.

- -

src\hid\hidusbfx2\sys

- -

Files Description

- -

Driver.c Contains code for driver entry and -dispatch functions.

- -

hid.c Contains code for handling HID -ioctls.

- -

usb.c Contains code for communicating -with USB stack.

- -

Trace.h Contains trace related definitions.

- -

Hidusbfx2.h Contains type definitions and function -declarations

- -

Hidusbfx2.rc Resource file for the driver.

- -

Hidusbfx2.inx INX file for the driver.

- -

Sources WDK sources file.

- -

Makefile WDK build environment make file.

- -

Makefile.inc A makefile that defines custom build -actions. This includes the conversion of the .INX file into a .INF file.

- -