From dc597ce8df5ae6efd2728a2d7ba7d92486028f79 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 2 Jul 2021 22:40:30 +0200 Subject: Adding upstream version 1.12. Signed-off-by: Daniel Baumann --- Documentation/nvme-compare.txt | 148 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 Documentation/nvme-compare.txt (limited to 'Documentation/nvme-compare.txt') diff --git a/Documentation/nvme-compare.txt b/Documentation/nvme-compare.txt new file mode 100644 index 0000000..9185c5f --- /dev/null +++ b/Documentation/nvme-compare.txt @@ -0,0 +1,148 @@ +nvme-compare(1) +=============== + +NAME +---- +nvme-compare - Send an NVMe Compare command, provide results + +SYNOPSIS +-------- +[verse] +'nvme-compare' [--start-block= | -s ] + [--block-count= | -c ] + [--data-size= | -z ] + [--metadata-size= | -y ] + [--ref-tag= | -r ] + [--data= | -d ] + [--metadata= | -M ] + [--prinfo= | -p ] + [--app-tag-mask= | -m ] + [--app-tag= | -a ] + [--limited-retry | -l] + [--force-unit-access | -f] + [--dir-type= | -T ] + [--dir-spec= | -S ] + [--dsm= | -D ] + [--show-command | -v] + [--dry-run | -w] + [--latency | -t] + +DESCRIPTION +----------- +The Compare command reads the logical blocks specified by the command +from the medium and compares the data read to a comparison data buffer +transferred as part of the command. If the data read from the controller +and the comparison data buffer are equivalent with no miscompares, +then the command completes successfully. If there is any miscompare, +the command completes with an error of Compare Failure. If metadata is +provided, then a comparison is also performed for the metadata. + +OPTIONS +------- +-s :: +--start-block=:: + 64-bit address of the first block to access. + +-c :: +--block-count=:: + Number of blocks to be accessed (zero-based). + +-z :: +--data-size=:: + Size of data to be compared in bytes. + +-y :: +--metadata-size=:: + Size of metadata to be trasnferred in bytes. + +-r :: +--ref-tag=:: + Reference Tag for Protection Information + +-d :: +--data=:: + Data file. + +-M :: +--metadata=:: + Metadata file. + +-p :: +--prinfo=:: + Protection Information and check field. + ++ +[] +|================= +|Bit|Description +|3|PRACT: Protection Information Action. When set to 1, PI is stripped/inserted +on read/write when the block format's metadata size is 8. When set to 0, +metadata is passes. +|2:0|PRCHK: Protection Information Check: +|2|Set to 1 enables checking the guard tag +|1|Set to 1 enables checking the application tag +|0|Set to 1 enables checking the reference tag +|================= + +-m :: +--app-tag-mask=:: + App Tag Mask for Protection Information + +-a :: +--app-tag=:: + App Tag for Protection Information + +-l:: +--limited-retry:: + Number of limited attempts to media. + +-f:: +--force-unit-access:: + FUA option to guarantee that data is stored to media. + +-T :: +--dir-type=:: + Optional directive type. The nvme-cli only enforces the value + be in the defined range for the directive type, though the NVMe + specifcation (1.3a) defines only one directive, 01h, for write + stream idenfiers. + +-S :: +--dir-spec=:: + Optional field for directive specifics. When used with + write streams, this value is defined to be the write stream + identifier. The nvme-cli will not validate the stream requested + is within the controller's capabilities. + +-D :: +--dsm=:: + The optional data set management attributes for this command. The + argument for this is the lower 16 bits of the DSM field in a write + command; the upper 16 bits of the field come from the directive + specific field, if used. This may be used to set attributes for + the LBAs being written, like access frequency, type, latency, + among other things, as well as yet to be defined types. Please + consult the NVMe specification for detailed breakdown of how to + use this field. + +-v:: +--show-cmd:: + Print out the command to be sent. + +-w:: +--dry-run:: + Do not actually send the command. If want to use --dry-run option, + --show-cmd option _must_ be set. Otherwise --dry-run option will be + _ignored_. + +-t:: +--latency:: + Print out the latency the IOCTL took (in us). + +EXAMPLES +-------- +No examples yet. + +NVME +---- +Part of the nvme-user suite -- cgit v1.2.3