Coverage for nova/conf/pci.py: 88%
8 statements
« prev ^ index » next coverage.py v7.6.12, created at 2025-04-17 15:08 +0000
1# Copyright (c) 2013 Intel, Inc.
2# Copyright (c) 2013 OpenStack Foundation
3# All Rights Reserved.
4#
5# Licensed under the Apache License, Version 2.0 (the "License"); you may
6# not use this file except in compliance with the License. You may obtain
7# a copy of the License at
8#
9# http://www.apache.org/licenses/LICENSE-2.0
10#
11# Unless required by applicable law or agreed to in writing, software
12# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14# License for the specific language governing permissions and limitations
15# under the License.
17from oslo_config import cfg
19pci_group = cfg.OptGroup(
20 name='pci',
21 title='PCI passthrough options')
23pci_opts = [
24 cfg.MultiStrOpt('alias',
25 default=[],
26 deprecated_name='pci_alias',
27 deprecated_group='DEFAULT',
28 help="""
29An alias for a PCI passthrough device requirement.
31This allows users to specify the alias in the extra specs for a flavor, without
32needing to repeat all the PCI property requirements.
34This should be configured for the ``nova-api`` service and, assuming you wish
35to use move operations, for each ``nova-compute`` service.
37Possible Values:
39* A JSON dictionary which describe a PCI device. It should take
40 the following format::
42 alias = {
43 "name": "<name>",
44 ["product_id": "<id>"],
45 ["vendor_id": "<id>"],
46 "device_type": "<type>",
47 ["numa_policy": "<policy>"],
48 ["resource_class": "<resource_class>"],
49 ["traits": "<traits>"]
50 ["live_migratable": "<live_migratable>"],
51 }
53 Where ``[`` indicates zero or one occurrences, ``{`` indicates zero or
54 multiple occurrences, and ``|`` mutually exclusive options.
56 For example::
58 alias = {
59 "name": "QuickAssist",
60 "product_id": "0443",
61 "vendor_id": "8086",
62 "device_type": "type-PCI",
63 "numa_policy": "required"
64 }
66 This defines an alias for the Intel QuickAssist card. (multi valued).
68 Another example::
70 alias = {
71 "name": "A16_16A",
72 "device_type": "type-VF",
73 resource_class: "CUSTOM_A16_16A",
74 }
76 Valid key values are :
78 ``name``
79 Name of the PCI alias.
81 ``product_id``
82 Product ID of the device in hexadecimal.
84 ``vendor_id``
85 Vendor ID of the device in hexadecimal.
87 ``device_type``
88 Type of PCI device. Valid values are: ``type-PCI``, ``type-PF`` and
89 ``type-VF``. Note that ``"device_type": "type-PF"`` **must** be specified
90 if you wish to passthrough a device that supports SR-IOV in its entirety.
92 ``numa_policy``
93 Required NUMA affinity of device. Valid values are: ``legacy``,
94 ``preferred``, ``required``, and ``socket``.
96 ``resource_class``
97 The optional Placement resource class name that is used
98 to track the requested PCI devices in Placement. It can be a standard
99 resource class from the ``os-resource-classes`` lib. Or it can be an
100 arbitrary string. If it is an non-standard resource class then Nova will
101 normalize it to a proper Placement resource class by
102 making it upper case, replacing any consecutive character outside of
103 ``[A-Z0-9_]`` with a single '_', and prefixing the name with ``CUSTOM_`` if
104 not yet prefixed. The maximum allowed length is 255 character including the
105 prefix. If ``resource_class`` is not provided Nova will generate it from
106 ``vendor_id`` and ``product_id`` values of the alias in the form of
107 ``CUSTOM_PCI_{vendor_id}_{product_id}``. The ``resource_class`` requested
108 in the alias is matched against the ``resource_class`` defined in the
109 ``[pci]device_spec``. This field can only be used only if
110 ``[filter_scheduler]pci_in_placement`` is enabled.
112 ``traits``
113 An optional comma separated list of Placement trait names requested to be
114 present on the resource provider that fulfills this alias. Each trait can
115 be a standard trait from ``os-traits`` lib or it can be an arbitrary
116 string. If it is a non-standard trait then Nova will normalize the
117 trait name by making it upper case, replacing any consecutive character
118 outside of ``[A-Z0-9_]`` with a single '_', and prefixing the name
119 with ``CUSTOM_`` if not yet prefixed. The maximum allowed length of a
120 trait name is 255 character including the prefix. Every trait in
121 ``traits`` requested in the alias ensured to be in the list of traits
122 provided in the ``traits`` field of the ``[pci]device_spec`` when
123 scheduling the request. This field can only be used only if
124 ``[filter_scheduler]pci_in_placement`` is enabled.
126 ``live_migratable``
127 Specify if live-migratable devices are desired.
128 May have boolean-like string values case-insensitive values:
129 "yes" or "no".
131 - ``live_migratable='yes'`` means that the user wants a device(s)
132 allowing live migration to a similar device(s) on another host.
134 - ``live_migratable='no'`` This explicitly indicates that the user
135 requires a non-live migratable device, making migration impossible.
137 - If not specified, the default is ``live_migratable=None``, meaning that
138 either a live migratable or non-live migratable device will be picked
139 automatically. However, in such cases, migration will **not** be
140 possible.
142* Supports multiple aliases by repeating the option (not by specifying
143 a list value)::
145 alias = {
146 "name": "QuickAssist-1",
147 "product_id": "0443",
148 "vendor_id": "8086",
149 "device_type": "type-PCI",
150 "numa_policy": "required"
151 }
152 alias = {
153 "name": "QuickAssist-2",
154 "product_id": "0444",
155 "vendor_id": "8086",
156 "device_type": "type-PCI",
157 "numa_policy": "required",
158 "live_migratable": "yes",
159 }
160"""),
161 cfg.MultiStrOpt('device_spec',
162 default=[],
163 deprecated_opts=[
164 cfg.DeprecatedOpt('passthrough_whitelist', group='pci'),
165 cfg.DeprecatedOpt('pci_passthrough_whitelist', group='DEFAULT'),
166 ],
167 help="""
168Specify the PCI devices available to VMs.
170Possible values:
172* A JSON dictionary which describe a PCI device. It should take
173 the following format::
175 ["vendor_id": "<id>",] ["product_id": "<id>",]
176 ["address": "[[[[<domain>]:]<bus>]:][<slot>][.[<function>]]" |
177 "devname": "<name>",]
178 {"<tag>": "<tag_value>",}
180 Where ``[`` indicates zero or one occurrences, ``{`` indicates zero or
181 multiple occurrences, and ``|`` mutually exclusive options. Note that any
182 missing fields are automatically wildcarded.
184 Valid key values are :
186 ``vendor_id``
187 Vendor ID of the device in hexadecimal.
189 ``product_id``
190 Product ID of the device in hexadecimal.
192 ``address``
193 PCI address of the device. Both traditional glob style and regular
194 expression syntax is supported. Please note that the address fields are
195 restricted to the following maximum values:
197 * domain - 0xFFFF
198 * bus - 0xFF
199 * slot - 0x1F
200 * function - 0x7
202 ``devname``
203 Device name of the device (for e.g. interface name). Not all PCI devices
204 have a name.
206 ``<tag>``
207 Additional ``<tag>`` and ``<tag_value>`` used for specifying PCI devices.
208 Supported ``<tag>`` values are :
210 - ``physical_network``
212 - ``trusted``
214 - ``remote_managed`` - a VF is managed remotely by an off-path networking
215 backend. May have boolean-like string values case-insensitive values:
216 "true" or "false". By default, "false" is assumed for all devices.
217 Using this option requires a networking service backend capable of
218 handling those devices. PCI devices are also required to have a PCI
219 VPD capability with a card serial number (either on a VF itself on
220 its corresponding PF), otherwise they will be ignored and not
221 available for allocation.
223 - ``managed`` - Specify if the PCI device is managed by libvirt.
224 May have boolean-like string values case-insensitive values:
225 "yes" or "no". By default, "yes" is assumed for all devices.
227 - ``managed='yes'`` means that nova will use libvirt to detach the
228 device from the host before attaching it to the guest and re-attach
229 it to the host after the guest is deleted.
231 - ``managed='no'`` means that nova will not request libvirt to
232 detach / attach the device from / to the host. In this case nova
233 assumes that the operator configured the host in a way that these
234 VFs are not attached to the host.
236 Warning: Incorrect configuration of this parameter may result in compute
237 node crashes.
239 - ``live_migratable`` - Specify if the PCI device is live_migratable by
240 libvirt.
241 May have boolean-like string values case-insensitive values:
242 "yes" or "no". By default, "no" is assumed for all devices.
244 - ``live_migratable='yes'`` means that the device can be live migrated.
245 Of course, this requires hardware support, as well as proper system
246 and hypervisor configuration.
248 - ``live_migratable='no'`` means that the device cannot be live migrated.
250 - ``resource_class`` - optional Placement resource class name to be used
251 to track the matching PCI devices in Placement when
252 [pci]report_in_placement is True.
253 It can be a standard resource class from the
254 ``os-resource-classes`` lib. Or can be any string. In that case Nova will
255 normalize it to a proper Placement resource class by making it upper
256 case, replacing any consecutive character outside of ``[A-Z0-9_]`` with a
257 single '_', and prefixing the name with ``CUSTOM_`` if not yet prefixed.
258 The maximum allowed length is 255 character including the prefix.
259 If ``resource_class`` is not provided Nova will generate it from the PCI
260 device's ``vendor_id`` and ``product_id`` in the form of
261 ``CUSTOM_PCI_{vendor_id}_{product_id}``.
262 The ``resource_class`` can be requested from a ``[pci]alias``
264 - ``traits`` - optional comma separated list of Placement trait names to
265 report on the resource provider that will represent the matching PCI
266 device. Each trait can be a standard trait from ``os-traits`` lib or can
267 be any string. If it is not a standard trait then Nova will normalize the
268 trait name by making it upper case, replacing any consecutive character
269 outside of ``[A-Z0-9_]`` with a single '_', and prefixing the name with
270 ``CUSTOM_`` if not yet prefixed. The maximum allowed length of a trait
271 name is 255 character including the prefix.
272 Any trait from ``traits`` can be requested from a ``[pci]alias``.
275 Valid examples are::
277 device_spec = {"devname":"eth0",
278 "physical_network":"physnet"}
279 device_spec = {"address":"*:0a:00.*"}
280 device_spec = {"address":":0a:00.",
281 "physical_network":"physnet1"}
282 device_spec = {"vendor_id":"1137",
283 "product_id":"0071"}
284 device_spec = {"vendor_id":"1137",
285 "product_id":"0071",
286 "address": "0000:0a:00.1",
287 "physical_network":"physnet1"}
288 device_spec = {"address":{"domain": ".*",
289 "bus": "02", "slot": "01",
290 "function": "[2-7]"},
291 "physical_network":"physnet1"}
292 device_spec = {"address":{"domain": ".*",
293 "bus": "02", "slot": "0[1-2]",
294 "function": ".*"},
295 "physical_network":"physnet1"}
296 device_spec = {"devname": "eth0", "physical_network":"physnet1",
297 "trusted": "true"}
298 device_spec = {"vendor_id":"a2d6",
299 "product_id":"15b3",
300 "remote_managed": "true"}
301 device_spec = {"vendor_id":"a2d6",
302 "product_id":"15b3",
303 "address": "0000:82:00.0",
304 "physical_network":"physnet1",
305 "remote_managed": "true"}
306 device_spec = {"vendor_id":"1002",
307 "product_id":"6929",
308 "address": "0000:82:00.0",
309 "resource_class": "PGPU",
310 "traits": "HW_GPU_API_VULKAN,my-awesome-gpu"}
311 device_spec = {"vendor_id":"10de",
312 "product_id":"25b6",
313 "address": "0000:25:00.4",
314 "managed": "no"}
315 device_spec = {"vendor_id":"10de",
316 "product_id":"25b6",
317 "address": "0000:25:00.4",
318 "resource_class": "CUSTOM_A16_16A",
319 "managed": "no"}
321 The following are invalid, as they specify mutually exclusive options::
323 device_spec = {"devname":"eth0",
324 "physical_network":"physnet",
325 "address":"*:0a:00.*"}
327 The following example is invalid because it specifies the ``remote_managed``
328 tag for a PF - it will result in an error during config validation at the
329 Nova Compute service startup::
331 device_spec = {"address": "0000:82:00.0",
332 "product_id": "a2d6",
333 "vendor_id": "15b3",
334 "physical_network": null,
335 "remote_managed": "true"}
337* A JSON list of JSON dictionaries corresponding to the above format. For
338 example::
340 device_spec = [{"product_id":"0001", "vendor_id":"8086"},
341 {"product_id":"0002", "vendor_id":"8086"}]
342"""),
343 cfg.BoolOpt('report_in_placement',
344 default=False,
345 help="""
346Enable PCI resource inventory reporting to Placement. If it is enabled then the
347nova-compute service will report PCI resource inventories to Placement
348according to the [pci]device_spec configuration and the PCI devices reported
349by the hypervisor. Once it is enabled it cannot be disabled any more. In a
350future release the default of this config will be change to True.
352Related options:
354* [pci]device_spec: to define which PCI devices nova are allowed to track and
355 assign to guests.
356"""),
357]
360def register_opts(conf):
361 conf.register_group(pci_group)
362 conf.register_opts(pci_opts, group=pci_group)
365def list_opts():
366 return {pci_group: pci_opts}