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:
360 def dev_id_from_dev_name(dev_name):
361 '''Take a device "name" - a string passed in by user to identify a NIC
362 device, and determine the device id - i.e. the domain:bus:slot.func - for
363 it, which can then be used to index into the devices array'''
365 # check if it's already a suitable index
366 if dev_name in devices:
368 # check if it's an index just missing the domain part
369 elif "0000:" + dev_name in devices:
370 return "0000:" + dev_name
372 # check if it's an interface name, e.g. eth1
373 for d in devices.keys():
374 if dev_name in devices[d]["Interface"].split(","):
375 return devices[d]["Slot"]
376 # if nothing else matches - error
377 print("Unknown device: %s. "
378 "Please specify device in \"bus:slot.func\" format" % dev_name)
382 def unbind_one(dev_id, force):
383 '''Unbind the device identified by "dev_id" from its current driver'''
384 dev = devices[dev_id]
385 if not has_driver(dev_id):
386 print("%s %s %s is not currently managed by any driver\n" %
387 (dev["Slot"], dev["Device_str"], dev["Interface"]))
390 # prevent us disconnecting ourselves
391 if dev["Ssh_if"] and not force:
392 print("Routing table indicates that interface %s is active. "
393 "Skipping unbind" % (dev_id))
396 # write to /sys to unbind
397 filename = "/sys/bus/pci/drivers/%s/unbind" % dev["Driver_str"]
399 f = open(filename, "a")
401 print("Error: unbind failed for %s - Cannot open %s"
402 % (dev_id, filename))
408 def bind_one(dev_id, driver, force):
409 '''Bind the device given by "dev_id" to the driver "driver". If the device
410 is already bound to a different driver, it will be unbound first'''
411 dev = devices[dev_id]
412 saved_driver = None # used to rollback any unbind in case of failure
414 # prevent disconnection of our ssh session
415 if dev["Ssh_if"] and not force:
416 print("Routing table indicates that interface %s is active. "
417 "Not modifying" % (dev_id))
420 # unbind any existing drivers we don't want
421 if has_driver(dev_id):
422 if dev["Driver_str"] == driver:
423 print("%s already bound to driver %s, skipping\n"
427 saved_driver = dev["Driver_str"]
428 unbind_one(dev_id, force)
429 dev["Driver_str"] = "" # clear driver string
431 # For kernels >= 3.15 driver_override can be used to specify the driver
432 # for a device rather than relying on the driver to provide a positive
433 # match of the device. The existing process of looking up
434 # the vendor and device ID, adding them to the driver new_id,
435 # will erroneously bind other devices too which has the additional burden
436 # of unbinding those devices
437 if driver in dpdk_drivers:
438 filename = "/sys/bus/pci/devices/%s/driver_override" % dev_id
439 if os.path.exists(filename):
441 f = open(filename, "w")
443 print("Error: bind failed for %s - Cannot open %s"
444 % (dev_id, filename))
447 f.write("%s" % driver)
450 print("Error: bind failed for %s - Cannot write driver %s to "
451 "PCI ID " % (dev_id, driver))
453 # For kernels < 3.15 use new_id to add PCI id's to the driver
455 filename = "/sys/bus/pci/drivers/%s/new_id" % driver
457 f = open(filename, "w")
459 print("Error: bind failed for %s - Cannot open %s"
460 % (dev_id, filename))
463 # Convert Device and Vendor Id to int to write to new_id
464 f.write("%04x %04x" % (int(dev["Vendor"],16),
465 int(dev["Device"], 16)))
468 print("Error: bind failed for %s - Cannot write new PCI ID to "
469 "driver %s" % (dev_id, driver))
472 # do the bind by writing to /sys
473 filename = "/sys/bus/pci/drivers/%s/bind" % driver
475 f = open(filename, "a")
477 print("Error: bind failed for %s - Cannot open %s"
478 % (dev_id, filename))
479 if saved_driver is not None: # restore any previous driver
480 bind_one(dev_id, saved_driver, force)
486 # for some reason, closing dev_id after adding a new PCI ID to new_id
487 # results in IOError. however, if the device was successfully bound,
488 # we don't care for any errors and can safely ignore IOError
489 tmp = get_pci_device_details(dev_id, True)
490 if "Driver_str" in tmp and tmp["Driver_str"] == driver:
492 print("Error: bind failed for %s - Cannot bind to driver %s"
494 if saved_driver is not None: # restore any previous driver
495 bind_one(dev_id, saved_driver, force)
498 # For kernels > 3.15 driver_override is used to bind a device to a driver.
499 # Before unbinding it, overwrite driver_override with empty string so that
500 # the device can be bound to any other driver
501 filename = "/sys/bus/pci/devices/%s/driver_override" % dev_id
502 if os.path.exists(filename):
504 f = open(filename, "w")
506 print("Error: unbind failed for %s - Cannot open %s"
507 % (dev_id, filename))
513 print("Error: unbind failed for %s - Cannot open %s"
514 % (dev_id, filename))
518 def unbind_all(dev_list, force=False):
519 """Unbind method, takes a list of device locations"""
520 dev_list = map(dev_id_from_dev_name, dev_list)
525 def bind_all(dev_list, driver, force=False):
526 """Bind method, takes a list of device locations"""
529 dev_list = map(dev_id_from_dev_name, dev_list)
532 bind_one(d, driver, force)
534 # For kenels < 3.15 when binding devices to a generic driver
535 # (i.e. one that doesn't have a PCI ID table) using new_id, some devices
536 # that are not bound to any other driver could be bound even if no one has
537 # asked them to. hence, we check the list of drivers again, and see if
538 # some of the previously-unbound devices were erroneously bound.
539 if not os.path.exists("/sys/bus/pci/devices/%s/driver_override" % d):
540 for d in devices.keys():
541 # skip devices that were already bound or that we know should be bound
542 if "Driver_str" in devices[d] or d in dev_list:
545 # update information about this device
546 devices[d] = dict(devices[d].items() +
547 get_pci_device_details(d, True).items())
549 # check if updated information indicates that the device was bound
550 if "Driver_str" in devices[d]:
554 def display_devices(title, dev_list, extra_params=None):
555 '''Displays to the user the details of a list of devices given in
556 "dev_list". The "extra_params" parameter, if given, should contain a string
557 with %()s fields in it for replacement by the named fields in each
558 device's dictionary.'''
559 strings = [] # this holds the strings to print. We sort before printing
560 print("\n%s" % title)
561 print("="*len(title))
562 if len(dev_list) == 0:
563 strings.append("<none>")
566 if extra_params is not None:
567 strings.append("%s '%s %s' %s" % (dev["Slot"],
572 strings.append("%s '%s'" % (dev["Slot"], dev["Device_str"]))
573 # sort before printing, so that the entries appear in PCI order
575 print("\n".join(strings)) # print one per line
577 def show_device_status(devices_type, device_name):
583 # split our list of network devices into the three categories above
584 for d in devices.keys():
585 if device_type_match(devices[d], devices_type):
586 if not has_driver(d):
587 no_drv.append(devices[d])
589 if devices[d]["Driver_str"] in dpdk_drivers:
590 dpdk_drv.append(devices[d])
592 kernel_drv.append(devices[d])
594 # print each category separately, so we can clearly see what's used by DPDK
595 display_devices("%s devices using DPDK-compatible driver" % device_name,
596 dpdk_drv, "drv=%(Driver_str)s unused=%(Module_str)s")
597 display_devices("%s devices using kernel driver" % device_name, kernel_drv,
598 "if=%(Interface)s drv=%(Driver_str)s "
599 "unused=%(Module_str)s %(Active)s")
600 display_devices("Other %s devices" % device_name, no_drv,
601 "unused=%(Module_str)s")
604 '''Function called when the script is passed the "--status" option.
605 Displays to the user what devices are bound to the igb_uio driver, the
606 kernel driver or to no driver'''
608 if status_dev == "net" or status_dev == "all":
609 show_device_status(network_devices, "Network")
611 if status_dev == "crypto" or status_dev == "all":
612 show_device_status(crypto_devices, "Crypto")
614 if status_dev == "event" or status_dev == "all":
615 show_device_status(eventdev_devices, "Eventdev")
617 if status_dev == "mempool" or status_dev == "all":
618 show_device_status(mempool_devices, "Mempool")
621 '''Parses the command-line arguments given by the user and takes the
622 appropriate action for each'''
628 if len(sys.argv) <= 1:
633 opts, args = getopt.getopt(sys.argv[1:], "b:us",
634 ["help", "usage", "status", "status-dev=",
635 "force", "bind=", "unbind", ])
636 except getopt.GetoptError as error:
638 print("Run '%s --usage' for further information" % sys.argv[0])
641 for opt, arg in opts:
642 if opt == "--help" or opt == "--usage":
645 if opt == "--status-dev":
648 if opt == "--status" or opt == "-s":
653 if opt == "-b" or opt == "-u" or opt == "--bind" or opt == "--unbind":
654 if b_flag is not None:
655 print("Error - Only one bind or unbind may be specified\n")
657 if opt == "-u" or opt == "--unbind":
663 def do_arg_actions():
664 '''do the actual action requested by the user'''
670 if b_flag is None and not status_flag:
671 print("Error: No action specified for devices."
672 "Please give a -b or -u option")
673 print("Run '%s --usage' for further information" % sys.argv[0])
676 if b_flag is not None and len(args) == 0:
677 print("Error: No devices specified.")
678 print("Run '%s --usage' for further information" % sys.argv[0])
681 if b_flag == "none" or b_flag == "None":
682 unbind_all(args, force_flag)
683 elif b_flag is not None:
684 bind_all(args, b_flag, force_flag)
686 if b_flag is not None:
688 # refresh if we have changed anything
689 get_device_details(network_devices)
690 get_device_details(crypto_devices)
691 get_device_details(eventdev_devices)
692 get_device_details(mempool_devices)
697 '''program main function'''
701 get_device_details(network_devices)
702 get_device_details(crypto_devices)
703 get_device_details(eventdev_devices)
704 get_device_details(mempool_devices)
707 if __name__ == "__main__":