driverctl(8)

1driverctl(8)                System Manager's Manual               driverctl(8)
2
3
4

NAME

6       driverctl - Device driver control utility.
7

SYNOPSIS

9       driverctl [OPTIONS] COMMAND [DEVICE [DRIVER]]
10
11

DESCRIPTION

13       driverctl  may  be  used  to  manipulate  and inspect the system device
14       driver choices.
15
16       Devices are normally assigned to their sole designated kernel driver by
17       default.  However  in  some situations it may be desireable to override
18       that default, for example to try an  older  driver  to  work  around  a
19       regression  in  a  driver or to try an experimental alternative driver.
20       Another common use-case is pass-through drivers  and  driver  stubs  to
21       allow userspace to drive the device, such as in case of virtualization.
22
23       driverctl  integrates  with udev to support overriding driver selection
24       for both cold- and hotplugged devices from the moment of discovery, but
25       can  also change already assigned drivers, assuming they are not in use
26       by the system. The driver overrides created by driverctl are persistent
27       across system reboots by default.
28
29

OPTIONS

31       The following options are understood:
32
33
34       -b|--bus <BUS>
35           Operate  on  devices on a given bus, such as pci or usb.  Available
36           options depend on system hardware and kernel,  for  example  as  of
37           kernel  4.6.7  the  USB subsystem does not yet support driver_over‐
38           ride.  By default pci bus is used.
39
40
41       --debug|--verbose|-v
42           Verbose mode, output more detailed information during operation.
43
44
45       -h|--help
46           Output usage information.
47
48
49       --noprobe
50           Do not (re)probe the device after changing the driver.  Applies  to
51           the *-override commands.
52
53
54       --nosave
55           Do  not  set/unset  permanently. Applies to set-override and unset-
56           override commands.
57
58

COMMANDS

60       The following commands are understood:
61
62
63       set-override <DEVICE> <DRIVER>
64           Set a driver override for a device. By default the  current  driver
65           is  unbound  from the device, the new driver is loaded into kernel,
66           bound and the override is saved permanently.
67
68           As a special case, specifying "none" as the driver will prevent any
69           driver to be bound to the device until the override is removed.
70
71
72       unset-override <DEVICE>
73           Unset a driver override for a device. By default the current driver
74           is unbound from the device, the default driver  of  the  device  is
75           bound and the override is permanently removed.
76
77
78       load-override <DEVICE>
79           Load a previously set driver override for device from disk. There's
80           usually no need to invoke this manually, the command exists  mostly
81           for udev interaction.
82
83
84       list-devices [DEVICETYPE]
85           List currently plugged, overridable system devices on a bus (pci by
86           default) along with their current drivers. Any  overridden  drivers
87           are marked with [*]. With -v options, additional device description
88           from udev database is shown to help identify devices.  It is possi‐
89           ble  to  limit  displayed devices by specifying a device type as an
90           optional argument, for  example  "network"  to  list  only  network
91           devices.
92
93
94       list-overrides [DEVICETYPE]
95           List currently overridden devices on a bus (pci by default) With -v
96           options, additional device description from udev database is  shown
97           to  help  identify  devices.   It  is  possible  to limit displayed
98           devices by specifying a device type as an  optional  argument,  for
99           example "network" to list only network devices.
100
101

EXIT STATUS

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

EXAMPLES

107       Find devices currently driven by ixgbe driver:
108
109       # driverctl -v list-devices | grep ixgbe
110       0000:01:00.0 ixgbe (Ethernet 10G 4P X520/I350 rNDC)
111       0000:01:00.1 ixgbe (Ethernet 10G 4P X520/I350 rNDC)
112
113       Change them to use the vfio-pci driver:
114       # driverctl set-override 0000:01:00.0 vfio-pci
115       # driverctl set-override 0000:01:00.1 vfio-pci
116
117       Find devices with driver overrides:
118       # driverctl -v list-overrides
119       0000:01:00.0 vfio-pci (Ethernet 10G 4P X520/I350 rNDC)
120       0000:01:00.1 vfio-pci (Ethernet 10G 4P X520/I350 rNDC)
121
122       Find network devices:
123       # driverctl list-devices network
124       0000:01:00.0 ixgbe
125       0000:01:00.1 ixgbe
126       0000:06:00.0 igb
127       0000:06:00.1 igb
128
129       Remove the override from slot 0000:01:00.1:
130       # driverctl unset-override 0000:01:00.1
131
132

FILES

134       /etc/driverctl.d/*
135
136