HID - Human Interface Device

Collaboration diagram for HID - Human Interface Device:

Files
file	hid.h
	USB HID (Human Interface Device) device class, HID 1.11.

Data Structures
struct	hid_iface
	One generic HID interface: a single instance of the class on a device. More...
struct	usb_hid_descriptor
	The 9-byte HID descriptor that points at the Report descriptor (Sec.6.2.1). More...
struct	hid_opts
	Per-instance configuration for a generic HID interface. More...

Macros
#define	HID_REPORT_INPUT
	Report types (high byte of wValue in Get/Set_Report), HID 1.11 Sec.7.2.1.
#define	HID_REPORT_OUTPUT
	Output report (host -> device)
#define	HID_REPORT_FEATURE
	Feature report (either direction, control only)
#define	HID_SUBCLASS_NONE
	hid_opts::subclass - bInterfaceSubClass, HID 1.11 Sec.4.2.
#define	HID_SUBCLASS_BOOT
	Boot interface: the fixed report layout a BIOS parses.
#define	HID_PROTOCOL_NONE
	hid_opts::protocol - bInterfaceProtocol, HID 1.11 Sec.4.3.
#define	HID_PROTOCOL_KEYBOARD
	Boot keyboard: 8-byte Input report.
#define	HID_PROTOCOL_MOUSE
	Boot mouse: 3-byte Input report.
#define	HID_BOOT_PROTOCOL
	hid_iface::protocol - Get/Set_Protocol values, HID 1.11 Sec.7.2.5.
#define	HID_REPORT_PROTOCOL
	Host wants the Report descriptor's layout (default)

Functions
hid_iface *	hid_add (usbip_device *dev, const hid_opts *opts)
	Add a generic HID interface to a device.
int	hid_send_report (hid_iface *iface, const void *data, int len)
	Send one Input report to the host on the interrupt-IN pipe (device -> host).

Variables
const usbip_device_class	usbip_device_hid
	The HID class, for usbip_device_add_class()

Report-descriptor item helpers (HID 1.11 Sec.6.2.2 short items)
Each macro expands to one short item (prefix byte + data byte(s)), so a Report descriptor reads like the spec when written as a static const uint8_t[]: static const uint8_t mouse[] = { HID_USAGE_PAGE(0x01), HID_USAGE(0x02), HID_COLLECTION(0x01), ... HID_END_COLLECTION }; The three item classes behave differently, and mixing them up is the usual reason a descriptor parses but describes the wrong device: Global (Usage Page, Logical Min/Max, Report Size/Count/ID) stays in force for every item that follows, until changed again. Local (Usage, Usage Min/Max) applies only to the next Main item, then is discarded. Main (Input, Output, Feature, Collection) is what actually declares fields in a report, out of the Global and Local state standing at that point.
#define	HID_USAGE_PAGE(x)
	Global: Usage Page in force for the Usages that follow - 1-byte page id, e.g.
#define	HID_USAGE_PAGE16(x)
	Global: HID_USAGE_PAGE with a 2-byte page id, for pages above 0xFF - notably the vendor-defined 0xFF00..0xFFFF range used by raw devices.
#define	HID_USAGE(x)
	Local: Usage for the next Main item, within the current Usage Page - e.g.
#define	HID_USAGE_MIN(x)
	Local: first Usage of a consecutive run applied to the next Main item.
#define	HID_USAGE_MAX(x)
	Local: last Usage of that run - HID_USAGE_MIN(0xE0), HID_USAGE_MAX(0xE7) hands the eight keyboard modifier Usages to the eight fields of the next Main item, in order.
#define	HID_LOGICAL_MIN(x)
	Global: smallest value a field may report, as one signed byte (-128..127).
#define	HID_LOGICAL_MAX(x)
	Global: largest value a field may report, as one signed byte - so it tops out at.
#define	HID_LOGICAL_MAX16(x)
	Global: HID_LOGICAL_MAX with 2 little-endian data bytes, for ranges a signed byte cannot hold - HID_LOGICAL_MAX16(255) for a byte-wide raw field, or a digitiser's absolute coordinate range.
#define	HID_REPORT_SIZE(x)
	Global: width of one field, in bits (not bytes).
#define	HID_REPORT_COUNT(x)
	Global: how many fields of that width the next Main item declares.
#define	HID_REPORT_ID(x)
	Global: start a numbered report.
#define	HID_COLLECTION(x)
	Main: open a collection - 0x00 Physical, 0x01 Application, 0x02 Logical (Sec.6.2.2.6).
#define	HID_END_COLLECTION
	Main: close the innermost open collection.
#define	HID_INPUT(x)
	Main: declare device -> host fields, sent on the interrupt IN pipe.
#define	HID_OUTPUT(x)
	Main: declare host -> device fields, taken from the interrupt OUT pipe or a SET_REPORT(Output) - keyboard LEDs are the classic case.
#define	HID_FEATURE(x)
	Main: declare fields the host reads and writes over EP0 only, with GET_REPORT/SET_REPORT(Feature) - configuration and state rather than live data.

Detailed Description

Macro Definition Documentation

HID_REPORT_INPUT

#define HID_REPORT_INPUT

Report types (high byte of wValue in Get/Set_Report), HID 1.11 Sec.7.2.1.

Input report (device -> host)

HID_REPORT_OUTPUT

#define HID_REPORT_OUTPUT

Output report (host -> device)

HID_REPORT_FEATURE

#define HID_REPORT_FEATURE

Feature report (either direction, control only)

HID_SUBCLASS_NONE

#define HID_SUBCLASS_NONE

hid_opts::subclass - bInterfaceSubClass, HID 1.11 Sec.4.2.

No subclass: a plain HID interface

HID_SUBCLASS_BOOT

#define HID_SUBCLASS_BOOT

Boot interface: the fixed report layout a BIOS parses.

HID_PROTOCOL_NONE

#define HID_PROTOCOL_NONE

hid_opts::protocol - bInterfaceProtocol, HID 1.11 Sec.4.3.

Only meaningful with HID_SUBCLASS_BOOT; a report-protocol-only interface leaves it HID_PROTOCOL_NONE. Neither of the two boot devices

HID_PROTOCOL_KEYBOARD

#define HID_PROTOCOL_KEYBOARD

Boot keyboard: 8-byte Input report.

HID_PROTOCOL_MOUSE

#define HID_PROTOCOL_MOUSE

Boot mouse: 3-byte Input report.

HID_BOOT_PROTOCOL

#define HID_BOOT_PROTOCOL

hid_iface::protocol - Get/Set_Protocol values, HID 1.11 Sec.7.2.5.

Which report layout the host has selected, distinct from the bInterfaceProtocol above. Host wants the boot layout

HID_REPORT_PROTOCOL

#define HID_REPORT_PROTOCOL

Host wants the Report descriptor's layout (default)

HID_USAGE_PAGE

#define HID_USAGE_PAGE

(

x

)

Global: Usage Page in force for the Usages that follow - 1-byte page id, e.g.

0x01 Generic Desktop, 0x07 Keyboard/Keypad, 0x08 LED, 0x0C Consumer (Sec.6.2.2.7).

HID_USAGE_PAGE16

#define HID_USAGE_PAGE16

(

x

)

Global: HID_USAGE_PAGE with a 2-byte page id, for pages above 0xFF - notably the vendor-defined 0xFF00..0xFFFF range used by raw devices.

HID_USAGE

#define HID_USAGE

(

x

)

Local: Usage for the next Main item, within the current Usage Page - e.g.

0x02 Mouse, 0x06 Keyboard, 0x30 X, 0x31 Y (Sec.6.2.2.8).

HID_USAGE_MIN

#define HID_USAGE_MIN

(

x

)

Local: first Usage of a consecutive run applied to the next Main item.

Pairs with HID_USAGE_MAX.

HID_USAGE_MAX

#define HID_USAGE_MAX

(

x

)

Local: last Usage of that run - HID_USAGE_MIN(0xE0), HID_USAGE_MAX(0xE7) hands the eight keyboard modifier Usages to the eight fields of the next Main item, in order.

HID_LOGICAL_MIN

#define HID_LOGICAL_MIN

(

x

)

Global: smallest value a field may report, as one signed byte (-128..127).

Sets how the host scales and interprets the raw bits (Sec.6.2.2.7).

HID_LOGICAL_MAX

#define HID_LOGICAL_MAX

(

x

)

Global: largest value a field may report, as one signed byte - so it tops out at.

1. Use HID_LOGICAL_MAX16 for anything above that.

HID_LOGICAL_MAX16

#define HID_LOGICAL_MAX16

(

x

)

Global: HID_LOGICAL_MAX with 2 little-endian data bytes, for ranges a signed byte cannot hold - HID_LOGICAL_MAX16(255) for a byte-wide raw field, or a digitiser's absolute coordinate range.

HID_REPORT_SIZE

#define HID_REPORT_SIZE

(

x

)

Global: width of one field, in bits (not bytes).

HID_REPORT_COUNT

#define HID_REPORT_COUNT

(

x

)

Global: how many fields of that width the next Main item declares.

Size x Count is the item's total bit width; a report must end on a byte boundary, so pad the remainder with a constant HID_INPUT(0x01).

HID_REPORT_ID

#define HID_REPORT_ID

(

x

)

Global: start a numbered report.

From here on every report on this interface carries this 1-byte ID as its first byte, in both directions and on EP0 as well - so hid_send_report() must send it too. Omit the item entirely when the interface has a single report.

HID_COLLECTION

#define HID_COLLECTION

(

x

)

Main: open a collection - 0x00 Physical, 0x01 Application, 0x02 Logical (Sec.6.2.2.6).

Close it with HID_END_COLLECTION. Each top-level thing the device is must be an Application collection.

HID_END_COLLECTION

#define HID_END_COLLECTION

Main: close the innermost open collection.

The one item here that takes no data.

HID_INPUT

#define HID_INPUT

(

x

)

Main: declare device -> host fields, sent on the interrupt IN pipe.

x is the data bitmap of Sec.6.2.2.5 - 0x02 Data,Variable,Absolute (buttons, LEDs, levels), 0x06 Data,Variable,Relative (mouse deltas), 0x00 Data,Array,Absolute (keycode slots), 0x01 Constant (padding to a byte boundary).

HID_OUTPUT

#define HID_OUTPUT

(

x

)

Main: declare host -> device fields, taken from the interrupt OUT pipe or a SET_REPORT(Output) - keyboard LEDs are the classic case.

Same x bitmap as HID_INPUT.

HID_FEATURE

#define HID_FEATURE

(

x

)

Main: declare fields the host reads and writes over EP0 only, with GET_REPORT/SET_REPORT(Feature) - configuration and state rather than live data.

Same x bitmap as HID_INPUT.

Function Documentation

hid_add()

hid_iface * hid_add	(	usbip_device *	dev,
		const hid_opts *	opts
	)

Add a generic HID interface to a device.

Parameters

dev	the device.
opts	HID configuration - Report descriptor, endpoints and callbacks (see hid_opts).

Returns

the HID handle (pass it to hid_send_report()), or NULL on error.

hid_send_report()

int hid_send_report	(	hid_iface *	iface,
		const void *	data,
		int	len
	)

Send one Input report to the host on the interrupt-IN pipe (device -> host).

The report is also cached as the value returned for a host GET_REPORT(Input).

Parameters

iface	the HID interface from hid_add().
data	the report bytes.
len	report length in bytes.

Returns

bytes sent (>= 0), or a negative USB_ERROR code.

Variable Documentation

usbip_device_hid

const usbip_device_class usbip_device_hid

extern

The HID class, for usbip_device_add_class()