Commit 24ea815b authored by Mike Gerdts's avatar Mike Gerdts Committed by Jim Harris
Browse files

doc/bdev_module: make claims documentation match reality 



The deprecation (commit 79ed1ba1) and
removal (commit a6b1e2c5) 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
9f9c7161.

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: default avatarMike Gerdts <mgerdts@nvidia.com>
Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/15111


Tested-by: default avatarSPDK CI Jenkins <sys_sgci@intel.com>
Reviewed-by: default avatarJim Harris <james.r.harris@intel.com>
Reviewed-by: default avatarShuhei Matsumoto <smatsumoto@nvidia.com>
parent a6e58cc4

doc/bdev_module.md

+22 −10
Original line number Diff line number Diff line
@@ -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.