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 NETWORK devices
42 NETWORK_BASE_CLASS = "02"
43 CRYPTO_BASE_CLASS = "0b"
45 # global dict ethernet devices present. Dictionary indexed by PCI address.
46 # Each device within this is itself a dictionary of device properties
48 # list of supported DPDK drivers
49 dpdk_drivers = ["igb_uio", "vfio-pci", "uio_pci_generic"]
51 # command-line arg flags
59 '''Print usage information for the program'''
60 argv0 = basename(sys.argv[0])
65 %(argv0)s [options] DEVICE1 DEVICE2 ....
67 where DEVICE1, DEVICE2 etc, are specified via PCI "domain:bus:slot.func" syntax
68 or "bus:slot.func" syntax. For devices bound to Linux kernel drivers, they may
69 also be referred to by Linux interface name e.g. eth0, eth1, em0, em1, etc.
73 Display usage information and quit
76 Print the current status of all known network and crypto devices.
77 For each device, it displays the PCI domain, bus, slot and function,
78 along with a text description of the device. Depending upon whether the
79 device is being used by a kernel driver, the igb_uio driver, or no
80 driver, other relevant information will be displayed:
81 * the Linux interface name e.g. if=eth0
82 * the driver being used e.g. drv=igb_uio
83 * any suitable drivers not currently using that device
85 NOTE: if this flag is passed along with a bind/unbind option, the
86 status display will always occur after the other operations have taken
89 -b driver, --bind=driver:
90 Select the driver to use or \"none\" to unbind the device
93 Unbind a device (Equivalent to \"-b none\")
96 By default, network devices which are used by Linux - as indicated by having
97 routes in the routing table - cannot be modified. Using the --force
98 flag overrides this behavior, allowing active links to be forcibly
100 WARNING: This can lead to loss of network connection and should be used
106 To display current device status:
109 To bind eth1 from the current driver and move to use igb_uio
110 %(argv0)s --bind=igb_uio eth1
112 To unbind 0000:01:00.0 from using any driver
113 %(argv0)s -u 0000:01:00.0
115 To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver
116 %(argv0)s -b ixgbe 02:00.0 02:00.1
118 """ % locals()) # replace items from local variables
121 # This is roughly compatible with check_output function in subprocess module
122 # which is only available in python 2.7.
123 def check_output(args, stderr=None):
124 '''Run a command and capture its output'''
125 return subprocess.Popen(args, stdout=subprocess.PIPE,
126 stderr=stderr).communicate()[0]
130 '''Checks that igb_uio is loaded'''
133 # list of supported modules
134 mods = [{"Name": driver, "Found": False} for driver in dpdk_drivers]
136 # first check if module is loaded
138 # Get list of sysfs modules (both built-in and dynamically loaded)
139 sysfs_path = '/sys/module/'
141 # Get the list of directories in sysfs_path
142 sysfs_mods = [os.path.join(sysfs_path, o) for o
143 in os.listdir(sysfs_path)
144 if os.path.isdir(os.path.join(sysfs_path, o))]
146 # Extract the last element of '/sys/module/abc' in the array
147 sysfs_mods = [a.split('/')[-1] for a in sysfs_mods]
149 # special case for vfio_pci (module is named vfio-pci,
150 # but its .ko is named vfio_pci)
151 sysfs_mods = [a if a != 'vfio_pci' else 'vfio-pci' for a in sysfs_mods]
154 if mod["Name"] in sysfs_mods:
159 # check if we have at least one loaded module
160 if True not in [mod["Found"] for mod in mods] and b_flag is not None:
161 if b_flag in dpdk_drivers:
162 print("Error - no supported modules(DPDK driver) are loaded")
165 print("Warning - no supported modules(DPDK driver) are loaded")
167 # change DPDK driver list to only contain drivers that are loaded
168 dpdk_drivers = [mod["Name"] for mod in mods if mod["Found"]]
171 def has_driver(dev_id):
172 '''return true if a device is assigned to a driver. False otherwise'''
173 return "Driver_str" in devices[dev_id]
176 def get_pci_device_details(dev_id):
177 '''This function gets additional details for a PCI device'''
180 extra_info = check_output(["lspci", "-vmmks", dev_id]).splitlines()
182 # parse lspci details
183 for line in extra_info:
186 name, value = line.decode().split("\t", 1)
187 name = name.strip(":") + "_str"
189 # check for a unix interface name
190 device["Interface"] = ""
191 for base, dirs, _ in os.walk("/sys/bus/pci/devices/%s/" % dev_id):
193 device["Interface"] = \
194 ",".join(os.listdir(os.path.join(base, "net")))
196 # check if a port is used for ssh connection
197 device["Ssh_if"] = False
198 device["Active"] = ""
203 def get_nic_details():
204 '''This function populates the "devices" dictionary. The keys used are
205 the pci addresses (domain:bus:slot.func). The values are themselves
206 dictionaries - one for each NIC.'''
212 # first loop through and read details for all devices
213 # request machine readable format, with numeric IDs
215 dev_lines = check_output(["lspci", "-Dvmmn"]).splitlines()
216 for dev_line in dev_lines:
217 if (len(dev_line) == 0):
218 if dev["Class"][0:2] == NETWORK_BASE_CLASS:
219 # convert device and vendor ids to numbers, then add to global
220 dev["Vendor"] = int(dev["Vendor"], 16)
221 dev["Device"] = int(dev["Device"], 16)
222 # use dict to make copy of dev
223 devices[dev["Slot"]] = dict(dev)
225 name, value = dev_line.decode().split("\t", 1)
226 dev[name.rstrip(":")] = value
228 # check what is the interface if any for an ssh connection if
229 # any to this host, so we can mark it later.
231 route = check_output(["ip", "-o", "route"])
232 # filter out all lines for 169.254 routes
233 route = "\n".join(filter(lambda ln: not ln.startswith("169.254"),
234 route.decode().splitlines()))
235 rt_info = route.split()
236 for i in range(len(rt_info) - 1):
237 if rt_info[i] == "dev":
238 ssh_if.append(rt_info[i+1])
240 # based on the basic info, get extended text details
241 for d in devices.keys():
242 # get additional info and add it to existing data
243 devices[d] = devices[d].copy()
244 devices[d].update(get_pci_device_details(d).items())
247 if _if in devices[d]["Interface"].split(","):
248 devices[d]["Ssh_if"] = True
249 devices[d]["Active"] = "*Active*"
252 # add igb_uio to list of supporting modules if needed
253 if "Module_str" in devices[d]:
254 for driver in dpdk_drivers:
255 if driver not in devices[d]["Module_str"]:
256 devices[d]["Module_str"] = \
257 devices[d]["Module_str"] + ",%s" % driver
259 devices[d]["Module_str"] = ",".join(dpdk_drivers)
261 # make sure the driver and module strings do not have any duplicates
263 modules = devices[d]["Module_str"].split(",")
264 if devices[d]["Driver_str"] in modules:
265 modules.remove(devices[d]["Driver_str"])
266 devices[d]["Module_str"] = ",".join(modules)
269 def get_crypto_details():
270 '''This function populates the "devices" dictionary. The keys used are
271 the pci addresses (domain:bus:slot.func). The values are themselves
272 dictionaries - one for each NIC.'''
278 # first loop through and read details for all devices
279 # request machine readable format, with numeric IDs
281 dev_lines = check_output(["lspci", "-Dvmmn"]).splitlines()
282 for dev_line in dev_lines:
283 if (len(dev_line) == 0):
284 if (dev["Class"][0:2] == CRYPTO_BASE_CLASS):
285 # convert device and vendor ids to numbers, then add to global
286 dev["Vendor"] = int(dev["Vendor"], 16)
287 dev["Device"] = int(dev["Device"], 16)
288 # use dict to make copy of dev
289 devices[dev["Slot"]] = dict(dev)
291 name, value = dev_line.decode().split("\t", 1)
292 dev[name.rstrip(":")] = value
294 # based on the basic info, get extended text details
295 for d in devices.keys():
296 if devices[d]["Class"][0:2] != CRYPTO_BASE_CLASS:
299 # get additional info and add it to existing data
300 devices[d] = devices[d].copy()
301 devices[d].update(get_pci_device_details(d).items())
303 # add igb_uio to list of supporting modules if needed
304 if "Module_str" in devices[d]:
305 for driver in dpdk_drivers:
306 if driver not in devices[d]["Module_str"]:
307 devices[d]["Module_str"] = \
308 devices[d]["Module_str"] + ",%s" % driver
310 devices[d]["Module_str"] = ",".join(dpdk_drivers)
312 # make sure the driver and module strings do not have any duplicates
314 modules = devices[d]["Module_str"].split(",")
315 if devices[d]["Driver_str"] in modules:
316 modules.remove(devices[d]["Driver_str"])
317 devices[d]["Module_str"] = ",".join(modules)
320 def dev_id_from_dev_name(dev_name):
321 '''Take a device "name" - a string passed in by user to identify a NIC
322 device, and determine the device id - i.e. the domain:bus:slot.func - for
323 it, which can then be used to index into the devices array'''
325 # check if it's already a suitable index
326 if dev_name in devices:
328 # check if it's an index just missing the domain part
329 elif "0000:" + dev_name in devices:
330 return "0000:" + dev_name
332 # check if it's an interface name, e.g. eth1
333 for d in devices.keys():
334 if dev_name in devices[d]["Interface"].split(","):
335 return devices[d]["Slot"]
336 # if nothing else matches - error
337 print("Unknown device: %s. "
338 "Please specify device in \"bus:slot.func\" format" % dev_name)
342 def unbind_one(dev_id, force):
343 '''Unbind the device identified by "dev_id" from its current driver'''
344 dev = devices[dev_id]
345 if not has_driver(dev_id):
346 print("%s %s %s is not currently managed by any driver\n" %
347 (dev["Slot"], dev["Device_str"], dev["Interface"]))
350 # prevent us disconnecting ourselves
351 if dev["Ssh_if"] and not force:
352 print("Routing table indicates that interface %s is active. "
353 "Skipping unbind" % (dev_id))
356 # write to /sys to unbind
357 filename = "/sys/bus/pci/drivers/%s/unbind" % dev["Driver_str"]
359 f = open(filename, "a")
361 print("Error: unbind failed for %s - Cannot open %s"
362 % (dev_id, filename))
368 def bind_one(dev_id, driver, force):
369 '''Bind the device given by "dev_id" to the driver "driver". If the device
370 is already bound to a different driver, it will be unbound first'''
371 dev = devices[dev_id]
372 saved_driver = None # used to rollback any unbind in case of failure
374 # prevent disconnection of our ssh session
375 if dev["Ssh_if"] and not force:
376 print("Routing table indicates that interface %s is active. "
377 "Not modifying" % (dev_id))
380 # unbind any existing drivers we don't want
381 if has_driver(dev_id):
382 if dev["Driver_str"] == driver:
383 print("%s already bound to driver %s, skipping\n"
387 saved_driver = dev["Driver_str"]
388 unbind_one(dev_id, force)
389 dev["Driver_str"] = "" # clear driver string
391 # if we are binding to one of DPDK drivers, add PCI id's to that driver
392 if driver in dpdk_drivers:
393 filename = "/sys/bus/pci/drivers/%s/new_id" % driver
395 f = open(filename, "w")
397 print("Error: bind failed for %s - Cannot open %s"
398 % (dev_id, filename))
401 f.write("%04x %04x" % (dev["Vendor"], dev["Device"]))
404 print("Error: bind failed for %s - Cannot write new PCI ID to "
405 "driver %s" % (dev_id, driver))
408 # do the bind by writing to /sys
409 filename = "/sys/bus/pci/drivers/%s/bind" % driver
411 f = open(filename, "a")
413 print("Error: bind failed for %s - Cannot open %s"
414 % (dev_id, filename))
415 if saved_driver is not None: # restore any previous driver
416 bind_one(dev_id, saved_driver, force)
422 # for some reason, closing dev_id after adding a new PCI ID to new_id
423 # results in IOError. however, if the device was successfully bound,
424 # we don't care for any errors and can safely ignore IOError
425 tmp = get_pci_device_details(dev_id)
426 if "Driver_str" in tmp and tmp["Driver_str"] == driver:
428 print("Error: bind failed for %s - Cannot bind to driver %s"
430 if saved_driver is not None: # restore any previous driver
431 bind_one(dev_id, saved_driver, force)
435 def unbind_all(dev_list, force=False):
436 """Unbind method, takes a list of device locations"""
437 dev_list = map(dev_id_from_dev_name, dev_list)
442 def bind_all(dev_list, driver, force=False):
443 """Bind method, takes a list of device locations"""
446 dev_list = map(dev_id_from_dev_name, dev_list)
449 bind_one(d, driver, force)
451 # when binding devices to a generic driver (i.e. one that doesn't have a
452 # PCI ID table), some devices that are not bound to any other driver could
453 # be bound even if no one has asked them to. hence, we check the list of
454 # drivers again, and see if some of the previously-unbound devices were
456 for d in devices.keys():
457 # skip devices that were already bound or that we know should be bound
458 if "Driver_str" in devices[d] or d in dev_list:
461 # update information about this device
462 devices[d] = dict(devices[d].items() +
463 get_pci_device_details(d).items())
465 # check if updated information indicates that the device was bound
466 if "Driver_str" in devices[d]:
470 def display_devices(title, dev_list, extra_params=None):
471 '''Displays to the user the details of a list of devices given in
472 "dev_list". The "extra_params" parameter, if given, should contain a string
473 with %()s fields in it for replacement by the named fields in each
474 device's dictionary.'''
475 strings = [] # this holds the strings to print. We sort before printing
476 print("\n%s" % title)
477 print("="*len(title))
478 if len(dev_list) == 0:
479 strings.append("<none>")
482 if extra_params is not None:
483 strings.append("%s '%s' %s" % (dev["Slot"],
484 dev["Device_str"], extra_params % dev))
486 strings.append("%s '%s'" % (dev["Slot"], dev["Device_str"]))
487 # sort before printing, so that the entries appear in PCI order
489 print("\n".join(strings)) # print one per line
493 '''Function called when the script is passed the "--status" option.
494 Displays to the user what devices are bound to the igb_uio driver, the
495 kernel driver or to no driver'''
501 # split our list of network devices into the three categories above
502 for d in devices.keys():
503 if (NETWORK_BASE_CLASS in devices[d]["Class"]):
504 if not has_driver(d):
505 no_drv.append(devices[d])
507 if devices[d]["Driver_str"] in dpdk_drivers:
508 dpdk_drv.append(devices[d])
510 kernel_drv.append(devices[d])
512 # print each category separately, so we can clearly see what's used by DPDK
513 display_devices("Network devices using DPDK-compatible driver", dpdk_drv,
514 "drv=%(Driver_str)s unused=%(Module_str)s")
515 display_devices("Network devices using kernel driver", kernel_drv,
516 "if=%(Interface)s drv=%(Driver_str)s "
517 "unused=%(Module_str)s %(Active)s")
518 display_devices("Other network devices", no_drv, "unused=%(Module_str)s")
520 # split our list of crypto devices into the three categories above
525 for d in devices.keys():
526 if (CRYPTO_BASE_CLASS in devices[d]["Class"]):
527 if not has_driver(d):
528 no_drv.append(devices[d])
530 if devices[d]["Driver_str"] in dpdk_drivers:
531 dpdk_drv.append(devices[d])
533 kernel_drv.append(devices[d])
535 display_devices("Crypto devices using DPDK-compatible driver", dpdk_drv,
536 "drv=%(Driver_str)s unused=%(Module_str)s")
537 display_devices("Crypto devices using kernel driver", kernel_drv,
538 "drv=%(Driver_str)s "
539 "unused=%(Module_str)s")
540 display_devices("Other crypto devices", no_drv, "unused=%(Module_str)s")
544 '''Parses the command-line arguments given by the user and takes the
545 appropriate action for each'''
550 if len(sys.argv) <= 1:
555 opts, args = getopt.getopt(sys.argv[1:], "b:us",
556 ["help", "usage", "status", "force",
558 except getopt.GetoptError as error:
560 print("Run '%s --usage' for further information" % sys.argv[0])
563 for opt, arg in opts:
564 if opt == "--help" or opt == "--usage":
567 if opt == "--status" or opt == "-s":
571 if opt == "-b" or opt == "-u" or opt == "--bind" or opt == "--unbind":
572 if b_flag is not None:
573 print("Error - Only one bind or unbind may be specified\n")
575 if opt == "-u" or opt == "--unbind":
581 def do_arg_actions():
582 '''do the actual action requested by the user'''
588 if b_flag is None and not status_flag:
589 print("Error: No action specified for devices."
590 "Please give a -b or -u option")
591 print("Run '%s --usage' for further information" % sys.argv[0])
594 if b_flag is not None and len(args) == 0:
595 print("Error: No devices specified.")
596 print("Run '%s --usage' for further information" % sys.argv[0])
599 if b_flag == "none" or b_flag == "None":
600 unbind_all(args, force_flag)
601 elif b_flag is not None:
602 bind_all(args, b_flag, force_flag)
604 if b_flag is not None:
605 get_nic_details() # refresh if we have changed anything
606 get_crypto_details() # refresh if we have changed anything
611 '''program main function'''
618 if __name__ == "__main__":