ivampiresp/Spdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
549be9ad81
Spdk/deprecation.md

80 lines
3.0 KiB
Markdown
Raw Normal View History

markdownlint: enable rule MD025 MD025 - Multiple top level headers in the same document Fixed all errors Update check_format.sh to fit new header style in jsonrpc.md Signed-off-by: Maciej Wawryk <maciejx.wawryk@intel.com> Change-Id: Ib5f832c549880771c99c15b89affe1e82acd3fa4 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/9045 Reviewed-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Ben Walker <benjamin.walker@intel.com> Community-CI: Broadcom CI <spdk-ci.pdl@broadcom.com> Community-CI: Mellanox Build Bot Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
2021-08-02 12:27:54 +00:00
# Deprecation
## ABI and API Deprecation {#deprecation}
deprecation: add a file to gather all deprecation notices Signed-off-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com> Change-Id: I66e442c4d10c1d40f4d9240f4f48374fc6966f29 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/6591 Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Ben Walker <benjamin.walker@intel.com> Reviewed-by: <dongx.yi@intel.com> Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Community-CI: Mellanox Build Bot
2021-02-26 12:33:12 +00:00
This document details the policy for maintaining stability of SPDK ABI and API.
Major ABI version can change at most once for each quarterly SPDK release.
spelling: deprecation.md Part of #2256 * versioning Change-Id: Ibba158baad1d26a264a7329d6645217fad7622c9 Signed-off-by: Josh Soref <jsoref@gmail.com> Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/10400 Community-CI: Broadcom CI <spdk-ci.pdl@broadcom.com> Reviewed-by: Karol Latecki <karol.latecki@intel.com> Reviewed-by: Shuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com> Reviewed-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com> Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
2021-11-25 01:40:57 +00:00
ABI versions are managed separately for each library and follow [Semantic Versioning](https://semver.org/).
deprecation: add a file to gather all deprecation notices Signed-off-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com> Change-Id: I66e442c4d10c1d40f4d9240f4f48374fc6966f29 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/6591 Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Ben Walker <benjamin.walker@intel.com> Reviewed-by: <dongx.yi@intel.com> Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Community-CI: Mellanox Build Bot
2021-02-26 12:33:12 +00:00
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.
log: add deprecated tracking API When use of deprecated featues is encountered, SPDK now calls SPDK_LOG_DEPRECATED(). This logs the use of deprecated functionality in a consistent way, making it easy to add further instrumentation to catch code paths that trigger deprecated behavior. Change-Id: Idfd33ade171307e5e8235a7aa0d969dc5d93e33d Signed-off-by: Mike Gerdts <mgerdts@nvidia.com> Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/15689 Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Aleksey Marchuk <alexeymar@nvidia.com> Community-CI: Mellanox Build Bot
2022-11-29 17:02:14 +00:00
Deprecated code paths must be registered with `SPDK_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.
markdownlint: enable rule MD025 MD025 - Multiple top level headers in the same document Fixed all errors Update check_format.sh to fit new header style in jsonrpc.md Signed-off-by: Maciej Wawryk <maciejx.wawryk@intel.com> Change-Id: Ib5f832c549880771c99c15b89affe1e82acd3fa4 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/9045 Reviewed-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Ben Walker <benjamin.walker@intel.com> Community-CI: Broadcom CI <spdk-ci.pdl@broadcom.com> Community-CI: Mellanox Build Bot Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
2021-08-02 12:27:54 +00:00
## Deprecation Notices {#deprecation-notices}
nvme: Deprecate spdk_nvme_ctrlr_prepare_for_reset() Signed-off-by: Shuhei Matsumoto <smatsumoto@nvidia.com> Change-Id: I3e5d1ef4816187b074dcf12ec4ec2dd42d880b65 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/12709 Community-CI: Broadcom CI <spdk-ci.pdl@broadcom.com> Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Reviewed-by: Ben Walker <benjamin.walker@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Aleksey Marchuk <alexeymar@nvidia.com>
2022-05-18 07:21:05 +00:00
deprecation: Remove support for PMDK Support for PMDK is winding down, see: https://pmem.io/blog/2022/11/update-on-pmdk-and-our-long-term-support-strategy/ Change-Id: I8999a31137aa372e757472cfb7d4bf4edf9d2fb6 Signed-off-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com> Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/16393 Reviewed-by: Konrad Sztyber <konrad.sztyber@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
2023-01-20 12:55:51 +00:00
### PMDK
PMDK is no longer supported and integrations with it in SPDK are now deprecated, and will be removed in SPDK 23.05.
Please see: [UPDATE ON PMDK AND OUR LONG TERM SUPPORT STRATEGY](https://pmem.io/blog/2022/11/update-on-pmdk-and-our-long-term-support-strategy/).
#### `bdev_pmem`
Deprecated `bdev_pmem` based on libpmemblk, it will be removed in SPDK 23.05.
#### `libreduce_pm_file`
Reduce library will no longer depend on libpmem. `pm_file_dir` parameter in `spdk_reduce_vol_init()`
will no longer point to pmem device or pmem file. Instead it will be possible to operate on a file,
without the benefits of persistency.
deprecation: VTune support VTune support was already deprecated in patch below, this one just formalizes that with SPDK 23.05 removal date. (6b97cc)bdev, bdev_nvme: deprecate VTUNE support Change-Id: I09f067a23453f994fa901aa3d82898257aa39a54 Signed-off-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com> Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/16391 Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Paul Luse <paul.e.luse@intel.com> Reviewed-by: Aleksey Marchuk <alexeymar@nvidia.com> Reviewed-by: Konrad Sztyber <konrad.sztyber@intel.com> Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
2023-01-20 12:46:49 +00:00
### VTune
deprecation: fix formating and reference to log Made sure that all tags matching the deprecation logs are level 4 header. Added missing vtune tag. Signed-off-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com> Change-Id: I96f1e608f33a8bd32c8757c4d2ca93c5f2efc214 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/16508 Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Konrad Sztyber <konrad.sztyber@intel.com> Reviewed-by: Xiaodong Liu <xiaodong.liu@intel.com>
2023-01-25 15:18:11 +00:00
#### `vtune_support`
deprecation: VTune support VTune support was already deprecated in patch below, this one just formalizes that with SPDK 23.05 removal date. (6b97cc)bdev, bdev_nvme: deprecate VTUNE support Change-Id: I09f067a23453f994fa901aa3d82898257aa39a54 Signed-off-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com> Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/16391 Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Paul Luse <paul.e.luse@intel.com> Reviewed-by: Aleksey Marchuk <alexeymar@nvidia.com> Reviewed-by: Konrad Sztyber <konrad.sztyber@intel.com> Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
2023-01-20 12:46:49 +00:00
VTune integration is in now deprecated and will be removed in SPDK 23.05.
deprecation: remove Open CAS Framework Support OCF is now winding down and will not see further updates. Change-Id: Ica2026d3a9ad13daf677fcce2b7974eb333971fc Signed-off-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com> Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/16392 Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Konrad Sztyber <konrad.sztyber@intel.com>
2023-01-20 12:54:25 +00:00
### OCF
#### `bdev_ocf`
The Open CAS Framework (OCF) integration via bdev module and env_ocf is now deprecated
and will be removed in SPDK 23.05.
nvme: Deprecate spdk_nvme_ctrlr_prepare_for_reset() Signed-off-by: Shuhei Matsumoto <smatsumoto@nvidia.com> Change-Id: I3e5d1ef4816187b074dcf12ec4ec2dd42d880b65 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/12709 Community-CI: Broadcom CI <spdk-ci.pdl@broadcom.com> Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Reviewed-by: Ben Walker <benjamin.walker@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Aleksey Marchuk <alexeymar@nvidia.com>
2022-05-18 07:21:05 +00:00
### nvme
bdev: examine and register on app thread This introduces a deprecation for calling spdk_bdev_register() and spdk_bdev_examine() on a thread other than the app thread. The deprecation period starts in SPDK 23.01 and removal is expected in SPDK 23.05. The intent of this deprecation is to ensure that bdev modules' examine_config() and examine_disk() callbacks are only ever called on the app thread. This largely a formalization of what has long happened due to the RPC poller running on the first thread started by spdk_app_start(). Signed-off-by: Mike Gerdts <mgerdts@nvidia.com> Change-Id: Ic9d7b87b6522be20357d2eab2d0c77cd5753452f Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/15690 Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Community-CI: Mellanox Build Bot Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Aleksey Marchuk <alexeymar@nvidia.com> Reviewed-by: Shuhei Matsumoto <smatsumoto@nvidia.com> Reviewed-by: Mateusz Kozlowski <mateusz.kozlowski@intel.com>
2022-11-29 18:58:22 +00:00
#### `nvme_ctrlr_prepare_for_reset`
nvme: annotate and log existing deprecation Use the deprecation API to annotate and log the deprecation of spdk_nvme_ctrlr_prepare_for_reset() using the tag "nvme_ctrlr_prepare_for_reset". Signed-off-by: Mike Gerdts <mgerdts@nvidia.com> Change-Id: I98fd840aa9acc028a49bb47daf4ab7e88f1eb818 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/15756 Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Aleksey Marchuk <alexeymar@nvidia.com> Reviewed-by: Ben Walker <benjamin.walker@intel.com>
2022-12-02 05:20:01 +00:00
nvme: Deprecate spdk_nvme_ctrlr_prepare_for_reset() Signed-off-by: Shuhei Matsumoto <smatsumoto@nvidia.com> Change-Id: I3e5d1ef4816187b074dcf12ec4ec2dd42d880b65 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/12709 Community-CI: Broadcom CI <spdk-ci.pdl@broadcom.com> Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Reviewed-by: Ben Walker <benjamin.walker@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Aleksey Marchuk <alexeymar@nvidia.com>
2022-05-18 07:21:05 +00:00
Deprecated `spdk_nvme_ctrlr_prepare_for_reset` API, which will be removed in SPDK 22.01.
For PCIe transport, `spdk_nvme_ctrlr_disconnect` should be used before freeing I/O qpairs.
bdev: examine and register on app thread This introduces a deprecation for calling spdk_bdev_register() and spdk_bdev_examine() on a thread other than the app thread. The deprecation period starts in SPDK 23.01 and removal is expected in SPDK 23.05. The intent of this deprecation is to ensure that bdev modules' examine_config() and examine_disk() callbacks are only ever called on the app thread. This largely a formalization of what has long happened due to the RPC poller running on the first thread started by spdk_app_start(). Signed-off-by: Mike Gerdts <mgerdts@nvidia.com> Change-Id: Ic9d7b87b6522be20357d2eab2d0c77cd5753452f Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/15690 Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Community-CI: Mellanox Build Bot Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Aleksey Marchuk <alexeymar@nvidia.com> Reviewed-by: Shuhei Matsumoto <smatsumoto@nvidia.com> Reviewed-by: Mateusz Kozlowski <mateusz.kozlowski@intel.com>
2022-11-29 18:58:22 +00:00
bdev_gpt: add new SPDK partition type for off-by-one fix The gpt bdev module has an off-by-one error. When it calculates the size of the partition, it simply does "end - start", when really it should be "end - start + 1". We cannot just fix it by changing the math here, any consumers of the partition may have put down metadata on the partition based on the old size. So instead add a new SPDK partition type. SPDK will keep the existing off-by-one behavior when it finds the old partition type, but will use the correct math when finding the new partition type. Fixes issue #2801. Signed-off-by: Jim Harris <james.r.harris@intel.com> Change-Id: I48eb48c781f1968b59e52b4477ca45e9c81eac11 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/16298 Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Reviewed-by: Aleksey Marchuk <alexeymar@nvidia.com> Reviewed-by: Paul Luse <paul.e.luse@intel.com> Reviewed-by: Mike Gerdts <mgerdts@nvidia.com> Reviewed-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com>
2023-01-13 23:13:35 +00:00
### gpt
deprecation: fix formating and reference to log Made sure that all tags matching the deprecation logs are level 4 header. Added missing vtune tag. Signed-off-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com> Change-Id: I96f1e608f33a8bd32c8757c4d2ca93c5f2efc214 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/16508 Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Konrad Sztyber <konrad.sztyber@intel.com> Reviewed-by: Xiaodong Liu <xiaodong.liu@intel.com>
2023-01-25 15:18:11 +00:00
#### `old_gpt_guid`
bdev_gpt: add new SPDK partition type for off-by-one fix The gpt bdev module has an off-by-one error. When it calculates the size of the partition, it simply does "end - start", when really it should be "end - start + 1". We cannot just fix it by changing the math here, any consumers of the partition may have put down metadata on the partition based on the old size. So instead add a new SPDK partition type. SPDK will keep the existing off-by-one behavior when it finds the old partition type, but will use the correct math when finding the new partition type. Fixes issue #2801. Signed-off-by: Jim Harris <james.r.harris@intel.com> Change-Id: I48eb48c781f1968b59e52b4477ca45e9c81eac11 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/16298 Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Reviewed-by: Aleksey Marchuk <alexeymar@nvidia.com> Reviewed-by: Paul Luse <paul.e.luse@intel.com> Reviewed-by: Mike Gerdts <mgerdts@nvidia.com> Reviewed-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com>
2023-01-13 23:13:35 +00:00
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](https://github.com/spdk/spdk/issues/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.
bdev/lvol: add param `size_in_mib` to replace `size` in bytes `rpc_bdev_lvol_resize` and `rpc_bdev_lvol_create` can now use size in MiB instead of `size` in bytes. This change make param `size` deprecated and using both `size` and `size_in_mib` return error. Since `bdev_lvol_resize` and `bdev_lvol_create` use size in MiB, name of param should reflect it, previously used param `size` is positional therefore there is no need to keep it as deprecated. This patch fix issue: #2346 Signed-off-by: Sebastian Brzezinka <sebastian.brzezinka@intel.com> Change-Id: Ibbe2c056bb63d9f82dee91c87fdd501ce441d5f8 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/16901 Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Tomasz Zawadzki <tomasz.zawadzki@intel.com> Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
2023-02-21 13:17:57 +00:00
### lvol
#### `vbdev_lvol_rpc_req_size`
Param `size` in rpc commands `rpc_bdev_lvol_create` and `rpc_bdev_lvol_resize` is deprecated and
replace by `size_in_mib`.
See GitHub issue [2346](https://github.com/spdk/spdk/issues/2346) for additional details.
Reference in New Issue Copy Permalink