exporter: Add USB hub abstraction for simpler device matching

[sjg20]

The exporter config requires full @ID_PATH strings for every USB resource, which are long and hard to maintain, particular for labs with multiple hubs.

This PR adds a 'hubs' section to the exporter config that defines USB hubs by name, base path, and a mapping of logical port numbers to USB path suffixes. Resources can then use 'hub' and 'port' in their match dict instead of a raw @ID_PATH string.

For example, instead of:

  board1:
    USBSerialPort:
      match:
        '@ID_PATH': 'pci-0000:04:00.0-usb-0:2.2.3'

the config can be written as:

  hubs:
    a:
      base: 'pci-0000:04:00.0-usb-0:2'
      ports:
        7: '2.3'

  board1:
    USBSerialPort:
      match:
        hub: a
        port: 7

The expansion happens at config load time before any resource matching, so it works with any USB resource type.

This feature is used to help diagnose problems - e.g. if a device's UART stops working, which USB port do I need to replug? It saves a lot of confusion mapping a string of numbers to a physical port.

This feature has been manually verified on my lab (about 30 boards) with 7 16-port hubs connected to a single machine. Operation appears to be the same before and after the change. I think modified the lab to actually use this feature and checked that things still work.

Checklist

• Documentation for the feature
• Tests for the feature
  If you add a feature other drivers/resources can benefit from:
• Add a section on how to use the feature to doc/usage.rst
• Add a section on how to use the feature to doc/development.rst
• PR has been tested

[codecov]

Codecov Report

❌ Patch coverage is 92.10526% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 47.3%. Comparing base (c246fab) to head (b4cc652).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
labgrid/remote/exporter.py	92.1%	3 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##           master   #1854     +/-   ##
========================================
+ Coverage    45.8%   47.3%   +1.5%     
========================================
  Files         182     182             
  Lines       14718   14756     +38     
========================================
+ Hits         6743    6991    +248     
+ Misses       7975    7765    -210     

Flag	Coverage Δ
3.10	47.3% <92.1%> (+1.5%)	⬆️
3.11	47.3% <92.1%> (+1.5%)	⬆️
3.12	47.3% <92.1%> (+1.5%)	⬆️
3.13	47.3% <92.1%> (+1.5%)	⬆️
3.14	47.3% <92.1%> (+1.5%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Emantor]

We already provide jinja2 templating in the exporter configuration, so a lot of USB resources can be added at once:

{% for idx, sysfs in [
        ('1', 'pci-0000:0d:00.4-usb-0:1.3'),
        ('2', 'pci-0000:0d:00.4-usb-0:1.2'),
        ('3', 'pci-0000:0d:00.4-usb-0:1.1'),
        ('4', 'pci-0000:0d:00.4-usb-0:1.4.4'),
        ('5', 'pci-0000:0d:00.4-usb-0:1.4.3'),
        ('6', 'pci-0000:0d:00.4-usb-0:1.4.2'),
        ('7', 'pci-0000:0d:00.4-usb-0:1.4.1')] %}

{% for if in [ '1.0', '1.1', '1.2', '1.3'] %}
lb-dlink-7-p{{idx}}-{{if}}:
  location: "7 Port Hub auf dem Schreibtisch"
  USBSerialPort:
    match:
      '@ID_PATH': '{{sysfs}}:{{if}}'
{% endfor %}

lb-usb3-7-p{{idx}}:
  location: "7 Port Hub auf dem Schreibtisch"
  IMXUSBLoader:
    match:
        'ID_PATH': '{{sysfs}}'
  AndroidFastboot:
    match:
        'ID_PATH': '{{sysfs}}'
  USBSDMuxDevice:
    match:
        '@ID_PATH': '{{sysfs}}'
  USBVideo:
    match:
        '@ID_PATH': '{{sysfs}}'
{% endfor %}

I'd rather properly document this than adding a special case for group parsing.

[sjg20]

We already provide jinja2 templating in the exporter configuration, so a lot of USB resources can be added at once:

{% for idx, sysfs in [
        ('1', 'pci-0000:0d:00.4-usb-0:1.3'),
        ('2', 'pci-0000:0d:00.4-usb-0:1.2'),
        ('3', 'pci-0000:0d:00.4-usb-0:1.1'),
        ('4', 'pci-0000:0d:00.4-usb-0:1.4.4'),
        ('5', 'pci-0000:0d:00.4-usb-0:1.4.3'),
        ('6', 'pci-0000:0d:00.4-usb-0:1.4.2'),
        ('7', 'pci-0000:0d:00.4-usb-0:1.4.1')] %}

{% for if in [ '1.0', '1.1', '1.2', '1.3'] %}
lb-dlink-7-p{{idx}}-{{if}}:
  location: "7 Port Hub auf dem Schreibtisch"
  USBSerialPort:
    match:
      '@ID_PATH': '{{sysfs}}:{{if}}'
{% endfor %}

lb-usb3-7-p{{idx}}:
  location: "7 Port Hub auf dem Schreibtisch"
  IMXUSBLoader:
    match:
        'ID_PATH': '{{sysfs}}'
  AndroidFastboot:
    match:
        'ID_PATH': '{{sysfs}}'
  USBSDMuxDevice:
    match:
        '@ID_PATH': '{{sysfs}}'
  USBVideo:
    match:
        '@ID_PATH': '{{sysfs}}'
{% endfor %}

I'd rather properly document this than adding a special case for group parsing.

Thanks for looking at this!

I did look at the templating. It is very powerful but also a bit fiddly for hubs. My proposal is to build in hubs as first-class citizens.

Here is an example, showing how this approach is very easy to follow. It is also self-documenting. The important distinction is that I can look at the board, immediately see which hub has the USB, if it needs a replug, etc.

hubs:
  a:
    base: 'pci-0000:00:14.0-usb-0:10'
    ports:
      1: '2.1'
      2: '2.2'
      3: '2.3'
      4: '2.4'
      5: '3.1'
      6: '3.2'
      7: '3.3'
      8: '3.4'
      9: '4.1'
      10: '4.2'
      11: '4.3'
      12: '4.4'
      13: '1.1'
      14: '1.2'
      15: '1.3'
      16: '1.4'

olimex-a20:
  USBSerialPort:
    match:
      hub: a
      port: 2
      iface: '1.0'

  HIDRelay:
    index: 4
    match:
      hub: a
      port: 14

  SunxiUSBLoader:
    match:
      hub: a
      port: 12
      iface: '1.0'