From 24ea815b3ee6e2a3989a2c31791080ea5899506d Mon Sep 17 00:00:00 2001 From: Mike Gerdts Date: Thu, 20 Oct 2022 23:09:41 -0500 Subject: [PATCH] doc/bdev_module: make claims documentation match reality The deprecation (commit 79ed1ba18dba76178c74f326c7fefe07dec5bfbb) and removal (commit a6b1e2c57d29e906fdcdb7d9fcfda682db33b69a) of spdk_bdev_open() did not make the necessary documentation changes related to obtaining claims. More clarity could be helpful related to when IO channels may be obtained and how spdk_bdev_module_claim_bdev() behaves when passed a NULL descriptor. See also commit 9f9c7161c942fc193dcb28d706edf240722897ef. These changes are primarily made to ensure a proper understanding of the current implementation before making changes to support a newer claims API. Change-Id: I01e253e2ec77256f4c2d9ee64ca38070700f7ee7 Signed-off-by: Mike Gerdts Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/15111 Tested-by: SPDK CI Jenkins Reviewed-by: Jim Harris Reviewed-by: Shuhei Matsumoto --- doc/bdev_module.md | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/doc/bdev_module.md b/doc/bdev_module.md index 68e1ba03e..3234e8cb3 100644 --- a/doc/bdev_module.md +++ b/doc/bdev_module.md @@ -151,13 +151,25 @@ bdev module. Refer to test/external_code/README.md and @ref so_linking for furth Block devices are considered virtual if they handle I/O requests by routing the I/O to other block devices. The canonical example would be a bdev module that implements RAID. Virtual bdevs are created in the same way as regular -bdevs, but take one additional step. The module can look up the underlying -bdevs it wishes to route I/O to using spdk_bdev_get_by_name(), where the string -name is provided by the user via an RPC. The module -then may proceed is normal by opening the bdev to obtain a descriptor, and -creating I/O channels for the bdev (probably in response to the -`get_io_channel` callback). The final step is to have the module use its open -descriptor to call spdk_bdev_module_claim_bdev(), indicating that it is -consuming the underlying bdev. This prevents other users from opening -descriptors with write permissions. This effectively 'promotes' the descriptor -to write-exclusive and is an operation only available to bdev modules. +bdevs, but take the one additional step of claiming the bdev. + +The module can open the underlying bdevs it wishes to route I/O to using +spdk_bdev_open_ext(), where the string name is provided by the user via an RPC. +This will return a bdev descriptor that may be used with future calls to +spdk_bdev_module_claim_bdev() and spdk_bdev_get_io_channel(). The bdev structure +required by spdk_bdev_module_claim_bdev() may be obtained with +spdk_bdev_module_open_ext() followed by spdk_bdev_desc_get_bdev(). + +The descriptor obtained from the successful spdk_bdev_open_ext() may be used +with spdk_bdev_get_io_channel() to obtain I/O channels for the bdev. This is +likely done in response to the virtual bdev's `get_io_channel` callback. +Channels may be obtained before and/or after claiming the underlying +bdev. Claims are described below. + +The final step is to have the module use its open descriptor to call +spdk_bdev_module_claim_bdev(), indicating that it is consuming the underlying +bdev. This prevents other users from opening descriptors with write permissions. +This effectively 'promotes' the descriptor to write-exclusive and is an +operation only available to bdev modules. If a virtual bdev module wishes to +prevent a descriptor from being upgraded to read-write, +spdk_bdev_module_claim_bdev() may be called with a NULL descriptor.