port-hints: api definition

The port hints extension (``port-hints``) introduces the ``hints``
port attribute. Hints are backend specific pieces of information,
mainly to allow backend specific performance tuning. In itself this
extension defines no particular hint, and therefore no valid values of
the ``hints`` attribute. It just serves as the base for other extensions
introducing concrete hints and signals the presence of the ``hints``
port attribute to the API user. By default policy, use of the ``hints``
attribute is restricted to admininstrative users.

Change-Id: I5cb21b25fcda62eae3743b2f96177dcc1fda4afb
Partially-Implements: #1990842
Related-Change (spec): https://review.opendev.org/c/openstack/neutron-specs/+/862133

api-ref/source/v2/ports.inc

@@ -110,6 +110,18 @@ The extension defines several attributes whose names have a prefix
 ``binding:`` including ``binding:host_id``, ``binding:vnic_type``,
 ``binding:vif_type``, ``binding:vif_details``, and ``binding:profile``.
 
+Port hints
+==========
+
+The port hints extension (``port-hints``) introduces the ``hints``
+port attribute. Hints are backend specific pieces of information,
+mainly to allow backend specific performance tuning. In itself this
+extension defines no particular hint, and therefore no valid values of
+the ``hints`` attribute. It just serves as the base for other extensions
+introducing concrete hints and signals the presence of the ``hints``
+port attribute to the API user. By default policy, use of the ``hints``
+attribute is restricted to admininstrative users.
+
 Port resource request
 =====================
 

neutron_lib/api/definitions/__init__.py

@@ -83,6 +83,7 @@ from neutron_lib.api.definitions import network_segment_range
 from neutron_lib.api.definitions import pagination
 from neutron_lib.api.definitions import port
 from neutron_lib.api.definitions import port_device_profile
+from neutron_lib.api.definitions import port_hints
 from neutron_lib.api.definitions import port_mac_address_override
 from neutron_lib.api.definitions import port_mac_address_regenerate
 from neutron_lib.api.definitions import port_numa_affinity_policy
@@ -225,6 +226,7 @@ _ALL_API_DEFINITIONS = {
     pagination,
     port,
     port_device_profile,
+    port_hints,
     port_mac_address_override,
     port_mac_address_regenerate,
     port_numa_affinity_policy,

neutron_lib/api/definitions/port_hints.py

@@ -0,0 +1,45 @@
+# Copyright (c) 2023 Ericsson Software Technology
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from neutron_lib.api.definitions import port
+
+
+ALIAS = 'port-hints'
+IS_SHIM_EXTENSION = False
+IS_STANDARD_ATTR_EXTENSION = False
+NAME = 'Port hints'
+DESCRIPTION = 'Backend specific port hints to allow backend specific tuning'
+UPDATED_TIMESTAMP = '2023-01-01T00:00:00-00:00'
+RESOURCE_NAME = port.RESOURCE_NAME
+COLLECTION_NAME = port.COLLECTION_NAME
+HINTS = 'hints'
+
+RESOURCE_ATTRIBUTE_MAP = {
+    COLLECTION_NAME: {
+        HINTS: {
+            'allow_post': True,
+            'allow_put': True,
+            'default': None,
+            'enforce_policy': True,
+            'is_visible': True,
+            'validate': {'type:dict_or_none': None},
+        },
+    },
+}
+
+SUB_RESOURCE_ATTRIBUTE_MAP = None
+ACTION_MAP = {}
+ACTION_STATUS = {}
+REQUIRED_EXTENSIONS = []
+OPTIONAL_EXTENSIONS = []

neutron_lib/tests/unit/api/definitions/test_port_hints.py

@@ -0,0 +1,22 @@
+# Copyright 2023 Ericsson Software Technology
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from neutron_lib.api.definitions import port_hints
+from neutron_lib.tests.unit.api.definitions import base
+
+
+class PortHintsDefinitionTestCase(base.DefinitionBaseTestCase):
+    extension_module = port_hints
+    extension_resources = (port_hints.COLLECTION_NAME,)
+    extension_attributes = (port_hints.HINTS,)

releasenotes/notes/port-hints-8273fa5b7454a8ef.yaml

@@ -0,0 +1,11 @@
+---
+features:
+  - |
+    The port hints extension (``port-hints``) introduces the ``hints``
+    port attribute. Hints are backend specific pieces of information,
+    mainly to allow backend specific performance tuning. In itself this
+    extension defines no particular hint, and therefore no valid values
+    of the ``hints`` attribute. It just serves as the base for other
+    extensions introducing concrete hints and signals the presence of
+    the ``hints`` port attribute to the API user. By default policy,
+    use of the ``hints`` attribute is restricted to admininstrative users.