From 45ad213b470a03f21e069fce24cc50676c432831 Mon Sep 17 00:00:00 2001
From: Stephen Finucane <stephen.finucane@intel.com>
Date: Mon, 9 Nov 2015 22:22:13 +0000
Subject: [PATCH] Improve 'pci' conf options documentation

The 'pci_passthrough_whitelist' conf option can be be specified in
different ways, but the current documentation, defines only limited
option. Similarly the 'pci_alias' option is a JSON dictionary, but this
is not specificed.

Further document both option per definition from the 'pci-passthrough-sriov'
spec.

Change-Id: I7ecc1dbc3ccc60e174c0057412896d3896d2648e
Closes-bug: 1381017
---
 nova/conf/pci.py | 93 +++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 80 insertions(+), 13 deletions(-)

diff --git a/nova/conf/pci.py b/nova/conf/pci.py
index 1da6cd365eac..4505d44e04c3 100644
--- a/nova/conf/pci.py
+++ b/nova/conf/pci.py
@@ -19,23 +19,90 @@ from oslo_config import cfg
 pci_alias_opt = cfg.MultiStrOpt(
     'pci_alias',
     default=[],
-    help='An alias for a PCI passthrough device requirement. This allows '
-    'users to specify the alias in the extra_spec for a flavor, '
-    'without needing to repeat all the PCI property requirements. For '
-    'example: pci_alias = { '
-    '"name": "QuickAssist", '
-    '"product_id": "0443", '
-    '"vendor_id": "8086", '
-    '"device_type": "type-PCI" '
-    '} defines an alias for the Intel QuickAssist card. (multi '
-    'valued).')
+    help="""
+An alias for a PCI passthrough device requirement.
+
+This allows users to specify the alias in the extra_spec for a flavor, without
+needing to repeat all the PCI property requirements.
+
+Possible Values:
+
+* A list of JSON values which describe the aliases. For example:
+
+    pci_alias = {
+      "name": "QuickAssist",
+      "product_id": "0443",
+      "vendor_id": "8086",
+      "device_type": "type-PCI"
+    }
+
+  defines an alias for the Intel QuickAssist card. (multi valued). Valid key
+  values are :
+
+  * "name"
+  * "product_id"
+  * "vendor_id"
+  * "device_type"
+
+Services which consume this:
+
+* nova-compute
+
+Related options:
+
+* None""")
 
 pci_passthrough_whitelist_opt = cfg.MultiStrOpt(
     'pci_passthrough_whitelist',
     default=[],
-    help='White list of PCI devices available to VMs. For example: '
-    'pci_passthrough_whitelist = '
-    '[{"vendor_id": "8086", "product_id": "0443"}]')
+    help="""
+White list of PCI devices available to VMs.
+
+Possible values:
+
+* A JSON dictionary which describe a whitelisted PCI device. It should take
+  the following format:
+
+    ["device_id": "<id>",] ["product_id": "<id>",]
+    ["address": "[[[[<domain>]:]<bus>]:][<slot>][.[<function>]]" |
+     "devname": "PCI Device Name",]
+    {"tag": "<tag_value>",}
+
+  where '[' indicates zero or one occurrences, '{' indicates zero or multiple
+  occurrences, and '|' mutually exclusive options. Note that any missing
+  fields are automatically wildcarded. Valid examples are:
+
+    pci_passthrough_whitelist = {"devname":"eth0",
+                                 "physical_network":"physnet"}
+    pci_passthrough_whitelist = {"address":"*:0a:00.*"}
+    pci_passthrough_whitelist = {"address":":0a:00.",
+                                 "physical_network":"physnet1"}
+    pci_passthrough_whitelist = {"vendor_id":"1137",
+                                 "product_id":"0071"}
+    pci_passthrough_whitelist = {"vendor_id":"1137",
+                                 "product_id":"0071",
+                                 "address": "0000:0a:00.1",
+                                 "physical_network":"physnet1"}
+
+  The following are invalid, as they specify mutually exclusive options:
+
+    pci_passthrough_whitelist = {"devname":"eth0",
+                                 "physical_network":"physnet",
+                                 "address":"*:0a:00.*"}
+
+* A JSON list of JSON dictionaries corresponding to the above format. For
+  example:
+
+    pci_passthrough_whitelist = [{"product_id":"0001", "vendor_id":"8086"},
+                                 {"product_id":"0002", "vendor_id":"8086"}]
+
+Services which consume this:
+
+* nova-compute
+
+Related options:
+
+* None""")
 
 ALL_OPTS = [pci_alias_opt,
             pci_passthrough_whitelist_opt]