Merge "Move to in-tree drivers for 6.x kernel"

doc/source/_includes/intel-driver-version-c6e3fa384ff7.rest

@@ -0,0 +1,2 @@
+.. intel-driver-version-begin
+.. intel-driver-version-end

doc/source/system_configuration/kubernetes/index-sysconf-kub-78f0e1e9ca5a.rst

@@ -120,6 +120,15 @@ Change Intel Multi-Driver Version
 
    intel-multi-driver-version-5e23e989daf5
 
+----------------------------
+Switch Intel Driver Versions
+----------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   intel-driver-version-c6e3fa384ff7
+
 ----------------------
 Application Management
 ----------------------

doc/source/system_configuration/kubernetes/intel-driver-version-c6e3fa384ff7.rst

@@ -0,0 +1,170 @@
+.. WARNING: Add no lines of text between the label immediately following
+.. and the title.
+
+.. _intel-driver-version-c6e3fa384ff7:
+
+============================
+Switch Intel Driver Versions
+============================
+
+.. contents:: |minitoc|
+   :local:
+   :depth: 2
+
+------------
+Introduction
+------------
+
+The system supports both in-tree and out-of-tree versions of the Intel ``ice``, ``i40e``,
+and ``iavf`` drivers. On initial installation, the system uses the default out-of-tree
+driver version. This sections describes how to switch between the in-tree and
+out-of-tree driver versions.
+
+.. warning::
+
+    The |NIC| firmware (NVM) has to align with one of the selected driver
+    listed below.
+
+-   Out-of-tree drivers (default)
+      - ice: 1.14.9.2 / Required NVM/firmware: 4.20 (Intel E810)
+      - i40e: 2.25.7 / Required NVM/firmware: 9.00
+      - iavf: 4.11.1
+
+-   In-tree drivers
+      - ice: Same as 6.6.7 kernel in-tree driver / Required NVM/firmware: 4.20
+      - i40e: Same as 6.6.7 kernel in-tree driver / Required NVM/firmware: 9.00
+      - iavf: Same as 6.6.7 kernel in-tree driver
+
+----------------------------------------------------------
+Switch between the In-tree and Out-of-tree Driver Versions
+----------------------------------------------------------
+
+The ``out_of_tree_drivers`` service parameter can be used to switch between the
+in-tree and out-of-tree versions of a given driver.
+
+Switch to In-tree Driver Versions
+---------------------------------
+
+The system can be switched to the in-tree versions of ``ice``, ``i40e``, and ``iavf``
+drivers using any of the following two mechanisms.
+
+-   Before installation, specify the ``out_of_tree_drivers`` service parameter
+    to none in the deployment config file.
+
+    .. code-block:: none
+
+        serviceParameters:
+                - service: platform
+                  section: kernel
+                  paramname: out_of_tree_drivers
+                  paramvalue: "none"
+
+-   After installation, modify the ``out_of_tree_drivers`` service parameter to
+    none and apply the configuration using the steps mentioned in :ref:`apply-driver-configuration-0342c0220631`.
+
+    .. code-block:: none
+
+        ~(keystone_admin)$ system service-parameter-modify platform kernel out_of_tree_drivers=none
+
+
+Switch to Out-of-tree Driver Versions
+-------------------------------------
+
+To use the out-of-tree drivers, set the out-of-tree drivers you want to load in
+the ``out_of_tree_drivers`` service parameter and apply the configuration using
+the steps mentioned in :ref:`apply-driver-configuration-0342c0220631`. You can set all
+the supported drivers, or only specific ones.
+
+-   Set all out-of-tree drivers:
+
+    .. code-block:: none
+
+        ~(keystone_admin)$ system service-parameter-modify platform kernel out_of_tree_drivers=ice,i40e,iavf
+
+-   Set specified out-of-tree drivers:
+
+    To set only ``ice`` and ``i40e``, but not ``iavf`` (in this case, the iavf is in the in-tree driver):
+
+    .. code-block:: none
+
+        ~(keystone_admin)$ system service-parameter-modify platform kernel out_of_tree_drivers=ice,i40e
+
+    To set ``iavf`` and ``ice``, but not ``i40e``:
+
+    .. code-block:: none
+
+        ~(keystone_admin)$ system service-parameter-modify platform kernel out_of_tree_drivers=ice,iavf
+
+    You can set any permutation or combination of ``ice``, ``i40e``, and ``iavf``
+    in the ``out_of_tree_drivers`` service parameter. Any driver not explicitly set
+    using the ``out_of_tree_drivers`` service parameter will use its in-tree version.
+
+.. _apply-driver-configuration-0342c0220631:
+
+Apply Driver Configuration
+--------------------------
+
+To apply the service parameter change, all the hosts need to be locked and unlocked.
+Use the following commands for each host depending on the deployed configuration:
+
+For |AIO-SX| deployments:
+
+.. code-block:: none
+
+    ~(keystone_admin)$ system host-lock controller-0
+    ~(keystone_admin)$ system host-unlock controller-0
+
+For |AIO-DX| and standards deployments, after ``controller-1`` is locked/unlocked,
+swact ``controller-0`` to make ``controller-1`` the active node. The next set of
+commands are executed on the ``controller-0`` node:
+
+.. code-block:: none
+
+    ~(keystone_admin)$ system host-lock controller-1
+    ~(keystone_admin)$ system host-unlock controller-1
+    ~(keystone_admin)$ system host-swact controller-0
+
+On ``controller-1``, after ``controller-0`` is locked/unlocked swact ``controller-1`` to go
+back to ``controller-0`` as the active node. The next set of commands are executed
+on the ``controller-1`` node:
+
+.. code-block:: none
+
+    ~(keystone_admin)$ system host-lock controller-0
+    ~(keystone_admin)$ system host-unlock controller-0
+    ~(keystone_admin)$ system host-swact controller-1
+
+All the remaining nodes in the deployment need to be locked/unlocked, one at a time.
+Use the following commands (replace ``worker-0`` with the name of the node being
+locked/unlocked):
+
+.. code-block:: none
+
+    ~(keystone_admin)$ system host-lock worker-0
+    ~(keystone_admin)$ system host-unlock worker-0
+
+.. note::
+
+    You must wait for the node to enter the locked state prior to unlocking.
+
+To verify the current Intel driver version use ``ethtool -i`` on the desired
+Intel network interface. For example:
+
+.. code-block:: none
+
+    ~(keystone_admin)$ ethtool -i ens785f0 | egrep '^(driver|version):'
+    driver: i40e
+    version: 6.6.40-stx.3
+
+
+Backup and Restore
+------------------
+
+If a backup and restore is performed, after unlocking the host during a restore
+operation, the system is configured to the driver version at the time of the backup.
+
+.. only:: partner
+
+    .. include:: /_includes/intel-driver-version-c6e3fa384ff7.rest
+        :start-after: intel-driver-version-begin
+        :end-before: intel-driver-version-end