HID ROM API, Documentation?

Discussion created by lpcware Employee on Jun 15, 2016
Content originally posted in LPCWare by mch0 on Sat Jun 07 02:40:22 MST 2014

I have just implemented a first HID generic project, starting with the sample project in LPCOpen 2.12.
It does work, yet I feel I do not understand all that is going on.
I have right now three sources for documentation:

- the UM, section 26 (USB API)
- the LPCOpen v2.12 online documentation (USBD ROM STACK)
- the source code of the USB example projects

Is there an additional documentation I could read? I did look at the FAQ and also did y keyword search at the forums.

Sample questions:

The UM suggest a 2048 byte alignment for the memory area handed to the USB stack.
(Table 592, init).
The source code has a comment about 4096 byte alignment.
(File app_usbd_cgf.h)

The UM suggest one should/could use get_memsize() to determine actual memory requirements, the source code never wants to know, it assumes obviously 8192 bytes are sufficient for everything.

The source code seems to use the same memory area (0x20000000+) for both hw_init() and hid_init(), although I would have thought these are two different modules wich would require private memory spaces each.

Furthermore, in the generic example, the code uses part of this space for its own purpose:

/* allocate USB accessable memory space for report data */
loopback_report =  (uint8_t *) hid_param.mem_base;
hid_param.mem_base += 4;
hid_param.mem_size += 4;
/* update memory variables */
*mem_base = hid_param.mem_base;
*mem_size = hid_param.mem_size;

How can I know from the documentation that the ROM drivers don't miss the space?
The +=4  in the code above looks like one would tell the HID driver(s) about the "missing" 4 bytes, now used for the loopback_report, but this really looks suspicious to me.
Even more, now the size has increased (second line)? It anything, I would have decremented by 4, since I just cut off the first 4 bytes of the original buffer?

In my first try the HID_Ep_Hdlr() never got called, although the host was sending IN tokens.
Actually by looking at the mouse-example one has to queue an IN report first and the handler gets called when that report has been sent.
OK so far, but I would have expected to be notified of NAKIN-events as well. Can I enable these somewhere?

The documentation says the drivers use a zero-copy model. This would be fine, but I get the impression that the function USBD_API->hw->WriteEP() actually does not save a pointer but copy data. At least a test suggested that.
Furthermore I assume there is no queueing of reports, i.e. I can prepare one report only and when that has been sent I get notified (ISR) to copy data for the next event. Hopefully before the host sends the next IN token if I want to avoid performance degrading NAKINs?

I really do appreciate the ROM drivers, since the last time I built the whole mess (USB enumeration) from scratch which took 6 month. This time it was 2 hours until success.
But I feel the documentation I have at hand leaves some questions open - I'm willing to read more for a better understanding.

Best regards,