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"
44 # global dict ethernet devices present. Dictionary indexed by PCI address.
45 # Each device within this is itself a dictionary of device properties
47 # list of supported DPDK drivers
48 dpdk_drivers = ["igb_uio", "vfio-pci", "uio_pci_generic"]
50 # command-line arg flags
58 '''Print usage information for the program'''
59 argv0 = basename(sys.argv[0])
64 %(argv0)s [options] DEVICE1 DEVICE2 ....
66 where DEVICE1, DEVICE2 etc, are specified via PCI "domain:bus:slot.func" syntax
67 or "bus:slot.func" syntax. For devices bound to Linux kernel drivers, they may
68 also be referred to by Linux interface name e.g. eth0, eth1, em0, em1, etc.
72 Display usage information and quit
75 Print the current status of all known network interfaces.
76 For each device, it displays the PCI domain, bus, slot and function,
77 along with a text description of the device. Depending upon whether the
78 device is being used by a kernel driver, the igb_uio driver, or no
79 driver, other relevant information will be displayed:
80 * the Linux interface name e.g. if=eth0
81 * the driver being used e.g. drv=igb_uio
82 * any suitable drivers not currently using that device
84 NOTE: if this flag is passed along with a bind/unbind option, the
85 status display will always occur after the other operations have taken
88 -b driver, --bind=driver:
89 Select the driver to use or \"none\" to unbind the device
92 Unbind a device (Equivalent to \"-b none\")
95 By default, devices which are used by Linux - as indicated by having
96 routes in the routing table - cannot be modified. Using the --force
97 flag overrides this behavior, allowing active links to be forcibly
99 WARNING: This can lead to loss of network connection and should be used
105 To display current device status:
108 To bind eth1 from the current driver and move to use igb_uio
109 %(argv0)s --bind=igb_uio eth1
111 To unbind 0000:01:00.0 from using any driver
112 %(argv0)s -u 0000:01:00.0
114 To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver
115 %(argv0)s -b ixgbe 02:00.0 02:00.1
117 """ % locals()) # replace items from local variables
120 # This is roughly compatible with check_output function in subprocess module
121 # which is only available in python 2.7.
122 def check_output(args, stderr=None):
123 '''Run a command and capture its output'''
124 return subprocess.Popen(args, stdout=subprocess.PIPE,
125 stderr=stderr).communicate()[0]
128 def find_module(mod):
129 '''find the .ko file for kernel module named mod.
130 Searches the $RTE_SDK/$RTE_TARGET directory, the kernel
131 modules directory and finally under the parent directory of
133 # check $RTE_SDK/$RTE_TARGET directory
134 if 'RTE_SDK' in os.environ and 'RTE_TARGET' in os.environ:
135 path = "%s/%s/kmod/%s.ko" % (os.environ['RTE_SDK'],
136 os.environ['RTE_TARGET'], mod)
142 depmod_out = check_output(["modinfo", "-n", mod],
143 stderr=subprocess.STDOUT).lower()
144 if "error" not in depmod_out:
145 path = depmod_out.strip()
148 except: # if modinfo can't find module, it fails, so continue
151 # check for a copy based off current path
152 tools_dir = dirname(abspath(sys.argv[0]))
153 if (tools_dir.endswith("tools")):
154 base_dir = dirname(tools_dir)
155 find_out = check_output(["find", base_dir, "-name", mod + ".ko"])
156 if len(find_out) > 0: # something matched
157 path = find_out.splitlines()[0]
163 '''Checks that igb_uio is loaded'''
166 # list of supported modules
167 mods = [{"Name": driver, "Found": False} for driver in dpdk_drivers]
169 # first check if module is loaded
171 # Get list of sysfs modules (both built-in and dynamically loaded)
172 sysfs_path = '/sys/module/'
174 # Get the list of directories in sysfs_path
175 sysfs_mods = [os.path.join(sysfs_path, o) for o
176 in os.listdir(sysfs_path)
177 if os.path.isdir(os.path.join(sysfs_path, o))]
179 # Extract the last element of '/sys/module/abc' in the array
180 sysfs_mods = [a.split('/')[-1] for a in sysfs_mods]
182 # special case for vfio_pci (module is named vfio-pci,
183 # but its .ko is named vfio_pci)
184 sysfs_mods = map(lambda a:
185 a if a != 'vfio_pci' else 'vfio-pci', sysfs_mods)
188 if mod["Name"] in sysfs_mods:
193 # check if we have at least one loaded module
194 if True not in [mod["Found"] for mod in mods] and b_flag is not None:
195 if b_flag in dpdk_drivers:
196 print("Error - no supported modules(DPDK driver) are loaded")
199 print("Warning - no supported modules(DPDK driver) are loaded")
201 # change DPDK driver list to only contain drivers that are loaded
202 dpdk_drivers = [mod["Name"] for mod in mods if mod["Found"]]
205 def has_driver(dev_id):
206 '''return true if a device is assigned to a driver. False otherwise'''
207 return "Driver_str" in devices[dev_id]
210 def get_pci_device_details(dev_id):
211 '''This function gets additional details for a PCI device'''
214 extra_info = check_output(["lspci", "-vmmks", dev_id]).splitlines()
216 # parse lspci details
217 for line in extra_info:
220 name, value = line.decode().split("\t", 1)
221 name = name.strip(":") + "_str"
223 # check for a unix interface name
224 device["Interface"] = ""
225 for base, dirs, _ in os.walk("/sys/bus/pci/devices/%s/" % dev_id):
227 device["Interface"] = \
228 ",".join(os.listdir(os.path.join(base, "net")))
230 # check if a port is used for ssh connection
231 device["Ssh_if"] = False
232 device["Active"] = ""
237 def get_nic_details():
238 '''This function populates the "devices" dictionary. The keys used are
239 the pci addresses (domain:bus:slot.func). The values are themselves
240 dictionaries - one for each NIC.'''
246 # first loop through and read details for all devices
247 # request machine readable format, with numeric IDs
249 dev_lines = check_output(["lspci", "-Dvmmn"]).splitlines()
250 for dev_line in dev_lines:
251 if (len(dev_line) == 0):
252 if dev["Class"][0:2] == NETWORK_BASE_CLASS:
253 # convert device and vendor ids to numbers, then add to global
254 dev["Vendor"] = int(dev["Vendor"], 16)
255 dev["Device"] = int(dev["Device"], 16)
256 # use dict to make copy of dev
257 devices[dev["Slot"]] = dict(dev)
259 name, value = dev_line.decode().split("\t", 1)
260 dev[name.rstrip(":")] = value
262 # check what is the interface if any for an ssh connection if
263 # any to this host, so we can mark it later.
265 route = check_output(["ip", "-o", "route"])
266 # filter out all lines for 169.254 routes
267 route = "\n".join(filter(lambda ln: not ln.startswith("169.254"),
268 route.decode().splitlines()))
269 rt_info = route.split()
270 for i in range(len(rt_info) - 1):
271 if rt_info[i] == "dev":
272 ssh_if.append(rt_info[i+1])
274 # based on the basic info, get extended text details
275 for d in devices.keys():
276 # get additional info and add it to existing data
277 devices[d] = devices[d].copy()
278 devices[d].update(get_pci_device_details(d).items())
281 if _if in devices[d]["Interface"].split(","):
282 devices[d]["Ssh_if"] = True
283 devices[d]["Active"] = "*Active*"
286 # add igb_uio to list of supporting modules if needed
287 if "Module_str" in devices[d]:
288 for driver in dpdk_drivers:
289 if driver not in devices[d]["Module_str"]:
290 devices[d]["Module_str"] = \
291 devices[d]["Module_str"] + ",%s" % driver
293 devices[d]["Module_str"] = ",".join(dpdk_drivers)
295 # make sure the driver and module strings do not have any duplicates
297 modules = devices[d]["Module_str"].split(",")
298 if devices[d]["Driver_str"] in modules:
299 modules.remove(devices[d]["Driver_str"])
300 devices[d]["Module_str"] = ",".join(modules)
303 def dev_id_from_dev_name(dev_name):
304 '''Take a device "name" - a string passed in by user to identify a NIC
305 device, and determine the device id - i.e. the domain:bus:slot.func - for
306 it, which can then be used to index into the devices array'''
308 # check if it's already a suitable index
309 if dev_name in devices:
311 # check if it's an index just missing the domain part
312 elif "0000:" + dev_name in devices:
313 return "0000:" + dev_name
315 # check if it's an interface name, e.g. eth1
316 for d in devices.keys():
317 if dev_name in devices[d]["Interface"].split(","):
318 return devices[d]["Slot"]
319 # if nothing else matches - error
320 print("Unknown device: %s. "
321 "Please specify device in \"bus:slot.func\" format" % dev_name)
325 def unbind_one(dev_id, force):
326 '''Unbind the device identified by "dev_id" from its current driver'''
327 dev = devices[dev_id]
328 if not has_driver(dev_id):
329 print("%s %s %s is not currently managed by any driver\n" %
330 (dev["Slot"], dev["Device_str"], dev["Interface"]))
333 # prevent us disconnecting ourselves
334 if dev["Ssh_if"] and not force:
335 print("Routing table indicates that interface %s is active. "
336 "Skipping unbind" % (dev_id))
339 # write to /sys to unbind
340 filename = "/sys/bus/pci/drivers/%s/unbind" % dev["Driver_str"]
342 f = open(filename, "a")
344 print("Error: unbind failed for %s - Cannot open %s"
345 % (dev_id, filename))
351 def bind_one(dev_id, driver, force):
352 '''Bind the device given by "dev_id" to the driver "driver". If the device
353 is already bound to a different driver, it will be unbound first'''
354 dev = devices[dev_id]
355 saved_driver = None # used to rollback any unbind in case of failure
357 # prevent disconnection of our ssh session
358 if dev["Ssh_if"] and not force:
359 print("Routing table indicates that interface %s is active. "
360 "Not modifying" % (dev_id))
363 # unbind any existing drivers we don't want
364 if has_driver(dev_id):
365 if dev["Driver_str"] == driver:
366 print("%s already bound to driver %s, skipping\n"
370 saved_driver = dev["Driver_str"]
371 unbind_one(dev_id, force)
372 dev["Driver_str"] = "" # clear driver string
374 # if we are binding to one of DPDK drivers, add PCI id's to that driver
375 if driver in dpdk_drivers:
376 filename = "/sys/bus/pci/drivers/%s/new_id" % driver
378 f = open(filename, "w")
380 print("Error: bind failed for %s - Cannot open %s"
381 % (dev_id, filename))
384 f.write("%04x %04x" % (dev["Vendor"], dev["Device"]))
387 print("Error: bind failed for %s - Cannot write new PCI ID to "
388 "driver %s" % (dev_id, driver))
391 # do the bind by writing to /sys
392 filename = "/sys/bus/pci/drivers/%s/bind" % driver
394 f = open(filename, "a")
396 print("Error: bind failed for %s - Cannot open %s"
397 % (dev_id, filename))
398 if saved_driver is not None: # restore any previous driver
399 bind_one(dev_id, saved_driver, force)
405 # for some reason, closing dev_id after adding a new PCI ID to new_id
406 # results in IOError. however, if the device was successfully bound,
407 # we don't care for any errors and can safely ignore IOError
408 tmp = get_pci_device_details(dev_id)
409 if "Driver_str" in tmp and tmp["Driver_str"] == driver:
411 print("Error: bind failed for %s - Cannot bind to driver %s"
413 if saved_driver is not None: # restore any previous driver
414 bind_one(dev_id, saved_driver, force)
418 def unbind_all(dev_list, force=False):
419 """Unbind method, takes a list of device locations"""
420 dev_list = map(dev_id_from_dev_name, dev_list)
425 def bind_all(dev_list, driver, force=False):
426 """Bind method, takes a list of device locations"""
429 dev_list = map(dev_id_from_dev_name, dev_list)
432 bind_one(d, driver, force)
434 # when binding devices to a generic driver (i.e. one that doesn't have a
435 # PCI ID table), some devices that are not bound to any other driver could
436 # be bound even if no one has asked them to. hence, we check the list of
437 # drivers again, and see if some of the previously-unbound devices were
439 for d in devices.keys():
440 # skip devices that were already bound or that we know should be bound
441 if "Driver_str" in devices[d] or d in dev_list:
444 # update information about this device
445 devices[d] = dict(devices[d].items() +
446 get_pci_device_details(d).items())
448 # check if updated information indicates that the device was bound
449 if "Driver_str" in devices[d]:
453 def display_devices(title, dev_list, extra_params=None):
454 '''Displays to the user the details of a list of devices given in
455 "dev_list". The "extra_params" parameter, if given, should contain a string
456 with %()s fields in it for replacement by the named fields in each
457 device's dictionary.'''
458 strings = [] # this holds the strings to print. We sort before printing
459 print("\n%s" % title)
460 print("="*len(title))
461 if len(dev_list) == 0:
462 strings.append("<none>")
465 if extra_params is not None:
466 strings.append("%s '%s' %s" % (dev["Slot"],
467 dev["Device_str"], extra_params % dev))
469 strings.append("%s '%s'" % (dev["Slot"], dev["Device_str"]))
470 # sort before printing, so that the entries appear in PCI order
472 print("\n".join(strings)) # print one per line
476 '''Function called when the script is passed the "--status" option.
477 Displays to the user what devices are bound to the igb_uio driver, the
478 kernel driver or to no driver'''
484 # split our list of devices into the three categories above
485 for d in devices.keys():
486 if not has_driver(d):
487 no_drv.append(devices[d])
489 if devices[d]["Driver_str"] in dpdk_drivers:
490 dpdk_drv.append(devices[d])
492 kernel_drv.append(devices[d])
494 # print each category separately, so we can clearly see what's used by DPDK
495 display_devices("Network devices using DPDK-compatible driver", dpdk_drv,
496 "drv=%(Driver_str)s unused=%(Module_str)s")
497 display_devices("Network devices using kernel driver", kernel_drv,
498 "if=%(Interface)s drv=%(Driver_str)s "
499 "unused=%(Module_str)s %(Active)s")
500 display_devices("Other network devices", no_drv, "unused=%(Module_str)s")
504 '''Parses the command-line arguments given by the user and takes the
505 appropriate action for each'''
510 if len(sys.argv) <= 1:
515 opts, args = getopt.getopt(sys.argv[1:], "b:us",
516 ["help", "usage", "status", "force",
518 except getopt.GetoptError as error:
520 print("Run '%s --usage' for further information" % sys.argv[0])
523 for opt, arg in opts:
524 if opt == "--help" or opt == "--usage":
527 if opt == "--status" or opt == "-s":
531 if opt == "-b" or opt == "-u" or opt == "--bind" or opt == "--unbind":
532 if b_flag is not None:
533 print("Error - Only one bind or unbind may be specified\n")
535 if opt == "-u" or opt == "--unbind":
541 def do_arg_actions():
542 '''do the actual action requested by the user'''
548 if b_flag is None and not status_flag:
549 print("Error: No action specified for devices."
550 "Please give a -b or -u option")
551 print("Run '%s --usage' for further information" % sys.argv[0])
554 if b_flag is not None and len(args) == 0:
555 print("Error: No devices specified.")
556 print("Run '%s --usage' for further information" % sys.argv[0])
559 if b_flag == "none" or b_flag == "None":
560 unbind_all(args, force_flag)
561 elif b_flag is not None:
562 bind_all(args, b_flag, force_flag)
564 if b_flag is not None:
565 get_nic_details() # refresh if we have changed anything
570 '''program main function'''
576 if __name__ == "__main__":