5 # Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
8 # Redistribution and use in source and binary forms, with or without
9 # modification, are permitted provided that the following conditions
12 # * Redistributions of source code must retain the above copyright
13 # notice, this list of conditions and the following disclaimer.
14 # * Redistributions in binary form must reproduce the above copyright
15 # notice, this list of conditions and the following disclaimer in
16 # the documentation and/or other materials provided with the
18 # * Neither the name of Intel Corporation nor the names of its
19 # contributors may be used to endorse or promote products derived
20 # from this software without specific prior written permission.
22 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
26 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
28 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 from os.path import exists, abspath, dirname, basename
41 # The PCI base class for all devices
42 network_class = {'Class': '02', 'Vendor': None, 'Device': None,
43 'SVendor': None, 'SDevice': None}
44 encryption_class = {'Class': '10', 'Vendor': None, 'Device': None,
45 'SVendor': None, 'SDevice': None}
46 intel_processor_class = {'Class': '0b', 'Vendor': '8086', 'Device': None,
47 'SVendor': None, 'SDevice': None}
49 network_devices = [network_class]
50 crypto_devices = [encryption_class, intel_processor_class]
52 # global dict ethernet devices present. Dictionary indexed by PCI address.
53 # Each device within this is itself a dictionary of device properties
55 # list of supported DPDK drivers
56 dpdk_drivers = ["igb_uio", "vfio-pci", "uio_pci_generic"]
58 # command-line arg flags
66 '''Print usage information for the program'''
67 argv0 = basename(sys.argv[0])
72 %(argv0)s [options] DEVICE1 DEVICE2 ....
74 where DEVICE1, DEVICE2 etc, are specified via PCI "domain:bus:slot.func" syntax
75 or "bus:slot.func" syntax. For devices bound to Linux kernel drivers, they may
76 also be referred to by Linux interface name e.g. eth0, eth1, em0, em1, etc.
80 Display usage information and quit
83 Print the current status of all known network and crypto devices.
84 For each device, it displays the PCI domain, bus, slot and function,
85 along with a text description of the device. Depending upon whether the
86 device is being used by a kernel driver, the igb_uio driver, or no
87 driver, other relevant information will be displayed:
88 * the Linux interface name e.g. if=eth0
89 * the driver being used e.g. drv=igb_uio
90 * any suitable drivers not currently using that device
92 NOTE: if this flag is passed along with a bind/unbind option, the
93 status display will always occur after the other operations have taken
96 -b driver, --bind=driver:
97 Select the driver to use or \"none\" to unbind the device
100 Unbind a device (Equivalent to \"-b none\")
103 By default, network devices which are used by Linux - as indicated by
104 having routes in the routing table - cannot be modified. Using the
105 --force flag overrides this behavior, allowing active links to be
107 WARNING: This can lead to loss of network connection and should be used
113 To display current device status:
116 To bind eth1 from the current driver and move to use igb_uio
117 %(argv0)s --bind=igb_uio eth1
119 To unbind 0000:01:00.0 from using any driver
120 %(argv0)s -u 0000:01:00.0
122 To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver
123 %(argv0)s -b ixgbe 02:00.0 02:00.1
125 """ % locals()) # replace items from local variables
128 # This is roughly compatible with check_output function in subprocess module
129 # which is only available in python 2.7.
130 def check_output(args, stderr=None):
131 '''Run a command and capture its output'''
132 return subprocess.Popen(args, stdout=subprocess.PIPE,
133 stderr=stderr).communicate()[0]
136 def find_module(mod):
137 '''find the .ko file for kernel module named mod.
138 Searches the $RTE_SDK/$RTE_TARGET directory, the kernel
139 modules directory and finally under the parent directory of
141 # check $RTE_SDK/$RTE_TARGET directory
142 if 'RTE_SDK' in os.environ and 'RTE_TARGET' in os.environ:
143 path = "%s/%s/kmod/%s.ko" % (os.environ['RTE_SDK'],
144 os.environ['RTE_TARGET'], mod)
150 depmod_out = check_output(["modinfo", "-n", mod],
151 stderr=subprocess.STDOUT).lower()
152 if "error" not in depmod_out:
153 path = depmod_out.strip()
156 except: # if modinfo can't find module, it fails, so continue
159 # check for a copy based off current path
160 tools_dir = dirname(abspath(sys.argv[0]))
161 if tools_dir.endswith("tools"):
162 base_dir = dirname(tools_dir)
163 find_out = check_output(["find", base_dir, "-name", mod + ".ko"])
164 if len(find_out) > 0: # something matched
165 path = find_out.splitlines()[0]
171 '''Checks that igb_uio is loaded'''
174 # list of supported modules
175 mods = [{"Name": driver, "Found": False} for driver in dpdk_drivers]
177 # first check if module is loaded
179 # Get list of sysfs modules (both built-in and dynamically loaded)
180 sysfs_path = '/sys/module/'
182 # Get the list of directories in sysfs_path
183 sysfs_mods = [os.path.join(sysfs_path, o) for o
184 in os.listdir(sysfs_path)
185 if os.path.isdir(os.path.join(sysfs_path, o))]
187 # Extract the last element of '/sys/module/abc' in the array
188 sysfs_mods = [a.split('/')[-1] for a in sysfs_mods]
190 # special case for vfio_pci (module is named vfio-pci,
191 # but its .ko is named vfio_pci)
192 sysfs_mods = map(lambda a:
193 a if a != 'vfio_pci' else 'vfio-pci', sysfs_mods)
196 if mod["Name"] in sysfs_mods:
201 # check if we have at least one loaded module
202 if True not in [mod["Found"] for mod in mods] and b_flag is not None:
203 if b_flag in dpdk_drivers:
204 print("Error - no supported modules(DPDK driver) are loaded")
207 print("Warning - no supported modules(DPDK driver) are loaded")
209 # change DPDK driver list to only contain drivers that are loaded
210 dpdk_drivers = [mod["Name"] for mod in mods if mod["Found"]]
213 def has_driver(dev_id):
214 '''return true if a device is assigned to a driver. False otherwise'''
215 return "Driver_str" in devices[dev_id]
218 def get_pci_device_details(dev_id, probe_lspci):
219 '''This function gets additional details for a PCI device'''
223 extra_info = check_output(["lspci", "-vmmks", dev_id]).splitlines()
225 # parse lspci details
226 for line in extra_info:
229 name, value = line.decode().split("\t", 1)
230 name = name.strip(":") + "_str"
232 # check for a unix interface name
233 device["Interface"] = ""
234 for base, dirs, _ in os.walk("/sys/bus/pci/devices/%s/" % dev_id):
236 device["Interface"] = \
237 ",".join(os.listdir(os.path.join(base, "net")))
239 # check if a port is used for ssh connection
240 device["Ssh_if"] = False
241 device["Active"] = ""
246 '''This function clears any old data'''
249 def get_device_details(devices_type):
250 '''This function populates the "devices" dictionary. The keys used are
251 the pci addresses (domain:bus:slot.func). The values are themselves
252 dictionaries - one for each NIC.'''
256 # first loop through and read details for all devices
257 # request machine readable format, with numeric IDs and String
259 dev_lines = check_output(["lspci", "-Dvmmnnk"]).splitlines()
260 for dev_line in dev_lines:
261 if len(dev_line) == 0:
262 if device_type_match(dev, devices_type):
263 # Replace "Driver" with "Driver_str" to have consistency of
264 # of dictionary key names
265 if "Driver" in dev.keys():
266 dev["Driver_str"] = dev.pop("Driver")
267 # use dict to make copy of dev
268 devices[dev["Slot"]] = dict(dev)
269 # Clear previous device's data
272 name, value = dev_line.decode().split("\t", 1)
273 value_list = value.rsplit(' ', 1)
274 if len(value_list) > 1:
275 # String stored in <name>_str
276 dev[name.rstrip(":") + '_str'] = value_list[0]
278 dev[name.rstrip(":")] = value_list[len(value_list) - 1] \
279 .rstrip("]").lstrip("[")
281 if devices_type == network_devices:
282 # check what is the interface if any for an ssh connection if
283 # any to this host, so we can mark it later.
285 route = check_output(["ip", "-o", "route"])
286 # filter out all lines for 169.254 routes
287 route = "\n".join(filter(lambda ln: not ln.startswith("169.254"),
288 route.decode().splitlines()))
289 rt_info = route.split()
290 for i in range(len(rt_info) - 1):
291 if rt_info[i] == "dev":
292 ssh_if.append(rt_info[i+1])
294 # based on the basic info, get extended text details
295 for d in devices.keys():
296 if not device_type_match(devices[d], devices_type):
299 # get additional info and add it to existing data
300 devices[d] = devices[d].copy()
301 # No need to probe lspci
302 devices[d].update(get_pci_device_details(d, False).items())
304 if devices_type == network_devices:
306 if _if in devices[d]["Interface"].split(","):
307 devices[d]["Ssh_if"] = True
308 devices[d]["Active"] = "*Active*"
311 # add igb_uio to list of supporting modules if needed
312 if "Module_str" in devices[d]:
313 for driver in dpdk_drivers:
314 if driver not in devices[d]["Module_str"]:
315 devices[d]["Module_str"] = \
316 devices[d]["Module_str"] + ",%s" % driver
318 devices[d]["Module_str"] = ",".join(dpdk_drivers)
320 # make sure the driver and module strings do not have any duplicates
322 modules = devices[d]["Module_str"].split(",")
323 if devices[d]["Driver_str"] in modules:
324 modules.remove(devices[d]["Driver_str"])
325 devices[d]["Module_str"] = ",".join(modules)
328 def device_type_match(dev, devices_type):
329 for i in range(len(devices_type)):
331 [x for x in devices_type[i].values() if x is not None])
333 if dev["Class"][0:2] == devices_type[i]["Class"]:
334 match_count = match_count + 1
335 for key in devices_type[i].keys():
336 if key != 'Class' and devices_type[i][key]:
337 value_list = devices_type[i][key].split(',')
338 for value in value_list:
339 if value.strip(' ') == dev[key]:
340 match_count = match_count + 1
341 # count must be the number of non None parameters to match
342 if match_count == param_count:
347 def dev_id_from_dev_name(dev_name):
348 '''Take a device "name" - a string passed in by user to identify a NIC
349 device, and determine the device id - i.e. the domain:bus:slot.func - for
350 it, which can then be used to index into the devices array'''
352 # check if it's already a suitable index
353 if dev_name in devices:
355 # check if it's an index just missing the domain part
356 elif "0000:" + dev_name in devices:
357 return "0000:" + dev_name
359 # check if it's an interface name, e.g. eth1
360 for d in devices.keys():
361 if dev_name in devices[d]["Interface"].split(","):
362 return devices[d]["Slot"]
363 # if nothing else matches - error
364 print("Unknown device: %s. "
365 "Please specify device in \"bus:slot.func\" format" % dev_name)
369 def unbind_one(dev_id, force):
370 '''Unbind the device identified by "dev_id" from its current driver'''
371 dev = devices[dev_id]
372 if not has_driver(dev_id):
373 print("%s %s %s is not currently managed by any driver\n" %
374 (dev["Slot"], dev["Device_str"], dev["Interface"]))
377 # prevent us disconnecting ourselves
378 if dev["Ssh_if"] and not force:
379 print("Routing table indicates that interface %s is active. "
380 "Skipping unbind" % (dev_id))
383 # For kernels > 3.15 driver_override is used to bind a device to a driver.
384 # Before unbinding it, overwrite driver_override with empty string so that
385 # the device can be bound to any other driver
386 filename = "/sys/bus/pci/devices/%s/driver_override" % dev_id
387 if os.path.exists(filename):
389 f = open(filename, "w")
391 print("Error: unbind failed for %s - Cannot open %s"
392 % (dev_id, filename))
398 print("Error: unbind failed for %s - Cannot open %s"
399 % (dev_id, filename))
402 # write to /sys to unbind
403 filename = "/sys/bus/pci/drivers/%s/unbind" % dev["Driver_str"]
405 f = open(filename, "a")
407 print("Error: unbind failed for %s - Cannot open %s"
408 % (dev_id, filename))
414 def bind_one(dev_id, driver, force):
415 '''Bind the device given by "dev_id" to the driver "driver". If the device
416 is already bound to a different driver, it will be unbound first'''
417 dev = devices[dev_id]
418 saved_driver = None # used to rollback any unbind in case of failure
420 # prevent disconnection of our ssh session
421 if dev["Ssh_if"] and not force:
422 print("Routing table indicates that interface %s is active. "
423 "Not modifying" % (dev_id))
426 # unbind any existing drivers we don't want
427 if has_driver(dev_id):
428 if dev["Driver_str"] == driver:
429 print("%s already bound to driver %s, skipping\n"
433 saved_driver = dev["Driver_str"]
434 unbind_one(dev_id, force)
435 dev["Driver_str"] = "" # clear driver string
437 # For kernels >= 3.15 driver_override can be used to specify the driver
438 # for a device rather than relying on the driver to provide a positive
439 # match of the device. The existing process of looking up
440 # the vendor and device ID, adding them to the driver new_id,
441 # will erroneously bind other devices too which has the additional burden
442 # of unbinding those devices
443 if driver in dpdk_drivers:
444 filename = "/sys/bus/pci/devices/%s/driver_override" % dev_id
445 if os.path.exists(filename):
447 f = open(filename, "w")
449 print("Error: bind failed for %s - Cannot open %s"
450 % (dev_id, filename))
453 f.write("%s" % driver)
456 print("Error: bind failed for %s - Cannot write driver %s to "
457 "PCI ID " % (dev_id, driver))
459 # For kernels < 3.15 use new_id to add PCI id's to the driver
461 filename = "/sys/bus/pci/drivers/%s/new_id" % driver
463 f = open(filename, "w")
465 print("Error: bind failed for %s - Cannot open %s"
466 % (dev_id, filename))
469 # Convert Device and Vendor Id to int to write to new_id
470 f.write("%04x %04x" % (int(dev["Vendor"],16),
471 int(dev["Device"], 16)))
474 print("Error: bind failed for %s - Cannot write new PCI ID to "
475 "driver %s" % (dev_id, driver))
478 # do the bind by writing to /sys
479 filename = "/sys/bus/pci/drivers/%s/bind" % driver
481 f = open(filename, "a")
483 print("Error: bind failed for %s - Cannot open %s"
484 % (dev_id, filename))
485 if saved_driver is not None: # restore any previous driver
486 bind_one(dev_id, saved_driver, force)
492 # for some reason, closing dev_id after adding a new PCI ID to new_id
493 # results in IOError. however, if the device was successfully bound,
494 # we don't care for any errors and can safely ignore IOError
495 tmp = get_pci_device_details(dev_id, True)
496 if "Driver_str" in tmp and tmp["Driver_str"] == driver:
498 print("Error: bind failed for %s - Cannot bind to driver %s"
500 if saved_driver is not None: # restore any previous driver
501 bind_one(dev_id, saved_driver, force)
505 def unbind_all(dev_list, force=False):
506 """Unbind method, takes a list of device locations"""
507 dev_list = map(dev_id_from_dev_name, dev_list)
512 def bind_all(dev_list, driver, force=False):
513 """Bind method, takes a list of device locations"""
516 dev_list = map(dev_id_from_dev_name, dev_list)
519 bind_one(d, driver, force)
521 # For kenels < 3.15 when binding devices to a generic driver
522 # (i.e. one that doesn't have a PCI ID table) using new_id, some devices
523 # that are not bound to any other driver could be bound even if no one has
524 # asked them to. hence, we check the list of drivers again, and see if
525 # some of the previously-unbound devices were erroneously bound.
526 if not os.path.exists("/sys/bus/pci/devices/%s/driver_override" % d):
527 for d in devices.keys():
528 # skip devices that were already bound or that we know should be bound
529 if "Driver_str" in devices[d] or d in dev_list:
532 # update information about this device
533 devices[d] = dict(devices[d].items() +
534 get_pci_device_details(d, True).items())
536 # check if updated information indicates that the device was bound
537 if "Driver_str" in devices[d]:
541 def display_devices(title, dev_list, extra_params=None):
542 '''Displays to the user the details of a list of devices given in
543 "dev_list". The "extra_params" parameter, if given, should contain a string
544 with %()s fields in it for replacement by the named fields in each
545 device's dictionary.'''
546 strings = [] # this holds the strings to print. We sort before printing
547 print("\n%s" % title)
548 print("="*len(title))
549 if len(dev_list) == 0:
550 strings.append("<none>")
553 if extra_params is not None:
554 strings.append("%s '%s %s' %s" % (dev["Slot"],
559 strings.append("%s '%s'" % (dev["Slot"], dev["Device_str"]))
560 # sort before printing, so that the entries appear in PCI order
562 print("\n".join(strings)) # print one per line
564 def show_device_status(devices_type, device_name):
570 # split our list of network devices into the three categories above
571 for d in devices.keys():
572 if device_type_match(devices[d], devices_type):
573 if not has_driver(d):
574 no_drv.append(devices[d])
576 if devices[d]["Driver_str"] in dpdk_drivers:
577 dpdk_drv.append(devices[d])
579 kernel_drv.append(devices[d])
581 # print each category separately, so we can clearly see what's used by DPDK
582 display_devices("%s devices using DPDK-compatible driver" % device_name,
583 dpdk_drv, "drv=%(Driver_str)s unused=%(Module_str)s")
584 display_devices("%s devices using kernel driver" % device_name, kernel_drv,
585 "if=%(Interface)s drv=%(Driver_str)s "
586 "unused=%(Module_str)s %(Active)s")
587 display_devices("Other %s devices" % device_name, no_drv,
588 "unused=%(Module_str)s")
591 '''Function called when the script is passed the "--status" option.
592 Displays to the user what devices are bound to the igb_uio driver, the
593 kernel driver or to no driver'''
595 show_device_status(network_devices, "Network")
596 show_device_status(crypto_devices, "Crypto")
599 '''Parses the command-line arguments given by the user and takes the
600 appropriate action for each'''
605 if len(sys.argv) <= 1:
610 opts, args = getopt.getopt(sys.argv[1:], "b:us",
611 ["help", "usage", "status", "force",
613 except getopt.GetoptError as error:
615 print("Run '%s --usage' for further information" % sys.argv[0])
618 for opt, arg in opts:
619 if opt == "--help" or opt == "--usage":
622 if opt == "--status" or opt == "-s":
626 if opt == "-b" or opt == "-u" or opt == "--bind" or opt == "--unbind":
627 if b_flag is not None:
628 print("Error - Only one bind or unbind may be specified\n")
630 if opt == "-u" or opt == "--unbind":
636 def do_arg_actions():
637 '''do the actual action requested by the user'''
643 if b_flag is None and not status_flag:
644 print("Error: No action specified for devices."
645 "Please give a -b or -u option")
646 print("Run '%s --usage' for further information" % sys.argv[0])
649 if b_flag is not None and len(args) == 0:
650 print("Error: No devices specified.")
651 print("Run '%s --usage' for further information" % sys.argv[0])
654 if b_flag == "none" or b_flag == "None":
655 unbind_all(args, force_flag)
656 elif b_flag is not None:
657 bind_all(args, b_flag, force_flag)
659 if b_flag is not None:
661 # refresh if we have changed anything
662 get_device_details(network_devices)
663 get_device_details(crypto_devices)
668 '''program main function'''
672 get_device_details(network_devices)
673 get_device_details(crypto_devices)
676 if __name__ == "__main__":