Coverage for nova/conf/pci.py: 88%
8 statements
« prev ^ index » next coverage.py v7.6.12, created at 2025-04-24 11:16 +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 Note that ``[...]`` indicates optional field.
55 For example::
57 alias = {
58 "name": "QuickAssist",
59 "product_id": "0443",
60 "vendor_id": "8086",
61 "device_type": "type-PCI",
62 "numa_policy": "required"
63 }
65 This defines an alias for the Intel QuickAssist card. (multi valued).
67 Another example::
69 alias = {
70 "name": "A16_16A",
71 "device_type": "type-VF",
72 "resource_class": "CUSTOM_A16_16A",
73 }
75 Valid key values are :
77 ``name``
78 Name of the PCI alias.
80 ``product_id``
81 Product ID of the device in hexadecimal.
83 ``vendor_id``
84 Vendor ID of the device in hexadecimal.
86 ``device_type``
87 Type of PCI device. Valid values are: ``type-PCI``, ``type-PF`` and
88 ``type-VF``. Note that ``"device_type": "type-PF"`` **must** be specified
89 if you wish to passthrough a device that supports SR-IOV in its entirety.
91 ``numa_policy``
92 Required NUMA affinity of device. Valid values are: ``legacy``,
93 ``preferred``, ``required``, and ``socket``.
95 ``resource_class``
96 The optional Placement resource class name that is used
97 to track the requested PCI devices in Placement. It can be a standard
98 resource class from the ``os-resource-classes`` lib. Or it can be an
99 arbitrary string. If it is an non-standard resource class then Nova will
100 normalize it to a proper Placement resource class by
101 making it upper case, replacing any consecutive character outside of
102 ``[A-Z0-9_]`` with a single '_', and prefixing the name with ``CUSTOM_`` if
103 not yet prefixed. The maximum allowed length is 255 character including the
104 prefix. If ``resource_class`` is not provided Nova will generate it from
105 ``vendor_id`` and ``product_id`` values of the alias in the form of
106 ``CUSTOM_PCI_{vendor_id}_{product_id}``. The ``resource_class`` requested
107 in the alias is matched against the ``resource_class`` defined in the
108 ``[pci]device_spec``. This field can only be used only if
109 ``[filter_scheduler]pci_in_placement`` is enabled.
111 ``traits``
112 An optional comma separated list of Placement trait names requested to be
113 present on the resource provider that fulfills this alias. Each trait can
114 be a standard trait from ``os-traits`` lib or it can be an arbitrary
115 string. If it is a non-standard trait then Nova will normalize the
116 trait name by making it upper case, replacing any consecutive character
117 outside of ``[A-Z0-9_]`` with a single '_', and prefixing the name
118 with ``CUSTOM_`` if not yet prefixed. The maximum allowed length of a
119 trait name is 255 character including the prefix. Every trait in
120 ``traits`` requested in the alias ensured to be in the list of traits
121 provided in the ``traits`` field of the ``[pci]device_spec`` when
122 scheduling the request. This field can only be used only if
123 ``[filter_scheduler]pci_in_placement`` is enabled.
125 ``live_migratable``
126 Specify if live-migratable devices are desired.
127 May have boolean-like string values case-insensitive values:
128 "yes" or "no".
130 - ``live_migratable='yes'`` means that the user wants a device(s)
131 allowing live migration to a similar device(s) on another host.
133 - ``live_migratable='no'`` This explicitly indicates that the user
134 requires a non-live migratable device, making migration impossible.
136 - If not specified, the default is ``live_migratable=None``, meaning that
137 either a live migratable or non-live migratable device will be picked
138 automatically. However, in such cases, migration will **not** be
139 possible.
141* Supports multiple aliases by repeating the option (not by specifying
142 a list value)::
144 alias = {
145 "name": "QuickAssist-1",
146 "product_id": "0443",
147 "vendor_id": "8086",
148 "device_type": "type-PCI",
149 "numa_policy": "required"
150 }
151 alias = {
152 "name": "QuickAssist-2",
153 "product_id": "0444",
154 "vendor_id": "8086",
155 "device_type": "type-PCI",
156 "numa_policy": "required",
157 "live_migratable": "yes",
158 }
159"""),
160 cfg.MultiStrOpt('device_spec',
161 default=[],
162 deprecated_opts=[
163 cfg.DeprecatedOpt('passthrough_whitelist', group='pci'),
164 cfg.DeprecatedOpt('pci_passthrough_whitelist', group='DEFAULT'),
165 ],
166 help="""
167Specify the PCI devices available to VMs.
169Possible values:
171* A JSON dictionary which describe a PCI device. It should take
172 the following format::
174 ["vendor_id": "<id>",] ["product_id": "<id>",]
175 ["address": "[[[[<domain>]:]<bus>]:][<slot>][.[<function>]]" |
176 "devname": "<name>",]
177 {"<tag>": "<tag_value>",}
179 Where ``[`` indicates zero or one occurrences, ``{`` indicates zero or
180 multiple occurrences, and ``|`` mutually exclusive options. Note that any
181 missing fields are automatically wildcarded.
183 Valid key values are :
185 ``vendor_id``
186 Vendor ID of the device in hexadecimal.
188 ``product_id``
189 Product ID of the device in hexadecimal.
191 ``address``
192 PCI address of the device. Both traditional glob style and regular
193 expression syntax is supported. Please note that the address fields are
194 restricted to the following maximum values:
196 * domain - 0xFFFF
197 * bus - 0xFF
198 * slot - 0x1F
199 * function - 0x7
201 ``devname``
202 Device name of the device (for e.g. interface name). Not all PCI devices
203 have a name.
205 ``<tag>``
206 Additional ``<tag>`` and ``<tag_value>`` used for specifying PCI devices.
207 Supported ``<tag>`` values are :
209 - ``physical_network``
211 - ``trusted``
213 - ``remote_managed`` - a VF is managed remotely by an off-path networking
214 backend. May have boolean-like string values case-insensitive values:
215 "true" or "false". By default, "false" is assumed for all devices.
216 Using this option requires a networking service backend capable of
217 handling those devices. PCI devices are also required to have a PCI
218 VPD capability with a card serial number (either on a VF itself on
219 its corresponding PF), otherwise they will be ignored and not
220 available for allocation.
222 - ``managed`` - Specify if the PCI device is managed by libvirt.
223 May have boolean-like string values case-insensitive values:
224 "yes" or "no". By default, "yes" is assumed for all devices.
226 - ``managed='yes'`` means that nova will use libvirt to detach the
227 device from the host before attaching it to the guest and re-attach
228 it to the host after the guest is deleted.
230 - ``managed='no'`` means that nova will not request libvirt to
231 detach / attach the device from / to the host. In this case nova
232 assumes that the operator configured the host in a way that these
233 VFs are not attached to the host.
235 Warning: Incorrect configuration of this parameter may result in compute
236 node crashes.
238 - ``live_migratable`` - Specify if the PCI device is live_migratable by
239 libvirt.
240 May have boolean-like string values case-insensitive values:
241 "yes" or "no". By default, "no" is assumed for all devices.
243 - ``live_migratable='yes'`` means that the device can be live migrated.
244 Of course, this requires hardware support, as well as proper system
245 and hypervisor configuration.
247 - ``live_migratable='no'`` means that the device cannot be live migrated.
249 - ``resource_class`` - optional Placement resource class name to be used
250 to track the matching PCI devices in Placement when
251 [pci]report_in_placement is True.
252 It can be a standard resource class from the
253 ``os-resource-classes`` lib. Or can be any string. In that case Nova will
254 normalize it to a proper Placement resource class by making it upper
255 case, replacing any consecutive character outside of ``[A-Z0-9_]`` with a
256 single '_', and prefixing the name with ``CUSTOM_`` if not yet prefixed.
257 The maximum allowed length is 255 character including the prefix.
258 If ``resource_class`` is not provided Nova will generate it from the PCI
259 device's ``vendor_id`` and ``product_id`` in the form of
260 ``CUSTOM_PCI_{vendor_id}_{product_id}``.
261 The ``resource_class`` can be requested from a ``[pci]alias``
263 - ``traits`` - optional comma separated list of Placement trait names to
264 report on the resource provider that will represent the matching PCI
265 device. Each trait can be a standard trait from ``os-traits`` lib or can
266 be any string. If it is not a standard trait then Nova will normalize the
267 trait name by making it upper case, replacing any consecutive character
268 outside of ``[A-Z0-9_]`` with a single '_', and prefixing the name with
269 ``CUSTOM_`` if not yet prefixed. The maximum allowed length of a trait
270 name is 255 character including the prefix.
271 Any trait from ``traits`` can be requested from a ``[pci]alias``.
274 Valid examples are::
276 device_spec = {"devname":"eth0",
277 "physical_network":"physnet"}
278 device_spec = {"address":"*:0a:00.*"}
279 device_spec = {"address":":0a:00.",
280 "physical_network":"physnet1"}
281 device_spec = {"vendor_id":"1137",
282 "product_id":"0071"}
283 device_spec = {"vendor_id":"1137",
284 "product_id":"0071",
285 "address": "0000:0a:00.1",
286 "physical_network":"physnet1"}
287 device_spec = {"address":{"domain": ".*",
288 "bus": "02", "slot": "01",
289 "function": "[2-7]"},
290 "physical_network":"physnet1"}
291 device_spec = {"address":{"domain": ".*",
292 "bus": "02", "slot": "0[1-2]",
293 "function": ".*"},
294 "physical_network":"physnet1"}
295 device_spec = {"devname": "eth0", "physical_network":"physnet1",
296 "trusted": "true"}
297 device_spec = {"vendor_id":"a2d6",
298 "product_id":"15b3",
299 "remote_managed": "true"}
300 device_spec = {"vendor_id":"a2d6",
301 "product_id":"15b3",
302 "address": "0000:82:00.0",
303 "physical_network":"physnet1",
304 "remote_managed": "true"}
305 device_spec = {"vendor_id":"1002",
306 "product_id":"6929",
307 "address": "0000:82:00.0",
308 "resource_class": "PGPU",
309 "traits": "HW_GPU_API_VULKAN,my-awesome-gpu"}
310 device_spec = {"vendor_id":"10de",
311 "product_id":"25b6",
312 "address": "0000:25:00.4",
313 "managed": "no"}
314 device_spec = {"vendor_id":"10de",
315 "product_id":"25b6",
316 "address": "0000:25:00.4",
317 "resource_class": "CUSTOM_A16_16A",
318 "managed": "no"}
320 The following are invalid, as they specify mutually exclusive options::
322 device_spec = {"devname":"eth0",
323 "physical_network":"physnet",
324 "address":"*:0a:00.*"}
326 The following example is invalid because it specifies the ``remote_managed``
327 tag for a PF - it will result in an error during config validation at the
328 Nova Compute service startup::
330 device_spec = {"address": "0000:82:00.0",
331 "product_id": "a2d6",
332 "vendor_id": "15b3",
333 "physical_network": null,
334 "remote_managed": "true"}
336* A JSON list of JSON dictionaries corresponding to the above format. For
337 example::
339 device_spec = [{"product_id":"0001", "vendor_id":"8086"},
340 {"product_id":"0002", "vendor_id":"8086"}]
341"""),
342 cfg.BoolOpt('report_in_placement',
343 default=False,
344 help="""
345Enable PCI resource inventory reporting to Placement. If it is enabled then the
346nova-compute service will report PCI resource inventories to Placement
347according to the [pci]device_spec configuration and the PCI devices reported
348by the hypervisor. Once it is enabled it cannot be disabled any more. In a
349future release the default of this config will be change to True.
351Related options:
353* [pci]device_spec: to define which PCI devices nova are allowed to track and
354 assign to guests.
355"""),
356]
359def register_opts(conf):
360 conf.register_group(pci_group)
361 conf.register_opts(pci_opts, group=pci_group)
364def list_opts():
365 return {pci_group: pci_opts}