Provided by: ddpt_0.97-1_amd64 
NAME
ddptctl - helper/auxiliary utility for ddpt
SYNOPSIS
ddptctl [--abort] [--all_toks] [--block] [--del_tkn] [--flexible] [--help] [--immed]
[--info] [--list_id=LID] [--oir=OIR] [--poll] [--pt=GL] [--readonly] [--prefer_rcs]
[--receive] [--rtf=RTF] [--rtype=RTYPE] [--size] [--timeout=ITO[,CMD]] [--verbose]
[--version] [--wut=SL] [DEVICE]
DESCRIPTION
This utility is a helper/auxiliary for the ddpt utility which copies data between or
within SCSI devices (logical units). While ddpt's command line syntax is modelled on that
of the POSIX dd command, this utility has a more standard Unix command line syntax with
both short and long variants of each option.
The T10 committee defines a family of SCSI commands for offloaded copy. The central (but
not the only) command is EXTENDED COPY often shortened to XCOPY or xcopy. There are now
two generations of xcopy, the older one is given the suffix "LID1" and the newer one:
"LID4". There is a subset of XCOPY(LID4) that supports disk to disk copies and is based on
the SBC-3 commands: POPULATE TOKEN (PT) and WRITE USING TOKEN (WUT). ODX is a market name
that has become associated with this subset. This utility can issue PT, WUT and related
commands, read the Third Party Copy VPD page and perform several other housekeeping tasks.
The xcopy family of commands are described in the SPC-4,5 and SBC-3,4 documents found at
https://www.t10.org .
Apart from PT and WUT, other command abbreviations used below are RRTI for the RECEIVE ROD
TOKEN INFORMATION command and RCS for the RECEIVE COPY STATUS(LID4) command.
OPTIONS
Arguments to long options are mandatory for short options as well.
-A, --abort
this option will issue the COPY OPERATION ABORT command with the LID given in the
--list_id=LID option. If the --list_id=LID option is not given then its default LID
(257) is used. If there is an xcopy operation ongoing on this I-T nexus (i.e.
issued by this machine to any LU sharing the same target) using that LID then the
copy is aborted. Note there is a sense key (COPY ABORTED) indicating some but not
all data has been copied due to this action.
-a, --all_toks
send the REPORT ALL ROD TOKENS SCSI command to DEVICE and decode the response. An
ODX implementation is not required to support this command.
-B, --block
treat DEVICE as a block device when checking its --size. The default action of this
utility is to treat DEVICE as a SCSI pass-through device.
-D, --del_tkn
set the DEL_TKN bit in a WUT command (default: clear the DEL_TKN bit). Since an
ODX copy manager deletes the ROD Token when its inactivity time-out is reached,
this option is typically not needed. It may be useful for long-lived ROD Tokens
that are no longer needed.
To delete an unused ROD Token a degenerate scatter list seems to be acceptable
(e.g. '--wut=0,0 --del_tkn').
-f, --flexible
this option currently only effects the parsing of sgl_s in files that are in
hexadecimal plus they have a leading line with 'HEX' in them. Without this option
any such line must be invoked with 'H@' before the filename; in other words the 'H'
in the invocation needs to match the HEX in the file. With this option a sgl in a
file can be invoked with '@' and if a line with HEX is parsed before any LBA,NUM
pairs then it switches to hexadecimal mode; so all the parsed LBA,NUM pairs are
assumed to be in hexadecimal.
-h, --help
outputs the usage message summarizing command line options then exits.
-I, --immed
set the IMMED bit in the PT or WUT command. When given the PT and WUT commands
return promptly before the data transfer is complete; then this utility exits. The
user should then invoke the utility again with the --poll option and the same LID
and DEVICE to await completion and receive the final transfer count. The default
action of PT and WUT (i.e. without this option) is to wait for completion (i.e.
all data transferred or an error occurs) before exiting this utility.
-i, --info
when the DEVICE argument is given then check its Third Party Copy VPD page and
print out anything found. Also check if the 3PC bit is set in the standard INQUIRY
response.
If the DEVICE argument is not given and the --rtf=RTF option is given then decode
part of the ROD Token held in the --RTF file. SPC-4 defines some parts of a ROD
Token that can be decoded but does not require the copy manager to set these
fields; so many fields may appear as zeros. A --RTF file that has been generated by
the ddpt utility may contain multiple ROD Tokens, each optionally followed by an 8
byte "number of bytes represented" integer. They are all decoded, based on --RTF
file length which should either be a multiple of 512 or 520 bytes.
-l, --list_id=LID
LID is a list identifier which is used to associate an originating xcopy command
(e.g. PT or WUT) with a follow-up command that retrieves associated information or
aborts the operation. T10 requires each active LID to be unique on a given I-T
nexus. An I-T nexus is the current machine (more precisely a HBA if a machine has
two or more) and a specific target which will contain one or more logical units
(LUs) of which DEVICE is one. If the DEVICE's copy manager feels that rather
complex condition has not been met then an error is generated with sense data that
decodes to "operation in progress". Rather than try to work out who is doing what
elsewhere, try another LID value.
The default value for LID is 257.
-O, --oir=OIR
OIR is the Offset In ROD, a field in the WUT command. It may be be used together
with the --wut=SL option. Its default value is 0 and its units are the logical
block size of DEVICE.
-p, --poll
send RRTI (or RCS) command to the DEVICE using the LID (i.e. from the
--list_id=LID option). If a copy status is received indicating the operation is
ongoing, then this SCSI command is sent periodically (as suggested by the previous
RRTI (or RCS) command or every 500 milliseconds) until some other copy status is
detected. If the --list_id=LID option is not given then a LID of 257 is assumed.
If the originating xcopy command was POPULATE TOKEN and the RRTI command indicates
that it has completed successfully then the associated ROD Token (returned in the
RRTI response) is written to the RTF file. If the --rtf=RTF option is not given
then the ROD token is written to a file called ddptctl_rod_tok.bin in the current
directory.
-q, --prefer_rcs
prefers using the RECEIVE COPY STATUS (RCS) command over the RRTI command which is
the default. This only should be done following a WUT command since after a PT
command, the RRTI command is needed to fetch the ROD tokane.
-P, --pt=GL
send a POPULATE TOKEN (PT) command with the given gather list. The format of GL is
given in the NOTES section. If used without the --immed option then this utility,
after the PT command finishes successfully, will call the RRTI command. When the
RRTI command finishes, potentially with a new ROD Token, this utility will exit.
Prior to that exit, if a new ROD Token is available and the --rtf=RTF option is
given then that ROD Token is written to the RTF file. If the --rtf=RTF option is
not given then the ROD token is written to a file called ddptctl_rod_tok.bin in the
current directory.
If the --immed option is given this utility will exit after the PT command
finishes. To complete the operation this utility should be invoked again with the
--poll option and the same DEVICE.
-y, --readonly
open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to
open it read-write.
-R, --receive
send the RRTI (or RCS) SCSI command to the DEVICE using the LID (i.e. from the
--list_id=LID option). If the --list_id=LID option is not given then a LID of 257
is assumed.
If the originating xcopy command was POPULATE TOKEN and the RRTI command indicates
that it has completed successfully then the associated ROD Token (returned in the
RRTI response) is written to the RTF file. If the --rtf=RTF option is not given
then the ROD token is written to a file called ddptctl_rod_tok.bin in the current
directory.
-r, --rtf=RTF
when RTF is a file containing an ODX ROD Token or the name of a file the ROD Token
is to be written to. A ROD Token used by ODX is 512 bytes long. If the RTF file was
produced by the ddpt utility then it might contain multiple ROD Tokens, each
optionally followed by an 8 byte integer containing the "number of bytes
represented" by the preceding ROD Token.
If an RTF file with multiple ROD Tokens is given to this utility with --wut=SL then
only the first ROD Token is used. If an RTF file is being decoded (i.e. no DEVICE
argument given) then all ROD Tokens are decoded.
-t, --rtype=RTYPE
where RTYPE is the ROD Type, a field in the PT command (apart from "zero"). The
default value (0) indicates that the copy manager (in the DEVICE) decides. RTYPE
can be a decimal number, a hex number (prefixed by 0x or with a "h" appended) or
one of "pit-def", "pit-vuln", "pit-pers", "pit-cow", "pit-any" or "zero". The
final truncated word can be spelt out (e.g. "pit-vulnerable"). The "pit-" lead-in
stands for "point in time" copy.
The "zero" is a special case and is not given to a PT command. Instead it causes a
special Block Device Zero Token to be created that can be used with the --wut=SL
option to write blocks of zeros to the given DEVICE.
-s, --size
prints the number of blocks and the size of each block for the given DEVICE.
Protection information is printed if available. By default uses the pass-through
interface and the READ CAPACITY command to obtain this information. If the --block
option is given then the block layer in the OS is query for size information (and
protection information is not reported).
-T, --timeout=ITO[,CMD]
where ITO is the inactivity timeout (units: seconds) given to the PT command. The
default is 0 in which case the copy manager uses its own default which is shown in
the Third party Copy VPD page.
CMD is the SCSI command timeout (units: seconds) applied to SCSI commands issued by
this utility; default is 0 which is translated to 600 seconds for originating xcopy
commands (e.g. PT and WUT) and 60 seconds for other commands. Best not to trigger
command timeouts.
-v, --verbose
increase the level of verbosity, (i.e. debug output).
-V, --version
print the version string and then exit.
-w, --wut=SL
send a WRITE USING TOKEN (WUT) command with the given scatter list. The format of
SL is given in the NOTES section. This option requires the --rtf=RTF option to
supply the ROD Token. If used without the --immed option then after the WUT command
finishes successfully this utility will call the RRTI command. When the RRTI
command finishes this utility will exit.
If the --immed option is given this utility will exit after the WUT command
finishes. To complete the operation this utility should be invoked again with the
--poll option and the same DEVICE.
NOTES
The scatter gather list given to the --pt=GL and --wut=SL options in the simplest case
contains a pair a numbers, separated by a comma. The first number is the starting LBA and
the second number is the number of blocks (no bigger than 32 bits) to read to or write
from that starting LBA. Another pair of numbers can appear after that forming the second
element of a scatter gather list. Starting LBAs can be in any order but T10 prohibits any
logical block appearing more than once in a scatter gather list.
Scatter gather lists can be placed in a file or read from stdin. A file name referring to
a file containing a scatter gather list must follow the "@" character (e.g.
--pt=@my_sgl.txt"). Reading a list from stdin is indicated by "@-" or "-" (e.g. "--pt=-").
Scatter gather lists in a file have a looser format and can take spaces and tabs as well
as a comma as separators. Anything from and including a "#" on a line is ignored.
Both the PT and WUT commands are issued "as is" without checking the Third Party Copy VPD
page. The copy manager may well reject these commands (with exit status 51: invalid field
in parameter list) if the maximum range descriptors field or the maximum token transfer
size field are exceeded.
There is a web page discussing ddptctl and ddpt, XCOPY and ODX at
https://sg.danny.cz/sg/ddpt_xcopy_odx.html
EXIT STATUS
The exit status of ddptctl is 0 when it is successful. Otherwise the exit status for this
utility is the same as that for ddpt. See the EXIT STATUS section in the ddpt man page.
EXAMPLES
First issue a PT command without the --immed option so RRTI is called to complete the
operation:
# ddptctl --pt=0x0,10k,20k,5k --rtf=aa.rt /dev/sdb
PT completes with a transfer count of 15360 [0x3c00]
The transfer count (10k + 5k == 15360) indicates the operation was successful and the ROD
Token is in the aa.rt file. Now use that ROD Token to write to the same locations on
/dev/sdc:
# ddptctl --rtf=aa.rt --wut=0x0,10k,20k,5k /dev/sdc
WUT completes with a transfer count of 15360 [0x3c00]
So the copy was successful. Now taking a closer look at the ROD token:
# ddptctl --info --rtf=aa.rt
Decoding information from ROD Token:
ROD type: point in time copy - default [0x800000]
Copy manager ROD Token identifier: 0x520000710000000c
Creator Logical Unit descriptor:
Peripheral Device type: 0x0
Relative initiator port identifier: 0x0
designator_type: NAA, code_set: Binary
associated with the addressed logical unit
0x60002ac0000000000000000c00009502
Number of bytes represented: 0 [0x0]
Device type specific data (for disk) has block size of 0; unlikely so skip
Target device descriptor: unexpected designator type [0x0]
T10 does not require implementations to supply much of the above (only the ROD type and
the token length) so expect to see some empty fields.
To see information about /dev/sdb relevant to ODX, try:
# ddptctl --info /dev/sdb
/dev/sdb [readcap]: num_blks=209715200 [0xc800000], blk_size=512, 107 GB
3PC (third party copy) bit set in standard INQUIRY response
Third Party Copy VPD page:
Block Device ROD Token Limits:
Maximum Range Descriptors: 8
Maximum Inactivity Timeout: 60 seconds
Default Inactivity Timeout: 30 seconds
Maximum Token Transfer Size: 524288
Optimal Transfer Count: 524288
That maximum token transfer size [524288 blocks each 512 bytes gives 256 MB] is the
largest size a ROD Token created by /dev/sdb can hold. Use that and show the --immed
option on the destination:
# ddptctl --pt=0x0,0x80000 --rtf=aa.rt /dev/sdb
PT completes with a transfer count of 524288 [0x80000]
# ddptctl --rtf=aa.rt --wut=0x0,0x80000 --immed /dev/sdc
Started ODX Write Using Token command in immediate mode.
User may need --list_id=257 on following invocation with --receive or
--poll for completion
# ddptctl --poll --rtf=aa.rt /dev/sdc
RRTI for Write using token: Operation completed without errors
transfer count of 524288 [0x80000]
To copy larger amounts and/or with a larger number of scatter gather elements (than 8
"range descriptors") use one of the four ODX variants in the ddpt utility.
AUTHORS
Written by Douglas Gilbert.
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright © 2014-2021 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO warranty; not even for
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
SEE ALSO
ddpt(8), ddpt_sgl(8)