5 # Copyright(c) 2010-2013 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.
36 import sys, os, getopt, subprocess
37 from os.path import exists, abspath, dirname, basename
40 # The PCI device class for ETHERNET devices
41 ETHERNET_CLASS = "0200"
43 # global dict ethernet devices present. Dictionary indexed by PCI address.
44 # Each device within this is itself a dictionary of device properties
46 # list of vendor:device pairs (again stored as dictionary) supported by igb_uio
50 '''Print usage information for the program'''
51 argv0 = basename(sys.argv[0])
56 %(argv0)s [options] DEVICE1 DEVICE2 ....
58 where DEVICE1, DEVICE2 etc, are specified via PCI "domain:bus:slot.func" syntax
59 or "bus:slot.func" syntax. For devices bound to Linux kernel drivers, they may
60 also be referred to by Linux interface name e.g. eth0, eth1, em0, em1, etc.
64 Display usage information and quit
67 Print the current status of all known network interfaces.
68 For each device, it displays the PCI domain, bus, slot and function,
69 along with a text description of the device. Depending upon whether the
70 device is being used by a kernel driver, the igb_uio driver, or no
71 driver, other relevant information will be displayed:
72 * the Linux interface name e.g. if=eth0
73 * the driver being used e.g. drv=igb_uio
74 * any suitable drivers not currently using that device
76 NOTE: if this flag is passed along with a bind/unbind option, the status
77 display will always occur after the other operations have taken place.
79 -b driver, --bind=driver:
80 Select the driver to use or \"none\" to unbind the device
83 Unbind a device (Equivalent to \"-b none\")
86 By default, devices which are used by Linux - as indicated by having
87 routes in the routing table - cannot be modified. Using the --force
88 flag overrides this behavior, allowing active links to be forcibly
90 WARNING: This can lead to loss of network connection and should be used
96 To display current device status:
99 To bind eth1 from the current driver and move to use igb_uio
100 %(argv0)s --bind=igb_uio eth1
102 To unbind 0000:01:00.0 from using any driver
103 %(argv0)s -u 0000:01:00.0
105 To bind 0000:02:00.0 and 0000:02:00.1 to the ixgbe kernel driver
106 %(argv0)s -b ixgbe 02:00.0 02:00.1
108 """ % locals() # replace items from local variables
110 # This is roughly compatible with check_output function in subprocess module
111 # which is only available in python 2.7.
112 def check_output(args, stderr=None):
113 '''Run a command and capture its output'''
114 return subprocess.Popen(args, stdout=subprocess.PIPE,
115 stderr=stderr).communicate()[0]
117 def find_module(mod):
118 '''find the .ko file for kernel module named mod.
119 Searches the $RTE_SDK/$RTE_TARGET directory, the kernel
120 modules directory and finally under the parent directory of
122 # check $RTE_SDK/$RTE_TARGET directory
123 if 'RTE_SDK' in os.environ and 'RTE_TARGET' in os.environ:
124 path = "%s/%s/kmod/%s.ko" % (os.environ['RTE_SDK'],\
125 os.environ['RTE_TARGET'], mod)
131 depmod_out = check_output(["modinfo", "-n", mod], \
132 stderr=subprocess.STDOUT).lower()
133 if "error" not in depmod_out:
134 path = depmod_out.strip()
137 except: # if modinfo can't find module, it fails, so continue
140 # check for a copy based off current path
141 tools_dir = dirname(abspath(sys.argv[0]))
142 if (tools_dir.endswith("tools")):
143 base_dir = dirname(tools_dir)
144 find_out = check_output(["find", base_dir, "-name", mod + ".ko"])
145 if len(find_out) > 0: #something matched
146 path = find_out.splitlines()[0]
151 '''Checks that the needed modules (igb_uio) is loaded, and then
152 determine from the .ko file, what its supported device ids are'''
153 global module_dev_ids
155 fd = file("/proc/modules")
156 loaded_mods = fd.readlines()
160 # first check if module is loaded
162 for line in loaded_mods:
163 if line.startswith(mod):
167 print "Error - module %s not loaded" %mod
170 # now find the .ko and get list of supported vendor/dev-ids
171 modpath = find_module(mod)
173 print "Cannot find module file %s" % (mod + ".ko")
175 depmod_output = check_output(["depmod", "-n", modpath]).splitlines()
176 for line in depmod_output:
177 if not line.startswith("alias"):
179 if not line.endswith(mod):
181 lineparts = line.split()
182 if not(lineparts[1].startswith("pci:")):
185 lineparts[1] = lineparts[1][4:]
186 vendor = lineparts[1][:9]
187 device = lineparts[1][9:18]
188 if vendor.startswith("v") and device.startswith("d"):
189 module_dev_ids.append({"Vendor": int(vendor[1:],16),
190 "Device": int(device[1:],16)})
192 def is_supported_device(dev_id):
193 '''return true if device is supported by igb_uio, false otherwise'''
194 for dev in module_dev_ids:
195 if (dev["Vendor"] == devices[dev_id]["Vendor"] and
196 dev["Device"] == devices[dev_id]["Device"]):
200 def has_driver(dev_id):
201 '''return true if a device is assigned to a driver. False otherwise'''
202 return "Driver_str" in devices[dev_id]
204 def get_nic_details():
205 '''This function populates the "devices" dictionary. The keys used are
206 the pci addresses (domain:bus:slot.func). The values are themselves
207 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"] == ETHERNET_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 devices[dev["Slot"]] = dict(dev) # use dict to make copy of dev
224 name, value = dev_line.split("\t", 1)
225 dev[name.rstrip(":")] = value
227 # check what is the interface if any for an ssh connection if
228 # any to this host, so we can mark it later.
230 route = check_output(["ip", "-o", "route"])
231 # filter out all lines for 169.254 routes
232 route = "\n".join(filter(lambda ln: not ln.startswith("169.254"),
234 rt_info = route.split()
235 for i in xrange(len(rt_info) - 1):
236 if rt_info[i] == "dev":
237 ssh_if.append(rt_info[i+1])
239 # based on the basic info, get extended text details
240 for d in devices.keys():
241 extra_info = check_output(["lspci", "-vmmks", d]).splitlines()
242 # parse lspci details
243 for line in extra_info:
246 name, value = line.split("\t", 1)
247 name = name.strip(":") + "_str"
248 devices[d][name] = value
249 # check for a unix interface name
250 sys_path = "/sys/bus/pci/devices/%s/net/" % d
252 devices[d]["Interface"] = ",".join(os.listdir(sys_path))
254 devices[d]["Interface"] = ""
255 # check if a port is used for ssh connection
256 devices[d]["Ssh_if"] = False
257 devices[d]["Active"] = ""
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 is_supported_device(d):
266 if "Module_str" in devices[d]:
267 if "igb_uio" not in devices[d]["Module_str"]:
268 devices[d]["Module_str"] = devices[d]["Module_str"] + ",igb_uio"
270 devices[d]["Module_str"] = "igb_uio"
271 if "Module_str" not in devices[d]:
272 devices[d]["Module_str"] = "<none>"
273 # make sure the driver and module strings do not have any duplicates
275 modules = devices[d]["Module_str"].split(",")
276 if devices[d]["Driver_str"] in modules:
277 modules.remove(devices[d]["Driver_str"])
278 devices[d]["Module_str"] = ",".join(modules)
280 def dev_id_from_dev_name(dev_name):
281 '''Take a device "name" - a string passed in by user to identify a NIC
282 device, and determine the device id - i.e. the domain:bus:slot.func - for
283 it, which can then be used to index into the devices array'''
285 # check if it's already a suitable index
286 if dev_name in devices:
288 # check if it's an index just missing the domain part
289 elif "0000:" + dev_name in devices:
290 return "0000:" + dev_name
292 # check if it's an interface name, e.g. eth1
293 for d in devices.keys():
294 if dev_name in devices[d]["Interface"].split(","):
295 return devices[d]["Slot"]
296 # if nothing else matches - error
297 print "Unknown device: %s. " \
298 "Please specify device in \"bus:slot.func\" format" % dev_name
301 def unbind_one(dev_id, force):
302 '''Unbind the device identified by "dev_id" from its current driver'''
303 dev = devices[dev_id]
304 if not has_driver(dev_id):
305 print "%s %s %s is not currently managed by any driver\n" % \
306 (dev["Slot"], dev["Device_str"], dev["Interface"])
309 # prevent us disconnecting ourselves
310 if dev["Ssh_if"] and not force:
311 print "Routing table indicates that interface %s is active" \
312 ". Skipping unbind" % (dev_id)
315 # write to /sys to unbind
316 filename = "/sys/bus/pci/drivers/%s/unbind" % dev["Driver_str"]
318 f = open(filename, "a")
320 print "Error: unbind failed for %s - Cannot open %s" % (dev_id, filename)
325 def bind_one(dev_id, driver, force):
326 '''Bind the device given by "dev_id" to the driver "driver". If the device
327 is already bound to a different driver, it will be unbound first'''
328 dev = devices[dev_id]
329 saved_driver = None # used to rollback any unbind in case of failure
331 # prevent disconnection of our ssh session
332 if dev["Ssh_if"] and not force:
333 print "Routing table indicates that interface %s is active" \
334 ". Not modifying" % (dev_id)
337 # unbind any existing drivers we don't want
338 if has_driver(dev_id):
339 if dev["Driver_str"] == driver:
340 print "%s already bound to driver %s, skipping\n" % (dev_id, driver)
343 saved_driver = dev["Driver_str"]
344 unbind_one(dev_id, force)
345 dev["Driver_str"] = "" # clear driver string
347 # do the bind by writing to /sys
348 filename = "/sys/bus/pci/drivers/%s/bind" % driver
350 f = open(filename, "a")
352 print "Error: bind failed for %s - Cannot open %s" % (dev_id, filename)
353 if saved_driver is not None: # restore any previous driver
354 bind_one(dev_id, saved_driver, force)
360 print "Error: bind failed for %s - Cannot bind to driver %s" % (dev_id, driver)
361 if saved_driver is not None: # restore any previous driver
362 bind_one(dev_id, saved_driver, force)
366 def unbind_all(dev_list, force=False):
367 """Unbind method, takes a list of device locations"""
368 dev_list = map(dev_id_from_dev_name, dev_list)
372 def bind_all(dev_list, driver, force=False):
373 """Unbind method, takes a list of device locations"""
374 dev_list = map(dev_id_from_dev_name, dev_list)
376 bind_one(d, driver, force)
378 def display_devices(title, dev_list, extra_params = None):
379 '''Displays to the user the details of a list of devices given in "dev_list"
380 The "extra_params" parameter, if given, should contain a string with
381 %()s fields in it for replacement by the named fields in each device's
383 strings = [] # this holds the strings to print. We sort before printing
386 if len(dev_list) == 0:
387 strings.append("<none>")
390 if extra_params is not None:
391 strings.append("%s '%s' %s" % (dev["Slot"], \
392 dev["Device_str"], extra_params % dev))
394 strings.append("%s '%s'" % (dev["Slot"], dev["Device_str"]))
395 # sort before printing, so that the entries appear in PCI order
397 print "\n".join(strings) # print one per line
400 '''Function called when the script is passed the "--status" option. Displays
401 to the user what devices are bound to the igb_uio driver, the kernel driver
406 # split our list of devices into the three categories above
407 for d in devices.keys():
408 if not has_driver(d):
409 no_drv.append(devices[d])
411 if devices[d]["Driver_str"] == "igb_uio":
412 uio_drv.append(devices[d])
414 kernel_drv.append(devices[d])
416 # print each category separately, so we can clearly see what's used by DPDK
417 display_devices("Network devices using IGB_UIO driver", uio_drv, \
418 "drv=%(Driver_str)s unused=%(Module_str)s")
419 display_devices("Network devices using kernel driver", kernel_drv,
420 "if=%(Interface)s drv=%(Driver_str)s unused=%(Module_str)s %(Active)s")
421 display_devices("Other network devices", no_drv,\
422 "unused=%(Module_str)s")
425 '''Parses the command-line arguments given by the user and takes the
426 appropriate action for each'''
430 if len(sys.argv) <= 1:
435 opts, args = getopt.getopt(sys.argv[1:], "b:u",
436 ["help", "usage", "status", "force",
438 except getopt.GetoptError, error:
440 print "Run '%s --usage' for further information" % sys.argv[0]
443 for opt, arg in opts:
444 if opt == "--help" or opt == "--usage":
447 if opt == "--status":
451 if opt == "-b" or opt == "-u" or opt == "--bind" or opt == "--unbind":
452 if b_flag is not None:
453 print "Error - Only one bind or unbind may be specified\n"
455 if opt == "-u" or opt == "--unbind":
460 if b_flag is None and not status_flag:
461 print "Error: No action specified for devices. Please give a -b or -u option"
462 print "Run '%s --usage' for further information" % sys.argv[0]
465 if b_flag is not None and len(args) == 0:
466 print "Error: No devices specified."
467 print "Run '%s --usage' for further information" % sys.argv[0]
470 if b_flag == "none" or b_flag == "None":
471 unbind_all(args, force_flag)
472 elif b_flag is not None:
473 bind_all(args, b_flag, force_flag)
475 if b_flag is not None:
476 get_nic_details() # refresh if we have changed anything
480 '''program main function'''
485 if __name__ == "__main__":