libudev and Sysfs Tutorial

Introduction and Motivation

On Unix and Unix-like systems, hardware devices are accessed through special files (also called device files or nodes) located in the /dev directory. These files are read from and written to just like normal files, but instead of writing and reading data on a disk, they communicate directly with a kernel driver which then communicates with the hardware. There are many online resources describing /dev files in more detail. Traditonally, these special files were created at install time by the distribution, using the mknod command. In recent years, Linux systems began using udev to manage these /dev files at runtime. For example, udev will create nodes when devices are detected and delete them when devices are removed (including hotplug devices at runtime). This way, the /dev directory contains (for the most part) only entries for devices which actually exist on the system at the current time, as opposed to devices which could exist.

Udev also has a powerful scripting interface (with files commonly located in /etc/udev/rules.d) which distributors (and end users) often use to customize the way device nodes are created. Customizable properties include file permissions, location within the filesystem, and symbolic links. As could be imagined, this customization can make it difficult for application writers to locate specific device files (or types of devices), because they could be easily moved by modifying the udev rules. For example, in recent years, the js (joystick) nodes were moved from /dev to /dev/input. Many older programs explicitly opened devices in /dev (for example /dev/js0). When these older programs are run today, and try to open /dev/js0, they will simply not work since /dev/js0 has been moved.

Another problem is that when using multiple devices of the same type, the order in which they appear in /dev is not guaranteed to be the same every time. This often happens with USB devices. Some USB devices will show up in a different order after a reboot even when plugged into the same USB ports. I've observed this directly with FTDI USB serial ports. For example, with two of these ports plugged in, udev will create /dev/ttyUSB0 and /dev/ttyUSB1, but the order is undefined. (This particular problem can be worked around by creating udev rules which create symlinks based on something like a device serial number).

Another issue is that when dealing with things like HID devices, simply knowing that an entry such as /dev/hidraw0 exists tells you nothing about what kind of device it is. It could be any type of HID device.

The Solution - sysfs

Sysfs is a virtual filesystem exported by the kernel, similar to /proc. The files in Sysfs contain information about devices and drivers. Some files in Sysfs are even writable, for configuration and control of devices attached to the system. Sysfs is always mounted on /sys.

The directories in Sysfs contain the heirarchy of devices, as they are attached to the computer. For example, on my computer, the hidraw0 device is located under:

/sys/devices/pci0000:00/0000:00:12.2/usb1/1-5/1-5.4/1-5.4:1.0/0003:04D8:003F.0001/hidraw/hidraw0

Based on the path, the device is attached to (roughly, starting from the end) configuration 1 (:1.0) of the device attached to port number 4 of device 1-5, connected to USB controller 1 (usb1), connected to the PCI bus. While interesting, this directory path doesn't do us very much good, since it's dependent on how the hardware is physically connected to the computer.

Fortunately, Sysfs also provides a large number of symlinks, for easy access to devices without having to know which PCI and USB ports they are connected to. In /sys/class there is a directory for each different class of device. My /sys/class directory looks like this:

alan@ato:/sys/class$ ls
 atm graphics ieee1394_protocol printer thermal backlight hidraw input rfkill tty bdi hwmon mem scsi_device usb block i2c-adapter misc scsi_disk vc bluetooth ide_port net scsi_generic video_output dma ieee1394 pci_bus scsi_host vtconsole dmi ieee1394_host power_supply sound firmware ieee1394_node ppdev spi_master 

Following our example of using hidraw, one can see that there is a hidraw directory here. Inside it is a symbolic link named hidraw0 which points to

../../devices/pci0000:00/0000:00:12.2/usb1/1-5/1-5.4/1-5.4:1.0/0003:04D8:003F.0001/hidraw/hidraw0

This way, hidraw devices can easily be found under /sys/class/hidraw without knowing anything about their USB or PCI heirarchy. It would be a good exercise to examine the contents of the /sys directory, especially /sys/bus, /sys/class, and /sys/subsystem. Since much of /sys is symbolic links, it may also benefit you to use the utility realpath to show physical directory paths, as opposed to symbolic link paths. This is useful when trying to find the actual parent directories of device directories. For example, to find the containing USB device entry for hidraw0, one could use realpath to do something like the following:

alan@ato:/sys$ cd /sys/class/hidraw/hidraw0/
alan@ato:/sys/class/hidraw/hidraw0$ ls
dev  device power  subsystem  uevent
alan@ato:/sys/class/hidraw/hidraw0$ cd `realpath $PWD`
alan@ato:/sys/devices/pci0000:00/0000:00:12.2/usb2/2-5/2-5.4/2-5.4:1.0/0003:04D8:003F.0001/hidraw/hidraw0$ ls
dev  device power  subsystem  uevent
alan@ato:/sys/devices/pci0000:00/0000:00:12.2/usb2/2-5/2-5.4/2-5.4:1.0/0003:04D8:003F.0001/hidraw/hidraw0$ cd ../../../../
alan@ato:/sys/devices/pci0000:00/0000:00:12.2/usb2/2-5/2-5.4$ ls
2-5.4:1.0            bDeviceSubClass     configuration  idProduct     remove
authorized           bmAttributes        descriptors    idVendor      serial
avoid_reset_quirk    bMaxPacketSize0     dev            manufacturer  speed
bcdDevice            bMaxPower           devnum         maxchild      subsystem
bConfigurationValue  bNumConfigurations  devpath        power         uevent
bDeviceClass         bNumInterfaces      driver         product       urbnum
bDeviceProtocol      busnum              ep_00          quirks
version
alan@ato:/sys/devices/pci0000:00/0000:00:12.2/usb2/2-5/2-5.4$ 

libudev

Because it's cumbersome and error-prone to walk the Sysfs tree from within an application's code, there's a convenient library called libudev to do this task for us. Currently, the closest thing to a manual for libudev is the gtk-doc-genereated API reference located here:

http://www.kernel.org/pub/linux/utils/kernel/hotplug/libudev/

The documentation there is not really enough for the average developer to get started, so hopefully this guide and its example will make it a bit easier.

For the remainder of this guide, we'll be using libudev to access hidraw devices. Using libudev, we'll be able to inspect the devices, including their Vendor ID (VID), Product ID (PID), serial number, and device strings, without ever opening the device. Further, libudev will tell us exactly where inside /dev the device's node is located, giving the application a robust and distribution-independent way of accessing the device.

Building with libudev is as simple as including libudev.h and passing -ludev to the compiler to link with the libudev library.

The first example gets a list of the hidraw objects connected to the system, and prints out their device node path, manufacturer strings, and serial number. To do this, audev_enumerate object is created, and the text string "hidraw" is specified to be used as its filter. libudev will then return a list of udev_device objects which match the filter. In our example, this will be a list of all the hidraw devices attached to the system. The example code performs the following tasks:

1. Initialize the library, getting handle to a struct udev.
2. Enumerate the devices
3. For each device:
   1. Print its node name (eg: /dev/hidraw0).
   2. Find the ancestor node which represents the actual USB device (as opposed to the device's HID interface).
   3. Print the USB device information (IDs, serial number, etc).
   4. Unreference the device object.
4. Unreference the enumeration object.
5. Unreference the udev object.

#include <libudev.h>
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
#include <unistd.h> int main (void)
{
 struct udev *udev;
 struct udev_enumerate *enumerate;
 struct udev_list_entry *devices, *dev_list_entry;
 struct udev_device *dev;
 
 /* Create the udev object */
 udev = udev_new();
 if (!udev) {
  printf("Can't create udev\n");
  exit(1);
 }
 
 /* Create a list of the devices in the 'hidraw' subsystem. */
 enumerate = udev_enumerate_new(udev);
 udev_enumerate_add_match_subsystem(enumerate, "hidraw");
 udev_enumerate_scan_devices(enumerate);
 devices = udev_enumerate_get_list_entry(enumerate);
 /* For each item enumerated, print out its information. udev_list_entry_foreach is a macro which expands to a loop. The loop will be executed for each member in devices, setting dev_list_entry to a list entry which contains the device's path in /sys. */
 udev_list_entry_foreach(dev_list_entry, devices) {
  const char *path;
  
  /* Get the filename of the /sys entry for the device and create a udev_device object (dev) representing it */
  path = udev_list_entry_get_name(dev_list_entry);
  dev = udev_device_new_from_syspath(udev, path);

  /* usb_device_get_devnode() returns the path to the device node itself in /dev. */
  printf("Device Node Path: %s\n", udev_device_get_devnode(dev));

  /* The device pointed to by dev contains information about the hidraw device. In order to get information about the USB device, get the parent device with the subsystem/devtype pair of "usb"/"usb_device". This will be several levels up the tree, but the function will find it.*/
  dev = udev_device_get_parent_with_subsystem_devtype(
         dev,
         "usb",
         "usb_device");
  if (!dev) {
   printf("Unable to find parent usb device.");
   exit(1);
  }
 
  /* From here, we can call get_sysattr_value() for each file in the device's /sys entry. The strings passed into these functions (idProduct, idVendor, serial, etc.) correspond directly to the files in the directory which represents the USB device. Note that USB strings are Unicode, UCS2 encoded, but the strings returned from udev_device_get_sysattr_value() are UTF-8 encoded. */
  printf(" VID/PID: %s %s\n",
          udev_device_get_sysattr_value(dev,"idVendor"),
          udev_device_get_sysattr_value(dev, "idProduct"));
  printf(" %s\n %s\n",
          udev_device_get_sysattr_value(dev,"manufacturer"),
          udev_device_get_sysattr_value(dev,"product"));
  printf(" serial: %s\n",
           udev_device_get_sysattr_value(dev, "serial"));
  udev_device_unref(dev);
 }
 /* Free the enumerator object */
 udev_enumerate_unref(enumerate);

 udev_unref(udev);

 return 0;       
}

libudev programs can be compiled using the following:

gcc -Wall -g -o udev_example udev_example.c -ludev

On my system, I have a Microchip Application Demo connected, so my output is the following (notice how the non-ASCII, Unicode character from the USB serial number is propagated through to userspace as UTF-8):

alan@alan-desktop:~/tmp$ ./test_udev 
Device Node Path: /dev/hidraw0
  VID/PID: 04d8 003f
  Microchip Technology Inc.
  Simple HID Device Demo
  serial: 1234Å

Some Notes on libudev

Before moving on, it seems appropriate to mention some important things about libudev.

• libudev's functions are string-based. Since the data is coming directly from sysfs (which contains (virtual) files with text in them), all the data which comes from libudev is in text string format. This means that the user will have to manually convert strings to integer types if desired.
• The strings passed to udev_device_get_sysattr_value() correspond to file names in the sysfs tree. In this example, idVendor corresponds to

  /sys/devices/pci0000:00/0000:00:12.2/usb1/1-5/1-5.4/idVendor

  which can also be reached as (using the sysfs symlinks)

  /sys/bus/usb/devices/1-5.4/idVendor

  In order to find out which properties are available for a device, simply find the device in sysfs, and look at which files exist. On my system, my /sys/bus/usb/devices/1-5.4/ directory looks like the following:

  
  1-5.4:1.0            bDeviceSubClass     configuration  idProduct     remove
  authorized           bmAttributes        descriptors    idVendor      serial
  avoid_reset_quirk    bMaxPacketSize0     dev            manufacturer  speed
  bcdDevice            bMaxPower           devnum         maxchild      subsystem
  bConfigurationValue  bNumConfigurations  devpath        power         uevent
  bDeviceClass         bNumInterfaces      driver         product       urbnum
  bDeviceProtocol      busnum              ep_00          quirks
  version
  

  Any non-directory file or link in that directory can be queried with udev_device_get_sysattr_value() to determine the properties of the device.
• All the strings which come from sysfs are Unicode UTF-8. It is an error to assume that they are ASCII.
• libudev is reference counted. Instead of specifically allocating and freeing objects, ref() and unref() functions (such as udev_ref() and udev_unref()) are used for keeping track of how many references to an object exist. When the reference count drops to zero, the object is freed. Functions which return a new object return it with a reference count of 1, so calling its unref() function will effectively free it. See the libudev documentation (referenced above).

libudev - Monitoring Interface

libudev also provides a monitoring interface. The monitoring interface will report events to the application when the status of a device changes. This is useful for receiving notification when devices are connected or disconnected from the system. Like the enumeration interface described above, the monitoring interface also provides a filtering mechanisn, so that an application can subscribe to only events with which it is concerned. For example, if an application added "hidraw" to the filter, only events concerning hidraw devices would be delivered to the application. When a device changes state, the udev_monitor_receive_device() function will return a handle to a udev_device which represents the object which changed. The returned object can then be queried with the udev_device_get_action() function to determine which action occurred. The actions are returned as the following strings:

• add - Device is connected to the system
• remove - Device is disconnected from the system
• change - Something about the device changed
• move - Device node was moved, renamed, or re-parented

The udev_monitor_receive_device() function is blocking. That is, when called, program execution will stop until there is an event to be returned. This use case does not seem to be very useful. Fortunately, the udev_monitor object can provide a file descriptor, suitable for use with the select() system call. select() can be used to determine if a call toudev_monitor_receive_device() will block, providing a way to receive events in a non-blocking way.

The following code shows an example of the libudev monitor interface. The example runs a loop which executes select() to determine if there has been an event. If there has, it calls udev_monitor_receive_device() to receive the event and prints it out. At the end of the loop it sleep()'s for 250 milliseconds. In real life, a simple program like this would be just fine to not use select() and just let udev_monitor_receive_device() block, but it is written this way to show an example of how to get non-blocking behavior from thelibudev monitoring interface.

 /* Set up a monitor to monitor hidraw devices */
 mon = udev_monitor_new_from_netlink(udev, "udev");
 udev_monitor_filter_add_match_subsystem_devtype(mon, "hidraw", NULL);
 udev_monitor_enable_receiving(mon);
 /* Get the file descriptor (fd) for the monitor. This fd will get passed to select() */
 fd = udev_monitor_get_fd(mon);
 
 /* This section will run continuously, calling usleep() at the end of each pass. This is to demonstrate how to use a udev_monitor in a non-blocking way. */
 while (1) {
  /* Set up the call to select(). In this case, select() will only operate on a single file descriptor, the one associated with our udev_monitor. Note that the timeval object is set to 0, which will cause select() to not block. */
  fd_set fds;
  struct timeval tv;
  int ret;
  
  FD_ZERO(&fds);
  FD_SET(fd, &fds);
  tv.tv_sec = 0;
  tv.tv_usec = 0;
  
  ret = select(fd+1, &fds, NULL, NULL, &tv);
  
  /* Check if our file descriptor has received data. */
  if (ret > 0 && FD_ISSET(fd, &fds)) {
   printf("\nselect() says there should be data\n");
   
   /* Make the call to receive the device. select() ensured that this will not block. */
   dev = udev_monitor_receive_device(mon);
   if (dev) {
    printf("Got Device\n");
    printf(" Node: %s\n", udev_device_get_devnode(dev));
    printf(" Subsystem: %s\n", udev_device_get_subsystem(dev));
    printf(" Devtype: %s\n", udev_device_get_devtype(dev));

    printf(" Action: %s\n",udev_device_get_action(dev));
    udev_device_unref(dev);
   }
   else {
    printf("No Device from receive_device(). An error occured.\n");
   }     
  }
  usleep(250*1000);
  printf(".");
  fflush(stdout);
 }

It's important to note that when using monitoring and enumeration together, that monitoring should be enabled before enumeration. This way, any events (for example devices being attached to the system) which happen during enumeration will not be lost. If enumeration is done before monitoring is enabled, any device attached between the time the enumeration happens and when monitoring starts will be missed. The algorithm should be:

1. Set up monitoring.
2. Enumerate devices (optionally opening desired devices).
3. Begin checking the monitoring interface for events.

The example file (linked at the end of this document) uses enumeration and monitoring together, and follows this algorithm. The code above shows only monitoring, for simplicity.

Output

The code above will run forever. (Terminate it with Ctrl-C). With the above section of code running, the following data is printed out as I disconnect and reconnect my HID device (note that a . character is printed every 250 milliseconds):

...........................
select() says there should be data
Got Device
   Node: /dev/hidraw0
   Subsystem: hidraw
   Devtype: (null)
   Action: remove
.............
select() says there should be data
Got Device
   Node: /dev/hidraw0
   Subsystem: hidraw
   Devtype: (null)
   Action: add
......^C

Conclusion

The libudev interface is very useful for creating robust software which needs to access a specific hardware device or monitor the real-time connection and disconnection status of hot-pluggable hardware. I hope you find this document useful. The full source code of the demo is available through the following link:

udev_example.c