1*4882a593Smuzhiyun================================================================ 2*4882a593SmuzhiyunHIDRAW - Raw Access to USB and Bluetooth Human Interface Devices 3*4882a593Smuzhiyun================================================================ 4*4882a593Smuzhiyun 5*4882a593SmuzhiyunThe hidraw driver provides a raw interface to USB and Bluetooth Human 6*4882a593SmuzhiyunInterface Devices (HIDs). It differs from hiddev in that reports sent and 7*4882a593Smuzhiyunreceived are not parsed by the HID parser, but are sent to and received from 8*4882a593Smuzhiyunthe device unmodified. 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunHidraw should be used if the userspace application knows exactly how to 11*4882a593Smuzhiyuncommunicate with the hardware device, and is able to construct the HID 12*4882a593Smuzhiyunreports manually. This is often the case when making userspace drivers for 13*4882a593Smuzhiyuncustom HID devices. 14*4882a593Smuzhiyun 15*4882a593SmuzhiyunHidraw is also useful for communicating with non-conformant HID devices 16*4882a593Smuzhiyunwhich send and receive data in a way that is inconsistent with their report 17*4882a593Smuzhiyundescriptors. Because hiddev parses reports which are sent and received 18*4882a593Smuzhiyunthrough it, checking them against the device's report descriptor, such 19*4882a593Smuzhiyuncommunication with these non-conformant devices is impossible using hiddev. 20*4882a593SmuzhiyunHidraw is the only alternative, short of writing a custom kernel driver, for 21*4882a593Smuzhiyunthese non-conformant devices. 22*4882a593Smuzhiyun 23*4882a593SmuzhiyunA benefit of hidraw is that its use by userspace applications is independent 24*4882a593Smuzhiyunof the underlying hardware type. Currently, Hidraw is implemented for USB 25*4882a593Smuzhiyunand Bluetooth. In the future, as new hardware bus types are developed which 26*4882a593Smuzhiyunuse the HID specification, hidraw will be expanded to add support for these 27*4882a593Smuzhiyunnew bus types. 28*4882a593Smuzhiyun 29*4882a593SmuzhiyunHidraw uses a dynamic major number, meaning that udev should be relied on to 30*4882a593Smuzhiyuncreate hidraw device nodes. Udev will typically create the device nodes 31*4882a593Smuzhiyundirectly under /dev (eg: /dev/hidraw0). As this location is distribution- 32*4882a593Smuzhiyunand udev rule-dependent, applications should use libudev to locate hidraw 33*4882a593Smuzhiyundevices attached to the system. There is a tutorial on libudev with a 34*4882a593Smuzhiyunworking example at: 35*4882a593Smuzhiyun 36*4882a593Smuzhiyun http://www.signal11.us/oss/udev/ 37*4882a593Smuzhiyun 38*4882a593SmuzhiyunThe HIDRAW API 39*4882a593Smuzhiyun--------------- 40*4882a593Smuzhiyun 41*4882a593Smuzhiyunread() 42*4882a593Smuzhiyun------- 43*4882a593Smuzhiyunread() will read a queued report received from the HID device. On USB 44*4882a593Smuzhiyundevices, the reports read using read() are the reports sent from the device 45*4882a593Smuzhiyunon the INTERRUPT IN endpoint. By default, read() will block until there is 46*4882a593Smuzhiyuna report available to be read. read() can be made non-blocking, by passing 47*4882a593Smuzhiyunthe O_NONBLOCK flag to open(), or by setting the O_NONBLOCK flag using 48*4882a593Smuzhiyunfcntl(). 49*4882a593Smuzhiyun 50*4882a593SmuzhiyunOn a device which uses numbered reports, the first byte of the returned data 51*4882a593Smuzhiyunwill be the report number; the report data follows, beginning in the second 52*4882a593Smuzhiyunbyte. For devices which do not use numbered reports, the report data 53*4882a593Smuzhiyunwill begin at the first byte. 54*4882a593Smuzhiyun 55*4882a593Smuzhiyunwrite() 56*4882a593Smuzhiyun------- 57*4882a593SmuzhiyunThe write() function will write a report to the device. For USB devices, if 58*4882a593Smuzhiyunthe device has an INTERRUPT OUT endpoint, the report will be sent on that 59*4882a593Smuzhiyunendpoint. If it does not, the report will be sent over the control endpoint, 60*4882a593Smuzhiyunusing a SET_REPORT transfer. 61*4882a593Smuzhiyun 62*4882a593SmuzhiyunThe first byte of the buffer passed to write() should be set to the report 63*4882a593Smuzhiyunnumber. If the device does not use numbered reports, the first byte should 64*4882a593Smuzhiyunbe set to 0. The report data itself should begin at the second byte. 65*4882a593Smuzhiyun 66*4882a593Smuzhiyunioctl() 67*4882a593Smuzhiyun------- 68*4882a593SmuzhiyunHidraw supports the following ioctls: 69*4882a593Smuzhiyun 70*4882a593SmuzhiyunHIDIOCGRDESCSIZE: 71*4882a593Smuzhiyun Get Report Descriptor Size 72*4882a593Smuzhiyun 73*4882a593SmuzhiyunThis ioctl will get the size of the device's report descriptor. 74*4882a593Smuzhiyun 75*4882a593SmuzhiyunHIDIOCGRDESC: 76*4882a593Smuzhiyun Get Report Descriptor 77*4882a593Smuzhiyun 78*4882a593SmuzhiyunThis ioctl returns the device's report descriptor using a 79*4882a593Smuzhiyunhidraw_report_descriptor struct. Make sure to set the size field of the 80*4882a593Smuzhiyunhidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE. 81*4882a593Smuzhiyun 82*4882a593SmuzhiyunHIDIOCGRAWINFO: 83*4882a593Smuzhiyun Get Raw Info 84*4882a593Smuzhiyun 85*4882a593SmuzhiyunThis ioctl will return a hidraw_devinfo struct containing the bus type, the 86*4882a593Smuzhiyunvendor ID (VID), and product ID (PID) of the device. The bus type can be one 87*4882a593Smuzhiyunof:: 88*4882a593Smuzhiyun 89*4882a593Smuzhiyun - BUS_USB 90*4882a593Smuzhiyun - BUS_HIL 91*4882a593Smuzhiyun - BUS_BLUETOOTH 92*4882a593Smuzhiyun - BUS_VIRTUAL 93*4882a593Smuzhiyun 94*4882a593Smuzhiyunwhich are defined in uapi/linux/input.h. 95*4882a593Smuzhiyun 96*4882a593SmuzhiyunHIDIOCGRAWNAME(len): 97*4882a593Smuzhiyun Get Raw Name 98*4882a593Smuzhiyun 99*4882a593SmuzhiyunThis ioctl returns a string containing the vendor and product strings of 100*4882a593Smuzhiyunthe device. The returned string is Unicode, UTF-8 encoded. 101*4882a593Smuzhiyun 102*4882a593SmuzhiyunHIDIOCGRAWPHYS(len): 103*4882a593Smuzhiyun Get Physical Address 104*4882a593Smuzhiyun 105*4882a593SmuzhiyunThis ioctl returns a string representing the physical address of the device. 106*4882a593SmuzhiyunFor USB devices, the string contains the physical path to the device (the 107*4882a593SmuzhiyunUSB controller, hubs, ports, etc). For Bluetooth devices, the string 108*4882a593Smuzhiyuncontains the hardware (MAC) address of the device. 109*4882a593Smuzhiyun 110*4882a593SmuzhiyunHIDIOCSFEATURE(len): 111*4882a593Smuzhiyun Send a Feature Report 112*4882a593Smuzhiyun 113*4882a593SmuzhiyunThis ioctl will send a feature report to the device. Per the HID 114*4882a593Smuzhiyunspecification, feature reports are always sent using the control endpoint. 115*4882a593SmuzhiyunSet the first byte of the supplied buffer to the report number. For devices 116*4882a593Smuzhiyunwhich do not use numbered reports, set the first byte to 0. The report data 117*4882a593Smuzhiyunbegins in the second byte. Make sure to set len accordingly, to one more 118*4882a593Smuzhiyunthan the length of the report (to account for the report number). 119*4882a593Smuzhiyun 120*4882a593SmuzhiyunHIDIOCGFEATURE(len): 121*4882a593Smuzhiyun Get a Feature Report 122*4882a593Smuzhiyun 123*4882a593SmuzhiyunThis ioctl will request a feature report from the device using the control 124*4882a593Smuzhiyunendpoint. The first byte of the supplied buffer should be set to the report 125*4882a593Smuzhiyunnumber of the requested report. For devices which do not use numbered 126*4882a593Smuzhiyunreports, set the first byte to 0. The report will be returned starting at 127*4882a593Smuzhiyunthe first byte of the buffer (ie: the report number is not returned). 128*4882a593Smuzhiyun 129*4882a593SmuzhiyunExample 130*4882a593Smuzhiyun------- 131*4882a593SmuzhiyunIn samples/, find hid-example.c, which shows examples of read(), write(), 132*4882a593Smuzhiyunand all the ioctls for hidraw. The code may be used by anyone for any 133*4882a593Smuzhiyunpurpose, and can serve as a starting point for developing applications using 134*4882a593Smuzhiyunhidraw. 135*4882a593Smuzhiyun 136*4882a593SmuzhiyunDocument by: 137*4882a593Smuzhiyun 138*4882a593Smuzhiyun Alan Ott <alan@signal11.us>, Signal 11 Software 139