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, crypto, event
91 For each device, it displays the PCI domain, bus, slot and function,
92 along with a text description of the device. Depending upon whether the
93 device is being used by a kernel driver, the igb_uio driver, or no
94 driver, other relevant information will be displayed:
95 * the Linux interface name e.g. if=eth0
96 * the driver being used e.g. drv=igb_uio
97 * any suitable drivers not currently using that device
99 NOTE: if this flag is passed along with a bind/unbind option, the
100 status display will always occur after the other operations have taken
104 Print the status of given device group. Supported device groups are:
105 "net", "crypto", "event" and "mempool"
107 -b driver, --bind=driver:
108 Select the driver to use or \"none\" to unbind the device
111 Unbind a device (Equivalent to \"-b none\")
114 By default, network devices which are used by Linux - as indicated by
115 having routes in the routing table - cannot be modified. Using the
116 --force flag overrides this behavior, allowing active links to be
118 WARNING: This can lead to loss of network connection and should be used
124 To display current device status:
127 To display current network device status:
128 %(argv0)s --status-dev net
130 To bind eth1 from the current driver and move to use igb_uio
131 %(argv0)s --bind=igb_uio eth1
133 To unbind 0000:01:00.0 from using any driver
134 %(argv0)s -u 0000:01:00.0
136 To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver
137 %(argv0)s -b ixgbe 02:00.0 02:00.1
139 """ % locals()) # replace items from local variables
142 # This is roughly compatible with check_output function in subprocess module
143 # which is only available in python 2.7.
144 def check_output(args, stderr=None):
145 '''Run a command and capture its output'''
146 return subprocess.Popen(args, stdout=subprocess.PIPE,
147 stderr=stderr).communicate()[0]
150 def find_module(mod):
151 '''find the .ko file for kernel module named mod.
152 Searches the $RTE_SDK/$RTE_TARGET directory, the kernel
153 modules directory and finally under the parent directory of
155 # check $RTE_SDK/$RTE_TARGET directory
156 if 'RTE_SDK' in os.environ and 'RTE_TARGET' in os.environ:
157 path = "%s/%s/kmod/%s.ko" % (os.environ['RTE_SDK'],
158 os.environ['RTE_TARGET'], mod)
164 with open(os.devnull, "w") as fnull:
165 path = check_output(["modinfo", "-n", mod], stderr=fnull).strip()
167 if path and exists(path):
169 except: # if modinfo can't find module, it fails, so continue
172 # check for a copy based off current path
173 tools_dir = dirname(abspath(sys.argv[0]))
174 if tools_dir.endswith("tools"):
175 base_dir = dirname(tools_dir)
176 find_out = check_output(["find", base_dir, "-name", mod + ".ko"])
177 if len(find_out) > 0: # something matched
178 path = find_out.splitlines()[0]
184 '''Checks that igb_uio is loaded'''
187 # list of supported modules
188 mods = [{"Name": driver, "Found": False} for driver in dpdk_drivers]
190 # first check if module is loaded
192 # Get list of sysfs modules (both built-in and dynamically loaded)
193 sysfs_path = '/sys/module/'
195 # Get the list of directories in sysfs_path
196 sysfs_mods = [os.path.join(sysfs_path, o) for o
197 in os.listdir(sysfs_path)
198 if os.path.isdir(os.path.join(sysfs_path, o))]
200 # Extract the last element of '/sys/module/abc' in the array
201 sysfs_mods = [a.split('/')[-1] for a in sysfs_mods]
203 # special case for vfio_pci (module is named vfio-pci,
204 # but its .ko is named vfio_pci)
205 sysfs_mods = map(lambda a:
206 a if a != 'vfio_pci' else 'vfio-pci', sysfs_mods)
209 if mod["Name"] in sysfs_mods:
214 # check if we have at least one loaded module
215 if True not in [mod["Found"] for mod in mods] and b_flag is not None:
216 if b_flag in dpdk_drivers:
217 print("Error - no supported modules(DPDK driver) are loaded")
220 print("Warning - no supported modules(DPDK driver) are loaded")
222 # change DPDK driver list to only contain drivers that are loaded
223 dpdk_drivers = [mod["Name"] for mod in mods if mod["Found"]]
226 def has_driver(dev_id):
227 '''return true if a device is assigned to a driver. False otherwise'''
228 return "Driver_str" in devices[dev_id]
231 def get_pci_device_details(dev_id, probe_lspci):
232 '''This function gets additional details for a PCI device'''
236 extra_info = check_output(["lspci", "-vmmks", dev_id]).splitlines()
238 # parse lspci details
239 for line in extra_info:
242 name, value = line.decode().split("\t", 1)
243 name = name.strip(":") + "_str"
245 # check for a unix interface name
246 device["Interface"] = ""
247 for base, dirs, _ in os.walk("/sys/bus/pci/devices/%s/" % dev_id):
249 device["Interface"] = \
250 ",".join(os.listdir(os.path.join(base, "net")))
252 # check if a port is used for ssh connection
253 device["Ssh_if"] = False
254 device["Active"] = ""
259 '''This function clears any old data'''
262 def get_device_details(devices_type):
263 '''This function populates the "devices" dictionary. The keys used are
264 the pci addresses (domain:bus:slot.func). The values are themselves
265 dictionaries - one for each NIC.'''
269 # first loop through and read details for all devices
270 # request machine readable format, with numeric IDs and String
272 dev_lines = check_output(["lspci", "-Dvmmnnk"]).splitlines()
273 for dev_line in dev_lines:
274 if len(dev_line) == 0:
275 if device_type_match(dev, devices_type):
276 # Replace "Driver" with "Driver_str" to have consistency of
277 # of dictionary key names
278 if "Driver" in dev.keys():
279 dev["Driver_str"] = dev.pop("Driver")
280 # use dict to make copy of dev
281 devices[dev["Slot"]] = dict(dev)
282 # Clear previous device's data
285 name, value = dev_line.decode().split("\t", 1)
286 value_list = value.rsplit(' ', 1)
287 if len(value_list) > 1:
288 # String stored in <name>_str
289 dev[name.rstrip(":") + '_str'] = value_list[0]
291 dev[name.rstrip(":")] = value_list[len(value_list) - 1] \
292 .rstrip("]").lstrip("[")
294 if devices_type == network_devices:
295 # check what is the interface if any for an ssh connection if
296 # any to this host, so we can mark it later.
298 route = check_output(["ip", "-o", "route"])
299 # filter out all lines for 169.254 routes
300 route = "\n".join(filter(lambda ln: not ln.startswith("169.254"),
301 route.decode().splitlines()))
302 rt_info = route.split()
303 for i in range(len(rt_info) - 1):
304 if rt_info[i] == "dev":
305 ssh_if.append(rt_info[i+1])
307 # based on the basic info, get extended text details
308 for d in devices.keys():
309 if not device_type_match(devices[d], devices_type):
312 # get additional info and add it to existing data
313 devices[d] = devices[d].copy()
314 # No need to probe lspci
315 devices[d].update(get_pci_device_details(d, False).items())
317 if devices_type == network_devices:
319 if _if in devices[d]["Interface"].split(","):
320 devices[d]["Ssh_if"] = True
321 devices[d]["Active"] = "*Active*"
324 # add igb_uio to list of supporting modules if needed
325 if "Module_str" in devices[d]:
326 for driver in dpdk_drivers:
327 if driver not in devices[d]["Module_str"]:
328 devices[d]["Module_str"] = \
329 devices[d]["Module_str"] + ",%s" % driver
331 devices[d]["Module_str"] = ",".join(dpdk_drivers)
333 # make sure the driver and module strings do not have any duplicates
335 modules = devices[d]["Module_str"].split(",")
336 if devices[d]["Driver_str"] in modules:
337 modules.remove(devices[d]["Driver_str"])
338 devices[d]["Module_str"] = ",".join(modules)
341 def device_type_match(dev, devices_type):
342 for i in range(len(devices_type)):
344 [x for x in devices_type[i].values() if x is not None])
346 if dev["Class"][0:2] == devices_type[i]["Class"]:
347 match_count = match_count + 1
348 for key in devices_type[i].keys():
349 if key != 'Class' and devices_type[i][key]:
350 value_list = devices_type[i][key].split(',')
351 for value in value_list:
352 if value.strip(' ') == dev[key]:
353 match_count = match_count + 1
354 # count must be the number of non None parameters to match
355 if match_count == param_count:
359 def dev_id_from_dev_name(dev_name):
360 '''Take a device "name" - a string passed in by user to identify a NIC
361 device, and determine the device id - i.e. the domain:bus:slot.func - for
362 it, which can then be used to index into the devices array'''
364 # check if it's already a suitable index
365 if dev_name in devices:
367 # check if it's an index just missing the domain part
368 elif "0000:" + dev_name in devices:
369 return "0000:" + dev_name
371 # check if it's an interface name, e.g. eth1
372 for d in devices.keys():
373 if dev_name in devices[d]["Interface"].split(","):
374 return devices[d]["Slot"]
375 # if nothing else matches - error
376 print("Unknown device: %s. "
377 "Please specify device in \"bus:slot.func\" format" % dev_name)
381 def unbind_one(dev_id, force):
382 '''Unbind the device identified by "dev_id" from its current driver'''
383 dev = devices[dev_id]
384 if not has_driver(dev_id):
385 print("%s %s %s is not currently managed by any driver\n" %
386 (dev["Slot"], dev["Device_str"], dev["Interface"]))
389 # prevent us disconnecting ourselves
390 if dev["Ssh_if"] and not force:
391 print("Routing table indicates that interface %s is active. "
392 "Skipping unbind" % (dev_id))
395 # write to /sys to unbind
396 filename = "/sys/bus/pci/drivers/%s/unbind" % dev["Driver_str"]
398 f = open(filename, "a")
400 print("Error: unbind failed for %s - Cannot open %s"
401 % (dev_id, filename))
407 def bind_one(dev_id, driver, force):
408 '''Bind the device given by "dev_id" to the driver "driver". If the device
409 is already bound to a different driver, it will be unbound first'''
410 dev = devices[dev_id]
411 saved_driver = None # used to rollback any unbind in case of failure
413 # prevent disconnection of our ssh session
414 if dev["Ssh_if"] and not force:
415 print("Routing table indicates that interface %s is active. "
416 "Not modifying" % (dev_id))
419 # unbind any existing drivers we don't want
420 if has_driver(dev_id):
421 if dev["Driver_str"] == driver:
422 print("%s already bound to driver %s, skipping\n"
426 saved_driver = dev["Driver_str"]
427 unbind_one(dev_id, force)
428 dev["Driver_str"] = "" # clear driver string
430 # For kernels >= 3.15 driver_override can be used to specify the driver
431 # for a device rather than relying on the driver to provide a positive
432 # match of the device. The existing process of looking up
433 # the vendor and device ID, adding them to the driver new_id,
434 # will erroneously bind other devices too which has the additional burden
435 # of unbinding those devices
436 if driver in dpdk_drivers:
437 filename = "/sys/bus/pci/devices/%s/driver_override" % dev_id
438 if os.path.exists(filename):
440 f = open(filename, "w")
442 print("Error: bind failed for %s - Cannot open %s"
443 % (dev_id, filename))
446 f.write("%s" % driver)
449 print("Error: bind failed for %s - Cannot write driver %s to "
450 "PCI ID " % (dev_id, driver))
452 # For kernels < 3.15 use new_id to add PCI id's to the driver
454 filename = "/sys/bus/pci/drivers/%s/new_id" % driver
456 f = open(filename, "w")
458 print("Error: bind failed for %s - Cannot open %s"
459 % (dev_id, filename))
462 # Convert Device and Vendor Id to int to write to new_id
463 f.write("%04x %04x" % (int(dev["Vendor"],16),
464 int(dev["Device"], 16)))
467 print("Error: bind failed for %s - Cannot write new PCI ID to "
468 "driver %s" % (dev_id, driver))
471 # do the bind by writing to /sys
472 filename = "/sys/bus/pci/drivers/%s/bind" % driver
474 f = open(filename, "a")
476 print("Error: bind failed for %s - Cannot open %s"
477 % (dev_id, filename))
478 if saved_driver is not None: # restore any previous driver
479 bind_one(dev_id, saved_driver, force)
485 # for some reason, closing dev_id after adding a new PCI ID to new_id
486 # results in IOError. however, if the device was successfully bound,
487 # we don't care for any errors and can safely ignore IOError
488 tmp = get_pci_device_details(dev_id, True)
489 if "Driver_str" in tmp and tmp["Driver_str"] == driver:
491 print("Error: bind failed for %s - Cannot bind to driver %s"
493 if saved_driver is not None: # restore any previous driver
494 bind_one(dev_id, saved_driver, force)
497 # For kernels > 3.15 driver_override is used to bind a device to a driver.
498 # Before unbinding it, overwrite driver_override with empty string so that
499 # the device can be bound to any other driver
500 filename = "/sys/bus/pci/devices/%s/driver_override" % dev_id
501 if os.path.exists(filename):
503 f = open(filename, "w")
505 print("Error: unbind failed for %s - Cannot open %s"
506 % (dev_id, filename))
512 print("Error: unbind failed for %s - Cannot open %s"
513 % (dev_id, filename))
517 def unbind_all(dev_list, force=False):
518 """Unbind method, takes a list of device locations"""
519 dev_list = map(dev_id_from_dev_name, dev_list)
524 def bind_all(dev_list, driver, force=False):
525 """Bind method, takes a list of device locations"""
528 dev_list = map(dev_id_from_dev_name, dev_list)
531 bind_one(d, driver, force)
533 # For kenels < 3.15 when binding devices to a generic driver
534 # (i.e. one that doesn't have a PCI ID table) using new_id, some devices
535 # that are not bound to any other driver could be bound even if no one has
536 # asked them to. hence, we check the list of drivers again, and see if
537 # some of the previously-unbound devices were erroneously bound.
538 if not os.path.exists("/sys/bus/pci/devices/%s/driver_override" % d):
539 for d in devices.keys():
540 # skip devices that were already bound or that we know should be bound
541 if "Driver_str" in devices[d] or d in dev_list:
544 # update information about this device
545 devices[d] = dict(devices[d].items() +
546 get_pci_device_details(d, True).items())
548 # check if updated information indicates that the device was bound
549 if "Driver_str" in devices[d]:
553 def display_devices(title, dev_list, extra_params=None):
554 '''Displays to the user the details of a list of devices given in
555 "dev_list". The "extra_params" parameter, if given, should contain a string
556 with %()s fields in it for replacement by the named fields in each
557 device's dictionary.'''
558 strings = [] # this holds the strings to print. We sort before printing
559 print("\n%s" % title)
560 print("="*len(title))
561 if len(dev_list) == 0:
562 strings.append("<none>")
565 if extra_params is not None:
566 strings.append("%s '%s %s' %s" % (dev["Slot"],
571 strings.append("%s '%s'" % (dev["Slot"], dev["Device_str"]))
572 # sort before printing, so that the entries appear in PCI order
574 print("\n".join(strings)) # print one per line
576 def show_device_status(devices_type, device_name):
582 # split our list of network devices into the three categories above
583 for d in devices.keys():
584 if device_type_match(devices[d], devices_type):
585 if not has_driver(d):
586 no_drv.append(devices[d])
588 if devices[d]["Driver_str"] in dpdk_drivers:
589 dpdk_drv.append(devices[d])
591 kernel_drv.append(devices[d])
593 # print each category separately, so we can clearly see what's used by DPDK
594 display_devices("%s devices using DPDK-compatible driver" % device_name,
595 dpdk_drv, "drv=%(Driver_str)s unused=%(Module_str)s")
596 display_devices("%s devices using kernel driver" % device_name, kernel_drv,
597 "if=%(Interface)s drv=%(Driver_str)s "
598 "unused=%(Module_str)s %(Active)s")
599 display_devices("Other %s devices" % device_name, no_drv,
600 "unused=%(Module_str)s")
603 '''Function called when the script is passed the "--status" option.
604 Displays to the user what devices are bound to the igb_uio driver, the
605 kernel driver or to no driver'''
607 if status_dev == "net" or status_dev == "all":
608 show_device_status(network_devices, "Network")
610 if status_dev == "crypto" or status_dev == "all":
611 show_device_status(crypto_devices, "Crypto")
613 if status_dev == "event" or status_dev == "all":
614 show_device_status(eventdev_devices, "Eventdev")
616 if status_dev == "mempool" or status_dev == "all":
617 show_device_status(mempool_devices, "Mempool")
620 '''Parses the command-line arguments given by the user and takes the
621 appropriate action for each'''
627 if len(sys.argv) <= 1:
632 opts, args = getopt.getopt(sys.argv[1:], "b:us",
633 ["help", "usage", "status", "status-dev=",
634 "force", "bind=", "unbind", ])
635 except getopt.GetoptError as error:
637 print("Run '%s --usage' for further information" % sys.argv[0])
640 for opt, arg in opts:
641 if opt == "--help" or opt == "--usage":
644 if opt == "--status-dev":
647 if opt == "--status" or opt == "-s":
652 if opt == "-b" or opt == "-u" or opt == "--bind" or opt == "--unbind":
653 if b_flag is not None:
654 print("Error - Only one bind or unbind may be specified\n")
656 if opt == "-u" or opt == "--unbind":
662 def do_arg_actions():
663 '''do the actual action requested by the user'''
669 if b_flag is None and not status_flag:
670 print("Error: No action specified for devices."
671 "Please give a -b or -u option")
672 print("Run '%s --usage' for further information" % sys.argv[0])
675 if b_flag is not None and len(args) == 0:
676 print("Error: No devices specified.")
677 print("Run '%s --usage' for further information" % sys.argv[0])
680 if b_flag == "none" or b_flag == "None":
681 unbind_all(args, force_flag)
682 elif b_flag is not None:
683 bind_all(args, b_flag, force_flag)
685 if b_flag is not None:
687 # refresh if we have changed anything
688 get_device_details(network_devices)
689 get_device_details(crypto_devices)
690 get_device_details(eventdev_devices)
691 get_device_details(mempool_devices)
696 '''program main function'''
700 get_device_details(network_devices)
701 get_device_details(crypto_devices)
702 get_device_details(eventdev_devices)
703 get_device_details(mempool_devices)
706 if __name__ == "__main__":