avocado.utils.pci: Explicitly distinguish between partial and full addrs

The `avocado.utils.pci` library incorporates many functions related to
pcis and some functions accept only full pci address, some partial and
some only special format (domain+bus, ...). Let's explicitly distinguish
by using:

* pci_address - for any segment of pci address
* full_pci_address - for full pci address only
* dom_pci_address - for special usecase where domain is required
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

avocado/utils/pci.py

@@ -48,7 +48,7 @@ def get_pci_addresses():
     Gets list of pci addresses in the system.
     Does not return the PCI Bridges/Switches.
 
-    :return: list of pci addresses.
+    :return: list of full pci addresses including domain (0000:00:14.0)
     """
     addresses = []
     cmd = "lspci -D"
@@ -84,7 +84,7 @@ def get_disks_in_pci_address(pci_address):
     """
     Gets disks in a pci_address.
 
-    :parm pci_address: pci address.
+    :parm pci_address: Any segment of a pci address (1f, 0000:00:1f, ...)
 
     :return: list of disks in a pci address.
     """
@@ -101,7 +101,7 @@ def get_nics_in_pci_address(pci_address):
     """
     Gets network interface(nic) in a pci address.
 
-    :parm pci_address: pci address.
+    :parm pci_address: Any segment of a pci address (1f, 0000:00:1f, ...)
 
     :return: list of network interfaces in a pci address.
     """
@@ -118,26 +118,26 @@ def get_pci_fun_list(pci_address):
     Gets list of functions in the given pci address.
     Example: in address 0000:03:00, functions are 0000:03:00.0 and 0000:03:00.1
 
-    :parm pci_address: pci address.
+    :parm pci_address: Any segment of a pci address (1f, 0000:00:1f, ...)
 
     :return: list of functions in a pci address.
     """
     return list(dev for dev in get_pci_addresses() if pci_address in dev)
 
 
-def get_slot_from_sysfs(pci_address):
+def get_slot_from_sysfs(full_pci_address):
     """
     Gets the pci slot of given address.
 
     :note: Specific for ppc64 processor.
 
-    :parm pci_address: pci address.
+    :parm full_pci_address: Full pci address including domain (0000:03:00.0)
 
     :return: slot of pci address from sysfs.
     """
-    if not os.path.isfile('/sys/bus/pci/devices/%s/devspec' % pci_address):
+    if not os.path.isfile('/sys/bus/pci/devices/%s/devspec' % full_pci_address):
         return
-    devspec = read_file("/sys/bus/pci/devices/%s/devspec" % pci_address)
+    devspec = read_file("/sys/bus/pci/devices/%s/devspec" % full_pci_address)
     if not os.path.isfile("/proc/device-tree/%s/ibm,loc-code" % devspec):
         return
     slot = read_file("/proc/device-tree/%s/ibm,loc-code" % devspec)
@@ -156,15 +156,15 @@ def get_slot_list():
     return list(set(get_slot_from_sysfs(dev) for dev in get_pci_addresses()))
 
 
-def get_pci_id_from_sysfs(pci_address):
+def get_pci_id_from_sysfs(full_pci_address):
     """
     Gets the pci id from sysfs of given pci address.
 
-    :parm pci_address: pci address.
+    :parm full_pci_address: Full pci address including domain (0000:03:00.0)
 
     :return: pci id of a pci address from sysfs.
     """
-    path = "/sys/bus/pci/devices/%s" % pci_address
+    path = "/sys/bus/pci/devices/%s" % full_pci_address
     if os.path.isdir(path):
         path = "%s/%%s" % path
         return ":".join(["%04x" % int(open(path % param).read(), 16)
@@ -174,9 +174,9 @@ def get_pci_id_from_sysfs(pci_address):
 
 def get_pci_prop(pci_address, prop):
     """
-    Gets specific pci id of given pci address.
+    Gets specific pci id of given pci address. (first match only)
 
-    :parm pci_address: pci address.
+    :parm pci_address: Any segment of a pci address (1f, 0000:00:1f, ...)
     :parm part: prop of pci id.
 
     :return: specific pci id of a pci address.
@@ -191,9 +191,9 @@ def get_pci_prop(pci_address, prop):
 
 def get_pci_id(pci_address):
     """
-    Gets pci id of given address.
+    Gets pci id of given address. (first match only)
 
-    :parm pci_address: pci address.
+    :parm pci_address: Any segment of a pci address (1f, 0000:00:1f, ...)
 
     :return: pci id of a pci address.
     """
@@ -209,9 +209,9 @@ def get_pci_id(pci_address):
 
 def get_driver(pci_address):
     """
-    Gets the kernel driver in use of given pci address.
+    Gets the kernel driver in use of given pci address. (first match only)
 
-    :parm pci_address: pci address.
+    :parm pci_address: Any segment of a pci address (1f, 0000:00:1f, ...)
 
     :return: driver of a pci address.
     """
@@ -225,12 +225,12 @@ def get_driver(pci_address):
 
 def get_memory_address(pci_address):
     """
-    Gets the memory address of a pci address.
+    Gets the memory address of a pci address. (first match only)
 
     :note: There may be multiple memory address for a pci address.
     :note: This function returns only the first such address.
 
-    :parm pci_address: pci address.
+    :parm pci_address: Any segment of a pci address (1f, 0000:00:1f, ...)
 
     :return: memory address of a pci_address.
     """
@@ -244,12 +244,12 @@ def get_memory_address(pci_address):
 
 def get_mask(pci_address):
     """
-    Gets the mask of pci address.
+    Gets the mask of pci address. (first match only)
 
     :note: There may be multiple memory entries for a pci address.
     :note: This mask is calculated only with the first such entry.
 
-    :parm pci_address: pci address.
+    :parm pci_address: Any segment of a pci address (1f, 0000:00:1f, ...)
 
     :return: mask of a pci address.
     """
@@ -267,18 +267,19 @@ def get_mask(pci_address):
         return mask
 
 
-def get_vpd(pci_addr):
+def get_vpd(dom_pci_address):
     """
     Gets the vpd of the given pci address.
     lsvpd lists the Vital Product Data of a pci address.
 
     :note: Specific for ppc64 processor.
 
-    :parm pci_addr: pci address.
+    :parm dom_pci_address: Partial pci address including domain addr and at
+                           least bus addr (0003:00, 0003:00:1f.2, ...)
 
     :return: dictionary of vpd of a pci address.
     """
-    cmd = "lsvpd -l %s" % pci_addr
+    cmd = "lsvpd -l %s" % dom_pci_address
     vpd = process.system_output(cmd)
     vpd_dic = {}
     dev_list = []
@@ -292,28 +293,30 @@ def get_vpd(pci_addr):
         elif '*FC' in line:
             vpd_dic['feature_code'] = line[4:]
         elif '*AX' in line:
-            if not (pci_addr in line or vpd_dic['pci_id'].split()[0] in line):
+            if not (dom_pci_address in line or
+                    vpd_dic['pci_id'].split()[0] in line):
                 dev_list.append(line[4:])
     vpd_dic['devices'] = dev_list
     return vpd_dic
 
 
-def get_cfg(pci_addr):
+def get_cfg(dom_pci_address):
     """
     Gets the cfg data of the given pci address.
     lscfg lists the hardware configuration of a pci address.
 
     :note: Specific for ppc64 processor.
 
-    :parm pci_addr: pci address.
+    :parm dom_pci_address: Partial pci address including domain addr and at
+                           least bus addr (0003:00, 0003:00:1f.2, ...)
 
     :return: dictionary of cfg data of a pci address.
     """
-    cmd = "lscfg -vl %s" % pci_addr
+    cmd = "lscfg -vl %s" % dom_pci_address
     cfg = process.system_output(cmd)
     cfg_dic = {}
-    desc = re.match(r'  (%s)( [-\w+,\.]+)+([ \n])+([-\w+, \(\)])+' % pci_addr,
-                    cfg).group()
+    desc = re.match(r'  (%s)( [-\w+,\.]+)+([ \n])+([-\w+, \(\)])+'
+                    % dom_pci_address, cfg).group()
     cfg_dic['Description'] = desc
     for line in cfg.splitlines():
         if 'Manufacturer Name' in line: