Deprecation

ABI and API Deprecation

This document details the policy for maintaining stability of SPDK ABI and API.

Major ABI version can change at most once for each SPDK release. ABI versions are managed separately for each library and follow Semantic Versioning.

API and ABI deprecation notices shall be posted in the next section. Each entry must describe what will be removed and can suggest the future use or alternative. Specific future SPDK release for the removal must be provided. ABI cannot be removed without providing deprecation notice for at least single SPDK release.

Deprecated code paths must be registered with SPDK_LOG_DEPRECATION_REGISTER() and logged with SPDK_LOG_DEPRECATED(). The tag used with these macros will appear in the SPDK log at the warn level when SPDK_LOG_DEPRECATED() is called, subject to rate limits. The tags can be matched with the level 4 headers below.

Deprecation Notices

bdev

bdev_get_memory_domains

spdk_bdev_get_memory_domains and the get_memory_domains fn_table entry are deprecated. Use spdk_bdev_get_memory_domain_types and get_memory_domain_types instead. Will be removed in the v27.01 release.

fsdev

The current fsdev layer and its consumers are deprecated in preparation for replacing with a new implementation in the v27.01 release.

fsdev

The fsdev library, including the public APIs in include/spdk/fsdev.h and include/spdk/fsdev_module.h, the fsdev event subsystem, and the aio fsdev module (the fsdev_aio_create/fsdev_aio_delete RPCs and the --with-aio-fsdev configure option) are deprecated and will be replaced in the v27.01 release.

fuse_dispatcher

The fuse_dispatcher library and its internal API (include/spdk_internal/fuse_dispatcher.h) are deprecated and will be removed in the v27.01 release. There will be no replacement; the new fsdev implementation will not require a fuse_dispatcher.

vfu_virtio_create_fs_endpoint

The virtio-fs vfu_device support, exposed via the vfu_virtio_create_fs_endpoint RPC, is deprecated and will be removed in the v27.01 release.

gpt

old_gpt_guid

Deprecated the SPDK partition type GUID 7c5222bd-8f5d-4087-9c00-bf9843c7b58c. Partitions of this type have bdevs created that are one block less than the actual size of the partition. Existing partitions using the deprecated GUID can continue to use that GUID; support for the deprecated GUID will remain in SPDK indefinitely, and will continue to exhibit the off-by-one bug so that on-disk metadata layouts based on the incorrect size are not affected.

See GitHub issue 2801 for additional details on the bug.

New SPDK partition types should use GUID 6527994e-2c5a-4eec-9613-8f5944074e8b which will create a bdev of the correct size.

nvme

spdk_nvme_error_information_entry.error_location

The error_location field in struct spdk_nvme_error_information_entry is deprecated and will be removed in v27.01. Use the pel field instead; pel.raw provides equivalent raw-value access.

nvme_ns_get_format_index

spdk_nvme_ns_get_format_index is deprecated and will be removed in v27.01. Use spdk_nvme_ns_get_active_format_index instead.

spdk_nvme_ns_get_nguid

spdk_nvme_ns_get_nguid() is deprecated and will be removed in v27.01. Read nguid directly from spdk_nvme_ns_get_data_head(ns) (compatible with both full and head-only nsdata allocations).

nvme_ctrlr_opts_ns_data_alloc_mode_default

spdk_nvme_ctrlr_opts.ns_data_alloc_mode defaults to SPDK_NVME_NS_DATA_ALLOC_MODE_DEFAULT, which today resolves to SPDK_NVME_NS_DATA_ALLOC_MODE_FULL (the legacy 4 KB per-namespace allocation including vendor_specific[]). The default will flip to SPDK_NVME_NS_DATA_ALLOC_MODE_HEAD in v27.01 to reduce the per-namespace memory footprint.

Applications that read vendor_specific[] via spdk_nvme_ns_get_vendor_specific() must set the field to SPDK_NVME_NS_DATA_ALLOC_MODE_FULL explicitly to retain current behavior; setting it explicitly also silences this deprecation log. All other applications should switch to spdk_nvme_ns_get_data_head() and either rely on the upcoming default flip or opt in early by setting the field to SPDK_NVME_NS_DATA_ALLOC_MODE_HEAD. Applications that scale namespace count aggressively and can guarantee attached controllers advertise NLBAF < 4 can opt in to SPDK_NVME_NS_DATA_ALLOC_MODE_HEAD_LBAF_4 for a further 240 B per-namespace saving over HEAD.

sock

spdk_sock_group_add_sock_callbacks

The remaining cb_arg parameter of spdk_sock_group_add_sock is deprecated and will be removed in v27.01. spdk_sock_set_user_ctx() updates a socket's callback context. In v26.09, spdk_sock_group_add_sock() overwrites that context with its cb_arg argument, so applications must still pass the intended context when adding a socket. Setting the context before adding the socket does not replace that argument.