DOCA Backward Compatibility Policy
The NVIDIA DOCA™ SDK enables developers to rapidly create applications and services on top of NVIDIA® BlueField® networking platforms.
The DOCA software package is released on a quarterly release cadence to deliver new features, performance improvements, and critical bug fixes. DOCA compatibility allows users to update the latest DOCA software package (including all libraries, drivers, and tools) without requiring updating the application.
DOCA versions follow the Semantic Versioning scheme. That is, the DOCA version is of the form X.Y.Z, and each part is incremented when the following applies:
Major version – when incompatible API changes may be introduced
Minor version – when functionality is added in a backwards compatible manner
Patch version – when backwards compatible bug fixes are submitted
One of the key attributes of enterprise grade SDK is backward compatibility. Backward compatible APIs allows application developers using the SDK to monetize on their investment, by guaranteeing that their application will continue to operate successfully as they update to a newer SDK version.
DOCA SDK APIs may go through the following lifecycle stages:
Experimental – an API marked as DOCA_EXPERIMENTAL is an experimental API and is not guaranteed to be present across upcoming releases
Stable – an API marked as DOCA_STABLE is guaranteed to be supported throughout the lifecycle of the current major version
Deprecated – an API marked as DOCA_DEPRECATED will be removed from DOCA SDKs header files in an upcoming major release
Removed – an API marked as DOCA_STABLE or DOCA_DEPRECATED on an older major version and is now no longer supported. If this API was previously marked as DOCA_STABLE, the binary representation is preserved to maintain binary backwards compatibility.
The following subsections explain the different backwards compatibility types including how semantic versions are mapped to these different types.
Source Compatibility
Source compatibility guarantees that a program written and compiled using a given DOCA SDK version compiles successfully against a newer DOCA SDK version.
As described in section "DOCA SDK Versioning", DOCA SDK is source compatible across minor and patch versions. However, across major version, APIs can be changed, deprecated, or removed (see the lifecycle stages under section "DOCA SDK API Backwards Compatibility"). Therefore, an application that compiles successfully on an older major DOCA SDK version of the toolkit may require changes to compile against a newer major version.
Binary Compatibility
Binary compatibility guarantees that a program dynamically linked against a given DOCA SDK library (*.so) successfully links against a newer DOCA SDK library.
DOCA SDK API has a versioned C-style application binary interface (ABI) which guarantees binary compatibility across both minor and major versions. This means that upgrading the DOCA SDK package installed on a system to a newer version always supports existing applications and their functions.
Behavioral Compatibility
Behavioral compatibility (i.e., semantic compatibility) guarantees that given the same inputs, a function or component will produce the same outputs. Thus, an application developed, compiled, linked, and tested with a given DOCA SDK and relying on the SDK’s behavior, can successfully run with newer version of DOCA SDK, as the behavior will be compatible (apart from fixing bugs).
Some DOCA SDK components include interaction across remote entities (host-to-BlueField, BlueField-to-BlueField, or host-to-host). That is, communication channel between a process running on the host server and a process running on the BlueField networking platform Arm processors. Since applications using DOCA may be deployed in large clusters and upgraded on a different schedule, DOCA SDK guarantees maintaining different DOCA SDK versions protocol-compatible with each other. This allows the flexibility to perform a rolling upgrade to DOCA SDK applications while maintaining operations throughout the process (nodes with different SDK versions maintain communication).
DOCA is distributed in a meta-package format, either as a *.bfb file for installation on the BlueField networking platform Arm processor, or as a DOCA-for-host package (*.rpm or *.deb) for installation on the server hosting the BlueField networking platform. This package includes different libraries, tools, executables, firmware, and sample applications.
DOCA SDK is developed and tested to work with all components included in the meta-package. There is no guarantee that DOCA SDK would work correctly if any of these components is upgraded independently. Thus, updating DOCA to a newer version requires updating the meta-package with all its components.