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}
50 cavium_fpa = {'Class': '08', 'Vendor': '177d', 'Device': 'a053',
51 'SVendor': None, 'SDevice': None}
53 network_devices = [network_class]
54 crypto_devices = [encryption_class, intel_processor_class]
55 eventdev_devices = [cavium_sso]
56 mempool_devices = [cavium_fpa]
58 # global dict ethernet devices present. Dictionary indexed by PCI address.
59 # Each device within this is itself a dictionary of device properties
61 # list of supported DPDK drivers
62 dpdk_drivers = ["igb_uio", "vfio-pci", "uio_pci_generic"]
64 # command-line arg flags
72 '''Print usage information for the program'''
73 argv0 = basename(sys.argv[0])
78 %(argv0)s [options] DEVICE1 DEVICE2 ....
80 where DEVICE1, DEVICE2 etc, are specified via PCI "domain:bus:slot.func" syntax
81 or "bus:slot.func" syntax. For devices bound to Linux kernel drivers, they may
82 also be referred to by Linux interface name e.g. eth0, eth1, em0, em1, etc.
86 Display usage information and quit
89 Print the current status of all known network and crypto devices.
90 For each device, it displays the PCI domain, bus, slot and function,
91 along with a text description of the device. Depending upon whether the
92 device is being used by a kernel driver, the igb_uio driver, or no
93 driver, other relevant information will be displayed:
94 * the Linux interface name e.g. if=eth0
95 * the driver being used e.g. drv=igb_uio
96 * any suitable drivers not currently using that device
98 NOTE: if this flag is passed along with a bind/unbind option, the
99 status display will always occur after the other operations have taken
102 -b driver, --bind=driver:
103 Select the driver to use or \"none\" to unbind the device
106 Unbind a device (Equivalent to \"-b none\")
109 By default, network devices which are used by Linux - as indicated by
110 having routes in the routing table - cannot be modified. Using the
111 --force flag overrides this behavior, allowing active links to be
113 WARNING: This can lead to loss of network connection and should be used
119 To display current device status:
122 To bind eth1 from the current driver and move to use igb_uio
123 %(argv0)s --bind=igb_uio eth1
125 To unbind 0000:01:00.0 from using any driver
126 %(argv0)s -u 0000:01:00.0
128 To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver
129 %(argv0)s -b ixgbe 02:00.0 02:00.1
131 """ % locals()) # replace items from local variables
134 # This is roughly compatible with check_output function in subprocess module
135 # which is only available in python 2.7.
136 def check_output(args, stderr=None):
137 '''Run a command and capture its output'''
138 return subprocess.Popen(args, stdout=subprocess.PIPE,
139 stderr=stderr).communicate()[0]
142 def find_module(mod):
143 '''find the .ko file for kernel module named mod.
144 Searches the $RTE_SDK/$RTE_TARGET directory, the kernel
145 modules directory and finally under the parent directory of
147 # check $RTE_SDK/$RTE_TARGET directory
148 if 'RTE_SDK' in os.environ and 'RTE_TARGET' in os.environ:
149 path = "%s/%s/kmod/%s.ko" % (os.environ['RTE_SDK'],
150 os.environ['RTE_TARGET'], mod)
156 depmod_out = check_output(["modinfo", "-n", mod],
157 stderr=subprocess.STDOUT).lower()
158 if "error" not in depmod_out:
159 path = depmod_out.strip()
162 except: # if modinfo can't find module, it fails, so continue
165 # check for a copy based off current path
166 tools_dir = dirname(abspath(sys.argv[0]))
167 if tools_dir.endswith("tools"):
168 base_dir = dirname(tools_dir)
169 find_out = check_output(["find", base_dir, "-name", mod + ".ko"])
170 if len(find_out) > 0: # something matched
171 path = find_out.splitlines()[0]
177 '''Checks that igb_uio is loaded'''
180 # list of supported modules
181 mods = [{"Name": driver, "Found": False} for driver in dpdk_drivers]
183 # first check if module is loaded
185 # Get list of sysfs modules (both built-in and dynamically loaded)
186 sysfs_path = '/sys/module/'
188 # Get the list of directories in sysfs_path
189 sysfs_mods = [os.path.join(sysfs_path, o) for o
190 in os.listdir(sysfs_path)
191 if os.path.isdir(os.path.join(sysfs_path, o))]
193 # Extract the last element of '/sys/module/abc' in the array
194 sysfs_mods = [a.split('/')[-1] for a in sysfs_mods]
196 # special case for vfio_pci (module is named vfio-pci,
197 # but its .ko is named vfio_pci)
198 sysfs_mods = map(lambda a:
199 a if a != 'vfio_pci' else 'vfio-pci', sysfs_mods)
202 if mod["Name"] in sysfs_mods:
207 # check if we have at least one loaded module
208 if True not in [mod["Found"] for mod in mods] and b_flag is not None:
209 if b_flag in dpdk_drivers:
210 print("Error - no supported modules(DPDK driver) are loaded")
213 print("Warning - no supported modules(DPDK driver) are loaded")
215 # change DPDK driver list to only contain drivers that are loaded
216 dpdk_drivers = [mod["Name"] for mod in mods if mod["Found"]]
219 def has_driver(dev_id):
220 '''return true if a device is assigned to a driver. False otherwise'''
221 return "Driver_str" in devices[dev_id]
224 def get_pci_device_details(dev_id, probe_lspci):
225 '''This function gets additional details for a PCI device'''
229 extra_info = check_output(["lspci", "-vmmks", dev_id]).splitlines()
231 # parse lspci details
232 for line in extra_info:
235 name, value = line.decode().split("\t", 1)
236 name = name.strip(":") + "_str"
238 # check for a unix interface name
239 device["Interface"] = ""
240 for base, dirs, _ in os.walk("/sys/bus/pci/devices/%s/" % dev_id):
242 device["Interface"] = \
243 ",".join(os.listdir(os.path.join(base, "net")))
245 # check if a port is used for ssh connection
246 device["Ssh_if"] = False
247 device["Active"] = ""
252 '''This function clears any old data'''
255 def get_device_details(devices_type):
256 '''This function populates the "devices" dictionary. The keys used are
257 the pci addresses (domain:bus:slot.func). The values are themselves
258 dictionaries - one for each NIC.'''
262 # first loop through and read details for all devices
263 # request machine readable format, with numeric IDs and String
265 dev_lines = check_output(["lspci", "-Dvmmnnk"]).splitlines()
266 for dev_line in dev_lines:
267 if len(dev_line) == 0:
268 if device_type_match(dev, devices_type):
269 # Replace "Driver" with "Driver_str" to have consistency of
270 # of dictionary key names
271 if "Driver" in dev.keys():
272 dev["Driver_str"] = dev.pop("Driver")
273 # use dict to make copy of dev
274 devices[dev["Slot"]] = dict(dev)
275 # Clear previous device's data
278 name, value = dev_line.decode().split("\t", 1)
279 value_list = value.rsplit(' ', 1)
280 if len(value_list) > 1:
281 # String stored in <name>_str
282 dev[name.rstrip(":") + '_str'] = value_list[0]
284 dev[name.rstrip(":")] = value_list[len(value_list) - 1] \
285 .rstrip("]").lstrip("[")
287 if devices_type == network_devices:
288 # check what is the interface if any for an ssh connection if
289 # any to this host, so we can mark it later.
291 route = check_output(["ip", "-o", "route"])
292 # filter out all lines for 169.254 routes
293 route = "\n".join(filter(lambda ln: not ln.startswith("169.254"),
294 route.decode().splitlines()))
295 rt_info = route.split()
296 for i in range(len(rt_info) - 1):
297 if rt_info[i] == "dev":
298 ssh_if.append(rt_info[i+1])
300 # based on the basic info, get extended text details
301 for d in devices.keys():
302 if not device_type_match(devices[d], devices_type):
305 # get additional info and add it to existing data
306 devices[d] = devices[d].copy()
307 # No need to probe lspci
308 devices[d].update(get_pci_device_details(d, False).items())
310 if devices_type == network_devices:
312 if _if in devices[d]["Interface"].split(","):
313 devices[d]["Ssh_if"] = True
314 devices[d]["Active"] = "*Active*"
317 # add igb_uio to list of supporting modules if needed
318 if "Module_str" in devices[d]:
319 for driver in dpdk_drivers:
320 if driver not in devices[d]["Module_str"]:
321 devices[d]["Module_str"] = \
322 devices[d]["Module_str"] + ",%s" % driver
324 devices[d]["Module_str"] = ",".join(dpdk_drivers)
326 # make sure the driver and module strings do not have any duplicates
328 modules = devices[d]["Module_str"].split(",")
329 if devices[d]["Driver_str"] in modules:
330 modules.remove(devices[d]["Driver_str"])
331 devices[d]["Module_str"] = ",".join(modules)
334 def device_type_match(dev, devices_type):
335 for i in range(len(devices_type)):
337 [x for x in devices_type[i].values() if x is not None])
339 if dev["Class"][0:2] == devices_type[i]["Class"]:
340 match_count = match_count + 1
341 for key in devices_type[i].keys():
342 if key != 'Class' and devices_type[i][key]:
343 value_list = devices_type[i][key].split(',')
344 for value in value_list:
345 if value.strip(' ') == dev[key]:
346 match_count = match_count + 1
347 # count must be the number of non None parameters to match
348 if match_count == param_count:
353 def dev_id_from_dev_name(dev_name):
354 '''Take a device "name" - a string passed in by user to identify a NIC
355 device, and determine the device id - i.e. the domain:bus:slot.func - for
356 it, which can then be used to index into the devices array'''
358 # check if it's already a suitable index
359 if dev_name in devices:
361 # check if it's an index just missing the domain part
362 elif "0000:" + dev_name in devices:
363 return "0000:" + dev_name
365 # check if it's an interface name, e.g. eth1
366 for d in devices.keys():
367 if dev_name in devices[d]["Interface"].split(","):
368 return devices[d]["Slot"]
369 # if nothing else matches - error
370 print("Unknown device: %s. "
371 "Please specify device in \"bus:slot.func\" format" % dev_name)
375 def unbind_one(dev_id, force):
376 '''Unbind the device identified by "dev_id" from its current driver'''
377 dev = devices[dev_id]
378 if not has_driver(dev_id):
379 print("%s %s %s is not currently managed by any driver\n" %
380 (dev["Slot"], dev["Device_str"], dev["Interface"]))
383 # prevent us disconnecting ourselves
384 if dev["Ssh_if"] and not force:
385 print("Routing table indicates that interface %s is active. "
386 "Skipping unbind" % (dev_id))
389 # write to /sys to unbind
390 filename = "/sys/bus/pci/drivers/%s/unbind" % dev["Driver_str"]
392 f = open(filename, "a")
394 print("Error: unbind failed for %s - Cannot open %s"
395 % (dev_id, filename))
401 def bind_one(dev_id, driver, force):
402 '''Bind the device given by "dev_id" to the driver "driver". If the device
403 is already bound to a different driver, it will be unbound first'''
404 dev = devices[dev_id]
405 saved_driver = None # used to rollback any unbind in case of failure
407 # prevent disconnection of our ssh session
408 if dev["Ssh_if"] and not force:
409 print("Routing table indicates that interface %s is active. "
410 "Not modifying" % (dev_id))
413 # unbind any existing drivers we don't want
414 if has_driver(dev_id):
415 if dev["Driver_str"] == driver:
416 print("%s already bound to driver %s, skipping\n"
420 saved_driver = dev["Driver_str"]
421 unbind_one(dev_id, force)
422 dev["Driver_str"] = "" # clear driver string
424 # For kernels >= 3.15 driver_override can be used to specify the driver
425 # for a device rather than relying on the driver to provide a positive
426 # match of the device. The existing process of looking up
427 # the vendor and device ID, adding them to the driver new_id,
428 # will erroneously bind other devices too which has the additional burden
429 # of unbinding those devices
430 if driver in dpdk_drivers:
431 filename = "/sys/bus/pci/devices/%s/driver_override" % dev_id
432 if os.path.exists(filename):
434 f = open(filename, "w")
436 print("Error: bind failed for %s - Cannot open %s"
437 % (dev_id, filename))
440 f.write("%s" % driver)
443 print("Error: bind failed for %s - Cannot write driver %s to "
444 "PCI ID " % (dev_id, driver))
446 # For kernels < 3.15 use new_id to add PCI id's to the driver
448 filename = "/sys/bus/pci/drivers/%s/new_id" % driver
450 f = open(filename, "w")
452 print("Error: bind failed for %s - Cannot open %s"
453 % (dev_id, filename))
456 # Convert Device and Vendor Id to int to write to new_id
457 f.write("%04x %04x" % (int(dev["Vendor"],16),
458 int(dev["Device"], 16)))
461 print("Error: bind failed for %s - Cannot write new PCI ID to "
462 "driver %s" % (dev_id, driver))
465 # do the bind by writing to /sys
466 filename = "/sys/bus/pci/drivers/%s/bind" % driver
468 f = open(filename, "a")
470 print("Error: bind failed for %s - Cannot open %s"
471 % (dev_id, filename))
472 if saved_driver is not None: # restore any previous driver
473 bind_one(dev_id, saved_driver, force)
479 # for some reason, closing dev_id after adding a new PCI ID to new_id
480 # results in IOError. however, if the device was successfully bound,
481 # we don't care for any errors and can safely ignore IOError
482 tmp = get_pci_device_details(dev_id, True)
483 if "Driver_str" in tmp and tmp["Driver_str"] == driver:
485 print("Error: bind failed for %s - Cannot bind to driver %s"
487 if saved_driver is not None: # restore any previous driver
488 bind_one(dev_id, saved_driver, force)
491 # For kernels > 3.15 driver_override is used to bind a device to a driver.
492 # Before unbinding it, overwrite driver_override with empty string so that
493 # the device can be bound to any other driver
494 filename = "/sys/bus/pci/devices/%s/driver_override" % dev_id
495 if os.path.exists(filename):
497 f = open(filename, "w")
499 print("Error: unbind failed for %s - Cannot open %s"
500 % (dev_id, filename))
506 print("Error: unbind failed for %s - Cannot open %s"
507 % (dev_id, filename))
511 def unbind_all(dev_list, force=False):
512 """Unbind method, takes a list of device locations"""
513 dev_list = map(dev_id_from_dev_name, dev_list)
518 def bind_all(dev_list, driver, force=False):
519 """Bind method, takes a list of device locations"""
522 dev_list = map(dev_id_from_dev_name, dev_list)
525 bind_one(d, driver, force)
527 # For kenels < 3.15 when binding devices to a generic driver
528 # (i.e. one that doesn't have a PCI ID table) using new_id, some devices
529 # that are not bound to any other driver could be bound even if no one has
530 # asked them to. hence, we check the list of drivers again, and see if
531 # some of the previously-unbound devices were erroneously bound.
532 if not os.path.exists("/sys/bus/pci/devices/%s/driver_override" % d):
533 for d in devices.keys():
534 # skip devices that were already bound or that we know should be bound
535 if "Driver_str" in devices[d] or d in dev_list:
538 # update information about this device
539 devices[d] = dict(devices[d].items() +
540 get_pci_device_details(d, True).items())
542 # check if updated information indicates that the device was bound
543 if "Driver_str" in devices[d]:
547 def display_devices(title, dev_list, extra_params=None):
548 '''Displays to the user the details of a list of devices given in
549 "dev_list". The "extra_params" parameter, if given, should contain a string
550 with %()s fields in it for replacement by the named fields in each
551 device's dictionary.'''
552 strings = [] # this holds the strings to print. We sort before printing
553 print("\n%s" % title)
554 print("="*len(title))
555 if len(dev_list) == 0:
556 strings.append("<none>")
559 if extra_params is not None:
560 strings.append("%s '%s %s' %s" % (dev["Slot"],
565 strings.append("%s '%s'" % (dev["Slot"], dev["Device_str"]))
566 # sort before printing, so that the entries appear in PCI order
568 print("\n".join(strings)) # print one per line
570 def show_device_status(devices_type, device_name):
576 # split our list of network devices into the three categories above
577 for d in devices.keys():
578 if device_type_match(devices[d], devices_type):
579 if not has_driver(d):
580 no_drv.append(devices[d])
582 if devices[d]["Driver_str"] in dpdk_drivers:
583 dpdk_drv.append(devices[d])
585 kernel_drv.append(devices[d])
587 # print each category separately, so we can clearly see what's used by DPDK
588 display_devices("%s devices using DPDK-compatible driver" % device_name,
589 dpdk_drv, "drv=%(Driver_str)s unused=%(Module_str)s")
590 display_devices("%s devices using kernel driver" % device_name, kernel_drv,
591 "if=%(Interface)s drv=%(Driver_str)s "
592 "unused=%(Module_str)s %(Active)s")
593 display_devices("Other %s devices" % device_name, no_drv,
594 "unused=%(Module_str)s")
597 '''Function called when the script is passed the "--status" option.
598 Displays to the user what devices are bound to the igb_uio driver, the
599 kernel driver or to no driver'''
601 show_device_status(network_devices, "Network")
602 show_device_status(crypto_devices, "Crypto")
603 show_device_status(eventdev_devices, "Eventdev")
604 show_device_status(mempool_devices, "Mempool")
607 '''Parses the command-line arguments given by the user and takes the
608 appropriate action for each'''
613 if len(sys.argv) <= 1:
618 opts, args = getopt.getopt(sys.argv[1:], "b:us",
619 ["help", "usage", "status", "force",
621 except getopt.GetoptError as error:
623 print("Run '%s --usage' for further information" % sys.argv[0])
626 for opt, arg in opts:
627 if opt == "--help" or opt == "--usage":
630 if opt == "--status" or opt == "-s":
634 if opt == "-b" or opt == "-u" or opt == "--bind" or opt == "--unbind":
635 if b_flag is not None:
636 print("Error - Only one bind or unbind may be specified\n")
638 if opt == "-u" or opt == "--unbind":
644 def do_arg_actions():
645 '''do the actual action requested by the user'''
651 if b_flag is None and not status_flag:
652 print("Error: No action specified for devices."
653 "Please give a -b or -u option")
654 print("Run '%s --usage' for further information" % sys.argv[0])
657 if b_flag is not None and len(args) == 0:
658 print("Error: No devices specified.")
659 print("Run '%s --usage' for further information" % sys.argv[0])
662 if b_flag == "none" or b_flag == "None":
663 unbind_all(args, force_flag)
664 elif b_flag is not None:
665 bind_all(args, b_flag, force_flag)
667 if b_flag is not None:
669 # refresh if we have changed anything
670 get_device_details(network_devices)
671 get_device_details(crypto_devices)
672 get_device_details(eventdev_devices)
673 get_device_details(mempool_devices)
678 '''program main function'''
682 get_device_details(network_devices)
683 get_device_details(crypto_devices)
684 get_device_details(eventdev_devices)
685 get_device_details(mempool_devices)
688 if __name__ == "__main__":