umockdev

umockdev — Build a test bed for testing software that handles Linux hardware devices.

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── UMockdevTestbed

Description

Please see README.md about an overview of the parts of umockdev, and how they fit together.

Functions

umockdev_testbed_new ()

UMockdevTestbed *
umockdev_testbed_new (void);

Create a new UMockdevTestbed object. This is initially empty, call methods like umockdev_testbed_add_device or umockdev_testbed_add_from_string to fill it.

Returns

The newly created UMockdevTestbed object.


umockdev_testbed_add_device ()

gchar *
umockdev_testbed_add_device (UMockdevTestbed *self,
                             const gchar *subsystem,
                             const gchar *name,
                             const gchar *parent,
                             ...);

Add a new device to the testbed. A Linux kernel device always has a subsystem (such as "usb" or "pci"), and a device name. The test bed only builds a very simple sysfs structure without nested namespaces, so it requires device names to be unique. Some gudev client programs might make assumptions about the name (e. g. a SCSI disk block device should be called sdaN). A device also has an arbitrary number of sysfs attributes and udev properties; usually you should specify them upon creation, but it is also possible to change them later on with umockdev_testbed_set_attribute() and umockdev_testbed_set_property().

This will synthesize an "add" uevent.

Example:

1
2
3
umockdev_testbed_add_device (testbed, "usb", "dev1", NULL,
                           "idVendor", "0815", "idProduct", "AFFE", NULL,
                           "ID_MODEL", "KoolGadget", NULL);

[skip]

Parameters

self

A UMockdevTestbed.

 

subsystem

The subsystem name, e. g. "usb"

 

name

The device name; arbitrary, but needs to be unique within the testbed

 

parent

device path of the parent device. Use NULL for a top-level device.

[allow-none]

...

Arbitrarily many pairs of sysfs attributes (alternating names and values), terminated by NULL, followed by arbitrarily many pairs of udev properties, terminated by another NULL.

 

Returns

The sysfs path for the newly created device. Free with g_free().


umockdev_testbed_add_devicev ()

gchar *
umockdev_testbed_add_devicev (UMockdevTestbed *self,
                              const gchar *subsystem,
                              const gchar *name,
                              const gchar *parent,
                              gchar **attributes,
                              gchar **properties);

This method is mostly meant for language bindings (where it is named umockdev_testbed_add_device()). For C programs it is usually more convenient to use umockdev_testbed_add_device().

Add a new device to the testbed. A Linux kernel device always has a subsystem (such as "usb" or "pci"), and a device name. The test bed only builds a very simple sysfs structure without nested namespaces, so it requires device names to be unique. Some gudev client programs might make assumptions about the name (e. g. a SCSI disk block device should be called sdaN). A device also has an arbitrary number of sysfs attributes and udev properties; usually you should specify them upon creation, but it is also possible to change them later on with umockdev_testbed_set_attribute() and umockdev_testbed_set_property().

This will synthesize an "add" uevent.

Parameters

self

A UMockdevTestbed.

 

subsystem

The subsystem name, e. g. "usb"

 

name

The device name; arbitrary, but needs to be unique within the testbed

 

parent

device path of the parent device. Use NULL for a top-level device.

[allow-none]

attributes

A list of device sysfs attributes, alternating names and values, terminated with NULL: { "key1", "value1", "key2", "value2", ..., NULL }.

[array zero-terminated=1]

properties

A list of device udev properties; same format as attributes .

[array zero-terminated=1]

Returns

The sysfs path for the newly created device. Free with g_free().

Rename to: umockdev_testbed_add_device


umockdev_testbed_remove_device ()

void
umockdev_testbed_remove_device (UMockdevTestbed *self,
                                const gchar *syspath);

Remove a device from the testbed. This removes the sysfs directory, the /sys/class/ link, the device node, and all other information related to it. Note that this will also remove all child devices (i. e. subdirectories of syspath ).

Parameters

self

A UMockdevTestbed.

 

syspath

Sysfs path of device

 

umockdev_testbed_get_root_dir ()

gchar *
umockdev_testbed_get_root_dir (UMockdevTestbed *self);

Get the root directory for the testbed. This is mostly useful for setting up the "dev/" or "proc/" testbed directories in this root directory. For getting the mocked "sys/" dir, use umockdev_testbed_get_sys_dir.

Parameters

self

A UMockdevTestbed.

 

Returns

The testbed's root directory.


umockdev_testbed_get_sys_dir ()

gchar *
umockdev_testbed_get_sys_dir (UMockdevTestbed *self);

Get the sysfs directory for the testbed.

Parameters

self

A UMockdevTestbed.

 

Returns

The testbed's sysfs directory.


umockdev_testbed_set_attribute ()

void
umockdev_testbed_set_attribute (UMockdevTestbed *self,
                                const gchar *devpath,
                                const gchar *name,
                                const gchar *value);

Set a text sysfs attribute for a device.

Parameters

self

A UMockdevTestbed.

 

devpath

The full device path, as returned by umockdev_testbed_add_device()

 

name

Attribute name

 

value

Attribute string value

 

umockdev_testbed_set_attribute_int ()

void
umockdev_testbed_set_attribute_int (UMockdevTestbed *self,
                                    const gchar *devpath,
                                    const gchar *name,
                                    gint value);

Set an integer sysfs attribute for a device.

Parameters

self

A UMockdevTestbed.

 

devpath

The full device path, as returned by umockdev_testbed_add_device()

 

name

Attribute name (may contain leading directories like "queue/rotational")

 

value

Attribute integer value

 

umockdev_testbed_set_attribute_hex ()

void
umockdev_testbed_set_attribute_hex (UMockdevTestbed *self,
                                    const gchar *devpath,
                                    const gchar *name,
                                    guint value);

Set an integer sysfs attribute for a device. Set an integer udev property for a device. value is interpreted as a hexadecimal number. For example, for value==31 this sets the attribute contents to "1f".

Parameters

self

A UMockdevTestbed.

 

devpath

The full device path, as returned by umockdev_testbed_add_device()

 

name

Attribute name

 

value

Attribute integer value

 

umockdev_testbed_set_attribute_binary ()

void
umockdev_testbed_set_attribute_binary (UMockdevTestbed *self,
                                       const gchar *devpath,
                                       const gchar *name,
                                       guint8 *value,
                                       gint value_length1);

Set a binary sysfs attribute for a device.

Parameters

self

A UMockdevTestbed.

 

devpath

The full device path, as returned by umockdev_testbed_add_device()

 

name

Attribute name (may contain leading directories like "queue/rotational")

 

value

Attribute binary value

 

value_length1

Length of value in bytes.

 

umockdev_testbed_set_attribute_link ()

void
umockdev_testbed_set_attribute_link (UMockdevTestbed *self,
                                     const gchar *devpath,
                                     const gchar *name,
                                     const gchar *value);

Set a symlink sysfs attribute for a device; this is primarily important for setting "driver" links.

Parameters

self

A UMockdevTestbed.

 

devpath

The full device path, as returned by umockdev_testbed_add_device()

 

name

Attribute name

 

value

Attribute link target value

 

umockdev_testbed_set_property ()

void
umockdev_testbed_set_property (UMockdevTestbed *self,
                               const gchar *devpath,
                               const gchar *name,
                               const gchar *value);

Set a string udev property for a device.

Parameters

self

A UMockdevTestbed.

 

devpath

The full device path, as returned by umockdev_testbed_add_device()

 

name

Property name

 

value

Property string value

 

umockdev_testbed_set_property_int ()

void
umockdev_testbed_set_property_int (UMockdevTestbed *self,
                                   const gchar *devpath,
                                   const gchar *name,
                                   gint value);

Set an integer udev property for a device.

Parameters

self

A UMockdevTestbed.

 

devpath

The full device path, as returned by umockdev_testbed_add_device()

 

name

Property name

 

value

Property integer value

 

umockdev_testbed_set_property_hex ()

void
umockdev_testbed_set_property_hex (UMockdevTestbed *self,
                                   const gchar *devpath,
                                   const gchar *name,
                                   guint value);

Set an integer udev property for a device. value is interpreted as a hexadecimal number. For example, for value==31 this sets the property's value to "1f".

Parameters

self

A UMockdevTestbed.

 

devpath

The full device path, as returned by umockdev_testbed_add_device()

 

name

Property name

 

value

Property integer value

 

umockdev_testbed_get_property ()

gchar *
umockdev_testbed_get_property (UMockdevTestbed *self,
                               const gchar *devpath,
                               const gchar *name);

Get a string udev property for a device. Note that this is mostly for testing umockdev itself; for real application testing, use libudev/gudev.

Parameters

self

A UMockdevTestbed.

 

devpath

The full device path, as returned by umockdev_testbed_add_device()

 

name

Property name

 

Returns

property value, or NULL if it does not exist


umockdev_testbed_uevent ()

void
umockdev_testbed_uevent (UMockdevTestbed *self,
                         const gchar *devpath,
                         const gchar *action);

Generate an uevent for a device.

Parameters

self

A UMockdevTestbed.

 

devpath

The full device path, as returned by umockdev_testbed_add_device()

 

action

"add", "remove", or "change"

 

umockdev_testbed_add_from_string ()

gboolean
umockdev_testbed_add_from_string (UMockdevTestbed *self,
                                  const gchar *data,
                                  GError **error);

Add a set of devices to the testbed from a textual description. This reads the format generated by the umockdev-record tool.

Each paragraph defines one device. A line starts with a type tag (like 'E'), followed by a colon, followed by either a value or a "key=value" assignment, depending on the type tag. A device description must start with a 'P:' line. Available type tags are:

  • P:path: device path in sysfs, starting with /devices/; must occur exactly once at the start of device definition
  • E:key=value: udev property
  • A:key=value: ASCII sysfs attribute, with backslash-style escaping of \ (\\) and newlines (\n)
  • H:key=value: binary sysfs attribute, with the value being written as continuous hex string (e. g. 0081FE0A..)
  • N:devname[=contents]: device node name (without the /dev/ prefix); if contents is given (encoded in a continuous hex string), it creates a /dev/devname in the mock environment with the given contents, otherwise the created dev file will be a pty; see umockdev_testbed_get_dev_fd for details.
  • S:linkname: device node symlink (without the /dev/ prefix); ignored right now.

Parameters

self

A UMockdevTestbed.

 

data

Description of the device(s) as generated with umockdev-record

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE if the data is invalid and an error occurred.


umockdev_testbed_add_from_file ()

gboolean
umockdev_testbed_add_from_file (UMockdevTestbed *self,
                                const gchar *path,
                                GError **error);

Add a set of devices to the testbed from a textual description. This reads a file with the format generated by the umockdev-record tool, and is mostly a convenience wrapper around umockdev_testbed_add_from_string .

Parameters

self

A UMockdevTestbed.

 

path

Path to file with description of the device(s) as generated with umockdev-record

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE if the path cannot be read or thhe data is invalid and an error occurred.


umockdev_testbed_attach_ioctl ()

gboolean
umockdev_testbed_attach_ioctl (UMockdevTestbed *self,
                               const gchar *dev,
                               UMockdevIoctlBase *handler,
                               GError **error);

Attach an UMockdevIoctlBase object to handle ioctl, read and write syscalls on the given device file. This allows emulating arbitrary ioctl's and read/write calls for which umockdev does not have builtin support.

Parameters

self

A UMockdevTestbed.

 

dev

Device path (/dev/...) to attach to.

 

handler

a UMockdevIoctlBase instance to handle requests

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error.

Since: 0.16


umockdev_testbed_detach_ioctl ()

gboolean
umockdev_testbed_detach_ioctl (UMockdevTestbed *self,
                               const gchar *dev,
                               GError **error);

Detach a custom UMockdevIoctlBase object from an device node again. See umockdev_testbed_attach_ioctl(). It is an error to call this function if the path is not currently attached.

Parameters

self

A UMockdevTestbed.

 

dev

Device path (/dev/...) to detach.

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error.

Since: 0.16


umockdev_testbed_load_ioctl ()

gboolean
umockdev_testbed_load_ioctl (UMockdevTestbed *self,
                             const gchar *dev,
                             const gchar *recordfile,
                             GError **error);

Load an ioctl record file for a particular device into the testbed. ioctl records can be created with umockdev-record --ioctl. They can optionally be xz compressed to save space (but then are required to have an .xz file name suffix).

Parameters

self

A UMockdevTestbed.

 

dev

Device path (/dev/...) for which to load the ioctl record. NULL is valid; in this case the ioctl record is associated with the device node it was recorded from.

 

recordfile

Path of the ioctl record file.

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE if the data is invalid and an error occurred.


umockdev_testbed_load_pcap ()

gboolean
umockdev_testbed_load_pcap (UMockdevTestbed *self,
                            const gchar *sysfs,
                            const gchar *recordfile,
                            GError **error);

Load a USB pcap/pcapng recording created using e.g. wireshark. The device must have been added previously as the device path in /dev as well as the bus and device numbers need to be extraced from the udev information.

Parameters

self

A UMockdevTestbed.

 

sysfs

sysfs path for device (/sys/...)

 

recordfile

Path of the pcap or pcapng file.

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE if the recording could not be loaded

Since: 0.16


umockdev_testbed_load_script ()

gboolean
umockdev_testbed_load_script (UMockdevTestbed *self,
                              const gchar *dev,
                              const gchar *recordfile,
                              GError **error);

Load a script record file for a particular device into the testbed. script records can be created with umockdev-record --script.

Parameters

self

A UMockdevTestbed.

 

dev

Device path (/dev/...) for which to load the script record. NULL is valid; in this case the script is associated with the device node it was recorded from.

 

recordfile

Path of the script record file.

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE if recordfile is invalid and an error occurred.


umockdev_testbed_load_socket_script ()

gboolean
umockdev_testbed_load_socket_script (UMockdevTestbed *self,
                                     const gchar *path,
                                     gint type,
                                     const gchar *recordfile,
                                     GError **error);

Add an Unix socket to the testbed that is backed by a recorded script. Clients can connect to the socket using path (i. e. without the testbed prefix).

Parameters

self

A UMockdevTestbed.

 

path

Unix socket path

 

type

Unix socket type (SOCK_STREAM, SOCK_DGRAM)

 

recordfile

Path of the script record file.

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE if the path or type are invalid and an error occurred.


umockdev_testbed_load_evemu_events ()

gboolean
umockdev_testbed_load_evemu_events (UMockdevTestbed *self,
                                    const gchar *dev,
                                    const gchar *eventsfile,
                                    GError **error);

Load an evemu event file for a particular device into the testbed. These have a very simple line-based format with 4 fields that represent the data in a struct input_event:

E: sec.usec evtype(hex) evcode(hex) evvalue

The timestamps in those are absolute, and are usually as they were at record time. When loading them into umockdev they are interpreted relatively: the first event happens immediately, and the time to the next event is the difference between the corresponding timestamps in the .event file.

Parameters

self

A UMockdevTestbed.

 

dev

Device path (/dev/...) for which to load the evemu events. NULL is valid; in this case the events are associated with the device node it was recorded from.

 

eventsfile

Path of the evemu events file.

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE if eventsfile is invalid and an error occurred.


umockdev_testbed_get_dev_fd ()

gint
umockdev_testbed_get_dev_fd (UMockdevTestbed *self,
                             const gchar *devnode);

Simulated devices without a pre-defined contents are backed by a stream-like device node (PTY). Return the file descriptor for accessing their "master" side, i. e. the end that gets controlled by test suites. The tested program opens the "slave" side, which is just openening the device specified by devnode , e. g. /dev/ttyUSB2. Once that happened, your test can directly communicate with the tested program over that descriptor.

Parameters

self

A UMockdevTestbed.

 

devnode

Device node name ("/dev/...")

 

Returns

File descriptor for communicating with clients that connect to devnode , or -1 if devnode does not exist or is not a simulated stream device. This must not be closed!


umockdev_testbed_clear ()

void
umockdev_testbed_clear (UMockdevTestbed *self);

Remove all added devices from testbed directory. After that, the umockdev root directory will be in the same state as directly after the constructor.

Parameters

self

A UMockdevTestbed.

 

umockdev_testbed_disable ()

void
umockdev_testbed_disable (UMockdevTestbed *self);

Disable the testbed. This can be used for temporarily switching back to the real /sys and /dev without having to destroy or change $UMOCKDEV_DIR and the UMockdevTestbed instance. Use umockdev_testbed_enable() to re-enable the testbed.

Parameters

self

A UMockdevTestbed.

 

umockdev_testbed_enable ()

void
umockdev_testbed_enable (UMockdevTestbed *self);

Re-enable the testbed after @umockdev_testbed_disable() .

Parameters

self

A UMockdevTestbed.

 

Types and Values

struct UMockdevTestbed

struct UMockdevTestbed;

The UMockdevTestbed class builds a temporary sandbox for mock devices. You can add a number of devices including arbitrary sysfs attributes and udev properties, and then run your software in that test bed that is independent of the actual hardware it is running on. With this you can simulate particular hardware in virtual environments up to some degree, without needing any particular privileges or disturbing the whole system.

You can either add devices by specifying individual device paths, properties, and attributes, or use the umockdev-record tool to create a human readable/editable record of a real device (and all its parents) and load that into the testbed with umockdev_testbed_add_from_string().

Instantiating a UMockdevTestbed object creates a temporary directory with an empty sysfs tree and sets the $UMOCKDEV_DIR environment variable so that programs subsequently started under umockdev-wrapper will use the test bed instead of the system's real sysfs.