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]

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

[jeremyzhou]

Nick Guzzardo

Thank you for your clarification。
Q1) Ture.
Q2) No, as there's no difference for the USB protocol to send the HID report whose format may be different.

Have a great day,
TIC

-------------------------------------------------------------------------------
Note:
- If this post answers your question, please click the "Mark Correct" button. Thank you!

- We are following threads for 7 weeks after the last post, later replies are ignored
Please open a new thread and refer to the closed one, if you have a related question at a later point in time.
-------------------------------------------------------------------------------

[nbgatgi]

jeremyzhou,

T‌hank you again for your reply.  To effectively and efficiently create the communications backbone for my product using USB HID, I must understand the interaction between the report descriptors and the USB stack from both the device and host side.  This takes me back to the originally posted questions (highlighted in red).  Would you or one of your colleges be able to more completely respond to those questions?

Nick

[jeremyzhou]

Hi  Nick Guzzardo,

Thanks for your reply.
Q1) 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?
-- Ture.
q2) 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, regarding the USB packet, it consists of the byte, not the word, so it always conforms to the specification even if receiving or transferring different format of Report.
The USB_DeviceEhciTransfer() is the last function to be called by the upper layer in the USB stack to receiving or sending the endpoint's data, please review its code to learn the mechanism of USB data transferring.

Have a great day,
TIC

-------------------------------------------------------------------------------
Note:
- If this post answers your question, please click the "Mark Correct" button. Thank you!

- We are following threads for 7 weeks after the last post, later replies are ignored
Please open a new thread and refer to the closed one, if you have a related question at a later point in time.
-------------------------------------------------------------------------------

[nbgatgi]

jeremyzhou,

I'm almost there!

In my specific case of generic HID for the sole purpose of transmitting data with guaranteed latency and guaranteed delivery of data using interrupt transfers, with no implied hardware function like a mouse or a keyboard, it does not appear that the report descriptor is particularly useful.  As I am understanding, the hardware level is transmitting data as bytes to/from sequential memory segments.  After a transfer is complete, the data can be cast into whatever structure the application needs.

If this is the case then there is one outstanding point from my original post:  "... If that is the case, then what is the point of creating the report descriptor at all?"

Parameters in a report descriptor like logical max and min don't appear to be necessary for proper function.  So, are there parts of a report descriptor that ARE required for establishing proper communications with a host or is the only required info from the interface descriptor?

Nick

[jeremyzhou]

Hi  Nick Guzzardo,

Q1) If that is the case, then what is the point of creating the report descriptor at all?
-- HID descriptor structure should conform to HID class definition, meanwhile, the HID report is free to set by the developer to design a customized HID class device.
Q2) So, are there parts of a report descriptor that ARE required for establishing proper communications with a host or is the only required info from the interface descriptor?
-- It's required for establishing proper communications with a host.

Have a great day,
TIC

-------------------------------------------------------------------------------
Note:
- If this post answers your question, please click the "Mark Correct" button. Thank you!

- We are following threads for 7 weeks after the last post, later replies are ignored
Please open a new thread and refer to the closed one, if you have a related question at a later point in time.
-------------------------------------------------------------------------------

[nbgatgi]

Carlos,

I have provided the information you requested.  Will you be able to help explain how the data received/transmitted in a single USB data packet is associated with the report descriptor and then how that data is connected to a data structure (struct) for use in the application?

Nick

[nbgatgi]

CarlosCasillas‌,

You asked for my hardware and software configuration, but then deleted your request.  Is there other information I can provide to help you answer my questions?

Nick

[CarlosCasillas]

Hi,

I asked such information to redirect your question with the proper team. So, in case if still having questions, please continue with jeremyzhou‌.

Best regards!

[nbgatgi]

Hardware:  MIMXRT1064-EVK

IDE:  MCUXpresso (latest version)

SDK:  2.4.1

Example Code Project:  dev_hid_generic_freertos

[jeremyzhou]

Hi Nick Guzzardo，

Thank you for your interest in NXP Semiconductor products and for the opportunity to serve you.
In my opinion, I'd highly recommend you not to try other units of report size except for uint8, otherwise, you should consider spending some time to check whether really report size is consistent with the size that defined in the USB stack architecture, even, do some modification about the USB stack, however, the stack usually seems a bit complicated for most developers.

Have a great day,
TIC

-------------------------------------------------------------------------------
Note:
- If this post answers your question, please click the "Mark Correct" button. Thank you!

- We are following threads for 7 weeks after the last post, later replies are ignored
Please open a new thread and refer to the closed one, if you have a related question at a later point in time.
-------------------------------------------------------------------------------

[nbgatgi]

Jeremy,

With the research I have done regarding the HID implementation of USB, changing report sizes in various combinations within a USB packet using the report descriptors in whatever fashion is needed is a fundamental benefit of using the HID class.  Suggesting that I don't make changes is not realistic for new product development.

I am not interested in modifying the stack itself.  What I need is an understanding of how the data received/transmitted in a single USB data packet is associated with the report descriptor and then how that data is connected to a data structure (struct) for use in the application.  Are you able to help explain this?

Nick

[jeremyzhou]

Hi Nick Guzzardo，

Thanks for your reply.
Okay, I know you mean, so how's going on with your testing?
Maybe I can do a favor.

Have a great day,
TIC

-------------------------------------------------------------------------------
Note:
- If this post answers your question, please click the "Mark Correct" button. Thank you!

- We are following threads for 7 weeks after the last post, later replies are ignored
Please open a new thread and refer to the closed one, if you have a re

[nbgatgi]

jeremyzhou,

Thank you for your reply, but you didn't seem to attempt to answer my questions.  I have replied to my original post with a few more details.  Hopefully that will help you understand what I'm looking for.

Nick