Hipersocket changes (#2036)

Details:

* Changed the name of the Partition Link created in
  AdapterManager.create_hipersocket() by using the name of the Hipersocket
  adapter unchanged, without the previously used "HS" prefix.

* Added an example script "hipersocket_lifecycle.py" for creating and deleting
  Hipersocket adapters.

* Updated the descriptions of AdapterManager.create_hipersocket() and
  Adapter.delete() to better describe the dependency on the
  API feature.

* Updated the description of the Nic.create() method to describe the
  limitation of not supporting SSC management NICs backed by
  Hipersocket adapters on z16 CPCs, and how to lift this limitation.

* Added a design file "hipersocket-changes-z16.md" that summarizes the
  changes related to Hipersocket operations since z16.

Signed-off-by: Andreas Maier <[email protected]>

Author: andy-maier

changes/noissue.89.1.feature.rst

@@ -0,0 +1,3 @@
+Changed the name of the Partition Link created in
+:meth:`zhmcclient.AdapterManager.create_hipersocket`, by using the name of the
+Hipersocket adapter unchanged, without the previously used "HS" prefix.

changes/noissue.89.2.feature.rst

@@ -0,0 +1,2 @@
+Added an example script hipersocket_lifecycle.py for creating and deleting
+Hipersocket adapters.

changes/noissue.89.3.feature.rst

@@ -0,0 +1,8 @@
+Docs: Updated the descriptions of the :meth:`zhmcclient.NicManager.create`,
+:meth:`zhmcclient.Partition.attach_network_link`,
+:meth:`zhmcclient.PartitionLinkManager.create` and
+:meth:`zhmcclient.PartitionLink.update_properties` methods
+to describe the limitation of not supporting SSC management NICs backed by
+Hipersocket adapters on z16 CPCs that have the API feature
+"dpm-hipersockets-partition-link-management" enabled, and how to lift this
+limitation.

design/hipersocket-changes-z16.md

@@ -0,0 +1,60 @@
+# Hipersocket changes since z16
+
+This summarizes the changes to Hipersocket related operations at the HMC WS-API
+since z16.
+
+These changes apply to the indicated CPC version, regardless of the HMC version
+(as long as the HMC version is supported for the CPC, of course).
+
+## Changes in z16 CPCs (GA 1.0)
+
+* Support for Partition Links for SMC-D was added.
+  - indicated by firmware feature "dpm-smcd-partition-link-management"
+
+* Virtual Switches are still supported.
+
+* No changes to Hipersocket related operations:
+  - Hipersocket adapters can be created only by "Create Hipersocket".
+  - Hipersocket-backed NICs can be created only by "Create NIC" with backing
+    vswitch.
+  - Creating an SSC management NIC backed by Hipersockets is supported.
+
+## Changes in z16 CPCs (GA 1.5)
+
+* Support for Partition Links was extended to add Hipersocket (and CTC) support.
+  - indicated by API feature "dpm-hipersockets-partition-link-management".
+
+* Virtual Switches are still supported.
+
+* Hipersocket adapters now can be created in two ways:
+  - "Create Hipersocket", as before.
+  - "Create Partition Link" with type hipersocket.
+
+* Hipersocket-backed NICs now can be created in two ways:
+  - "Create NIC", with backing vswitch, as before.
+  - "Modify Partition Link" with "added-connections".
+
+* Creating an SSC management NIC backed by Hipersockets is not supported, unless
+  the "dpm-hipersockets-partition-link-management" API feature gets disabled.
+  That can be achieved by installing the firmware feature "DPM IQD Links - Disable",
+  which can be requested by customers from IBM support.
+
+## Changes in z17 CPCs (GA 1.0)
+
+* "Create Hipersocket" is no longer supported.
+  - indicated by API feature "network-express-support".
+
+* Virtual Switches are no longer supported.
+  - indicated by API feature "network-express-support".
+
+* Hipersocket adapters now can be created only by:
+  - "Create Partition Link" with type hipersocket.
+
+* Hipersocket-backed NICs can still be created in two ways:
+  - "Create NIC", but now with backing adapter port.
+    - The requirement to use the backing port is indicated by API feature
+      "network-express-support".
+  - "Modify Partition Link" with "added-connections".
+
+* Creating an SSC management NIC backed by Hipersockets is supported again,
+  using any of the two ways to create NICs.

examples/hipersocket_lifecycle.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python
+# Copyright 2025 IBM Corp. All Rights Reserved.
+#
+# 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.
+
+"""
+Example that creates and deletes a Hipersocket adapter in a CPC in DPM mode.
+"""
+
+import sys
+import uuid
+import urllib3
+
+import zhmcclient
+from zhmcclient.testutils import hmc_definitions, setup_hmc_session
+
+
+def main():
+    "Main function of the script"
+
+    urllib3.disable_warnings()
+
+    print(__doc__)
+
+    # Get HMC info from HMC inventory and vault files
+    hmc_def = hmc_definitions()[0]
+    host = hmc_def.host
+    print(f"Creating a session with the HMC at {host} ...")
+    try:
+        session = setup_hmc_session(hmc_def)
+    except zhmcclient.Error as exc:
+        print(f"Error: Cannot establish session with HMC {host}: "
+              f"{exc.__class__.__name__}: {exc}")
+        return 1
+
+    try:
+        client = zhmcclient.Client(session)
+
+        print("Determining the CPC to use ...")
+        cpc_name = None
+        for name, props in hmc_def.cpcs.items():
+            if props.get("dpm_enabled", False) is True:
+                cpc_name = name
+                break
+        if cpc_name:
+            print(f"Finding CPC {cpc_name} specified in HMC inventory ...")
+            try:
+                cpc = client.cpcs.find_by_name(cpc_name)
+            except zhmcclient.Error as exc:
+                print(f"Error: Cannot find CPC {cpc_name}: "
+                      f"{exc.__class__.__name__}: {exc}")
+                return 1
+        else:
+            print("Finding any CPC in DPM mode ...")
+            cpcs = client.cpcs.list(filter_args={'dpm-enabled': True})
+            if not cpcs:
+                print(f"Error: HMC at {host} does not manage any CPCs in DPM "
+                      "mode")
+                return 1
+            cpc = cpcs[0]
+        print(f"Using CPC {cpc.name}")
+
+        ad_name = f"zhmc_test_{uuid.uuid4()}"
+        print(f"Creating Hipersocket adapter {ad_name} ...")
+        ad_props = {
+            'name': ad_name,
+            'description': 'Original adapter description.',
+        }
+        try:
+            ad = cpc.adapters.create_hipersocket(properties=ad_props)
+        except zhmcclient.Error as exc:
+            print(f"Error: Cannot create Hipersocket adapter {ad_name} on CPC "
+                  f"{cpc.name}: {exc.__class__.__name__}: {exc}")
+            return 1
+
+        print(f"Deleting Hipersocket adapter {ad_name} ...")
+        try:
+            ad.delete()
+        except zhmcclient.Error as exc:
+            print(f"Error: Cannot delete Hipersocket adapter {ad_name} on CPC "
+                  f"{cpc.name}: {exc.__class__.__name__}: {exc}")
+            return 1
+
+        return 0
+
+    finally:
+        print("Logging off ...")
+        session.logoff()
+
+
+if __name__ == '__main__':
+    sys.exit(main())

zhmcclient/_adapter.py

@@ -193,10 +193,10 @@ def create_hipersocket(self, properties):
         Create and configure a HiperSockets Adapter in this CPC.
 
         z17 CPCs removed the "Create Hipersocket" operation. This method uses
-        the "Create Hipersocket" operation z15 and earlier CPCs, and the
-        "Create Partition Link" operation on z16 and later CPCs. The distinction
-        is made based on the "dpm-hipersockets-partition-link-management"
-        API feature on the CPC.
+        the "Create Partition Link" operation when the API feature
+        "dpm-hipersockets-partition-link-management" is enabled, and otherwise
+        the earlier "Create Hipersocket" operation. As a result, this method
+        supports all generations of CPCs.
 
         HMC/SE version requirements:
 
@@ -206,17 +206,18 @@ def create_hipersocket(self, properties):
         Authorization requirements:
 
         * Object-access permission to the scoping CPC.
-        * On CPCs of z15 and earlier: Task permission to the
-          "Create HiperSockets Adapter" task.
-        * On CPCs of z16 and later: Task permission to the
-          "Create Partition Link" task.
+        * When the "dpm-hipersockets-partition-link-management" API feature is
+          enabled, task permission to the "Create Partition Link" task;
+          otherwise task permission to the "Create HiperSockets Adapter" task.
 
         Parameters:
 
           properties (dict): Initial property values.
             Allowable properties are the following:
 
-            * "name" (str): Required: The adapter's 'name' property.
+            * "name" (str): Required: The adapter's 'name' property. When
+              the Hipersocket adapter is created via a Partition Link, this
+              also becomes the name of the Partition Link.
 
             * "description" (str): Optional: The adapter's 'description'
               property. Default: An empty string.
@@ -230,7 +231,8 @@ def create_hipersocket(self, properties):
 
             These properties are defined in section 'Request body contents'
             in section 'Create Hipersocket' in the :term:`HMC API` book, but
-            they are valid for both approaches.
+            they are valid also when the Hipersocket adapter is created via
+            a Partition Link.
 
         Returns:
 
@@ -252,13 +254,8 @@ def create_hipersocket(self, properties):
         if pl_feature:
             name = properties['name']
             console = cpc.manager.console
-            pl_name = f"Hipersocket {name}"
-            if len(pl_name) > 64:
-                pl_name = f"HS {name}"
-                if len(pl_name) > 64:
-                    pl_name = pl_name[0:64]
             part_link = console.partition_links.create({
-                "name": f"HS {properties['name']}",
+                "name": name,
                 "type": "hipersockets",
                 "cpc-uri": cpc.uri,
             })
@@ -472,16 +469,16 @@ def maximum_crypto_domains(self):
     @logged_api_call
     def delete(self):
         """
-        Delete this Adapter.
+        Delete this Hipersocket Adapter.
 
         The Adapter must be a HiperSockets Adapter and must not currently be
         the backing adapter of any partition NICs.
 
         z17 CPCs removed the "Delete Hipersocket" operation. This method uses
-        the "Delete Hipersocket" operation z15 and earlier CPCs, and the
-        "Delete Partition Link" operation on z16 and later CPCs. The distinction
-        is made based on the "dpm-hipersockets-partition-link-management"
-        API feature on the CPC.
+        the "Delete Partition Link" operation when the API feature
+        "dpm-hipersockets-partition-link-management" is enabled, and otherwise
+        the earlier "Delete Hipersocket" operation. As a result, this method
+        supports all generations of CPCs.
 
         HMC/SE version requirements:
 
@@ -491,10 +488,9 @@ def delete(self):
         Authorization requirements:
 
         * Object-access permission to the HiperSockets Adapter to be deleted.
-        * On CPCs of z15 and earlier: Task permission to the
-          "Delete HiperSockets Adapter" task.
-        * On CPCs of z16 and later: Task permission to the
-          "Delete Partition Link" task.
+        * When the "dpm-hipersockets-partition-link-management" API feature is
+          enabled, task permission to the "Delete Partition Link" task;
+          otherwise task permission to the "Delete HiperSockets Adapter" task.
 
         Raises:
 

zhmcclient/_nic.py

@@ -213,6 +213,14 @@ def create(self, properties):
 
               properties['virtual-switch-uri'] = vswitch.uri
 
+        Limitations:
+
+          * When the API feature "dpm-hipersockets-partition-link-management"
+            is enabled on a z16 CPC (and only there), SSC management NICs
+            cannot be backed by Hipersocket adapters. This limitation can be
+            lifted by installing the firmware feature "DPM IQD Links - Disable",
+            which can be requested by customers from IBM support.
+
         HMC/SE version requirements:
 
         * SE version 2.13.1

zhmcclient/_partition.py

@@ -1680,6 +1680,20 @@ def attach_network_link(
 
         By default, this method waits for completion of its asynchronous job.
 
+        SSC management NICs backed by a Hipersocket adapter can be created
+        by first attaching a Hipersocket-typed Partition Link to this
+        partition, and then updating the created NIC with the
+        :meth:`zhmcclient.Nic.update_properties` method to become an SSC
+        management NIC.
+
+        Limitations:
+
+          * When the API feature "dpm-hipersockets-partition-link-management"
+            is enabled on a z16 CPC (and only there), SSC management NICs
+            cannot be backed by Hipersocket adapters. This limitation can be
+            lifted by installing the firmware feature "DPM IQD Links - Disable",
+            which can be requested by customers from IBM support.
+
         HMC/SE version requirements:
 
         * SE version >= 2.16.0

zhmcclient/_partition_link.py

@@ -245,6 +245,21 @@ def create(self, properties=None):
         This method performs the "Create Partition Link" HMC operation and
         waits for completion of its asynchronous job.
 
+        SSC management NICs backed by a Hipersocket adapter can be created
+        by first creating a Partition Link using this method with a
+        "bus-connections" property that specifies partitions to be linked, and
+        then updating the created NIC(s) with the
+        :meth:`zhmcclient.Nic.update_properties` method to become an SSC
+        management NIC.
+
+        Limitations:
+
+          * When the API feature "dpm-hipersockets-partition-link-management"
+            is enabled on a z16 CPC (and only there), SSC management NICs
+            cannot be backed by Hipersocket adapters. This limitation can be
+            lifted by installing the firmware feature "DPM IQD Links - Disable",
+            which can be requested by customers from IBM support.
+
         HMC/SE version requirements:
 
         * SE version >= 2.16.0
@@ -617,6 +632,20 @@ def update_properties(self, properties):
         This method performs the "Modify Partition Link" HMC operation and
         waits for completion of its asynchronous job.
 
+        SSC management NICs backed by a Hipersocket adapter can be created
+        by first attaching this partition link to a partition using the
+        "added-connections" property, and then updating the created NIC(s) with
+        the :meth:`zhmcclient.Nic.update_properties` method to become an SSC
+        management NIC.
+
+        Limitations:
+
+          * When the API feature "dpm-hipersockets-partition-link-management"
+            is enabled on a z16 CPC (and only there), SSC management NICs
+            cannot be backed by Hipersocket adapters. This limitation can be
+            lifted by installing the firmware feature "DPM IQD Links - Disable",
+            which can be requested by customers from IBM support.
+
         HMC/SE version requirements:
 
         * SE version >= 2.16.0