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.
35 import sys, os, getopt, subprocess
36 from os.path import exists, abspath, dirname, basename
39 # The PCI device class for ETHERNET devices
40 ETHERNET_CLASS = "0200"
42 # global dict ethernet devices present. Dictionary indexed by PCI address.
43 # Each device within this is itself a dictionary of device properties
45 # list of supported DPDK drivers
46 dpdk_drivers = [ "igb_uio", "vfio-pci", "uio_pci_generic" ]
48 # command-line arg flags
55 '''Print usage information for the program'''
56 argv0 = basename(sys.argv[0])
61 %(argv0)s [options] DEVICE1 DEVICE2 ....
63 where DEVICE1, DEVICE2 etc, are specified via PCI "domain:bus:slot.func" syntax
64 or "bus:slot.func" syntax. For devices bound to Linux kernel drivers, they may
65 also be referred to by Linux interface name e.g. eth0, eth1, em0, em1, etc.
69 Display usage information and quit
72 Print the current status of all known network interfaces.
73 For each device, it displays the PCI domain, bus, slot and function,
74 along with a text description of the device. Depending upon whether the
75 device is being used by a kernel driver, the igb_uio driver, or no
76 driver, other relevant information will be displayed:
77 * the Linux interface name e.g. if=eth0
78 * the driver being used e.g. drv=igb_uio
79 * any suitable drivers not currently using that device
81 NOTE: if this flag is passed along with a bind/unbind option, the status
82 display will always occur after the other operations have taken place.
84 -b driver, --bind=driver:
85 Select the driver to use or \"none\" to unbind the device
88 Unbind a device (Equivalent to \"-b none\")
91 By default, devices which are used by Linux - as indicated by having
92 routes in the routing table - cannot be modified. Using the --force
93 flag overrides this behavior, allowing active links to be forcibly
95 WARNING: This can lead to loss of network connection and should be used
101 To display current device status:
104 To bind eth1 from the current driver and move to use igb_uio
105 %(argv0)s --bind=igb_uio eth1
107 To unbind 0000:01:00.0 from using any driver
108 %(argv0)s -u 0000:01:00.0
110 To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver
111 %(argv0)s -b ixgbe 02:00.0 02:00.1
113 """ % locals() # replace items from local variables
115 # This is roughly compatible with check_output function in subprocess module
116 # which is only available in python 2.7.
117 def check_output(args, stderr=None):
118 '''Run a command and capture its output'''
119 return subprocess.Popen(args, stdout=subprocess.PIPE,
120 stderr=stderr).communicate()[0]
122 def find_module(mod):
123 '''find the .ko file for kernel module named mod.
124 Searches the $RTE_SDK/$RTE_TARGET directory, the kernel
125 modules directory and finally under the parent directory of
127 # check $RTE_SDK/$RTE_TARGET directory
128 if 'RTE_SDK' in os.environ and 'RTE_TARGET' in os.environ:
129 path = "%s/%s/kmod/%s.ko" % (os.environ['RTE_SDK'],\
130 os.environ['RTE_TARGET'], mod)
136 depmod_out = check_output(["modinfo", "-n", mod], \
137 stderr=subprocess.STDOUT).lower()
138 if "error" not in depmod_out:
139 path = depmod_out.strip()
142 except: # if modinfo can't find module, it fails, so continue
145 # check for a copy based off current path
146 tools_dir = dirname(abspath(sys.argv[0]))
147 if (tools_dir.endswith("tools")):
148 base_dir = dirname(tools_dir)
149 find_out = check_output(["find", base_dir, "-name", mod + ".ko"])
150 if len(find_out) > 0: #something matched
151 path = find_out.splitlines()[0]
156 '''Checks that igb_uio is loaded'''
159 fd = file("/proc/modules")
160 loaded_mods = fd.readlines()
163 # list of supported modules
164 mods = [{"Name" : driver, "Found" : False} for driver in dpdk_drivers]
166 # first check if module is loaded
167 for line in loaded_mods:
169 if line.startswith(mod["Name"]):
171 # special case for vfio_pci (module is named vfio-pci,
172 # but its .ko is named vfio_pci)
173 elif line.replace("_", "-").startswith(mod["Name"]):
176 # check if we have at least one loaded module
177 if True not in [mod["Found"] for mod in mods] and b_flag is not None:
178 if b_flag in dpdk_drivers:
179 print "Error - no supported modules(DPDK driver) are loaded"
182 print "Warning - no supported modules(DPDK driver) are loaded"
184 # change DPDK driver list to only contain drivers that are loaded
185 dpdk_drivers = [mod["Name"] for mod in mods if mod["Found"]]
187 def has_driver(dev_id):
188 '''return true if a device is assigned to a driver. False otherwise'''
189 return "Driver_str" in devices[dev_id]
191 def get_pci_device_details(dev_id):
192 '''This function gets additional details for a PCI device'''
195 extra_info = check_output(["lspci", "-vmmks", dev_id]).splitlines()
197 # parse lspci details
198 for line in extra_info:
201 name, value = line.split("\t", 1)
202 name = name.strip(":") + "_str"
204 # check for a unix interface name
205 sys_path = "/sys/bus/pci/devices/%s/net/" % dev_id
207 device["Interface"] = ",".join(os.listdir(sys_path))
209 device["Interface"] = ""
210 # check if a port is used for ssh connection
211 device["Ssh_if"] = False
212 device["Active"] = ""
216 def get_nic_details():
217 '''This function populates the "devices" dictionary. The keys used are
218 the pci addresses (domain:bus:slot.func). The values are themselves
219 dictionaries - one for each NIC.'''
225 # first loop through and read details for all devices
226 # request machine readable format, with numeric IDs
228 dev_lines = check_output(["lspci", "-Dvmmn"]).splitlines()
229 for dev_line in dev_lines:
230 if (len(dev_line) == 0):
231 if dev["Class"] == ETHERNET_CLASS:
232 #convert device and vendor ids to numbers, then add to global
233 dev["Vendor"] = int(dev["Vendor"],16)
234 dev["Device"] = int(dev["Device"],16)
235 devices[dev["Slot"]] = dict(dev) # use dict to make copy of dev
237 name, value = dev_line.split("\t", 1)
238 dev[name.rstrip(":")] = value
240 # check what is the interface if any for an ssh connection if
241 # any to this host, so we can mark it later.
243 route = check_output(["ip", "-o", "route"])
244 # filter out all lines for 169.254 routes
245 route = "\n".join(filter(lambda ln: not ln.startswith("169.254"),
247 rt_info = route.split()
248 for i in xrange(len(rt_info) - 1):
249 if rt_info[i] == "dev":
250 ssh_if.append(rt_info[i+1])
252 # based on the basic info, get extended text details
253 for d in devices.keys():
254 # get additional info and add it to existing data
255 devices[d] = dict(devices[d].items() +
256 get_pci_device_details(d).items())
259 if _if in devices[d]["Interface"].split(","):
260 devices[d]["Ssh_if"] = True
261 devices[d]["Active"] = "*Active*"
264 # add igb_uio to list of supporting modules if needed
265 if "Module_str" in devices[d]:
266 for driver in dpdk_drivers:
267 if driver not in devices[d]["Module_str"]:
268 devices[d]["Module_str"] = devices[d]["Module_str"] + ",%s" % driver
270 devices[d]["Module_str"] = ",".join(dpdk_drivers)
272 # make sure the driver and module strings do not have any duplicates
274 modules = devices[d]["Module_str"].split(",")
275 if devices[d]["Driver_str"] in modules:
276 modules.remove(devices[d]["Driver_str"])
277 devices[d]["Module_str"] = ",".join(modules)
279 def dev_id_from_dev_name(dev_name):
280 '''Take a device "name" - a string passed in by user to identify a NIC
281 device, and determine the device id - i.e. the domain:bus:slot.func - for
282 it, which can then be used to index into the devices array'''
284 # check if it's already a suitable index
285 if dev_name in devices:
287 # check if it's an index just missing the domain part
288 elif "0000:" + dev_name in devices:
289 return "0000:" + dev_name
291 # check if it's an interface name, e.g. eth1
292 for d in devices.keys():
293 if dev_name in devices[d]["Interface"].split(","):
294 return devices[d]["Slot"]
295 # if nothing else matches - error
296 print "Unknown device: %s. " \
297 "Please specify device in \"bus:slot.func\" format" % dev_name
300 def unbind_one(dev_id, force):
301 '''Unbind the device identified by "dev_id" from its current driver'''
302 dev = devices[dev_id]
303 if not has_driver(dev_id):
304 print "%s %s %s is not currently managed by any driver\n" % \
305 (dev["Slot"], dev["Device_str"], dev["Interface"])
308 # prevent us disconnecting ourselves
309 if dev["Ssh_if"] and not force:
310 print "Routing table indicates that interface %s is active" \
311 ". Skipping unbind" % (dev_id)
314 # write to /sys to unbind
315 filename = "/sys/bus/pci/drivers/%s/unbind" % dev["Driver_str"]
317 f = open(filename, "a")
319 print "Error: unbind failed for %s - Cannot open %s" % (dev_id, filename)
324 def bind_one(dev_id, driver, force):
325 '''Bind the device given by "dev_id" to the driver "driver". If the device
326 is already bound to a different driver, it will be unbound first'''
327 dev = devices[dev_id]
328 saved_driver = None # used to rollback any unbind in case of failure
330 # prevent disconnection of our ssh session
331 if dev["Ssh_if"] and not force:
332 print "Routing table indicates that interface %s is active" \
333 ". Not modifying" % (dev_id)
336 # unbind any existing drivers we don't want
337 if has_driver(dev_id):
338 if dev["Driver_str"] == driver:
339 print "%s already bound to driver %s, skipping\n" % (dev_id, driver)
342 saved_driver = dev["Driver_str"]
343 unbind_one(dev_id, force)
344 dev["Driver_str"] = "" # clear driver string
346 # if we are binding to one of DPDK drivers, add PCI id's to that driver
347 if driver in dpdk_drivers:
348 filename = "/sys/bus/pci/drivers/%s/new_id" % driver
350 f = open(filename, "w")
352 print "Error: bind failed for %s - Cannot open %s" % (dev_id, filename)
355 f.write("%04x %04x" % (dev["Vendor"], dev["Device"]))
358 print "Error: bind failed for %s - Cannot write new PCI ID to " \
359 "driver %s" % (dev_id, driver)
362 # do the bind by writing to /sys
363 filename = "/sys/bus/pci/drivers/%s/bind" % driver
365 f = open(filename, "a")
367 print "Error: bind failed for %s - Cannot open %s" % (dev_id, filename)
368 if saved_driver is not None: # restore any previous driver
369 bind_one(dev_id, saved_driver, force)
375 # for some reason, closing dev_id after adding a new PCI ID to new_id
376 # results in IOError. however, if the device was successfully bound,
377 # we don't care for any errors and can safely ignore IOError
378 tmp = get_pci_device_details(dev_id)
379 if "Driver_str" in tmp and tmp["Driver_str"] == driver:
381 print "Error: bind failed for %s - Cannot bind to driver %s" % (dev_id, driver)
382 if saved_driver is not None: # restore any previous driver
383 bind_one(dev_id, saved_driver, force)
387 def unbind_all(dev_list, force=False):
388 """Unbind method, takes a list of device locations"""
389 dev_list = map(dev_id_from_dev_name, dev_list)
393 def bind_all(dev_list, driver, force=False):
394 """Unbind method, takes a list of device locations"""
397 dev_list = map(dev_id_from_dev_name, dev_list)
400 bind_one(d, driver, force)
402 # when binding devices to a generic driver (i.e. one that doesn't have a
403 # PCI ID table), some devices that are not bound to any other driver could
404 # be bound even if no one has asked them to. hence, we check the list of
405 # drivers again, and see if some of the previously-unbound devices were
407 for d in devices.keys():
408 # skip devices that were already bound or that we know should be bound
409 if "Driver_str" in devices[d] or d in dev_list:
412 # update information about this device
413 devices[d] = dict(devices[d].items() +
414 get_pci_device_details(d).items())
416 # check if updated information indicates that the device was bound
417 if "Driver_str" in devices[d]:
420 def display_devices(title, dev_list, extra_params = None):
421 '''Displays to the user the details of a list of devices given in "dev_list"
422 The "extra_params" parameter, if given, should contain a string with
423 %()s fields in it for replacement by the named fields in each device's
425 strings = [] # this holds the strings to print. We sort before printing
428 if len(dev_list) == 0:
429 strings.append("<none>")
432 if extra_params is not None:
433 strings.append("%s '%s' %s" % (dev["Slot"], \
434 dev["Device_str"], extra_params % dev))
436 strings.append("%s '%s'" % (dev["Slot"], dev["Device_str"]))
437 # sort before printing, so that the entries appear in PCI order
439 print "\n".join(strings) # print one per line
442 '''Function called when the script is passed the "--status" option. Displays
443 to the user what devices are bound to the igb_uio driver, the kernel driver
450 # split our list of devices into the three categories above
451 for d in devices.keys():
452 if not has_driver(d):
453 no_drv.append(devices[d])
455 if devices[d]["Driver_str"] in dpdk_drivers:
456 dpdk_drv.append(devices[d])
458 kernel_drv.append(devices[d])
460 # print each category separately, so we can clearly see what's used by DPDK
461 display_devices("Network devices using DPDK-compatible driver", dpdk_drv, \
462 "drv=%(Driver_str)s unused=%(Module_str)s")
463 display_devices("Network devices using kernel driver", kernel_drv,
464 "if=%(Interface)s drv=%(Driver_str)s unused=%(Module_str)s %(Active)s")
465 display_devices("Other network devices", no_drv,\
466 "unused=%(Module_str)s")
469 '''Parses the command-line arguments given by the user and takes the
470 appropriate action for each'''
475 if len(sys.argv) <= 1:
480 opts, args = getopt.getopt(sys.argv[1:], "b:u",
481 ["help", "usage", "status", "force",
483 except getopt.GetoptError, error:
485 print "Run '%s --usage' for further information" % sys.argv[0]
488 for opt, arg in opts:
489 if opt == "--help" or opt == "--usage":
492 if opt == "--status":
496 if opt == "-b" or opt == "-u" or opt == "--bind" or opt == "--unbind":
497 if b_flag is not None:
498 print "Error - Only one bind or unbind may be specified\n"
500 if opt == "-u" or opt == "--unbind":
505 def do_arg_actions():
506 '''do the actual action requested by the user'''
512 if b_flag is None and not status_flag:
513 print "Error: No action specified for devices. Please give a -b or -u option"
514 print "Run '%s --usage' for further information" % sys.argv[0]
517 if b_flag is not None and len(args) == 0:
518 print "Error: No devices specified."
519 print "Run '%s --usage' for further information" % sys.argv[0]
522 if b_flag == "none" or b_flag == "None":
523 unbind_all(args, force_flag)
524 elif b_flag is not None:
525 bind_all(args, b_flag, force_flag)
527 if b_flag is not None:
528 get_nic_details() # refresh if we have changed anything
532 '''program main function'''
538 if __name__ == "__main__":