USB support in Circle (specifically for non-HID devices)

[SteveSpencer]

Be gentle with me, I haven't been here very long ...

I am trying to understand how USB device handlers are "connected" in Circle.

I know a little about some parts of what is going on underneath, but not enough to help me understand it properly.
Perhaps if I could "see" the sequence of calls that happen as a device handler is 'plugged in', it would help.

I think the CUSBDeviceFactory::GetDevice does a lot of the heavy lifting. It is being called with the 'container' for the device, and a string name to identify the device.

I see that there are known interfaces (such as 9-0-0, 9-0-2, 3-1-1 etc) which I think come from the device class, device subclass, and interface number, prefixed by "int").

Am I right in thinking that the vendor specific or unspecified (255 and 0) are never used for this?
I suspect this is the case, and then there are calls into GetDevice usingt vendor-product identifiers, prefixed by "ven".

This would seem to make sense, as I can see in the source where the SMSC951x gets created.
Is this correct?

[rsta2]

The USB enumeration process is complex, so explaining this all would take much time. I try to give a short summary. On the lower layer the USB root port or a hub, if the device is connected to it, detects a newly attached device. Then the root or hub port is enabled and the device descriptor of the USB device (a small data structure) is read. It contains the vendor and device ID of this device. This forms the vendor string ("venXXXX-XXXX") in Circle. Then the configuration descriptor is read, which consists of the configuration descriptor header itself and of (possibly) multiple interface and endpoint descriptors in a row. These interface descriptor structures contain the device class, subclass and protocol values, which form the interface string ("int-XX- XX-XX") in Circle. With these mentioned strings Circle enters the factory class for the function drivers. It starts with the vendor string and continuous with the interface strings. When the vendor string is found in the factory, a USB function driver class is instantiated for this known device. Only when it is not found, the USB interface descriptors will be scanned in this process. The further initialization depends on the device class and is different. Normally the endpoint descriptors are scanned by the function driver and an instance of CUSBEndpoint is created for each endpoint, which is accessed by the driver. You are right, USB interfaces with values of 255 ( vendor specific) in the interface descriptor's device class/subclass/protocol fields are never detected in the USB device factory. They must be detected using the vendor string.

[SteveSpencer]

OK, I understand this part of the process, and have produced a stub driver for a device that has two endpoints (it is a display and touchscreen) for the single interface the device has.

I found that I was consistently getting problems trying to iterate the endpoints with GetDescriptor inside my Configure function, as it showed an error, a problem with the configuration descriptor (always at the same address 0x19).

When I added code to CUSBDevice to increment ucConfigIndex, as required for the NetChip,RealTek devices, this was resolved, and I was able to get the endpoints successfully.

As far as I can determine, the device descriptor reports bNumConfigurations as 1. I would expect that asking for the default would be OK, but clearly not.

I put some code into CUSBDevice to retrieve DeviceConfiguration for both index#0 and index#1, and there is an obvious difference, in that bNumConfigurations is 0x32 (50) in the first case, while in the second case it is 0x01 (1).

I am confused as to why this would cause a problem, since as far as I can see, this member is never referred to directly.

[SteveSpencer]

Yes, I agree it sounds odd. Here is the lsusb -v output
usb.txt

My original code wasn't calling ConfigurationError(). The error was being raised within my call the CUSBFunction::GetDescriptor in order to retrieve the descriptors for the endpoints.

I have been doing more experimenting. Within CUsbDevice::Initialize, I tried to get the DESCRIPTOR_CONFIGURATION for three different values, 0, 1 and 12 (picked at random). For the USB hub, I saw that only 0 worked, the others returned -1 as you would expect.
However, for the device I am working with, both 0 and 1 worked, and interestingly, returned the same results (with bNumConfigurations set to 0x32!). For the RealTek USB adapter, that too works for 0 and 1, and again, returns 0x32 as the value.
I unplugged the RealTek (which has a hub), and plugged the display back in, and the device was rediscovered; this time all three calls (0,1 and 12) worked, but the value of bNumConfigurations was 0x32,0x32 and 0x00 respectively.. This is very curious!

Ultimately, since support for each non-HID device requires a driver, the simple workaround is to change usbdevice to ask for the correct configuration, and usbfactory to cater for the venVID-PID strings.

[rsta2]

Thanks for the lsusb -v output! I cannot see a problem here. That's a normal USB 2.0 device with a vendor defined USB interface. So you have to use the vendor string venfccf-a001 in the device factory for device detection.

However, for the device I am working with, both 0 and 1 worked, and interestingly, returned the same results (with bNumConfigurations set to 0x32!). For the RealTek USB adapter, that too works for 0 and 1, and again, returns 0x32 as the value.

Your device does not seem to honor the descriptor index, when reading the device descriptor. Because there is only one device descriptor, that's not a real problem. I can reproduce this behavior with the RealTek RTL8152 adapter here, but the value of bNumConfigurations is 2 as expected (with or without using an USB hub for connecting the RTL8152). I'm dumping the device descriptor here.

[SteveSpencer]

My RTL8152 is "embedded" with a 4 port hub (using one of the available ports), but shows what I expect. I am not too surprised by the finding that some devices don't properly honor the index; as you say, for cases where there is only one descriptor, it isn't an issue.

Looking at linux USB support code, there are many "tweaks" required for the odd behaviour of certain devices.

Thanks for your help with this.

[SteveSpencer]

Despite the oddities of the device, I have basic functionality now, as I am able to send data to the display (320x240 16-bit colour depth) and get touch information back. My next stage will be to present the touch side as a 'standard' device, then move on to the display side.
I aim to represent it as a framebuffer style device, as that would allow me to more easlity use the lvgl addon with it.

Again, many thanks for your assistance and patience!

[rsta2]

For the touchscreen function, you have to create an instance of CTouchScreenDevice in your driver and call CTouchScreenDevice::ReportHandler() from it, when an event from the touchscreen occurs.

Not sure, if it's the best solution to emulate a frame buffer, because this requires to send 320x240x2x30 bytes via USB every second (at 30 frames per second) for your screen. Also Circle is not prepared to handle non-HDMI-displays as frame buffers. Perhaps it's better to modify this method in the LVGL wrapper for your purpose.

[SteveSpencer]

Yes, thanks. I have the touchscreen already working in sample/28-touchscreen with no modifications to the sample files.
We mean different things by framebuffer, I think. I meant an off-screen buffer where the display pixels can be composed, with a flush method (like LVGL) to then copy it to the device. The LVGL wrapper with my changes now works - and my driver isn't too slow, despite being limited to the number of pixels I can transfer at once (around 30).

I know there is a standard device "touch1" when I create the CTouchScreenDevice instance. I would like to be able to identify the touchscreen display, if present, so that I can drive it independently of LVGL in some apps.

I assume that if I use a new prefix "rpdisp" I can use CDeviceNameService to add it (after allocating a device number) when initialising the device? Obviously then get the device by name in CKernel when I need to call member functions.

[rsta2]

Yes, but the device name of USB devices is usually preceded by an "u" in the device name service.