python3/usb_scan: Skip empty lines in usb-policy.conf, add more comments (#6616)

Allow empty lines in usb-policy.conf (it's standard practice in similar
configuration files to allow both comments and empty lines, and it can
help readability quite a bit).

Previously, the script would fail in a rather unhelpful manner:

    Traceback (most recent call last):
      File "/opt/xensource/libexec/usb_scan.py", line 681, in <module>
        pusbs = make_pusbs_list(devices, interfaces)
File "/opt/xensource/libexec/usb_scan.py", line 660, in make_pusbs_list
        policy = Policy()
      File "/opt/xensource/libexec/usb_scan.py", line 384, in __init__
        self.parse_line(line)
      File "/opt/xensource/libexec/usb_scan.py", line 444, in parse_line
        if action.lower() == "allow":
UnboundLocalError: local variable 'action' referenced before assignment

See this forum thread for a user figuring this out on their own:
https://xcp-ng.org/forum/topic/11091/usb-passthrough-has-stopped-working-after-update-and-updating-usb-policy.conf/

Add some more comments to usb-policy.conf to help debug cases like the
above.

Author: last-genius

python3/libexec/usb_scan.py

@@ -421,6 +421,10 @@ def parse_line(self, line):
         :param line: (str) single line of policy file
         :return: None
         """
+        # 0. skip empty lines
+        if line.strip() == '':
+            return
+
         # 1. remove comments
         # ^([^#]*)(#.*)?$
         i = line.find("#")

python3/tests/test_usb_scan.py

@@ -372,3 +372,11 @@ def test_usb_config_error_missing_colon(self):
 ALLOW # Otherwise allow everything else
 """
         self.verify_usb_config_error_common(content, "to unpack")
+
+    def test_usb_config_empty_line(self):
+        content = """# empty line
+ALLOW:vid=056a pid=0314 class=03  # Wacom Intuos tablet
+
+ALLOW # Otherwise allow everything else
+"""
+        self.verify_usb_config_error_common(content, "")

scripts/usb-policy.conf

@@ -1,11 +1,16 @@
 # When you change this file, run 'xe pusb-scan' to confirm
 # the file can be parsed correctly.
+# You can also run '/opt/xensource/libexec/usb_scan.py -d' to see
+# debug output from the script parsing this configuration file.
 #
 # Syntax is an ordered list of case insensitive rules where # is line comment
 #  and each rule is (ALLOW | DENY) : ( match )*
 #  and each match is (class|subclass|prot|vid|pid|rel) = hex-number
 # Maximum hex value for class/subclass/prot is FF, and for vid/pid/rel is FFFF
 #
+# Rules are ordered so that the first matching rule will override
+# any other rules for the device below it
+#
 # USB Hubs (class 09) are always denied, independently of the rules in this file
 DENY: vid=17e9 # All DisplayLink USB displays
 DENY: class=02 # Communications and CDC-Control