ivampiresp/Spdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc/bdev_module: make claims documentation match reality

Browse Source 
The deprecation (commit 79ed1ba18d) and
removal (commit a6b1e2c57d) 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
9f9c7161c9.

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 <mgerdts@nvidia.com>
Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/15111
Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
Reviewed-by: Jim Harris <james.r.harris@intel.com>
Reviewed-by: Shuhei Matsumoto <smatsumoto@nvidia.com>
This commit is contained in:
Mike Gerdts 2022-10-20 23:09:41 -05:00 committed by Jim Harris
parent a6e58cc44c
commit 24ea815b3e
1 changed files with 22 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
doc/bdev_module.md
View File

@ -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.