December 9, 2020

USB - a look at some other source code

A lot can be learned by looking at other peoples driver code, especially if they don't have weird coding styles and have some basic level of competence. I have done a fair bit of this on this and other projects, and there is absolutely no telling what you are going to end up looking at.

A great tool for this kind of thing is ctags, combined with some key setup for Vim. If you have a source tree with source files separate from include files (due to terrible brain damage) and in several directories, this will help you from going crazy. I have exactly that, and ctags has made things almost tolerable. The other old standby is "grep -r xyz ." in the root directory. I just made this a script I call "rgrep". There are other tools like cscope, but I have not yet used them.

What works great is to start with some file that has a routine like "usb_Init" or one of the basic interrupt handlers functions and then click on symbols to chase their definitions. Ctags finds definitions for you. If you want to know where functions are called (or symbols are used), you need cscope, or just resort to recursive grep.

The first (and primary) driver I am looking at is part of the Arduino_STM32 package and is found in Arduino_STM32/STM32F4/cores/maple/libmaple/usbF4. It is made of 3 components, like 3 part epoxy:

"Driver" is the low level STM32F4 specific chip driver.
"Library" is a higher level thing.
"VCP" is a "virtual COM port" layer. All I am interested in is making my driver act like a serial port, whereas this is a general framework to support various USB "classes", such as audio, cdc, dfu, hid, and msc. This means there is a lot of generalization that just adds complexity and confusion for me. The cdc class is the USB "communications device class" and includes modems (and hence serial ports persumably"). It is not clear if the VCP code simply bypasses this -- this may well be the case. The top level send and receive functions in usb.c call routines in the VCP package.

Clean up their mess

After spending a lot of time with this code base, I decided to do several things to make it easier to navigate. First I just outright renamed the long directory names to "Driver" and "Library". If anyone cares, the details about what Driver and Library these are should be conveyed by Readme files or the name of the directory containing these. I even went an additional step and made these names all lower case, as "driver" and "library". Then inside each directory where some idiot had separated the files into "src" and "inc" directories, I merged these. I did "mv src/* .; rmdir src" and so forth. Whew! Much better. Now rerun ctags again and life is much better. Note that I have absolutely no intention of compiling this code (at this point anyway) so whether or not I have broken anyones build system does not matter.

Next, I collapsed the entire "library" tree after noting that the filenames themselves make everything clear. So not only have I gotten rid of inc versus src, but now the "core" files and the cdc class files are all together in one directory. The filenames begin with usbd_ in one case and usbd_cdc_ in the other. Given that the "Driver" files all begin with usb_, I could even collapse library and device into one directory. But this is far enough. Now I just have 3 directories: driver, library, and vcp.

I run "ctags -R ." and life is much better.

Cube

Cube is an ST Micro "product" -- it is offered free to help accelerate the development of applications for their chips. All open source. I have not spent as much time with this as it is part of a much bigger framework. 
ST/Cube/STM32CubeF4/Drivers/STM32F4xx_HAL_Driver/Src
The USB code in this directory consists of 3 parts: The "ll" is apparently the low level USB code. "Hcd" seems to be for the host controller, "Pcd" seems to be for device mode (PCD = peripheral control driver)

Doing some searches trying to sort out this lingo led to the discovery of the following documents:

Feedback? Questions? Drop me a line!

Tom's Computer Info / tom@mmto.org