We're hiring!

Modern USB gadget on Linux & how to integrate it with systemd (Part 1)

Andrzej Pietrasiewicz avatar

Andrzej Pietrasiewicz
February 18, 2019

Share this post:

tl;dr: Automate your gadget creation. A look at how to implement USB gadget devices on Linux machines which have the necessary UDC hardware, automate the manual configfs process via declarative gadget "schemes", and use systemd for gadget composition at boot time.

The big picture

In order to understand what is a USB gadget we need to have a look at a broader picture. In USB there are two distinct roles: a host and a device. The purpose of USB is to extend the host with some functionalities provided by devices: be it a mass storage device, an Ethernet card on USB, a sound card or the like. On a given USB bus there can be only one host and many (up to 127) devices. The bus is host-centric, which means that all the activities happening on it are decided and directed by the host.

One way of implementing a USB device is to have a machine running Linux, equipped with a special piece of hardware called USB Device Controller (UDC), and appropriate software running on it. It is exactly this case we will be talking about in this post.

Linux machine as a USB device


The question you likely ask yourself is whether your machine has a UDC. In case of desktop PCs you most probably need a dedicated add-on card, which is not a very popular thing: there are not so many users who might want to convert their desktop PC into a USB device. But such boards do exist. The hardware supported by the Linux kernel can be found in drivers/usb/gadget/udc/Kconfig (line 306 in v5.0-rc6). In the embedded world a UDC is very often a part of your system-on-chip (SoC), but beware: merely having a UDC inside SoC does not mean that it is actually connected to anything on the board.

For example Raspberry Pi Zero's SoC does contain a UDC and it is connected to one of the micro USB sockets on the board. Other examples of suitably equipped boards are Odroid U3 and XU3, or Beagle Bone Black. If you don't have access to any hardware of this kind, fear not! You still can play (to some extent) with USB gadgets using an emulated UDC which is a part of the dummy_hcd kernel module. The dummy_hcd combines an emulated host controller with an emulated device controller, so your machine acts as both a USB host and a device. More on dummy_hcd will be in another blogpost which I'm going to write soon.

Oh, and one more thing: you can often come across the term OTG, which stands for on-the-go device and refers to chips which are capable of being either a host, or a device. For the purpose of this post we will be using the term UDC.


The Linux kernel provides drivers for various UDCs. But merely being able to drive a UDC is not enough to fully implement a USB device. What is missing is actual functionality, for example mass storage or Ethernet over USB. And here comes what USB standard says: a USB device can provide more than one functionality over a single USB cable at a time. A set of such functionalities is called a configuration. In fact the standard allows more than one configuration - only one can be active at a time, though - but devices providing more than one are rarely seen in practice.

In the Linux kernel an implementation of a USB device is called a USB gadget. This implementation of gadgets is nicely layered: there is a so called composite layer, which contains code common for all USB functionalities and allows composing gadgets out of several functionalities. The composite layer talks to the UDC driver. On top of the composite driver there are USB functionalities (such as mass storage or Ethernet), which are called USB functions. We will be focusing on the composite layer and functions.

A modern USB gadget

The traditional approach to gadgets composition was to create a kernel module for a given composition of a gadget. And even if you wanted only a slightly different set of USB functions in your gadget, you had to create another kernel module. Around late 2012 a new approach started appearing. The idea was to decouple information about gadget composition from code and only provide building blocks out of which the user composes their gadget at runtime. Very much in the spirit of "mechanism, not policy" philosophy. The interface chosen for userspace interaction was configfs (by default can be found in /sys/kernel/config). After about two years, all USB functions available in the Linux kernel had been converted to use the new interface.

The usage pattern is like this: the user creates a separate directory per each gadget they want to have, gives their gadget a personality by specifying vendor id, product id and USB strings (visible e.g. after running lsusb -v as root), then under that directory creates the configurations they want and instantiates USB functions they want (both by creating respective directories) and finally associates functions to configurations with symbolic links. At this point gadget's composition is already in memory, but is not bound to any UDC. To activate the gadget one must write UDC name to the UDC attribute in the gadget's configfs directory - the gadget then becomes bound to this particular UDC (and the UDC cannot be used by more than one gadget). Available UDC names are in /sys/class/udc. Only after a gadget is bound to a UDC can it be successfully enumerated by the USB host.

A working, minimal example of ECM (Ethernet) on an Odroid U3, which leaves some attributes at their default values:

# go to configfs directory for USB gadgets
CONFIGFS_ROOT=/sys/kernel/config # adapt to your machine
cd "${CONFIGFS_ROOT}"/usb_gadget

# create gadget directory and enter it
mkdir g1
cd g1

# USB ids
echo 0x1d6b > idVendor
echo 0x104 > idProduct

# USB strings, optional
mkdir strings/0x409 # US English, others rarely seen
echo "Collabora" > strings/0x409/manufacturer
echo "ECM" > strings/0x409/product

# create the (only) configuration
mkdir configs/c.1 # dot and number mandatory

# create the (only) function
mkdir functions/ecm.usb0 # .

# assign function to configuration
ln -s functions/ecm.usb0/ configs/c.1/

# bind!
echo 12480000.hsotg > UDC # ls /sys/class/udc to see available UDCs

Please note that your vendor id is assigned for a fee by USB Implementors Forum (USB IF) - this refers to products you want to put on the market. For your own tinkering you can choose whatever you like. However, these ids (vendor and product) can be used by the host to decide which host-side driver to use to talk to your device. 0x1d6b is for Linux Foundation and 0x0104 is for Ethernet Gagdet. If your USB host sees such ids it assumes it needs the cdc_ether host-side driver.

If your device is connected to a Linux host, then you shoud see output similar to the below in host's dmesg:

usb 3- New USB device found, idVendor=1d6b, idProduct=0104
usb 3- New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 3- Product: ECM
usb 3- Manufacturer: Collabora
cdc_ether 3- usb0: register 'cdc_ether' at usb-0000:3c:00.0-, CDC Ethernet Device, d2:c2:2d:b7:8e:6b

Note the Product and Manufacturer strings which are exactly what has been written to configfs.

A new usb interface should appear at the host side...

ifconfig -a

usb0: flags=4099<UP,BROADCAST,MULTICAST>  mtu 1500
        ether d2:c2:2d:b7:8e:6b  txqueuelen 1000  (Ethernet)
        RX packets 0  bytes 0 (0.0 B)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 1  bytes 90 (90.0 B)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

# why not configure it?
ifconfig usb0 up

...and at the device:

ifconfig -a

usb0: flags=4098<BROADCAST,MULTICAST>  mtu 1500
        ether f2:40:e6:d3:01:2c  txqueuelen 1000  (Ethernet)
        RX packets 0  bytes 0 (0.0 B)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 0  bytes 0 (0.0 B)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

# why not configure this one as well?
ifconfig usb0 up

# and ping the host?
PING ( 56(84) bytes of data.
64 bytes from icmp_seq=1 ttl=64 time=1.40 ms

Similarly, the device can be pinged from the host:

PING ( 56(84) bytes of data.
64 bytes from icmp_seq=1 ttl=64 time=1.06 ms

I want my modprobe g_ether back!

Poking around configfs is not difficult, but you need to know where to look, what to look for, what kind of directories to create and what values to write to particular files. And what to symlink from where. Creating a gadget containing just one function takes about 15-20 shell commands, which of course can be scripted. But it seems not a very nice approach. You can instead use an opensource tool called gt (https://github.com/kopasiak/gt) (requires https://github.com/libusbgx/libusbgx), which supports so called gadget schemes: instead of describing creating of your gadget procedurally (explicit shell commands) you describe it declaratively in a configuration file and the tool knows how to parse the file and do all the necessary configfs manipulation. This way modprobe g_ether can be changed to gt load my_ether.scheme, which is a very comparable amount of work :)

The scheme

A scheme corresponding to the above gadget is like this (let's call it ecm.scheme):

attrs : 
    idVendor = 0x1D6B;
    idProduct = 0x104;
strings = (
                lang = 0x409;
                manufacturer = "Collabora";
                product = "ECM";
functions : 
    ecm_usb0 : 
        instance = "usb0";
        type = "ecm";
configs = ( 
        id = 1;
        name = "c";
        functions = ( 
                name = "ecm.usb0";
                function = "ecm_usb0";
            } );
    } );

Now at the device side you can simply:

gt load ecm.scheme g1 # load the scheme and name the gadget 'g1'

and achieve the same gadget composition as with the above shell commands.

And systemd?

systemd is here. I'm not going to discuss whether it is a good thing or a bad thing. Instead, I want to share with you how you can have systemd compose your gadget, for example at system boot time. A typical example is to have your Ethernet connection over USB up and running and you want that controllable by systemd, so that you for example can systemctl enable/disable your gadget.

The event

The obvious event triggering our gadget creation is the appearance of a UDC in the system. https://github.com/systemd/systemd/issues/11587 points to a pull request, which adds a new udev rule for systemd:

SUBSYSTEM=="udc", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="usb-gadget.target"

The rule triggers reaching the usb-gadget.target, whose purpose is to mark the point when UDC is available and allow other units depend on it:

Description=Hardware activated USB gadget

The service

Now that we have a target to depend on, we can create a service which will be started once the target is reached. Let's call it usb-gadget.service.

Description=Load USB gadget scheme

ExecStart=/bin/gt load ecm.scheme ecm
ExecStop=/bin/gt rm -rf ecm


Such a service can be controlled with systemctl:

systemctl enable usb-gadget.service
systemctl disable usb-gadget.service

This way the usb-gadget.target can be reached with or without actually composing the gadget, or a different gadget can be chosen by the system administrator for each purpose.

I want my own USB function!

The selection of USB functions available for composition is quite large (20), but you still might need something else, for example some custom USB protocol. Or, even not so custom (such as e.g. ptp), but a protocol which is not likely to reach upstream kernel. What to do? FunctionFS to the rescue! I will talk about that in the next installment of this post, so stay tuned.

Continue reading (Modern USB gadget on Linux & how to integrate it with systemd - Part 2)

Comments (3)

  1. Diego Sueiro:
    Jul 01, 2019 at 07:06 AM

    Very interesting article.
    I'm trying to force the "dev_addr" and "host_addr" in the gadget scheme but I'm not able to do so.
    I added the options (dev_addr = "2e:2d:11:43:db:f7"; host_addr = "72:39:99:c0:06:24";) both after "type = "ecm";" and "function = "ecm_usb0";" lines but no success. When using gt load it allways configures with random MAC addr.

    Do you know how can I achieve this?

    Reply to this comment

    Reply to this comment

    1. Andrzej Pietrasiewicz:
      Jul 22, 2019 at 03:54 PM

      Hi, you need to put dev_addr and host_addr in the "attrs" section. This is required by libusbgx, which is used internally by gt. Please see https://github.com/libusbgx/libusbgx/blob/master/doc/gadget_schemes.txt for details.

      Reply to this comment

      Reply to this comment

  2. Sergei:
    Apr 20, 2022 at 05:01 PM

    Will this schema work if gadgets statically linked with kernel?

    Reply to this comment

    Reply to this comment

Add a Comment

Allowed tags: <b><i><br>Add a new comment:

Search the newsroom

Latest Blog Posts

Introducing the r600/NIR back-end


Adventures in NIR-land: the past, the present, and what's lies ahead for the native NIR back-end for Mesa's R600 driver.

Adding secondary command buffers to PanVk


Getting PanVk, an open source driver for Arm Mali Midgard and Bifrost GPUs, closer to conformancy by implementing one of the core Vulkan…

Bridging the synchronization gap on Linux


After fighting with the divide between implicit and explicit synchronization with Vulkan on Linux for over seven years, we may finally have…

Monado's hand tracking: hand-waving our way towards a first attempt


Optical hand tracking for XR has a bit of a reputation - getting training data, training neural nets, and deploying them in real-time, low-latency…

Visual-inertial tracking for Monado


Monado now has initial support for 6DoF ("inside-out") tracking for devices with cameras and an IMU! Three free and open source SLAM/VIO…

Spotlight on Meson's full-featured developer environment


When developing an application or a library, it is very common to want to run it without installing it, or to install it into a custom prefix…

Open Since 2005 logo

We use cookies on this website to ensure that you get the best experience. By continuing to use this website you are consenting to the use of these cookies. To find out more please follow this link.

Collabora Ltd © 2005-2022. All rights reserved. Privacy Notice. Sitemap.