Runtime Compatibility Policy

Compatibility Rule

CANN Runtime complies with the following compatibility principles.

Version Change Type	Compatibility Guarantee	Example
Patch version upgrade	Fully backward compatible	Bug fix and performance optimization
Minor version upgrade	API backward compatibility	New APIs and features
Major version upgrade	Compatibility not guaranteed	Removal of deprecated APIs, and architecture adjustment

Handling Policy for Deprecated APIs

Runtime uses the ACL_DEPRECATED_MESSAGE macro to mark deprecated APIs, which remain available during the deprecation period. If a replacement API exists, the system also displays the replacement API.

The deprecated APIs are marked as follows:

// Example of a deprecated API declaration.
ACL_DEPRECATED_MESSAGE("aclrtQueryEvent is deprecated, use aclrtQueryEventStatus instead")
ACL_FUNC_VISIBILITY aclError aclrtQueryEvent(aclrtEvent event, aclrtEventStatus *status);

The following warning information is generated during compilation:

warning: 'aclrtQueryEvent' is deprecated: aclrtQueryEvent is deprecated, use aclrtQueryEventStatus instead [-Wdeprecated-declarations]

The lifecycle of deprecated APIs is as follows.

Phase	Status	Recommendation
Deprecation notification	API available, with compilation warning	Start migrating to the replacement API.
Deprecation transition period	API available, with continuous warning	Complete migration.
Official removal	API unavailable	Use the replacement API.

Deprecation Handling Policy for Enumeration or Struct Members

Enumerated values and struct members may also be deprecated:

typedef enum aclrtLaunchKernelAttrId {
    ACL_RT_LAUNCH_KERNEL_ATTR_LOCAL_MEMORY_SIZE 
        ACL_DEPRECATED_MESSAGE("Use ACL_RT_LAUNCH_KERNEL_ATTR_DYN_UBUF_SIZE instead") = 2,
    ACL_RT_LAUNCH_KERNEL_ATTR_DYN_UBUF_SIZE = 2,  // Replacement value, the same as the original number.
    ...
} aclrtLaunchKernelAttrId;

typedef union aclrtLaunchKernelAttrValue {
    ACL_DEPRECATED_MESSAGE("Use dynUbufSize instead")
    uint32_t localMemorySize;  // Deprecated member.
    uint32_t dynUBufSize;      // Replacement member.
    ...
} aclrtLaunchKernelAttrValue;

Handling recommendations

Use the replacement enumerated value or member name.
Note that the replacement value may be equivalent to the deprecated value to ensure compatibility.

Parent topic: Compatibility Handling