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

Andrzej Pietrasiewicz avatar

Posted on 18/02/2019 by Andrzej Pietrasiewicz

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.

Comments (0)

Add a Comment

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

Latest Blog Posts

Bootstraping a minimal Arch Linux image


In this tutorial, we'll look at how to create a functional and simple Arch Linux virtual machine image, that can have network access, display…

An overview of the Panfrost driver


During the past few months significant progress has been made on the Open Source Arm Mali GPU driver front, culminating in the Panfrost…

Quick hack: Raspberry Pi meets Linux kernel mainline


With just a few simple steps, you can compile and boot a Raspberry Pi using the Linux kernel mainline source code. Here's how.

News from the Debian Cloud Team


Since the last Debian release, a number of changes have been made in the Debian Cloud Team, both on the technical & organisational level…

Panfrost update: A new kernel driver


Following two months of work to develop a new kernel driver for Midgard and Bifrost GPUs, the kernel side of Panfrost is now in a form close…

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


A look at how to implement USB gadget devices on Linux machines which have the necessary UDC hardware, automate the manual configfs process…

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-2019. All rights reserved. Website sitemap.