Provided by: ddpt_0.95-1_amd64 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]  [--readonly]  [--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 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').

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

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