Confused about itf and itf_num

[WestfW]

The itf_num is the basic identifier passed around in callbacks when there is more than one instance of a class, right?
And it's provided in the TUD_CONFIG_DESCRIPTOR entries that the user program provides?
Is this an arbitrary per-class number, or is it intimately tied to endpoint numbers in some way?

Because if you look at the "cdc_dual_ports" example, it seems that the code carefully skips some itf numbers to account for the data + control ports of a CDC:

enum
        {
          ITF_NUM_CDC_0 = 0,
          ITF_NUM_CDC_0_DATA,
          ITF_NUM_CDC_1,
          ITF_NUM_CDC_1_DATA,
          ITF_NUM_TOTAL
        };
// later
uint8_t const desc_fs_configuration[] =
        {
          // Config number, interface count, string index, total length, attribute, power in mA
          TUD_CONFIG_DESCRIPTOR(1, ITF_NUM_TOTAL, 0, CONFIG_TOTAL_LEN,  USB_DESC_CONFIG_ATT_REMOTE_WAKEUP, 100),      
      
          // 1st CDC: Interface number, string index, EP notification address and size, EP data address (out, in) and size.
          TUD_CDC_DESCRIPTOR(ITF_NUM_CDC_0, 4, EPNUM_CDC_0_NOTIF, 8, EPNUM_CDC_0_DATA, 0x80 | EPNUM_CDC_0_DATA, 64),
      
          // 2nd CDC: Interface number, string index, EP notification address and size, EP data address (out, in) and size.
          TUD_CDC_DESCRIPTOR(ITF_NUM_CDC_1, 4, EPNUM_CDC_1_NOTIF, 8, EPNUM_CDC_1_DATA, 0x80 | EPNUM_CDC_1_DATA, 64),
        };

So ITF_NUM_CDC_1 will be 2. ??

But in class/cdc/cdc_device.c, it looks like the code is expecting one itf per CDC:

CFG_TUSB_MEM_SECTION static cdcd_interface_t _cdcd_itf[CFG_TUD_CDC];

where CFG_TUD_CDC is 2 for the dual ports, and the subsequent references to _cdcd_itf[itf] will be referencing past the end of the array when itf is not 0...

What am I missing?
A supposedly working example https://github.com/Noltari/pico-uart-bridge has similar non-contiguous itf values for the dual CDC ports, where the largest itf used is greater than CFG_TUD_CDC...

[Syncena]

As best I can tell, the ITF_NUM_CDC* values are used to identify CDC interfaces in communications with the USB host (control transfers). They are not used as an index into the _cdcd_itf[].

The 'itf' variable, limited to the range 0 - (CFG_TUD_CDC - 1), identifies a specific CDC instance to firmware running on the device. Take a look at how 'itf' is determined in the cdcd_control_xfer_cb() and cdcd_xfer_cb() functions.

[WestfW]

Yes, you're right that the itf passed to the callbacks is derived from the array position, compared to endpoints.
The actual "assignment" of _cdcd_itf[n].itf_num = descriptor->bInterfaceNuber is in cdcd_open() (though it doesn't look like that.)
Thanks!

(that also means that my initial assumption/statement itf_num is the basic identifier passed around in callbacks was incorrect. The numbers passed IN via TUD_CONFIG_DESCRIPTOR are the USB-packet internal "interface number", and the numbers you use to reference a particular instance are created inside of tinyUSB and passed to the user code via the callbacks.)

[hathach]

it should be named instance instead of itf and is numbering as cdc 0, cdc1 etc as they appear in the configuration descriptor. I am renaming them to prevent confusion.

[WestfW]

Edit: NO, wait. The Adafruit getInterfaceDescriptor() is not the same as the tinyUSB callback and it does it's own managment of the itf_num and count. I think. Let me poke around some more.

So does that mean that this code from the Adafruit Arduino version of TinyUSB is wrong?
it seems to be dynamically creating a CONFIG descriptor, but using the "instance number" passed to it as an itf_num in the descriptor...

https://github.com/adafruit/Adafruit_TinyUSB_Arduino/blob/master/src/arduino/Adafruit_USBD_CDC.cpp#L50

uint16_t Adafruit_USBD_CDC::getInterfaceDescriptor(uint8_t itfnum, uint8_t *buf,
                                                   uint16_t bufsize) {
  // CDC is mostly always existed for DFU
  // usb core will automatically update endpoint number
  uint8_t desc[] = {TUD_CDC_DESCRIPTOR(itfnum, 0, EPIN, 8, EPOUT, EPIN, 64)};
  uint16_t const len = sizeof(desc);

  if (bufsize < len) {
    return 0;
  }

  memcpy(buf, desc, len);
  return len;
}