USAGE_MAXIMUM in Report Descriptor

[Doug D.]

Jan,

I used the USB-IF's HID Descriptor Tool to generate a HID report descriptor for an input and output report.  My REPORT_COUNT for each report is 64 bytes. 

It was my understanding that each field (byte) in REPORT_COUNT must be associated with a USAGE number, so I attempted to enter a USAGE range from 1 to 64 into the Descriptor Tool.  The tool let me enter a USAGE_MINIMUM of "Vendor Usage 1", which generated a value of 0x01.  It then let me enter a USAGE_MAXIMUM of "Vendor Usage 2", which generated a value of 0x02.  This is how it parsed, without finding any errors:

USAGE_PAGE (Vendor Defined Page 1) 06 00 FF
USAGE (Vendor Usage 1) 09 01
COLLECTION (Application) A1 01
  LOGICAL_MINIMUM (0) 15 00
  LOGICAL_MAXIMUM (255) 26 FF 00
  REPORT_SIZE (8) 75 08
  REPORT_ID (1) 85 01
  REPORT_COUNT (64) 95 40
  USAGE_MINIMUM (Vendor Usage 1) 19 01
  USAGE_MAXIMUM (Vendor Usage 2) 29 02
  INPUT (Data,Var,Abs) 81 02
  REPORT_ID (2) 85 02
  REPORT_COUNT (64) 95 40
  USAGE_MINIMUM (Vendor Usage 1) 19 01
  USAGE_MAXIMUM (Vendor Usage 2) 29 02
  OUTPUT (Data,Var,Abs) 91 02
END_COLLECTION C0

Shouldn't this have given me USAGE errors?  I can manually change USAGE_MAXIMUM from 0x02 to 0x40 (64), but this descriptor only had 2 USAGEs for 64 fields, and I thought I needed 64 USAGE numbers for the 64 fields in each REPORT_ID.

[Jan Axelson]

From the HID class spec:

6.2.2.8

While Local items do not carry over to the next Main item, they may apply to
more than one control within a single item. For example, if an Input item
defining five controls is preceded by three Usage tags, the three usages would
be assigned sequentially to the first three controls, and the third usage would
also be assigned to the fourth and fifth controls. If an item has no controls
(Report Count = 0), the Local item tags apply to the Main item (usually a
collection item).

To assign unique usages to every control in a single Main item, simply specify
each Usage tag sequentially (or use Usage Minimum or Usage Maximum).

In other words, a Usage will apply to all Local items until you declare a new Usage or start a new Main item.

See the HID spec for definitions of Main and Local items.

[Doug D.]

I have read section 6.2.2 (Report Descriptor) of the HID 1.11 specification as well as Chapter 12 of your book (HID Reports), but I still need help in understanding USAGE.

Does this apply to multiple data fields (e.g. bytes), as well as control fields (e.g. keyboard buttons)?  All 64 of my REPORT_COUNT items will be interpreted by my host application as data bytes, not as controls.  I need a report descriptor for transferring my 64-byte reports into a buffer, where I can unpack them into a known data format of 8-bit and 32-bit data words.

I understand that "Local" items in a report descriptor (e.g. USAGE) modify the subsequent "Main" item in the descriptor (e.g. INPUT), but how many USAGEs do I need?  Can I really have the same USAGE number for all 64 of my REPORT_COUNT fields (bytes)?

If so, why would I need to declare the usage range "USAGE_MINIMUM" to "USAGE_MAXIMUM"?  Couldn't I just declare a single usage number (e.g. "USAGE (Vendor Usage 1)", i.e. 0x09 0x01) for all of my "Main" INPUT and OUTPUT fields?  Or, since this is a vendor-defined application, could I even declare "USAGE (Undefined)", i.e. 0x09 0x00?

If not, then that brings me back to my original question--how can I specify a USAGE_MAXIMUM for my 64 fields with the Descriptor Tool?

[Jan Axelson]

The purpose of Usages is to help the host decide how to use the report data. If the data is vendor-defined and your host application will know how to use it, go ahead and use the same Usage value for all of the data.

If you want to give each byte a unique Usage, you can use the MINIMUM and MAXIMUM items to define them all at once.

[Doug D.]

Thanks for explaining that Jan.  That section of the USB specification is sheer torture.  I can't believe how convoluted the design is, and how badly it was written--complete with grammatical errors in the worst possible places.  I'm sure developers have been suffering over it for 17 years now.

[Jan Axelson]

Agree!