ICE Wireless Edge Dynamic Device Personalization (DDP) Package
**************************************************************

August 29, 2024


Contents
^^^^^^^^

* ICE Wireless Edge Dynamic Device Personalization (DDP) Package

  * Overview

  * Supported Operating Systems

  * Contents of This Package

  * Related Documentation

  * Notes

  * Installation

  * Troubleshooting

  * Legal / Disclaimers


Overview
========

Devices based on the Intel(R) Ethernet 800 Series require a Dynamic
Device Personalization (DDP) package file to enable advanced features
(such as dynamic tunneling, Intel(R) Ethernet Flow Director, RSS, and
ADQ).

DDP allows you to change the packet processing pipeline of a device by
applying a profile package to the device at runtime. Profiles can be
used to, for example, add support for new protocols, change existing
protocols, or change default settings. DDP profiles can also be rolled
back without rebooting the system.

The DDP package loads during device initialization or driver runtime,
depending on the operating system. The driver checks to see if the DDP
package is present and compatible. If this file exists, the driver
will load it into the device. If the DDP package file is missing or
incompatible with the driver, the driver will go into Safe Mode where
it will use the configuration contained in the device's NVM.

Safe Mode disables advanced and performance features, and supports
only basic traffic and minimal functionality, such as updating the NVM
or downloading a new driver or DDP package.

Refer to the Intel(R) Ethernet Adapters and Devices User Guide for
more details on DDP and Safe Mode.

A general-purpose, default DDP package is automatically installed with
all supported Intel Ethernet 800 Series drivers on supported operating
systems. Additional DDP packages are available to address needs for
specific market segments or targeted solutions.

The default DDP package supports the following:

* MAC

* EtherType

* VLAN

* IPv4

* IPv6

* TCP

* ARP

* UDP

* SCTP

* ICMP

* ICMPv6

* CTRL

* LLDP

* VXLAN-GPE

* VXLAN (non-GPE)

* Geneve

* GRE

* NVGRE

* RoCEv2

* MPLS (up to 5 consecutive MPLS labels in the outermost Layer 2
  header group)

In addition to the previous list, the ICE Wireless Edge DDP package
also supports the following:

* GTPv1 and GTPv2 with extension headers

* ESP

* IPSec

* eCPRI


Supported Operating Systems
===========================

This DDP package is supported on the following operating systems:

* Linux*

Refer to the Intel(R) Ethernet Adapters and Devices User Guide for
currently supported versions of these operating systems.


Contents of This Package
========================

The zip file for this DDP package (ice_wireless_edge-x.x.x.x.zip)
contains the following:

* This readme

* Licensing information

* Two package files:

  * ice_wireless_edge-x.x.x.x.pkg - where <x.x.x.x> is the version of
    the package file

  * ice.pkg - A Linux symbolic link file pointing to
    ice_wireless_edge-x.x.x.x.pkg (in the same path)


Related Documentation
=====================

See the "Intel(R) Ethernet Adapters and Devices User Guide" for
additional information on features:

* https://cdrdv2.intel.com/v1/dl/getContent/705831/

Additionally, a detailed technology guide is available for this DDP
package:

* https://cdrdv2.intel.com/v1/dl/getContent/785730


Notes
=====

* In Linux, you cannot update the DDP package if any PF drivers are
  already loaded. To overwrite a package, unload all PFs and then
  reload the driver with the new package.

* In Linux, only the first loaded PF per device can download a package
  for that device.

* If you are using DPDK, see the DPDK documentation at
  https://www.dpdk.org/ for installation instructions and more
  information.


Installation
============


Linux
-----


TO INSTALL THE OS DEFAULT DDP PACKAGE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Linux driver automatically installs the default DDP package file
during driver installation. Read the base driver README for general
installation and building instructions.

The DDP package loads during device initialization. The driver looks
for intel/ice/ddp/ice.pkg in your firmware root (typically
/lib/firmware/ or /lib/firmware/updates/) and checks that it contains
a valid DDP package file. The ice.pkg file is a symbolic link to the
default DDP package file installed by the linux-firmware software
package or the out-of-tree driver installation.


TO INSTALL A DDP PACKAGE FOR SPECIFIC MARKET SEGMENTS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can install specific DDP package files for different physical
devices in the same system. To install a specific DDP package:

1. Download the DDP package file you want for your device
   (ice_wireless_edge-x.x.x.x.zip).

2. Copy the file ice_wireless_edge-x.x.x.x.pkg to
   /lib/firmware/updates/intel/ice/ddp/. If the directory does not yet
   exist, create it before copying the file.

3. Unload all of the PFs on the device.

4. Create a symbolic link to the DDP package as follows:

      ln -s /lib/firmware/updates/intel/ice/ddp/ice_wireless_edge-x.x.x.x.pkg /lib/firmware/updates/intel/ice/ddp/ice.pkg

5. To update the initramfs file system and force the new package to
   load, run the following:

      dracut --force

6. Reload the driver with the new package.


TO INSTALL A SPECIFIC DDP PACKAGE ON A DEVICE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can also install a specific DDP package file for a physical device
in the system while other devices utilize OS-default DDP package.

1. Download the DDP package file you want for your device
   (ice_wireless_edge-x.x.x.x.zip).

2. Rename the ice.pkg file as ice-xxxxxxxxxxxxxxxx.pkg, where
   "xxxxxxxxxxxxxxxx" is the unique 64-bit PCI Express device serial
   number (in hex) of the device you want the package downloaded on.
   The file name must include the complete serial number (including
   leading zeros) and be all lowercase. For example, if the 64-bit
   serial number is b887a3ffffca0568, then the file name would be ice-
   b887a3ffffca0568.pkg.

   To find the serial number from the PCI bus address, you can use the
   following command:

      lspci -vv -s af:00.0 | grep -i Serial
      Capabilities: [150 v1] Device Serial Number b8-87-a3-ff-ff-ca-05-68

   You can use the following command to format the serial number
   without the dashes:

      lspci -vv -s af:00.0 | grep -i Serial | awk '{print $7}' | sed s/-//g b887a3ffffca0568

3. Copy the renamed DDP package file ice-xxxxxxxxxxxxxxxx.pkg and
   ice_wireless_edge-x.x.x.x.pkg to
   /lib/firmware/updates/intel/ice/ddp/. If the directory does not yet
   exist, create it before copying the file.

4. Unload all of the PFs on the device.

5. Create a symbolic link with the serial number linking to the DDP
   package as follows, where "xxxxxxxxxxxxxxxx" is the lowercase
   serial number:

      ln -s /lib/firmware/updates/intel/ice/ddp/ice_wireless_edge-x.x.x.x.pkg /lib/firmware/updates/intel/ice/ddp/ice-xxxxxxxxxxxxxxxx.pkg

6. Do the following to update the dracut configuration and the
   initramfs file system:

   1. Change to the "dracut.conf.d" directory:

         cd /etc/dracut.conf.d

   2. Update the dracut configuration:

         vi ice.conf
         install_items+=" /lib/firmware/updates/intel/ice/ddp/* "

   3. Run the following to force the new package to load on a specific
      physical device:

         dracut --force

7. Reload the driver with the new package.

Note:

  The presence of a device-specific DDP package file overrides the
  loading of the default DDP package file.


Troubleshooting
===============


Linux
-----

If you encounter issues with the DDP package file, you may need to
download an updated driver or DDP package file. Refer to the log
messages for more information.


Legal / Disclaimers
===================

Copyright (c) 2020 - 2024, Intel Corporation.

Intel technologies may require enabled hardware, software or service
activation.

No product or component can be absolutely secure.

Your costs and results may vary.

Intel, the Intel logo, and other Intel marks are trademarks of Intel
Corporation or its subsidiaries.  Other names and brands may be
claimed as the property of others.

Performance varies by use, configuration, and other factors. Learn
more at https://www.Intel.com/PerformanceIndex.

The products described may contain design defects or errors known as
errata which may cause the product to deviate from published
specifications. Current characterized errata are available on request.

This software and the related documents are Intel copyrighted
materials, and your use of them is governed by the express license
under which they were provided to you ("License"). Unless the License
provides otherwise, you may not use, modify, copy, publish,
distribute, disclose or transmit this software or the related
documents without Intel's prior written permission.

This software and the related documents are provided as is, with no
express or implied warranties, other than those that are expressly
stated in the License.
