DOCA Backward Compatibility Policy

The NVIDIA DOCA™ SDK enables developers to efficiently build applications and services on NVIDIA® BlueField® networking platforms.

DOCA follows a quarterly release cadence, delivering new features, performance enhancements, and critical bug fixes. The backward compatibility policy ensures that users can update to the latest DOCA software package—including libraries, drivers, and tools—without requiring modifications to their applications.

DOCA versions follow the Semantic Versioning scheme (i.e., X.Y.Z) where each component is updated based on the following criteria:

• Major version (X) – Introduces incompatible API changes

• Minor version (Y) – Adds functionality in a backward-compatible manner

• Patch version (Z) – Includes backward-compatible bug fixes

A key characteristic of an enterprise-grade SDK is backward compatibility, which allows application developers to upgrade SDK versions without breaking existing functionality. This preserves their investment by ensuring applications remain operational across updates.

DOCA SDK APIs progress through the following lifecycle stages:

• Experimental – APIs marked as DOCA_EXPERIMENTAL are not guaranteed to be available in future releases.

• Stable – APIs marked as DOCA_STABLE are supported throughout the lifecycle of the current major version.

• Deprecated – APIs marked as DOCA_DEPRECATED will be removed in a future release. If previously marked as DOCA_STABLE, removal will occur in a major release.

• Removed – APIs that were available in an older major version but are no longer supported. If previously DOCA_STABLE, the binary representation remains intact to maintain binary backward compatibility.

DOCA SDK APIs may go through the following lifecycle stages:

1. Experimental – an API marked as DOCA_EXPERIMENTAL is an experimental API and is not guaranteed to be present across upcoming releases

2. Stable – an API marked as DOCA_STABLE is guaranteed to be supported throughout the lifecycle of the current major version

3. Deprecated – an API marked as DOCA_DEPRECATED will be removed from DOCA SDKs header files in an upcoming release. If the API was previously marked as DOCA_STABLE, it will only be removed in an upcoming major release.

4. Removed – an API that was present 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 sections describe the types of backward compatibility and how they align with semantic versioning.

Source Compatibility

Source compatibility ensures that a program written and compiled using a given DOCA SDK version continues to compile successfully with a newer DOCA SDK version.

As outlined in section "DOCA SDK Versioning", DOCA SDK maintains source compatibility across minor and patch versions. However, major version updates may introduce API changes, deprecations, or removals (refer to "DOCA SDK API Backward Compatibility" for details on API lifecycle stages). As a result, an application that compiles successfully with an older major version may require modifications to compile against a newer major version.

Binary Compatibility

Binary compatibility ensures that a program dynamically linked to a given DOCA SDK library (*.so) can successfully link against a newer version of the same library.

DOCA SDK provides a versioned C-style application binary interface (ABI) that maintains binary compatibility across both minor and major versions. This guarantees that upgrading the installed DOCA SDK version does not break existing applications.

Behavioral Compatibility

Behavioral (or semantic) compatibility ensures that a function or component produces the same output given the same input. Applications developed, compiled, linked, and tested with a given DOCA SDK version will function correctly with newer DOCA SDK versions, as long as they rely on defined behaviors. Bug fixes are the only exceptions.

The compile-time struct dispatching (CTSD) mechanism enables backward compatibility for non-opaque structs in DOCA libraries.

CTSD allows developers to write applications using generic API and struct definitions, which the compiler replaces with version-specific implementations at compile time. This approach maintains type safety and runtime compatibility.

The mechanism employs a macro-based scheme to map version-agnostic names to version-specific implementations, ensuring type safety and compile-time verification.

For example, when a user writes code using doca_flow_func(), the compiler resolves it to the appropriate version-specific implementation (e.g., internal_doca_flow_func_v2_4()) based on the selected library version.

Library Version Management

Each DOCA library exposes non-opaque structs maintains its own version history, independent of the main DOCA SDK version. These versions are declared in the library's header file (e.g., doca_flow.h).

For instance, a library may define version constants such as:

            

            
#define LIB_FLOW_VERSION_2_4
#define LIB_FLOW_VERSION_2_5
        

User Responsibility

To use CTSD, users must specify the desired library version by setting a preprocessor definition. For example:

            

            
#define LIB_FLOW_VERSION LIB_FLOW_VERSION_2_4
        

By default, libraries use the latest available version.

For specific version changelogs and documentation, refer to the corresponding library's documentation.

Some DOCA SDK components facilitate communication between remote entities, such as:

• Host-to-BlueField

• BlueField-to-BlueField

• Host-to-host

Applications utilizing DOCA may be deployed in large clusters and upgraded at different times. To support seamless upgrades, DOCA SDK maintains protocol compatibility between different SDK versions, allowing for rolling upgrades without disrupting operations. Nodes running different DOCA SDK versions can continue communicating throughout the transition.

DOCA is distributed as a meta-package, available in the following formats:

• *.bfb – For installation on the BlueField networking platform’s Arm processor

• *.rpm/*.deb – For installation on the host server

Each package includes libraries, tools, executables, firmware, and sample applications.

DOCA SDK is tested as a complete package, ensuring that all components work together. There is no guarantee that upgrading individual components separately will maintain functionality. Therefore, updating to a newer DOCA version requires updating the entire meta-package.