From 16f832ad4baea0cd04d46071d8ceedf0396a6c54 Mon Sep 17 00:00:00 2001
From: Dan Smith <dansmith@redhat.com>
Date: Thu, 22 May 2025 06:50:37 -0700
Subject: [PATCH] pci: Add more detail and examples to pci.alias docs

This adds another example with traits, using a non-vendor-product
custom resource class. It also adds a note to the traits item to
indicate that it's not usable by itself and must be paired with a
vendor/product or resource_class.

Change-Id: Ica7bef7a7e0b27328cb551cdd3e2de633c0a3302
---
 nova/conf/pci.py | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/nova/conf/pci.py b/nova/conf/pci.py
index 6ed7a6aa31..f2373b8606 100644
--- a/nova/conf/pci.py
+++ b/nova/conf/pci.py
@@ -64,7 +64,8 @@ Possible Values:
 
   This defines an alias for the Intel QuickAssist card. (multi valued).
 
-  Another example::
+  Another example which matches a single device but by its placement resource
+  class is::
 
     alias = {
       "name": "A16_16A",
@@ -72,6 +73,18 @@ Possible Values:
       "resource_class": "CUSTOM_A16_16A",
     }
 
+  Yet another scenario where multiple devices with different ``vendor_id`` and
+  ``product_id`` values but which are functionally the same can be achieved
+  using a custom resource class in the ``device_spec`` which we request here.
+  A list of traits may be used for further refinement::
+
+    alias = {
+      "name": "NVME256G",
+      "device_type": "type-PCI",
+      "resource_class": "CUSTOM_NVME256G",
+      "traits": "nvme-with-crypto-erase",
+    }
+
   Valid key values are :
 
   ``name``
@@ -120,7 +133,9 @@ Possible Values:
     ``traits`` requested in the alias ensured to be in the list of traits
     provided in the ``traits`` field of the ``[pci]device_spec`` when
     scheduling the request. This field can only be used only if
-    ``[filter_scheduler]pci_in_placement`` is enabled.
+    ``[filter_scheduler]pci_in_placement`` is enabled. **NOTE**: An alias must
+    include either a ``vendor_id``/``product_id`` pair or a ``resource_class``.
+    An alias with only ``traits`` is not allowed.
 
   ``live_migratable``
     Specify if live-migratable devices are desired.