does the HID report descriptor matter?

[nerdralph]

I've looked at the firmware for a few different CMSIS-DAP probes, and noticed they aren't all the same. I couldn't find anything in the CMSIS-DAP v1 spec regarding HID report descriptor requirements, so I looked at what pyOCD requires. It looks like the report descriptor doesn't get parsed by pyOCD. It just seems to use the DAP packet format, up to the size of the endpoint.
https://github.com/pyocd/pyOCD/blob/7dccf5c5da825d36cb947a7b06c17f6a56852189/pyocd/probe/pydapaccess/interface/pyusb_backend.py

So is there anything actually required in the HID report descriptor for CMSIS-DAP v1?
Here's the report I've been using:

0x06, 0x00, 0xFF,  // Usage Page (Vendor Defined 0xFF00)
0x09, 0x01,        // Usage (0x01)
0xA1, 0x01,        // Collection (Application)
0x19, 0x01,        //   Usage Minimum (0x01)
0x29, 0x40,        //   Usage Maximum (0x40)
0x15, 0x00,        //   Logical Minimum (0)
0x26, 0xFF, 0x00,  //   Logical Maximum (255)
0x75, 0x08,        //   Report Size (8)
0x95, 0x40,        //   Report Count (64)
0x81, 0x00,        //   Input (Data,Array,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x19, 0x01,        //   Usage Minimum (0x01)
0x29, 0x40,        //   Usage Maximum (0x40)
0x91, 0x00,        //   Output (Data,Array,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
0xC0,              // End Collection
// 29 bytes

[nerdralph]

Through targeted trial and error, I've got a simplified report descriptor working:

0x06, 0x00, 0xFF,  // Usage Page (Vendor Defined 0xFF00)
0x09, 0x01,        // Usage (0x01)
0xA1, 0x01,        // Collection (Application)
0x15, 0x00,        //   Logical Minimum (0)
0x25, 0x40,        //   Logical Maximum (64)
0x75, 0x08,        //   Report Size (8)
0x95, 0x40,        //   Report Count (64)
0x81, 0x01,        //   Input (Const,Array,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x91, 0x01,        //   Output (Const,Array,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
0xC0,              // End Collection

It only works with the input and output as const (0x01). When it's just data (0x00), pyocd list doesn't find any adapters. FWIW, I've got hidapi 49.2.1 installed.

[flit]

The Logical Maximum needs to be 255. That, combined with Report Size, creates report that is a standard 8-bit byte. (With max at 64, you are saying it's every 8 bits of report data has only 6 bits of value.) Report Count then sets the number of bytes. There is probably minimal checking of report constraints in hidapi and the OS HID API, so I'm not surprised it works.

[flit]

PyOCD doesn't itself parse the HID report descriptor, but kernel HID drivers will, and hidapi and pywinusb backends rely on the OS HID support and therefore the parsed reports. For instance, if you tried to send an OUT report packet with hidapi for a device whose HID report descriptors only define IN reports, it will not work.

It will work on Linux with no HID reports defined, because on that OS pyocd just uses libusb (via pyusb) to directly access the device. On macOS and Windows the report descriptors matter, because you cannot detach the kernel HID driver.

[flit]

Fyi, I've taken a note to try to get a formal requirement for HID descriptors added to the CMSIS docs. (Though the CMSIS team generally feels the CMSIS-DAPv1 HID interface is legacy and should not be used anymore.)

[nerdralph]

Fyi, I've taken a note to try to get a formal requirement for HID descriptors added to the CMSIS docs. (Though the CMSIS team generally feels the CMSIS-DAPv1 HID interface is legacy and should not be used anymore.)

Well CMSIS-DAP v2 isn't really documented either. The limited docs refer to WinUSB rather than bulk endpoints. AFAIK, having descriptors that conform to the WinUSB driver standard has nothing to do with the v2 protocol.

[flit]

Yes, you're right. Working on trying to get that fixed too. (To be clear, I'm not a member of the CMSIS team, I work in the Arm Research group. So I don't have any direct control, and can simply supply suggestions. 😃)

[nerdralph]

Through targeted trial and error, I've got a simplified report descriptor working:

0x06, 0x00, 0xFF,  // Usage Page (Vendor Defined 0xFF00)
0x09, 0x01,        // Usage (0x01)
0xA1, 0x01,        // Collection (Application)
0x15, 0x00,        //   Logical Minimum (0)
0x25, 0x40,        //   Logical Maximum (64)
0x75, 0x08,        //   Report Size (8)
0x95, 0x40,        //   Report Count (64)
0x81, 0x01,        //   Input (Const,Array,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x91, 0x01,        //   Output (Const,Array,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
0xC0,              // End Collection

It only works with the input and output as const (0x01). When it's just data (0x00), pyocd list doesn't find any adapters. FWIW, I've got hidapi 49.2.1 installed.

From your comment, I guess it boils down to making sure the Windows HID driver accepts the report descriptor.

[flit]

I guess it boils down to making sure the Windows HID driver accepts the report descriptor.

Yup, exactly.

[nerdralph]

I discovered that it's not just the OS, the usb library used makes a difference. When I removed hidapi, pyocd on Win7 couldn't find my probe. I had to expand the report descriptor:

     0x06, 0x00, 0xFF,   // Usage Page = 0xFF00 (Vendor Defined Page 1)
     // USB-IF HID tool says vendor usage not required, but Win7 needs it
     0x09, 0x01,         // Usage (Vendor Usage 1)
     0xA1, 0x01,         // Collection (Application)
     0x25, 0x00,         //  Logical minimum
     0x25, 64,           //  Logical maximum
     0x75, 0x08,         //  Report Size: 8-bit field size
     0x95, 64,           //  Report Count: Make 64 fields

     // Input Report
     0x09, 0x01,         //  Usage (Vendor Usage 1)
     0x81, 0x02,         //  Input (Data,Var,Abs,No Wrap,Linear)

     // Output Report
     0x09, 0x01,         //  Usage (Vendor Usage 1)
     0x91, 0x02,         //  Output (Data,Var,Abs,No Wrap,Linear)

     0xC0                // End Collection

I used the USB-IF HID descriptor tool to validate it.
https://www.usb.org/document-library/hid-descriptor-tool