.\" driverctl - Device driver control utility

.TH driverctl 8

.SH NAME

driverctl - Device driver control utility.

.SH SYNOPSIS

\fBdriverctl\fR [OPTIONS] COMMAND [DEVICE [DRIVER]]\fR

.SH DESCRIPTION

\fBdriverctl\fR may be used to manipulate and inspect the system

device driver choices.

Devices are normally assigned to their sole designated kernel driver

by default. However in some situations it may be desireable to

override that default, for example to try an older driver to

work around a regression in a driver or to try an experimental alternative

driver. Another common use-case is pass-through drivers and driver

stubs to allow userspace to drive the device, such as in case of

virtualization.

\fBdriverctl\fR integrates with \fBudev\fR to support overriding

driver selection for both cold- and hotplugged devices from the

moment of discovery, but can also change already assigned drivers,

assuming they are not in use by the system. The driver overrides

created by \fBdriverctl\fR are persistent across system reboots

by default.

.SH OPTIONS

.PP

The following options are understood:

.PP

\fB-b|--bus <BUS>\fR

.RS 4

Operate on devices on a given bus, such as \fBpci\fR or \fBusb\fR.

Available options depend on system hardware and kernel, for example

as of kernel 4.6.7 the USB subsystem does not yet support driver_override.

By default \fBpci\fR bus is used.

.RE

.PP

\fB--debug|--verbose|-v\fR

.RS 4

Verbose mode, output more detailed information during operation.

.RE

.PP

\fB-h|--help\fR

.RS 4

Output usage information.

.RE

.PP

\fB--noprobe\fR

.RS 4

Do not (re)probe the device after changing the driver. Applies to

the \fB*-override\fR commands.

.RE

.PP

\fB--nosave\fR

.RS 4

Do not set/unset permanently. Applies to \fBset-override\fR and

\fBunset-override\fR commands.

.RE

.SH COMMANDS

.PP

The following commands are understood:

.PP

\fBset-override\fR <DEVICE> <DRIVER>

.RS 4

Set a driver override for a device. By default the current driver

is unbound from the device, the new driver is loaded into kernel,

bound and the override is saved permanently.

As a special case, specifying "none" as the driver will prevent

any driver to be bound to the device until the override is removed.

.RE

.PP

\fBunset-override\fR <DEVICE>

.RS 4

Unset a driver override for a device. By default the current driver

is unbound from the device, the default driver of the device is bound

and the override is permanently removed.

.RE

.PP

\fBload-override\fR <DEVICE>

.RS 4

Load a previously set driver override for device from disk. There's

usually no need to invoke this manually, the command exists mostly

for udev interaction.

.RE

.PP

\fBlist-devices\fR [DEVICETYPE]

.RS 4

List currently plugged, overridable system devices on a bus (\fBpci\fR

by default) along with their current drivers. Any overridden drivers

are marked with \fB[*]\fR. With \fB-v\fR options, additional device

description from udev database is shown to help identify devices.

It is possible to limit displayed devices by specifying a device type

as an optional argument, for example "network" to list only network devices.

.RE

.PP

\fBlist-overrides\fR [DEVICETYPE]

.RS 4

List currently overridden devices on a bus (\fBpci\fR by default)

With \fB-v\fR options, additional device

description from udev database is shown to help identify devices.

It is possible to limit displayed devices by specifying a device type

as an optional argument, for example "network" to list only network devices.

.RE

.SH "EXIT STATUS"

On success, 0 is returned, a non-zero failure code otherwise.

.SH EXAMPLES

.nf

Find devices currently driven by \fBixgbe\fR driver:

# driverctl -v list-devices | grep ixgbe

0000:01:00.0 ixgbe (Ethernet 10G 4P X520/I350 rNDC)

0000:01:00.1 ixgbe (Ethernet 10G 4P X520/I350 rNDC)

Change them to use the \fBvfio-pci\fR driver:

# driverctl set-override 0000:01:00.0 vfio-pci

# driverctl set-override 0000:01:00.1 vfio-pci

Find devices with driver overrides:

# driverctl -v list-overrides

0000:01:00.0 vfio-pci (Ethernet 10G 4P X520/I350 rNDC)

0000:01:00.1 vfio-pci (Ethernet 10G 4P X520/I350 rNDC)

Find network devices:

# driverctl list-devices network

0000:01:00.0 ixgbe

0000:01:00.1 ixgbe

0000:06:00.0 igb

0000:06:00.1 igb

Remove the override from slot 0000:01:00.1:

# driverctl unset-override 0000:01:00.1

.SH FILES

\fI/etc/driverctl.d/*\fR

.SH "SEE ALSO"

\fBudev\fR(7)

\fBudevadm\fR(8)

\fBlspci\fR(8)

\fBlsusb\fR(8)