2 # SPDX-License-Identifier: BSD-3-Clause
3 # Copyright(c) 2010-2014 Intel Corporation
6 from __future__ import print_function
11 from os.path import exists, abspath, dirname, basename
13 # The PCI base class for all devices
14 network_class = {'Class': '02', 'Vendor': None, 'Device': None,
15 'SVendor': None, 'SDevice': None}
16 acceleration_class = {'Class': '12', 'Vendor': None, 'Device': None,
17 'SVendor': None, 'SDevice': None}
18 ifpga_class = {'Class': '12', 'Vendor': '8086', 'Device': '0b30',
19 'SVendor': None, 'SDevice': None}
20 encryption_class = {'Class': '10', 'Vendor': None, 'Device': None,
21 'SVendor': None, 'SDevice': None}
22 intel_processor_class = {'Class': '0b', 'Vendor': '8086', 'Device': None,
23 'SVendor': None, 'SDevice': None}
24 cavium_sso = {'Class': '08', 'Vendor': '177d', 'Device': 'a04b,a04d',
25 'SVendor': None, 'SDevice': None}
26 cavium_fpa = {'Class': '08', 'Vendor': '177d', 'Device': 'a053',
27 'SVendor': None, 'SDevice': None}
28 cavium_pkx = {'Class': '08', 'Vendor': '177d', 'Device': 'a0dd,a049',
29 'SVendor': None, 'SDevice': None}
30 cavium_tim = {'Class': '08', 'Vendor': '177d', 'Device': 'a051',
31 'SVendor': None, 'SDevice': None}
32 cavium_zip = {'Class': '12', 'Vendor': '177d', 'Device': 'a037',
33 'SVendor': None, 'SDevice': None}
34 avp_vnic = {'Class': '05', 'Vendor': '1af4', 'Device': '1110',
35 'SVendor': None, 'SDevice': None}
37 octeontx2_sso = {'Class': '08', 'Vendor': '177d', 'Device': 'a0f9,a0fa',
38 'SVendor': None, 'SDevice': None}
39 octeontx2_npa = {'Class': '08', 'Vendor': '177d', 'Device': 'a0fb,a0fc',
40 'SVendor': None, 'SDevice': None}
41 octeontx2_dma = {'Class': '08', 'Vendor': '177d', 'Device': 'a081',
42 'SVendor': None, 'SDevice': None}
44 intel_ioat_bdw = {'Class': '08', 'Vendor': '8086', 'Device': '6f20,6f21,6f22,6f23,6f24,6f25,6f26,6f27,6f2e,6f2f',
45 'SVendor': None, 'SDevice': None}
46 intel_ioat_skx = {'Class': '08', 'Vendor': '8086', 'Device': '2021',
47 'SVendor': None, 'SDevice': None}
48 intel_ioat_icx = {'Class': '08', 'Vendor': '8086', 'Device': '0b00',
49 'SVendor': None, 'SDevice': None}
50 intel_ntb_skx = {'Class': '06', 'Vendor': '8086', 'Device': '201c',
51 'SVendor': None, 'SDevice': None}
53 network_devices = [network_class, cavium_pkx, avp_vnic, ifpga_class]
54 baseband_devices = [acceleration_class]
55 crypto_devices = [encryption_class, intel_processor_class]
56 eventdev_devices = [cavium_sso, cavium_tim, octeontx2_sso]
57 mempool_devices = [cavium_fpa, octeontx2_npa]
58 compress_devices = [cavium_zip]
59 misc_devices = [intel_ioat_bdw, intel_ioat_skx, intel_ioat_icx, intel_ntb_skx, octeontx2_dma]
61 # global dict ethernet devices present. Dictionary indexed by PCI address.
62 # Each device within this is itself a dictionary of device properties
64 # list of supported DPDK drivers
65 dpdk_drivers = ["igb_uio", "vfio-pci", "uio_pci_generic"]
66 # list of currently loaded kernel modules
69 # command-line arg flags
77 '''Print usage information for the program'''
78 argv0 = basename(sys.argv[0])
83 %(argv0)s [options] DEVICE1 DEVICE2 ....
85 where DEVICE1, DEVICE2 etc, are specified via PCI "domain:bus:slot.func" syntax
86 or "bus:slot.func" syntax. For devices bound to Linux kernel drivers, they may
87 also be referred to by Linux interface name e.g. eth0, eth1, em0, em1, etc.
91 Display usage information and quit
94 Print the current status of all known network, crypto, event
96 For each device, it displays the PCI domain, bus, slot and function,
97 along with a text description of the device. Depending upon whether the
98 device is being used by a kernel driver, the igb_uio driver, or no
99 driver, other relevant information will be displayed:
100 * the Linux interface name e.g. if=eth0
101 * the driver being used e.g. drv=igb_uio
102 * any suitable drivers not currently using that device
104 NOTE: if this flag is passed along with a bind/unbind option, the
105 status display will always occur after the other operations have taken
109 Print the status of given device group. Supported device groups are:
110 "net", "baseband", "crypto", "event", "mempool" and "compress"
112 -b driver, --bind=driver:
113 Select the driver to use or \"none\" to unbind the device
116 Unbind a device (Equivalent to \"-b none\")
119 By default, network devices which are used by Linux - as indicated by
120 having routes in the routing table - cannot be modified. Using the
121 --force flag overrides this behavior, allowing active links to be
123 WARNING: This can lead to loss of network connection and should be used
129 To display current device status:
132 To display current network device status:
133 %(argv0)s --status-dev net
135 To bind eth1 from the current driver and move to use igb_uio
136 %(argv0)s --bind=igb_uio eth1
138 To unbind 0000:01:00.0 from using any driver
139 %(argv0)s -u 0000:01:00.0
141 To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver
142 %(argv0)s -b ixgbe 02:00.0 02:00.1
144 """ % locals()) # replace items from local variables
147 # This is roughly compatible with check_output function in subprocess module
148 # which is only available in python 2.7.
149 def check_output(args, stderr=None):
150 '''Run a command and capture its output'''
151 return subprocess.Popen(args, stdout=subprocess.PIPE,
152 stderr=stderr).communicate()[0]
154 # check if a specific kernel module is loaded
155 def module_is_loaded(module):
156 global loaded_modules
158 if module == 'vfio_pci':
162 return module in loaded_modules
164 # Get list of sysfs modules (both built-in and dynamically loaded)
165 sysfs_path = '/sys/module/'
167 # Get the list of directories in sysfs_path
168 sysfs_mods = [m for m in os.listdir(sysfs_path)
169 if os.path.isdir(os.path.join(sysfs_path, m))]
171 # special case for vfio_pci (module is named vfio-pci,
172 # but its .ko is named vfio_pci)
173 sysfs_mods = [a if a != 'vfio_pci' else 'vfio-pci' for a in sysfs_mods]
175 loaded_modules = sysfs_mods
177 return module in sysfs_mods
181 '''Checks that igb_uio is loaded'''
184 # list of supported modules
185 mods = [{"Name": driver, "Found": False} for driver in dpdk_drivers]
187 # first check if module is loaded
189 if module_is_loaded(mod["Name"]):
192 # check if we have at least one loaded module
193 if True not in [mod["Found"] for mod in mods] and b_flag is not None:
194 print("Warning: no supported DPDK kernel modules are loaded", file=sys.stderr)
196 # change DPDK driver list to only contain drivers that are loaded
197 dpdk_drivers = [mod["Name"] for mod in mods if mod["Found"]]
200 def has_driver(dev_id):
201 '''return true if a device is assigned to a driver. False otherwise'''
202 return "Driver_str" in devices[dev_id]
205 def get_pci_device_details(dev_id, probe_lspci):
206 '''This function gets additional details for a PCI device'''
210 extra_info = check_output(["lspci", "-vmmks", dev_id]).splitlines()
212 # parse lspci details
213 for line in extra_info:
216 name, value = line.decode("utf8").split("\t", 1)
217 name = name.strip(":") + "_str"
219 # check for a unix interface name
220 device["Interface"] = ""
221 for base, dirs, _ in os.walk("/sys/bus/pci/devices/%s/" % dev_id):
223 device["Interface"] = \
224 ",".join(os.listdir(os.path.join(base, "net")))
226 # check if a port is used for ssh connection
227 device["Ssh_if"] = False
228 device["Active"] = ""
233 '''This function clears any old data'''
237 def get_device_details(devices_type):
238 '''This function populates the "devices" dictionary. The keys used are
239 the pci addresses (domain:bus:slot.func). The values are themselves
240 dictionaries - one for each NIC.'''
244 # first loop through and read details for all devices
245 # request machine readable format, with numeric IDs and String
247 dev_lines = check_output(["lspci", "-Dvmmnnk"]).splitlines()
248 for dev_line in dev_lines:
249 if len(dev_line) == 0:
250 if device_type_match(dev, devices_type):
251 # Replace "Driver" with "Driver_str" to have consistency of
252 # of dictionary key names
253 if "Driver" in dev.keys():
254 dev["Driver_str"] = dev.pop("Driver")
255 if "Module" in dev.keys():
256 dev["Module_str"] = dev.pop("Module")
257 # use dict to make copy of dev
258 devices[dev["Slot"]] = dict(dev)
259 # Clear previous device's data
262 name, value = dev_line.decode("utf8").split("\t", 1)
263 value_list = value.rsplit(' ', 1)
264 if len(value_list) > 1:
265 # String stored in <name>_str
266 dev[name.rstrip(":") + '_str'] = value_list[0]
268 dev[name.rstrip(":")] = value_list[len(value_list) - 1] \
269 .rstrip("]").lstrip("[")
271 if devices_type == network_devices:
272 # check what is the interface if any for an ssh connection if
273 # any to this host, so we can mark it later.
275 route = check_output(["ip", "-o", "route"])
276 # filter out all lines for 169.254 routes
277 route = "\n".join(filter(lambda ln: not ln.startswith("169.254"),
278 route.decode().splitlines()))
279 rt_info = route.split()
280 for i in range(len(rt_info) - 1):
281 if rt_info[i] == "dev":
282 ssh_if.append(rt_info[i+1])
284 # based on the basic info, get extended text details
285 for d in devices.keys():
286 if not device_type_match(devices[d], devices_type):
289 # get additional info and add it to existing data
290 devices[d] = devices[d].copy()
291 # No need to probe lspci
292 devices[d].update(get_pci_device_details(d, False).items())
294 if devices_type == network_devices:
296 if _if in devices[d]["Interface"].split(","):
297 devices[d]["Ssh_if"] = True
298 devices[d]["Active"] = "*Active*"
301 # add igb_uio to list of supporting modules if needed
302 if "Module_str" in devices[d]:
303 for driver in dpdk_drivers:
304 if driver not in devices[d]["Module_str"]:
305 devices[d]["Module_str"] = \
306 devices[d]["Module_str"] + ",%s" % driver
308 devices[d]["Module_str"] = ",".join(dpdk_drivers)
310 # make sure the driver and module strings do not have any duplicates
312 modules = devices[d]["Module_str"].split(",")
313 if devices[d]["Driver_str"] in modules:
314 modules.remove(devices[d]["Driver_str"])
315 devices[d]["Module_str"] = ",".join(modules)
318 def device_type_match(dev, devices_type):
319 for i in range(len(devices_type)):
321 [x for x in devices_type[i].values() if x is not None])
323 if dev["Class"][0:2] == devices_type[i]["Class"]:
324 match_count = match_count + 1
325 for key in devices_type[i].keys():
326 if key != 'Class' and devices_type[i][key]:
327 value_list = devices_type[i][key].split(',')
328 for value in value_list:
329 if value.strip(' ') == dev[key]:
330 match_count = match_count + 1
331 # count must be the number of non None parameters to match
332 if match_count == param_count:
336 def dev_id_from_dev_name(dev_name):
337 '''Take a device "name" - a string passed in by user to identify a NIC
338 device, and determine the device id - i.e. the domain:bus:slot.func - for
339 it, which can then be used to index into the devices array'''
341 # check if it's already a suitable index
342 if dev_name in devices:
344 # check if it's an index just missing the domain part
345 elif "0000:" + dev_name in devices:
346 return "0000:" + dev_name
348 # check if it's an interface name, e.g. eth1
349 for d in devices.keys():
350 if dev_name in devices[d]["Interface"].split(","):
351 return devices[d]["Slot"]
352 # if nothing else matches - error
353 raise ValueError("Unknown device: %s. "
354 "Please specify device in \"bus:slot.func\" format" % dev_name)
357 def unbind_one(dev_id, force):
358 '''Unbind the device identified by "dev_id" from its current driver'''
359 dev = devices[dev_id]
360 if not has_driver(dev_id):
361 print("Notice: %s %s %s is not currently managed by any driver" %
362 (dev["Slot"], dev["Device_str"], dev["Interface"]), file=sys.stderr)
365 # prevent us disconnecting ourselves
366 if dev["Ssh_if"] and not force:
367 print("Warning: routing table indicates that interface %s is active. "
368 "Skipping unbind" % dev_id, file=sys.stderr)
371 # write to /sys to unbind
372 filename = "/sys/bus/pci/drivers/%s/unbind" % dev["Driver_str"]
374 f = open(filename, "a")
376 sys.exit("Error: unbind failed for %s - Cannot open %s" %
382 def bind_one(dev_id, driver, force):
383 '''Bind the device given by "dev_id" to the driver "driver". If the device
384 is already bound to a different driver, it will be unbound first'''
385 dev = devices[dev_id]
386 saved_driver = None # used to rollback any unbind in case of failure
388 # prevent disconnection of our ssh session
389 if dev["Ssh_if"] and not force:
390 print("Warning: routing table indicates that interface %s is active. "
391 "Not modifying" % dev_id, file=sys.stderr)
394 # unbind any existing drivers we don't want
395 if has_driver(dev_id):
396 if dev["Driver_str"] == driver:
397 print("Notice: %s already bound to driver %s, skipping" %
398 (dev_id, driver), file=sys.stderr)
401 saved_driver = dev["Driver_str"]
402 unbind_one(dev_id, force)
403 dev["Driver_str"] = "" # clear driver string
405 # For kernels >= 3.15 driver_override can be used to specify the driver
406 # for a device rather than relying on the driver to provide a positive
407 # match of the device. The existing process of looking up
408 # the vendor and device ID, adding them to the driver new_id,
409 # will erroneously bind other devices too which has the additional burden
410 # of unbinding those devices
411 if driver in dpdk_drivers:
412 filename = "/sys/bus/pci/devices/%s/driver_override" % dev_id
413 if os.path.exists(filename):
415 f = open(filename, "w")
417 print("Error: bind failed for %s - Cannot open %s"
418 % (dev_id, filename), file=sys.stderr)
421 f.write("%s" % driver)
424 print("Error: bind failed for %s - Cannot write driver %s to "
425 "PCI ID " % (dev_id, driver), file=sys.stderr)
427 # For kernels < 3.15 use new_id to add PCI id's to the driver
429 filename = "/sys/bus/pci/drivers/%s/new_id" % driver
431 f = open(filename, "w")
433 print("Error: bind failed for %s - Cannot open %s"
434 % (dev_id, filename), file=sys.stderr)
437 # Convert Device and Vendor Id to int to write to new_id
438 f.write("%04x %04x" % (int(dev["Vendor"],16),
439 int(dev["Device"], 16)))
442 print("Error: bind failed for %s - Cannot write new PCI ID to "
443 "driver %s" % (dev_id, driver), file=sys.stderr)
446 # do the bind by writing to /sys
447 filename = "/sys/bus/pci/drivers/%s/bind" % driver
449 f = open(filename, "a")
451 print("Error: bind failed for %s - Cannot open %s"
452 % (dev_id, filename), file=sys.stderr)
453 if saved_driver is not None: # restore any previous driver
454 bind_one(dev_id, saved_driver, force)
460 # for some reason, closing dev_id after adding a new PCI ID to new_id
461 # results in IOError. however, if the device was successfully bound,
462 # we don't care for any errors and can safely ignore IOError
463 tmp = get_pci_device_details(dev_id, True)
464 if "Driver_str" in tmp and tmp["Driver_str"] == driver:
466 print("Error: bind failed for %s - Cannot bind to driver %s"
467 % (dev_id, driver), file=sys.stderr)
468 if saved_driver is not None: # restore any previous driver
469 bind_one(dev_id, saved_driver, force)
472 # For kernels > 3.15 driver_override is used to bind a device to a driver.
473 # Before unbinding it, overwrite driver_override with empty string so that
474 # the device can be bound to any other driver
475 filename = "/sys/bus/pci/devices/%s/driver_override" % dev_id
476 if os.path.exists(filename):
478 f = open(filename, "w")
480 sys.exit("Error: unbind failed for %s - Cannot open %s"
481 % (dev_id, filename))
486 sys.exit("Error: unbind failed for %s - Cannot open %s"
487 % (dev_id, filename))
490 def unbind_all(dev_list, force=False):
491 """Unbind method, takes a list of device locations"""
493 if dev_list[0] == "dpdk":
494 for d in devices.keys():
495 if "Driver_str" in devices[d]:
496 if devices[d]["Driver_str"] in dpdk_drivers:
497 unbind_one(devices[d]["Slot"], force)
501 dev_list = map(dev_id_from_dev_name, dev_list)
502 except ValueError as ex:
510 def bind_all(dev_list, driver, force=False):
511 """Bind method, takes a list of device locations"""
514 # a common user error is to forget to specify the driver the devices need to
515 # be bound to. check if the driver is a valid device, and if it is, show
516 # a meaningful error.
518 dev_id_from_dev_name(driver)
519 # if we've made it this far, this means that the "driver" was a valid
520 # device string, so it's probably not a valid driver name.
521 sys.exit("Error: Driver '%s' does not look like a valid driver. " \
522 "Did you forget to specify the driver to bind devices to?" % driver)
524 # driver generated error - it's not a valid device ID, so all is well
527 # check if we're attempting to bind to a driver that isn't loaded
528 if not module_is_loaded(driver.replace('-','_')):
529 sys.exit("Error: Driver '%s' is not loaded." % driver)
532 dev_list = map(dev_id_from_dev_name, dev_list)
533 except ValueError as ex:
537 bind_one(d, driver, force)
539 # For kernels < 3.15 when binding devices to a generic driver
540 # (i.e. one that doesn't have a PCI ID table) using new_id, some devices
541 # that are not bound to any other driver could be bound even if no one has
542 # asked them to. hence, we check the list of drivers again, and see if
543 # some of the previously-unbound devices were erroneously bound.
544 if not os.path.exists("/sys/bus/pci/devices/%s/driver_override" % d):
545 for d in devices.keys():
546 # skip devices that were already bound or that we know should be bound
547 if "Driver_str" in devices[d] or d in dev_list:
550 # update information about this device
551 devices[d] = dict(devices[d].items() +
552 get_pci_device_details(d, True).items())
554 # check if updated information indicates that the device was bound
555 if "Driver_str" in devices[d]:
559 def display_devices(title, dev_list, extra_params=None):
560 '''Displays to the user the details of a list of devices given in
561 "dev_list". The "extra_params" parameter, if given, should contain a string
562 with %()s fields in it for replacement by the named fields in each
563 device's dictionary.'''
564 strings = [] # this holds the strings to print. We sort before printing
565 print("\n%s" % title)
566 print("="*len(title))
567 if len(dev_list) == 0:
568 strings.append("<none>")
571 if extra_params is not None:
572 strings.append("%s '%s %s' %s" % (dev["Slot"],
577 strings.append("%s '%s'" % (dev["Slot"], dev["Device_str"]))
578 # sort before printing, so that the entries appear in PCI order
580 print("\n".join(strings)) # print one per line
582 def show_device_status(devices_type, device_name):
588 # split our list of network devices into the three categories above
589 for d in devices.keys():
590 if device_type_match(devices[d], devices_type):
591 if not has_driver(d):
592 no_drv.append(devices[d])
594 if devices[d]["Driver_str"] in dpdk_drivers:
595 dpdk_drv.append(devices[d])
597 kernel_drv.append(devices[d])
599 n_devs = len(dpdk_drv) + len(kernel_drv) + len(no_drv)
601 # don't bother displaying anything if there are no devices
603 msg = "No '%s' devices detected" % device_name
606 print("".join('=' * len(msg)))
609 # print each category separately, so we can clearly see what's used by DPDK
610 if len(dpdk_drv) != 0:
611 display_devices("%s devices using DPDK-compatible driver" % device_name,
612 dpdk_drv, "drv=%(Driver_str)s unused=%(Module_str)s")
613 if len(kernel_drv) != 0:
614 display_devices("%s devices using kernel driver" % device_name, kernel_drv,
615 "if=%(Interface)s drv=%(Driver_str)s "
616 "unused=%(Module_str)s %(Active)s")
618 display_devices("Other %s devices" % device_name, no_drv,
619 "unused=%(Module_str)s")
622 '''Function called when the script is passed the "--status" option.
623 Displays to the user what devices are bound to the igb_uio driver, the
624 kernel driver or to no driver'''
626 if status_dev == "net" or status_dev == "all":
627 show_device_status(network_devices, "Network")
629 if status_dev == "baseband" or status_dev == "all":
630 show_device_status(baseband_devices, "Baseband")
632 if status_dev == "crypto" or status_dev == "all":
633 show_device_status(crypto_devices, "Crypto")
635 if status_dev == "event" or status_dev == "all":
636 show_device_status(eventdev_devices, "Eventdev")
638 if status_dev == "mempool" or status_dev == "all":
639 show_device_status(mempool_devices, "Mempool")
641 if status_dev == "compress" or status_dev == "all":
642 show_device_status(compress_devices , "Compress")
644 if status_dev == "misc" or status_dev == "all":
645 show_device_status(misc_devices, "Misc (rawdev)")
648 '''Parses the command-line arguments given by the user and takes the
649 appropriate action for each'''
655 if len(sys.argv) <= 1:
660 opts, args = getopt.getopt(sys.argv[1:], "b:us",
661 ["help", "usage", "status", "status-dev=",
662 "force", "bind=", "unbind", ])
663 except getopt.GetoptError as error:
665 print("Run '%s --usage' for further information" % sys.argv[0])
668 for opt, arg in opts:
669 if opt == "--help" or opt == "--usage":
672 if opt == "--status-dev":
675 if opt == "--status" or opt == "-s":
680 if opt == "-b" or opt == "-u" or opt == "--bind" or opt == "--unbind":
681 if b_flag is not None:
682 sys.exit("Error: binding and unbinding are mutually exclusive")
683 if opt == "-u" or opt == "--unbind":
689 def do_arg_actions():
690 '''do the actual action requested by the user'''
696 if b_flag is None and not status_flag:
697 print("Error: No action specified for devices. "
698 "Please give a -b or -u option", file=sys.stderr)
702 if b_flag is not None and len(args) == 0:
703 print("Error: No devices specified.", file=sys.stderr)
707 if b_flag == "none" or b_flag == "None":
708 unbind_all(args, force_flag)
709 elif b_flag is not None:
710 bind_all(args, b_flag, force_flag)
712 if b_flag is not None:
714 # refresh if we have changed anything
715 get_device_details(network_devices)
716 get_device_details(baseband_devices)
717 get_device_details(crypto_devices)
718 get_device_details(eventdev_devices)
719 get_device_details(mempool_devices)
720 get_device_details(compress_devices)
721 get_device_details(misc_devices)
726 '''program main function'''
727 # check if lspci is installed, suppress any output
728 with open(os.devnull, 'w') as devnull:
729 ret = subprocess.call(['which', 'lspci'],
730 stdout=devnull, stderr=devnull)
732 sys.exit("'lspci' not found - please install 'pciutils'")
736 get_device_details(network_devices)
737 get_device_details(baseband_devices)
738 get_device_details(crypto_devices)
739 get_device_details(eventdev_devices)
740 get_device_details(mempool_devices)
741 get_device_details(compress_devices)
742 get_device_details(misc_devices)
745 if __name__ == "__main__":