d/numam-spdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

lvol/doc: update lvol documentation

Browse Source 
Signed-off-by: Maciej Szwed <maciej.szwed@intel.com>
Change-Id: Ib42a520b9ac2783c96dbe73d1f8b22a5ac9a5b74

Reviewed-on: https://review.gerrithub.io/407558
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Ben Walker <benjamin.walker@intel.com>
This commit is contained in:
Maciej Szwed 2018-04-13 15:20:12 +02:00 committed by Daniel Verkamp
parent 2536874e85
commit 897bb3ac7f
1 changed files with 49 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
doc/lvol.md
View File

@ -16,7 +16,7 @@ A logical volume store uses the super blob feature of blobstore to hold uuid (an
* Shorthand: lvol
* Type name: struct spdk_lvol
A logical volume is implemented as an SPDK blob created from an lvolstore. An lvol is uniquely identified by its lvol ID and lvolstore UUID from which it was created.
A logical volume is implemented as an SPDK blob created from an lvolstore. An lvol is uniquely identified by its UUID. Lvol additional can have alias name.
## Logical volume block device {#lvol_bdev}
@ -24,10 +24,18 @@ A logical volume is implemented as an SPDK blob created from an lvolstore. An lv
* Type name: struct spdk_lvol_bdev
Representation of an SPDK block device (spdk_bdev) with an lvol implementation.
A logical volume block device translates generic SPDK block device I/O (spdk_bdev_io) operations into the equivalent SPDK blob operations. Combination of lvol ID and lvolstore UUID gives lvol_bdev name in a form "uuid/lvolid". block_size of the created bdev is always 4096, due to blobstore page size. Cluster_size is configurable by parameter.
A logical volume block device translates generic SPDK block device I/O (spdk_bdev_io) operations into the equivalent SPDK blob operations. Combination of lvol name and lvolstore name gives lvol_bdev alias name in a form "lvs_name/lvol_name". block_size of the created bdev is always 4096, due to blobstore page size. Cluster_size is configurable by parameter.
Size of the new bdev will be rounded up to nearest multiple of cluster_size.
By default lvol bdevs claim part of lvol store equal to their set size. When thin provision option is enabled, no space is taken from lvol store until data is written to lvol bdev.
## Snapshots and clone {#lvol_snapshots}
Logical volumes support snapshots and clones functionality. User may at any given time create snapshot of existing logical volume to save a backup of current volume state.
When creating snapshot original volume becomes thin provisioned and saves only incremental differences from its underlying snapshot. This means that every read from unallocated cluster is actually a read from the snapshot and
every write to unallocated cluster triggers new cluster allocation and data copy from corresponding cluster in snapshot to the new cluster in logical volume before the actual write occurs.
User may also create clone of existing snapshot that will be thin provisioned and it will behave in the same way as logical volume from which snapshot is created.
There is no limit of clones and snapshots that may be created as long as there is enough space on logical volume store. Snapshots are read only. Clones may be created only from snapshots.
# Configuring Logical Volumes
There is no static configuration available for logical volumes. All configuration is done trough RPC. Information about logical volumes is kept on block devices.
@ -37,34 +45,44 @@ There is no static configuration available for logical volumes. All configuratio
RPC regarding lvolstore:
```
construct_lvol_store [-h] [-c CLUSTER_SZ] base_name
Constructs lvolstore on specified bdev. During construction bdev is unmapped
at initialization and all data is erased. Then original bdev is claimed by
construct_lvol_store [-h] [-c CLUSTER_SZ] bdev_name lvs_name
Constructs lvolstore on specified bdev with specified name. During
construction bdev is unmapped at initialization and all data is
erased. Then original bdev is claimed by
SPDK, but no additional spdk bdevs are created.
Returns uuid of created lvolstore.
Optional paramters:
-h show help
-c CLUSTER_SZ Specifies the size of cluster. By default its 4MiB.
destroy_lvol_store [-h] uuid
-h show help
-c CLUSTER_SZ Specifies the size of cluster. By default its 4MiB.
destroy_lvol_store [-h] [-u UUID] [-l LVS_NAME]
Destroy lvolstore on specified bdev. Removes lvolstore along with lvols on
it. Note that destroying lvolstore requires using this call, while deleting
single lvol requires using delete_bdev rpc call.
it. User can identify lvol store by UUID or its name. Note that destroying
lvolstore requires using this call, while deleting single lvol requires
using delete_bdev rpc call.
optional arguments:
-h, --help show help
get_lvol_stores [-h] [NAME]
get_lvol_stores [-h] [-u UUID] [-l LVS_NAME]
Display current logical volume store list
optional arguments:
-h, --help show help
NAME, show details of specified lvol store
-u UUID, --uuid UUID show details of specified lvol store
-l LVS_NAME, --lvs_name LVS_NAME show details of specified lvol store
rename_lvol_store [-h] old_name new_name
Change logical volume store name
optional arguments:
-h, --help show this help message and exit
```
RPC regarding lvol and spdk bdev:
```
construct_lvol_bdev [-h] [-t] uuid size
Creates lvol with specified size on lvolstore specified by its uuid.
Then constructs spdk bdev on top of that lvol and presents it as spdk bdev.
construct_lvol_bdev [-h] [-u UUID] [-l LVS_NAME] [-t] lvol_name size
Creates lvol with specified size and name on lvolstore specified by its uuid
or name. Then constructs spdk bdev on top of that lvol and presents it as spdk bdev.
User may use -t switch to create thin provisioned lvol.
Returns the name of new spdk bdev
optional arguments:
-h, --help show help
get_bdevs [-h] [-b NAME]
User can view created bdevs using this call including those created on top of lvols.
optional arguments:
@ -74,9 +92,20 @@ delete_bdev [-h] bdev_name
Deletes spdk bdev
optional arguments:
-h, --help show help
snapshot_lvol_bdev [-h] lvol_name snapshot_name
Create a snapshot with snapshot_name of a given lvol bdev.
optional arguments:
-h, --help show help
clone_lvol_bdev [-h] snapshot_name clone_name
Create a clone with clone_name of a given lvol snapshot.
optional arguments:
-h, --help show help
rename_lvol_bdev [-h] old_name new_name
Change lvol bdev name
optional arguments:
-h, --help show help
resize_lvol_bdev [-h] name size
Resize existing lvol bdev
optional arguments:
-h, --help show help
```
# Restrictions
- Nesting logical volumes on each other is not supported.
- Resizing lvol bdev is experimental. Code is present but not used.