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}
48 cavium_sso = {'Class': '08', 'Vendor': '177d', 'Device': 'a04b,a04d',
49 'SVendor': None, 'SDevice': None}
51 network_devices = [network_class]
52 crypto_devices = [encryption_class, intel_processor_class]
53 eventdev_devices = [cavium_sso]
55 # global dict ethernet devices present. Dictionary indexed by PCI address.
56 # Each device within this is itself a dictionary of device properties
58 # list of supported DPDK drivers
59 dpdk_drivers = ["igb_uio", "vfio-pci", "uio_pci_generic"]
61 # command-line arg flags
69 '''Print usage information for the program'''
70 argv0 = basename(sys.argv[0])
75 %(argv0)s [options] DEVICE1 DEVICE2 ....
77 where DEVICE1, DEVICE2 etc, are specified via PCI "domain:bus:slot.func" syntax
78 or "bus:slot.func" syntax. For devices bound to Linux kernel drivers, they may
79 also be referred to by Linux interface name e.g. eth0, eth1, em0, em1, etc.
83 Display usage information and quit
86 Print the current status of all known network and crypto devices.
87 For each device, it displays the PCI domain, bus, slot and function,
88 along with a text description of the device. Depending upon whether the
89 device is being used by a kernel driver, the igb_uio driver, or no
90 driver, other relevant information will be displayed:
91 * the Linux interface name e.g. if=eth0
92 * the driver being used e.g. drv=igb_uio
93 * any suitable drivers not currently using that device
95 NOTE: if this flag is passed along with a bind/unbind option, the
96 status display will always occur after the other operations have taken
99 -b driver, --bind=driver:
100 Select the driver to use or \"none\" to unbind the device
103 Unbind a device (Equivalent to \"-b none\")
106 By default, network devices which are used by Linux - as indicated by
107 having routes in the routing table - cannot be modified. Using the
108 --force flag overrides this behavior, allowing active links to be
110 WARNING: This can lead to loss of network connection and should be used
116 To display current device status:
119 To bind eth1 from the current driver and move to use igb_uio
120 %(argv0)s --bind=igb_uio eth1
122 To unbind 0000:01:00.0 from using any driver
123 %(argv0)s -u 0000:01:00.0
125 To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver
126 %(argv0)s -b ixgbe 02:00.0 02:00.1
128 """ % locals()) # replace items from local variables
131 # This is roughly compatible with check_output function in subprocess module
132 # which is only available in python 2.7.
133 def check_output(args, stderr=None):
134 '''Run a command and capture its output'''
135 return subprocess.Popen(args, stdout=subprocess.PIPE,
136 stderr=stderr).communicate()[0]
139 def find_module(mod):
140 '''find the .ko file for kernel module named mod.
141 Searches the $RTE_SDK/$RTE_TARGET directory, the kernel
142 modules directory and finally under the parent directory of
144 # check $RTE_SDK/$RTE_TARGET directory
145 if 'RTE_SDK' in os.environ and 'RTE_TARGET' in os.environ:
146 path = "%s/%s/kmod/%s.ko" % (os.environ['RTE_SDK'],
147 os.environ['RTE_TARGET'], mod)
153 depmod_out = check_output(["modinfo", "-n", mod],
154 stderr=subprocess.STDOUT).lower()
155 if "error" not in depmod_out:
156 path = depmod_out.strip()
159 except: # if modinfo can't find module, it fails, so continue
162 # check for a copy based off current path
163 tools_dir = dirname(abspath(sys.argv[0]))
164 if tools_dir.endswith("tools"):
165 base_dir = dirname(tools_dir)
166 find_out = check_output(["find", base_dir, "-name", mod + ".ko"])
167 if len(find_out) > 0: # something matched
168 path = find_out.splitlines()[0]
174 '''Checks that igb_uio is loaded'''
177 # list of supported modules
178 mods = [{"Name": driver, "Found": False} for driver in dpdk_drivers]
180 # first check if module is loaded
182 # Get list of sysfs modules (both built-in and dynamically loaded)
183 sysfs_path = '/sys/module/'
185 # Get the list of directories in sysfs_path
186 sysfs_mods = [os.path.join(sysfs_path, o) for o
187 in os.listdir(sysfs_path)
188 if os.path.isdir(os.path.join(sysfs_path, o))]
190 # Extract the last element of '/sys/module/abc' in the array
191 sysfs_mods = [a.split('/')[-1] for a in sysfs_mods]
193 # special case for vfio_pci (module is named vfio-pci,
194 # but its .ko is named vfio_pci)
195 sysfs_mods = map(lambda a:
196 a if a != 'vfio_pci' else 'vfio-pci', sysfs_mods)
199 if mod["Name"] in sysfs_mods:
204 # check if we have at least one loaded module
205 if True not in [mod["Found"] for mod in mods] and b_flag is not None:
206 if b_flag in dpdk_drivers:
207 print("Error - no supported modules(DPDK driver) are loaded")
210 print("Warning - no supported modules(DPDK driver) are loaded")
212 # change DPDK driver list to only contain drivers that are loaded
213 dpdk_drivers = [mod["Name"] for mod in mods if mod["Found"]]
216 def has_driver(dev_id):
217 '''return true if a device is assigned to a driver. False otherwise'''
218 return "Driver_str" in devices[dev_id]
221 def get_pci_device_details(dev_id, probe_lspci):
222 '''This function gets additional details for a PCI device'''
226 extra_info = check_output(["lspci", "-vmmks", dev_id]).splitlines()
228 # parse lspci details
229 for line in extra_info:
232 name, value = line.decode().split("\t", 1)
233 name = name.strip(":") + "_str"
235 # check for a unix interface name
236 device["Interface"] = ""
237 for base, dirs, _ in os.walk("/sys/bus/pci/devices/%s/" % dev_id):
239 device["Interface"] = \
240 ",".join(os.listdir(os.path.join(base, "net")))
242 # check if a port is used for ssh connection
243 device["Ssh_if"] = False
244 device["Active"] = ""
249 '''This function clears any old data'''
252 def get_device_details(devices_type):
253 '''This function populates the "devices" dictionary. The keys used are
254 the pci addresses (domain:bus:slot.func). The values are themselves
255 dictionaries - one for each NIC.'''
259 # first loop through and read details for all devices
260 # request machine readable format, with numeric IDs and String
262 dev_lines = check_output(["lspci", "-Dvmmnnk"]).splitlines()
263 for dev_line in dev_lines:
264 if len(dev_line) == 0:
265 if device_type_match(dev, devices_type):
266 # Replace "Driver" with "Driver_str" to have consistency of
267 # of dictionary key names
268 if "Driver" in dev.keys():
269 dev["Driver_str"] = dev.pop("Driver")
270 # use dict to make copy of dev
271 devices[dev["Slot"]] = dict(dev)
272 # Clear previous device's data
275 name, value = dev_line.decode().split("\t", 1)
276 value_list = value.rsplit(' ', 1)
277 if len(value_list) > 1:
278 # String stored in <name>_str
279 dev[name.rstrip(":") + '_str'] = value_list[0]
281 dev[name.rstrip(":")] = value_list[len(value_list) - 1] \
282 .rstrip("]").lstrip("[")
284 if devices_type == network_devices:
285 # check what is the interface if any for an ssh connection if
286 # any to this host, so we can mark it later.
288 route = check_output(["ip", "-o", "route"])
289 # filter out all lines for 169.254 routes
290 route = "\n".join(filter(lambda ln: not ln.startswith("169.254"),
291 route.decode().splitlines()))
292 rt_info = route.split()
293 for i in range(len(rt_info) - 1):
294 if rt_info[i] == "dev":
295 ssh_if.append(rt_info[i+1])
297 # based on the basic info, get extended text details
298 for d in devices.keys():
299 if not device_type_match(devices[d], devices_type):
302 # get additional info and add it to existing data
303 devices[d] = devices[d].copy()
304 # No need to probe lspci
305 devices[d].update(get_pci_device_details(d, False).items())
307 if devices_type == network_devices:
309 if _if in devices[d]["Interface"].split(","):
310 devices[d]["Ssh_if"] = True
311 devices[d]["Active"] = "*Active*"
314 # add igb_uio to list of supporting modules if needed
315 if "Module_str" in devices[d]:
316 for driver in dpdk_drivers:
317 if driver not in devices[d]["Module_str"]:
318 devices[d]["Module_str"] = \
319 devices[d]["Module_str"] + ",%s" % driver
321 devices[d]["Module_str"] = ",".join(dpdk_drivers)
323 # make sure the driver and module strings do not have any duplicates
325 modules = devices[d]["Module_str"].split(",")
326 if devices[d]["Driver_str"] in modules:
327 modules.remove(devices[d]["Driver_str"])
328 devices[d]["Module_str"] = ",".join(modules)
331 def device_type_match(dev, devices_type):
332 for i in range(len(devices_type)):
334 [x for x in devices_type[i].values() if x is not None])
336 if dev["Class"][0:2] == devices_type[i]["Class"]:
337 match_count = match_count + 1
338 for key in devices_type[i].keys():
339 if key != 'Class' and devices_type[i][key]:
340 value_list = devices_type[i][key].split(',')
341 for value in value_list:
342 if value.strip(' ') == dev[key]:
343 match_count = match_count + 1
344 # count must be the number of non None parameters to match
345 if match_count == param_count:
350 def dev_id_from_dev_name(dev_name):
351 '''Take a device "name" - a string passed in by user to identify a NIC
352 device, and determine the device id - i.e. the domain:bus:slot.func - for
353 it, which can then be used to index into the devices array'''
355 # check if it's already a suitable index
356 if dev_name in devices:
358 # check if it's an index just missing the domain part
359 elif "0000:" + dev_name in devices:
360 return "0000:" + dev_name
362 # check if it's an interface name, e.g. eth1
363 for d in devices.keys():
364 if dev_name in devices[d]["Interface"].split(","):
365 return devices[d]["Slot"]
366 # if nothing else matches - error
367 print("Unknown device: %s. "
368 "Please specify device in \"bus:slot.func\" format" % dev_name)
372 def unbind_one(dev_id, force):
373 '''Unbind the device identified by "dev_id" from its current driver'''
374 dev = devices[dev_id]
375 if not has_driver(dev_id):
376 print("%s %s %s is not currently managed by any driver\n" %
377 (dev["Slot"], dev["Device_str"], dev["Interface"]))
380 # prevent us disconnecting ourselves
381 if dev["Ssh_if"] and not force:
382 print("Routing table indicates that interface %s is active. "
383 "Skipping unbind" % (dev_id))
386 # For kernels > 3.15 driver_override is used to bind a device to a driver.
387 # Before unbinding it, overwrite driver_override with empty string so that
388 # the device can be bound to any other driver
389 filename = "/sys/bus/pci/devices/%s/driver_override" % dev_id
390 if os.path.exists(filename):
392 f = open(filename, "w")
394 print("Error: unbind failed for %s - Cannot open %s"
395 % (dev_id, filename))
401 print("Error: unbind failed for %s - Cannot open %s"
402 % (dev_id, filename))
405 # write to /sys to unbind
406 filename = "/sys/bus/pci/drivers/%s/unbind" % dev["Driver_str"]
408 f = open(filename, "a")
410 print("Error: unbind failed for %s - Cannot open %s"
411 % (dev_id, filename))
417 def bind_one(dev_id, driver, force):
418 '''Bind the device given by "dev_id" to the driver "driver". If the device
419 is already bound to a different driver, it will be unbound first'''
420 dev = devices[dev_id]
421 saved_driver = None # used to rollback any unbind in case of failure
423 # prevent disconnection of our ssh session
424 if dev["Ssh_if"] and not force:
425 print("Routing table indicates that interface %s is active. "
426 "Not modifying" % (dev_id))
429 # unbind any existing drivers we don't want
430 if has_driver(dev_id):
431 if dev["Driver_str"] == driver:
432 print("%s already bound to driver %s, skipping\n"
436 saved_driver = dev["Driver_str"]
437 unbind_one(dev_id, force)
438 dev["Driver_str"] = "" # clear driver string
440 # For kernels >= 3.15 driver_override can be used to specify the driver
441 # for a device rather than relying on the driver to provide a positive
442 # match of the device. The existing process of looking up
443 # the vendor and device ID, adding them to the driver new_id,
444 # will erroneously bind other devices too which has the additional burden
445 # of unbinding those devices
446 if driver in dpdk_drivers:
447 filename = "/sys/bus/pci/devices/%s/driver_override" % dev_id
448 if os.path.exists(filename):
450 f = open(filename, "w")
452 print("Error: bind failed for %s - Cannot open %s"
453 % (dev_id, filename))
456 f.write("%s" % driver)
459 print("Error: bind failed for %s - Cannot write driver %s to "
460 "PCI ID " % (dev_id, driver))
462 # For kernels < 3.15 use new_id to add PCI id's to the driver
464 filename = "/sys/bus/pci/drivers/%s/new_id" % driver
466 f = open(filename, "w")
468 print("Error: bind failed for %s - Cannot open %s"
469 % (dev_id, filename))
472 # Convert Device and Vendor Id to int to write to new_id
473 f.write("%04x %04x" % (int(dev["Vendor"],16),
474 int(dev["Device"], 16)))
477 print("Error: bind failed for %s - Cannot write new PCI ID to "
478 "driver %s" % (dev_id, driver))
481 # do the bind by writing to /sys
482 filename = "/sys/bus/pci/drivers/%s/bind" % driver
484 f = open(filename, "a")
486 print("Error: bind failed for %s - Cannot open %s"
487 % (dev_id, filename))
488 if saved_driver is not None: # restore any previous driver
489 bind_one(dev_id, saved_driver, force)
495 # for some reason, closing dev_id after adding a new PCI ID to new_id
496 # results in IOError. however, if the device was successfully bound,
497 # we don't care for any errors and can safely ignore IOError
498 tmp = get_pci_device_details(dev_id, True)
499 if "Driver_str" in tmp and tmp["Driver_str"] == driver:
501 print("Error: bind failed for %s - Cannot bind to driver %s"
503 if saved_driver is not None: # restore any previous driver
504 bind_one(dev_id, saved_driver, force)
508 def unbind_all(dev_list, force=False):
509 """Unbind method, takes a list of device locations"""
510 dev_list = map(dev_id_from_dev_name, dev_list)
515 def bind_all(dev_list, driver, force=False):
516 """Bind method, takes a list of device locations"""
519 dev_list = map(dev_id_from_dev_name, dev_list)
522 bind_one(d, driver, force)
524 # For kenels < 3.15 when binding devices to a generic driver
525 # (i.e. one that doesn't have a PCI ID table) using new_id, some devices
526 # that are not bound to any other driver could be bound even if no one has
527 # asked them to. hence, we check the list of drivers again, and see if
528 # some of the previously-unbound devices were erroneously bound.
529 if not os.path.exists("/sys/bus/pci/devices/%s/driver_override" % d):
530 for d in devices.keys():
531 # skip devices that were already bound or that we know should be bound
532 if "Driver_str" in devices[d] or d in dev_list:
535 # update information about this device
536 devices[d] = dict(devices[d].items() +
537 get_pci_device_details(d, True).items())
539 # check if updated information indicates that the device was bound
540 if "Driver_str" in devices[d]:
544 def display_devices(title, dev_list, extra_params=None):
545 '''Displays to the user the details of a list of devices given in
546 "dev_list". The "extra_params" parameter, if given, should contain a string
547 with %()s fields in it for replacement by the named fields in each
548 device's dictionary.'''
549 strings = [] # this holds the strings to print. We sort before printing
550 print("\n%s" % title)
551 print("="*len(title))
552 if len(dev_list) == 0:
553 strings.append("<none>")
556 if extra_params is not None:
557 strings.append("%s '%s %s' %s" % (dev["Slot"],
562 strings.append("%s '%s'" % (dev["Slot"], dev["Device_str"]))
563 # sort before printing, so that the entries appear in PCI order
565 print("\n".join(strings)) # print one per line
567 def show_device_status(devices_type, device_name):
573 # split our list of network devices into the three categories above
574 for d in devices.keys():
575 if device_type_match(devices[d], devices_type):
576 if not has_driver(d):
577 no_drv.append(devices[d])
579 if devices[d]["Driver_str"] in dpdk_drivers:
580 dpdk_drv.append(devices[d])
582 kernel_drv.append(devices[d])
584 # print each category separately, so we can clearly see what's used by DPDK
585 display_devices("%s devices using DPDK-compatible driver" % device_name,
586 dpdk_drv, "drv=%(Driver_str)s unused=%(Module_str)s")
587 display_devices("%s devices using kernel driver" % device_name, kernel_drv,
588 "if=%(Interface)s drv=%(Driver_str)s "
589 "unused=%(Module_str)s %(Active)s")
590 display_devices("Other %s devices" % device_name, no_drv,
591 "unused=%(Module_str)s")
594 '''Function called when the script is passed the "--status" option.
595 Displays to the user what devices are bound to the igb_uio driver, the
596 kernel driver or to no driver'''
598 show_device_status(network_devices, "Network")
599 show_device_status(crypto_devices, "Crypto")
600 show_device_status(eventdev_devices, "Eventdev")
603 '''Parses the command-line arguments given by the user and takes the
604 appropriate action for each'''
609 if len(sys.argv) <= 1:
614 opts, args = getopt.getopt(sys.argv[1:], "b:us",
615 ["help", "usage", "status", "force",
617 except getopt.GetoptError as error:
619 print("Run '%s --usage' for further information" % sys.argv[0])
622 for opt, arg in opts:
623 if opt == "--help" or opt == "--usage":
626 if opt == "--status" or opt == "-s":
630 if opt == "-b" or opt == "-u" or opt == "--bind" or opt == "--unbind":
631 if b_flag is not None:
632 print("Error - Only one bind or unbind may be specified\n")
634 if opt == "-u" or opt == "--unbind":
640 def do_arg_actions():
641 '''do the actual action requested by the user'''
647 if b_flag is None and not status_flag:
648 print("Error: No action specified for devices."
649 "Please give a -b or -u option")
650 print("Run '%s --usage' for further information" % sys.argv[0])
653 if b_flag is not None and len(args) == 0:
654 print("Error: No devices specified.")
655 print("Run '%s --usage' for further information" % sys.argv[0])
658 if b_flag == "none" or b_flag == "None":
659 unbind_all(args, force_flag)
660 elif b_flag is not None:
661 bind_all(args, b_flag, force_flag)
663 if b_flag is not None:
665 # refresh if we have changed anything
666 get_device_details(network_devices)
667 get_device_details(crypto_devices)
668 get_device_details(eventdev_devices)
673 '''program main function'''
677 get_device_details(network_devices)
678 get_device_details(crypto_devices)
679 get_device_details(eventdev_devices)
682 if __name__ == "__main__":