Use configfs to manage USB gadget

[drbild]

We are currently using the g_ether USB gadget driver to create and manage the ethernet-over-USB between the router card and the host. This approach is easy to implement (modprobe g_ether), but has a major disadvantage. It is hard coded to support just a single function, CDC ethernet.

A USB device can expose multiple interfaces and features, but the g_ether driver supports only one. Ultimately we want to support several features or interfaces:

• ethernet
• serial on the dev builds
• our "proxy tcp" functionality

configfs is the Linux kernel support for composing multiple USB gadget functions into one device from userspace using the filesystem. See here and here.

We need to modernize our USB gadget config from modprobe g_ether to use configfs.

Background

Gadgets are configured using configfs by creating and writing to a special filesystem. Each gadget configuration is represented by one directory, with a file inside for each piece of metadata (PID, VID, manufacturer name, power mode, etc.). Writing to those files sets that config. A subdirectory is created for each function, again with files inside to configure properties and metadata.

libusbgx is a C library for interacting with the configfs filesystem. It abstracts away the file-handling operations into a simple C API.

Configuring a gadget using configfs requires writing a script to manipulate the filesystem directory or a C program using libusbgx.

Alternative Approach

libusgbx introduced the idea of gadget "schemes", a declarative text file describing the USB gadget. These are much easier to read and write than the imperative commands to manipulate the filesystem.

Unfortunately, these scheme files aren't suitable for us. Some of the required information, like serial number, is only available at run time. Using a scheme would requiring expanding a template scheme at runtime to populate those dynamic variables. This requires additional software (like a template library) on the router card, which we would like to avoid for security reasons.

Approach

Write a C program that uses libusbgx to configure the USB gadget. This program can easily read the dynamic info (like serial number) as required. All of the logic and config will be contained in the one source file, not spread out across templates and template expansion scripts.

Requirements

• Create the USB gadget with one configuration using configfs
• Set the following attributes
  • idVendor = 0x2fe
  • idProduct = (depends on xap-rc-01 vs xap-rw-01, known at compile time)
  • bcdUSB = 0x0200
  • bcdDevice = 0x0000 (should be the firmware version number, e.g., 1.12. But it's low priority, so I'll open a separate issue to fix that later on.)
  • bcdDeviceClass = 0x00
  • bcdDeviceSubClass = 0x00
  • bcdDeviceProtocol = x00
• Set the following strings
  • lang = 0x409
  • manufacturer = "Xaptum, Inc."
  • product = (depends on xap-rc-01 "ENF Router Card" vs xap-rw-01 "ENF Router Card with Wi-Fi", known at compile time)
  • serialnumber = (read from /rom/serial_number)
• Include the CDC ethernet function
  • Set the following properties
    • instance = "usb0"
    • host_addr = (read from /rom/mac_address/1)
    • dev_addr = (read from /rom/mac_address/2)
• On dev builds, include the ACM (serial) function
  • Set the following properties
    • instance GS0

References

This libusbgx example does most of what we currently need. It should be a good starting point.

This branch has partial implementations using a variety of (rejected) templating approach. It might be a helpful reference for the specific properties to be set, but none of the code will be reusable.

[drbild]

@dberliner This is issue was resolved by #79 right?

[drbild]

Fixed by #79