Modifying USB Generic HID Example Code for Custom Report Descriptors

[nbgatgi]

*** After all the discussion below and others I created a summary post here ***

I have successfully used the generic HID example code to echo data sent from the PC to my target processor back to the PC with modifications to high-speed and packet size of 1024-bytes.

https://community.nxp.com/thread/484970

I went on to add my own tasks under FreeRTOS as well as adjust the task priorities for the purpose of justifying the use of USB HID for our instrument's communication interface.  With that complete, I'm on to the task of customizing the reports via the report descriptor and data structures.  After much debate the only significant change we want is to change the report size from 8-bits to 32-bits.  To remain within the 1kB packet size, this also requires the report count to change from 1024 to 256 as well as the logical min and max.  With the help of the report descriptor tutorial and the tool for generating the hex for the report descriptor, I made the following changes:

Report Descriptor 8-bit reports and 1024 report count

USB_DMA_INIT_DATA_ALIGN(USB_DATA_ALIGN_SIZE)
uint8_t g_UsbDeviceHidGenericReportDescriptor[] = {
   0x05U, 0x81U,          /* Usage Page (Vendor defined)*/
   0x09U, 0x82U,          /* Usage (Vendor defined) */
   0xA1U, 0x01U,          /* Collection (Application) */
   0x09U, 0x83U,          /* Usage (Vendor defined) */
   0x15U, 0x80U,          /* Logical Minimum (-128) */
   0x25U, 0x7FU,          /* Logical Maximum (127) */
   0x75U, 0x08U,          /* Report Size (8U) */
   0x96U, 0x00U, 0x04U,   /* Report Count (1024U) */
   0x81U, 0x02U,          /* Input(Data, Variable, Absolute) */
   0x09U, 0x84U,          /* Usage (Vendor defined) */
   0x15U, 0x80U,          /* Logical Minimum (-128) */
   0x25U, 0x7FU,          /* Logical Maximum (127) */
   0x75U, 0x08U,          /* Report Size (8U) */
   0x96U, 0x00U, 0x04U,   /* Report Count (1024U) */
  0x91U, 0x02U,           /* Output(Data, Variable, Absolute) */
   0xC0U, /* End collection */
};

Report Descriptor 32-bit reports and 256 report count

USB_DMA_INIT_DATA_ALIGN(USB_DATA_ALIGN_SIZE)
uint8_t g_UsbDeviceHidGenericReportDescriptor[] = {
   0x05U, 0x81U,                      /* Usage Page (Vendor defined)*/
   0x09U, 0x82U,                      /* Usage (Vendor defined) */
   0xA1U, 0x01U,                      /* Collection (Application) */
   0x09U, 0x83U,                      /* Usage (Vendor defined) */
   0x17U, 0x00U, 0x00U, 0x00U, 0x80U, /* Logical Minimum (-2,147,483,648) */
   0x27U, 0xFFU, 0xFFU, 0xFFU, 0x7FU, /* Logical Maximum (2,147,483,647) */
   0x75U, 0x20U,                      /* Report Size (32U) */
   0x96U, 0x00U, 0x01U,               /* Report Count (256U) */
   0x81U, 0x02U,                      /* Input(Data, Variable, Absolute) */
   0x09U, 0x84U,                      /* Usage (Vendor defined) */
   0x17U, 0x00U, 0x00U, 0x00U, 0x80U, /* Logical Minimum (-2,147,483,648) */
   0x27U, 0xFFU, 0xFFU, 0xFFU, 0x7FU, /* Logical Maximum (2,147,483,647) */
   0x75U, 0x20U,                      /* Report Size (32U) */
   0x96U, 0x00U, 0x01U,               /* Report Count (256U) */
   0x91U, 0x02U,                      /* Output(Data, Variable, Absolute) */
   0xC0U, /* End collection */
};

Where I am struggling now is finding documentation on how to associate the structure defined in the report descriptor with a structure for using the data in my application.

As I see it, there are two arrays acting as data buffers.

USB_DMA_NONINIT_DATA_ALIGN(USB_DATA_ALIGN_SIZE) static uint32_t s_GenericBuffer0[USB_HID_GENERIC_IN_BUFFER_LENGTH >> 2];
USB_DMA_NONINIT_DATA_ALIGN(USB_DATA_ALIGN_SIZE) static uint32_t s_GenericBuffer1[USB_HID_GENERIC_IN_BUFFER_LENGTH >> 2];

The value of "USB_HID_GENERIC_IN_BUFFER_LENGTH" is equal to the size of the USB packet in bytes which is 1024, but the buffers have been declared as uint32 so the array size was divided by 4.  When the buffer is used in the application, the buffers are cast as unint8 which matches the report size in the report descriptor.

In my specific case, I believe it is effectively done as long as I don't re-cast the buffers since it's already in 32-bit elements.  But what if I had several reports defined in various sizes?  Would I simply transfer the entire packet to an array of n-bytes and then cast it to whatever structure I deem appropriate?

If that is the case, then what is the point of creating the report descriptor at all?  Wouldn't it be just as effective and far more simple to just add the number of bits I need, make that the report size with a report count of 1?

[nbgatgi]

If you are interested in a more complete conversation on this topic here is the link:

https://community.nxp.com/thread/500874

Nick

[mjbcswitzerland]

Nick

Would not RAW HID be an option? https://www.pjrc.com/teensy/rawhid.html

Usage report example below:

/*
    /--------------------------\
    |     Device Descriptor    |
    /--------------------------\
                  |
    /--------------------------\
    | Configuration Descriptor |
    /--------------------------\
                  |
    /--------------------------\
    |    Interface Descriptor  |
    /--------------------------\
                  |   |
                  |   ----------------------------
                  |                              |
    /--------------------------\     /--------------------------\
    |    Endpoint Descriptor   |     |       HID Descriptor     |
    /--------------------------\     /--------------------------\
                                                 |
                                  -------------------------------
                                  |                             |
                   /--------------------------\     /--------------------------\
                   |      Report Descriptor   |     |   Physical Descriptor    |
                   /--------------------------\     /--------------------------\
*/
static const unsigned char ucRawReport[] = {
 0x06, LITTLE_SHORT_WORD_BYTES(RAWHID_USAGE_PAGE),
 0x0a, LITTLE_SHORT_WORD_BYTES(RAWHID_USAGE),
 0xa1, 0x01,                                                          // collection 0x01
 0x75, 0x08,                                                          // report size = 8 bits
 0x15, 0x00,                                                          // logical minimum = 0
 0x26, 255, 0x00,                                                     // logical maximum = 255
 0x95, HID_RAW_TX_SIZE,                                               // report count
 0x09, 0x01,                                                          // usage
 0x81, 0x02,                                                          // input (array)
 0x95, HID_RAW_RX_SIZE,                                               // report count
 0x09, 0x02,                                                          // usage
 0x91, 0x02,                                                          // output (array)
 0xc0                                                                 // end collection
};

‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Since the max. USB bulk packet size is defined to be max 64 for full speed and max 512 for high speed I suppose the HID packet size is a higher layer setting that is not HW related; 1024 would only be allowed when using HS isochronous transfer (1023 max. for FS).

Regards

Mark

[nbgatgi]

Mark,

I believe you are incorrect regarding max packet size for USB high-speed (HS) interrupt transfers.  512-bytes is the high-speed limit for bulk transfers, but it is 1024-bytes for interrupt transfers which are used by HID.  We chose an interrupt transfer class over bulk because it provides guaranteed latency (maximum time between transfer attempts) and bulk transfers do not.

For reference, here is table 2-1 in Jan Axelson's "USB Complete: The Developer's Guide" 5th Edition:

I have been able to validate that the packet transmission time for a HS port is the same up to and including 1024B.  Note that per the USB specification, up to 3x 1024B burst-packets can be sent within the 125µs polling period.  That is of particular note since that means that the maximum data-rate for interrupt transfers using a USB 2.0 high-speed port is the same as a USB 3.1 port!

What you are proposing is effectively what we are doing.  Starting with the generic HID example for the MCUXpresso SDK, I have modified the report descriptor for 32-bit reports.  We do not foresee a need for 64-bit information so 32-bit reports double the number of reports within a 1024-byte packet.  Furthermore, as I've discovered in researching this, for a generic or vendor defined "usage page", the information in the report descriptor is only relevant if you make it so on the host application side.  Otherwise, the received data can be cast to whatever data structure you want assuming you are controlling the applications for the device and host, which is what we are doing.  Of course if you are trying to communicate the structure to an unknown host application, the report descriptor becomes very relevant.

Nick

[mjbcswitzerland]

Nick

I referenced bulk (512/64) and isochronous (1024/1023) and not interrupt, which is as stated in your table (1024/64).

I had forgotten that interrupt endpoints are used rather than bulk...

Regards

Mark

[nbgatgi]

In the hopes of seeding the conversation to a more useful end, here is a little more of what I have found for this specific example code:

There is a structure type called "usb_hid_generic_struct_t" which I believe is intended to include all the information regarding the specific HID device.  It is located in the file "hid_generic.h".

typedef struct _usb_hid_generic_struct
{
   usb_device_handle deviceHandle;
   class_handle_t hidHandle;
   TaskHandle_t applicationTaskHandle;
   TaskHandle_t deviceTaskHandle;
   uint8_t *buffer[2];
   uint8_t bufferIndex;
   uint8_t idleRate;
   uint8_t speed;
   uint8_t attach;
   uint8_t currentConfiguration;
   uint8_t currentInterfaceAlternateSetting[USB_HID_GENERIC_INTERFACE_COUNT];
} usb_hid_generic_struct_t;

This structure includes an array of two uint8_t pointers ( .*buffer[] ) which points to arrays used together as a double-buffer for data received or data to be sent over the USB port.  The only object declared with this structure type is "g_UsbDeviceHidGeneric" and is declared in "hid_generic.c".

The actual buffer arrays are declared in "hid_generic.c" and their addresses loaded into g_UsbDeviceHidGeneric.buffer[] during application initialization.

USB_DMA_NONINIT_DATA_ALIGN(USB_DATA_ALIGN_SIZE) static uint32_t s_GenericBuffer0[USB_HID_GENERIC_IN_BUFFER_LENGTH >> 2];
USB_DMA_NONINIT_DATA_ALIGN(USB_DATA_ALIGN_SIZE) static uint32_t s_GenericBuffer1[USB_HID_GENERIC_IN_BUFFER_LENGTH >> 2];

...

static void USB_DeviceApplicationInit(void)

{

...

   g_UsbDeviceHidGeneric.buffer[0] = (uint8_t *)&s_GenericBuffer0[0];
   g_UsbDeviceHidGeneric.buffer[1] = (uint8_t *)&s_GenericBuffer1[0];

}

Since I have configured my USB application to run at high-speed instead of full-speed, the definition for "USB_HID_GENERIC_IN_BUFFER_LENGTH" was initially set to 1024 representing the number of bytes transmitted in each USB packet (full-speed is limited to 64-bytes per packet for interrupt transfers).  Note that the arrays are typed as uint32_t and so the size of each is divided by 4 ( ">> 2" = 2x binary right-shift = /4 ).  Also note that when their addresses are initialized into the structures buffer pointers that they are cast as uint8_t.

The USB send and receive procedures are USB_DeviceHidSend and USB_DeviceHidRecv and require the same four parameters.  The last two parameters are the data pointer and the number of bytes to be sent.

usb_status_t USB_DeviceHidRecv(class_handle_t handle, uint8_t ep, uint8_t *buffer, uint32_t length)

Note again that the data pointer is for a uint8_t.  Since there is not a separate send and receive procedure that uses any other bit configuration, I assume the low level for USB transfers is exclusively 8-bit.

Now to the nitty-gritty of what I was trying to understand at the beginning of this thread.  Regardless of the structure I use for my data (array of bytes, array of ints, mix of data types ...), in order to send or receive that data it appears to require all data being cast as uint8_t <-- TRUE or FALSE?

If the above question is TRUE, other than identifying the USB packet size, how are report descriptors relevant?  Stated another way, are there middle-ware checks in the stack that validate what is being transmitted against the report descriptor?

Nick

[danielchen]

Hi Nick ：

Regardless of the structure I use for my data (array of bytes, array of ints, mix of data types ...), in order to send or receive that data it appears to require all data being cast as uint8_t <-- TRUE or FALSE?

Yes, you can think so.

If the above question is TRUE, other than identifying the USB packet size, how are report descriptors relevant?  Stated another way, are there middle-ware checks in the stack that validate what is being transmitted against the report descriptor?

No, there aren't any middle-ware checks that validate what is being transmitted.

For your case, I would suggest you use Report Descriptor 8-bit reports and 1024 report count.    with this, you can transmit  packets  up to 1024 bytes.  It is the application's job to parse the packet. 

Regards

Daniel

[nbgatgi]

danielchen@fsl‌,

Thank you for your feedback, but expecting me to stick with the 8-bit report size and 1024 report count is not realistic.  The report descriptors have been designed for complex modification and as I have stated, I have the report descriptors as I want them and am confident that they are correct.

Do you have any colleges who may be more familiar with how the USB stack works with report descriptors?

Nick

[nbgatgi]

I have actually used this same example code for Kinetis K22 as well as LPC54608 and i.MX RT1064.  Since it is so similar between projects and my question is not really processor specific, I've posted the question in three groups.

Here is my current configuration:

Hardware:  MIMXRT1064-EVK

IDE:  MCUXpresso (latest version)

SDK:  2.4.1

Example Code Project:  dev_hid_generic_freertos

[danielchen]

Hi Nick:

For your case, I would suggest you assign an ''report ID".  Each report ID involves one data format. In your application, you need to parse the data according to the report ID.

Below descriptor is copied from other community, you can customize for your own. You need to manually set the report ID before you send the data.

static uint8_t arcade_report_desc[] = {
    0x05, 0x01,        // Usage Page (Generic Desktop Ctrls)
    0x09, 0x05,        // Usage (Game Pad)
    0xA1, 0x01,        // Collection (Application)
    0xA1, 0x00,        //   Collection (Physical)
    0x85, 0x01,        //     Report ID (1)
    0x05, 0x09,        //     Usage Page (Button)
    0x19, 0x01,        //     Usage Minimum (0x01)
    0x29, 0x07,        //     Usage Maximum (0x07)
    0x15, 0x00,        //     Logical Minimum (0)
    0x25, 0x01,        //     Logical Maximum (1)
    0x95, 0x07,        //     Report Count (7)
    0x75, 0x01,        //     Report Size (1)
    0x81, 0x02,        //     Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
    0x95, 0x01,        //     Report Count (1)
    0x75, 0x01,        //     Report Size (1)
    0x81, 0x03,        //     Input (Const,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
    0x05, 0x01,        //     Usage Page (Generic Desktop Ctrls)
    0x09, 0x30,        //     Usage (X)
    0x09, 0x31,        //     Usage (Y)
    0x15, 0x81,        //     Logical Minimum (129)
    0x25, 0x7F,        //     Logical Maximum (127)
    0x95, 0x02,        //     Report Count (2)
    0x75, 0x08,        //     Report Size (8)
    0x81, 0x02,        //     Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
    0x85, 0x02,        //     Report ID (2)
    0x15, 0x00,        //     Logical Minimum (0)
    0x25, 0x01,        //     Logical Maximum (1)
    0x05, 0x0A,        //     Usage Page (Ordinal)
    0x09, 0x01,        //     Usage (0x01)
    0xA1, 0x02,        //     Collection (Logical)
    0x05, 0x08,        //       Usage Page (LEDs)
    0x09, 0x4B,        //       Usage (Generic Indicator)
    0x75, 0x01,        //       Report Size (1)
    0x95, 0x01,        //       Report Count (1)
    0x91, 0x02,        //       Output (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
    0xC0,              //     End Collection
    0x05, 0x0A,        //     Usage Page (Ordinal)
    0x09, 0x02,        //     Usage (0x02)
    0xA1, 0x02,        //     Collection (Logical)
    0x05, 0x08,        //       Usage Page (LEDs)
    0x09, 0x4B,        //       Usage (Generic Indicator)
    0x75, 0x01,        //       Report Size (1)
    0x95, 0x01,        //       Report Count (1)
    0x91, 0x02,        //       Output (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
    0xC0,              //     End Collection
    0x05, 0x0A,        //     Usage Page (Ordinal)
    0x09, 0x03,        //     Usage (0x03)
    0xA1, 0x02,        //     Collection (Logical)
    0x05, 0x08,        //       Usage Page (LEDs)
    0x09, 0x4B,        //       Usage (Generic Indicator)
    0x75, 0x01,        //       Report Size (1)
    0x95, 0x01,        //       Report Count (1)
    0x91, 0x02,        //       Output (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
    0xC0,              //     End Collection
    0x05, 0x0A,        //     Usage Page (Ordinal)
    0x09, 0x04,        //     Usage (0x04)
    0xA1, 0x02,        //     Collection (Logical)
    0x05, 0x08,        //       Usage Page (LEDs)
    0x09, 0x4B,        //       Usage (Generic Indicator)
    0x75, 0x01,        //       Report Size (1)
    0x95, 0x01,        //       Report Count (1)
    0x91, 0x02,        //       Output (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
    0xC0,              //     End Collection
    0x05, 0x0A,        //     Usage Page (Ordinal)
    0x09, 0x05,        //     Usage (0x05)
    0xA1, 0x02,        //     Collection (Logical)
    0x05, 0x08,        //       Usage Page (LEDs)
    0x09, 0x4B,        //       Usage (Generic Indicator)
    0x75, 0x01,        //       Report Size (1)
    0x95, 0x01,        //       Report Count (1)
    0x91, 0x02,        //       Output (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
    0xC0,              //     End Collection
    0x05, 0x0A,        //     Usage Page (Ordinal)
    0x09, 0x06,        //     Usage (0x06)
    0xA1, 0x02,        //     Collection (Logical)
    0x05, 0x08,        //       Usage Page (LEDs)
    0x09, 0x4B,        //       Usage (Generic Indicator)
    0x75, 0x01,        //       Report Size (1)
    0x95, 0x01,        //       Report Count (1)
    0x91, 0x02,        //       Output (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
    0xC0,              //     End Collection
    0x05, 0x0A,        //     Usage Page (Ordinal)
    0x09, 0x07,        //     Usage (0x07)
    0xA1, 0x02,        //     Collection (Logical)
    0x05, 0x08,        //       Usage Page (LEDs)
    0x09, 0x4B,        //       Usage (Generic Indicator)
    0x75, 0x01,        //       Report Size (1)
    0x95, 0x01,        //       Report Count (1)
    0x91, 0x02,        //       Output (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
    0xC0,              //     End Collection
    0x95, 0x01,        //     Report Count (1)
    0x75, 0x09,        //     Report Size (9)
    0x91, 0x03,        //     Output (Const,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
    0xC0,              //   End Collection
    0xC0,              // End Collection

// 181 bytes

};

Sorry I don't have a document, I will update you if I have, your tutorial about USB HID Report Descriptor is a good one:)

Regards

Daniel

[nbgatgi]

danielchen@fsl‌

Thank you for your reply, but your reply with the report descriptor suggestion was not relevant to my original request.  I have replied to my original post with a few more details.  Hopefully that will help you understand what I'm looking for.

Nick

[danielchen]

Hi Nick:

Thank you for your question, in order to understand you question better, could you please let me know your hardware and software ? I am assuming you are using Kinetis, right?

Regards

Daniel