Provided by: ddpt_0.94-1_i386 bug

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
       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  and  SBC-3
       documents found 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
              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 after is
              has been fully copied from (once), this option is typically  not
              needed.  It  may  be  useful for long-lived ROD Tokens that have
              only been partially written from (or not used at all) and 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').

       -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 information or aborts the operation.  T10
              requires  active  LIDs 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 RECEIVE ROD TOKEN INFORMATION SCSI commands (RRTIs) 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 command or 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.

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

       -R, --receive
              send  the  RECEIVE  ROD TOKEN INFORMATION SCSI command (RRTI) 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-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
       http://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 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