MAN page from OpenSuSE ddpt-0.94-1.1.x86_64.rpm

DDPTCTL

Section: DDPT (8)
Updated: April 2014
Index

NAME

ddptctl - helper/auxiliary utility for ddpt

SYNOPSIS

ddptctl[--abort] [--all_toks] [--block] [--del_tkn][--help] [--immed] [--info] [--list_id=LID][--oir=OIR] [--poll] [--pt=GL] [--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 databetween or within SCSI devices (logical units). While ddpt's command linesyntax is modelled on that of the POSIX dd command, this utility has a morestandard Unix command line syntax with both short and long variants of eachoption.

The T10 committee defines a family of SCSI commands for offloaded copy. Thecentral (but not the only) command is EXTENDED COPY often shortened to XCOPYor xcopy. There are now two generations of xcopy, the older one is given thesuffix "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 hasbecome associated with this subset. This utility can issue PT, WUT and relatedcommands, read the Third Party Copy VPD page and perform several otherhousekeeping tasks.

The xcopy family of commands are described in the SPC-4 and SBC-3 documentsfound at http://www.t10.org .

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 LIDgiven in the --list_id=LID option. If the --list_id=LIDoption is not given then its default LID (257) is used. If there isan xcopy operation ongoing on this I-T nexus (i.e. issued by thismachine to any LU sharing the same target) using that LID then thecopy is aborted. Note there is a sense key (COPY ABORTED) indicating somebut 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 theresponse. An ODX implementation is not required to support this command.
-B, --block: treat DEVICE as a block device when checking its --size. Thedefault action of this utility is to treat DEVICE as a SCSIpass-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 after is has beenfully copied from (once), this option is typically not needed. It maybe useful for long-lived ROD Tokens that have only been partiallywritten from (or not used at all) and are no longer needed.
To delete an unused ROD Token a degenerate scatter list seems to beacceptable (e.g. '--wut=0,0 --del_tkn').
-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 WUTcommands return promptly before the data transfer is complete; then thisutility exits. The user should then invoke the utility again with the--poll option and the same LID and DEVICE to awaitcompletion and receive the final transfer count. The default action ofPT 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 VPDpage and print out anything found. Also check if the 3PC bit is set in thestandard INQUIRY response.
If the DEVICE argument is not given and the --rtf=RTF optionis 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 notrequire the copy manager to set these fields; so many fields may appear aszeros. A --RTF file that has been generated by the ddpt utility maycontain multiple ROD Tokens, each optionally followed by an 8 byte "numberof bytes represented" integer. They are all decoded, based on --RTFfile 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 originatingxcopy command (e.g. PT or WUT) with a follow-up command that retrievesinformation or aborts the operation. T10 requires active LIDs to beunique on a given I-T nexus. An I-T nexus is the current machine (moreprecisely a HBA if a machine has two or more) and a specific target whichwill contain one or more logical units (LUs) of which DEVICE is one.If the DEVICE's copy manager feels that rather complex condition hasnot been met then an error is generated with sense data that decodesto "operation in progress". Rather than try to work out who is doingwhat 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 beused together with the --wut=SL option. Its default value is 0 andits units are the logical block size of DEVICE.
-p, --poll: send RECEIVE ROD TOKEN INFORMATION SCSI commands (RRTIs) to the DEVICEusing the LID (i.e. from the --list_id=LID option). Ifa copy status is received indicating the operation is ongoing, then thisSCSI command is sent periodically (as suggested by the previous RRTI commandor 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 commandindicates that it has completed successfully then the associatedROD Token (returned in the RRTI response) is written to the RTFfile. If the --rtf=RTF option is not given then the ROD token iswritten to a file called ddptctl_rod_tok.bin in the current directory.
-P, --pt=GL: send a POPULATE TOKEN (PT) command with the given gather list. The formatof GL is given in the NOTES section. If used without the --immedoption then this utility, after the PT command finishes successfully, willcall the RRTI command. When the RRTI command finishes, potentially with anew ROD Token, this utility will exit. Prior to that exit, if a new RODToken is available and the --rtf=RTF option is given then thatROD Token is written to the RTF file. If the --rtf=RTFoption is not given then the ROD token is written to a file calledddptctl_rod_tok.bin in the current directory.
If the --immed option is given this utility will exit after thePT command finishes. To complete the operation this utility should beinvoked again with the --poll option and the same DEVICE.
-R, --receive: send the RECEIVE ROD TOKEN INFORMATION SCSI command (RRTI) to the DEVICEusing 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 commandindicates that it has completed successfully then the associatedROD Token (returned in the RRTI response) is written to the RTFfile. If the --rtf=RTF option is not given then the ROD token iswritten 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 filethe ROD Token is to be written to. A ROD Token used by ODX is 512 byteslong. If the RTF file was produced by the ddpt utility then it mightcontain multiple ROD Tokens, each optionally followed by an 8 byte integercontaining 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 fileis being decoded (i.e. no DEVICE argument given) then all ROD Tokensare decoded.
-t, --rtype=RTYPE: where RTYPE is the ROD Type, a field in the PT command (apartfrom "zero"). The default value (0) indicates that the copy manager (in theDEVICE) decides. RTYPE can be a decimal number, a hexnumber (prefixed by 0x or with a "h" appended) or oneof "pit-def", "pit-vuln", "pit-pers", "pit-any" or "zero". The finaltruncated 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 itcauses a special Block Device Zero Token to be created that can be usedwith the --wut=SL option to write blocks of zeros to the givenDEVICE.
-s, --size: prints the number of blocks and the size of each block for the givenDEVICE. Protection information is printed if available. By defaultuses the pass-through interface and the READ CAPACITY command to obtainthis information. If the --block option is given then the blocklayer in the OS is query for size information (and protection informationis not reported).
-T, --timeout=ITO[,CMD]: where ITO is the inactivity timeout (units: seconds) given to thePT command. The default is 0 in which case the copy manager uses its owndefault which is shown in the Third party Copy VPD page.
CMD is the SCSI command timeout (units: seconds) applied to SCSIcommands issued by this utility; default is 0 which is translated to 600seconds for originating xcopy commands (e.g. PT and WUT) and 60 secondsfor 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. Theformat of SL is given in the NOTES section. This option requiresthe --rtf=RTF option to supply the ROD Token. If used without the--immed option then after the WUT command finishes successfullythis utility will call the RRTI command. When the RRTI command finishesthis utility will exit.
If the --immed option is given this utility will exit after theWUT command finishes. To complete the operation this utility should beinvoked again with the --poll option and the same DEVICE.

NOTES

The scatter gather list given to the --pt=GL and --wut=SLoptions in the simplest case contains a pair a numbers, separated by acomma. The first number is the starting LBA and the second number isthe number of blocks (no bigger than 32 bits) to read to or write from thatstarting LBA. Another pair of numbers can appear after that forming thesecond element of a scatter gather list. Starting LBAs can be in any orderbut T10 prohibits any logical block appearing more than once in a scattergather list.

Scatter gather lists can be placed in a file or read from stdin. A filename referring to a file containing a scatter gather list must followthe "@" character (e.g. --pt=@my_sgl.txt"). Reading a list from stdin isindicated by "@-" or "-" (e.g. "--pt=-"). Scatter gather lists in afile have a looser format and can take spaces and tabs as well as a commaas separators. Anything from and including a "#" on a line is ignored.

Both the PT and WUT commands are issued "as is" without checking the ThirdParty Copy VPD page. The copy manager may well reject these commands (withexit status 51: invalid field in parameter list) if the maximum rangedescriptors field or the maximum token transfer size field are exceeded.

There is a web page discussing ddptctl and ddpt, XCOPY and ODX athttp://sg.danny.cz/sg/ddpt_xcopy_odx.html

EXIT STATUS

The exit status of ddptctl is 0 when it is successful. Otherwise the exitstatus for this utility is the same as that for ddpt. See the EXIT STATUSsection in the ddpt man page.

EXAMPLES

First issue a PT command without the --immed option so RRTI iscalled 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 successfuland the ROD Token is in the aa.rt file. Now use that ROD Token to write tothe 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 theROD 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 andshow 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 gatherelements (than 8 "range descriptors") use one of the four ODX variants inthe ddpt utility.

AUTHORS

Written by Douglas Gilbert.

REPORTING BUGS

Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT

This document was created byman2html,using the manual pages.