1DDPTCTL(8)                           DDPT                           DDPTCTL(8)
2
3
4

NAME

6       ddptctl - helper/auxiliary utility for ddpt
7

SYNOPSIS

9       ddptctl [--abort] [--all_toks] [--block] [--del_tkn] [--help] [--immed]
10       [--info] [--list_id=LID] [--oir=OIR]  [--poll]  [--pt=GL]  [--readonly]
11       [--receive]  [--rtf=RTF] [--rtype=RTYPE] [--size] [--timeout=ITO[,CMD]]
12       [--verbose] [--version] [--wut=SL] [DEVICE]
13

DESCRIPTION

15       This utility is a helper/auxiliary for the ddpt  utility  which  copies
16       data  between or within SCSI devices (logical units). While ddpt's com‐
17       mand line syntax is modelled on that of  the  POSIX  dd  command,  this
18       utility  has  a  more standard Unix command line syntax with both short
19       and long variants of each option.
20
21       The T10 committee defines a family of SCSI commands for offloaded copy.
22       The central (but not the only) command is EXTENDED COPY often shortened
23       to XCOPY or xcopy. There are now two generations of  xcopy,  the  older
24       one  is  given  the suffix "LID1" and the newer one: "LID4". There is a
25       subset of XCOPY(LID4) that supports disk to disk copies and is based on
26       the  SBC-3  commands:  POPULATE TOKEN (PT) and WRITE USING TOKEN (WUT).
27       ODX is a market name that has become associated with this subset.  This
28       utility  can  issue  PT, WUT and related commands, read the Third Party
29       Copy VPD page and perform several other housekeeping tasks.
30
31       The xcopy family of commands are described in the SPC-4 and SBC-3 docu‐
32       ments found at http://www.t10.org .
33

OPTIONS

35       Arguments to long options are mandatory for short options as well.
36
37       -A, --abort
38              this option will issue the COPY OPERATION ABORT command with the
39              LID given in the  --list_id=LID  option.  If  the  --list_id=LID
40              option is not given then its default LID (257) is used. If there
41              is an xcopy operation ongoing on this I-T nexus (i.e. issued  by
42              this  machine  to any LU sharing the same target) using that LID
43              then the copy is aborted.  Note  there  is  a  sense  key  (COPY
44              ABORTED) indicating some but not all data has been copied due to
45              this action.
46
47       -a, --all_toks
48              send the REPORT ALL ROD TOKENS SCSI command to DEVICE and decode
49              the  response.  An ODX implementation is not required to support
50              this command.
51
52       -B, --block
53              treat DEVICE as a block device when  checking  its  --size.  The
54              default  action  of  this  utility  is to treat DEVICE as a SCSI
55              pass-through device.
56
57       -D, --del_tkn
58              set the DEL_TKN bit in a WUT command (default: clear the DEL_TKN
59              bit).   Since an ODX copy manager deletes the ROD Token when its
60              inactivity time-out is reached, this  option  is  typically  not
61              needed.  It  may be useful for long-lived ROD Tokens that are no
62              longer needed.
63              To delete an unused ROD Token a degenerate scatter list seems to
64              be acceptable (e.g. '--wut=0,0 --del_tkn').
65
66       -h, --help
67              outputs  the usage message summarizing command line options then
68              exits.
69
70       -I, --immed
71              set the IMMED bit in the PT or WUT command. When  given  the  PT
72              and  WUT  commands  return  promptly before the data transfer is
73              complete; then this utility exits. The user should  then  invoke
74              the  utility  again  with the --poll option and the same LID and
75              DEVICE to await completion and receive the final transfer count.
76              The  default action of PT and WUT (i.e.  without this option) is
77              to wait for completion (i.e.  all data transferred or  an  error
78              occurs) before exiting this utility.
79
80       -i, --info
81              when  the  DEVICE  argument  is given then check its Third Party
82              Copy VPD page and print out anything found. Also  check  if  the
83              3PC bit is set in the standard INQUIRY response.
84              If  the DEVICE argument is not given and the --rtf=RTF option is
85              given then decode part of the ROD Token held in the --RTF  file.
86              SPC-4  defines some parts of a ROD Token that can be decoded but
87              does not require the copy manager to set these fields;  so  many
88              fields may appear as zeros. A --RTF file that has been generated
89              by the ddpt  utility  may  contain  multiple  ROD  Tokens,  each
90              optionally  followed  by an 8 byte "number of bytes represented"
91              integer. They are all decoded, based on --RTF file length  which
92              should either be a multiple of 512 or 520 bytes.
93
94       -l, --list_id=LID
95              LID is a list identifier which is used to associate an originat‐
96              ing xcopy command (e.g. PT or WUT) with a follow-up command that
97              retrieves  information  or  aborts  the  operation. T10 requires
98              active LIDs to be unique on a given I-T nexus. An I-T  nexus  is
99              the  current  machine (more precisely a HBA if a machine has two
100              or more) and a specific target which will contain  one  or  more
101              logical  units  (LUs)  of  which DEVICE is one.  If the DEVICE's
102              copy manager feels that rather complex condition  has  not  been
103              met  then  an error is generated with sense data that decodes to
104              "operation in progress". Rather than try  to  work  out  who  is
105              doing what elsewhere, try another LID value.
106              The default value for LID is 257.
107
108       -O, --oir=OIR
109              OIR  is the Offset In ROD, a field in the WUT command. It may be
110              be used together with the --wut=SL option. Its default value  is
111              0 and its units are the logical block size of DEVICE.
112
113       -p, --poll
114              send  RECEIVE ROD TOKEN INFORMATION SCSI commands (RRTIs) to the
115              DEVICE using the LID (i.e. from the --list_id=LID option). If  a
116              copy  status  is  received  indicating the operation is ongoing,
117              then this SCSI command is sent periodically (as suggested by the
118              previous RRTI command or 500 milliseconds) until some other copy
119              status is detected. If the --list_id=LID  option  is  not  given
120              then a LID of 257 is assumed.
121              If the originating xcopy command was POPULATE TOKEN and the RRTI
122              command indicates that it has completed  successfully  then  the
123              associated  ROD Token (returned in the RRTI response) is written
124              to the RTF file. If the --rtf=RTF option is not given  then  the
125              ROD token is written to a file called ddptctl_rod_tok.bin in the
126              current directory.
127
128       -P, --pt=GL
129              send a POPULATE TOKEN (PT) command with the given  gather  list.
130              The  format of GL is given in the NOTES section. If used without
131              the --immed option then this utility, after the PT command  fin‐
132              ishes  successfully,  will  call the RRTI command. When the RRTI
133              command finishes, potentially with a new ROD Token, this utility
134              will  exit.  Prior to that exit, if a new ROD Token is available
135              and the --rtf=RTF option is given then that ROD Token is written
136              to  the  RTF file. If the --rtf=RTF option is not given then the
137              ROD token is written to a file called ddptctl_rod_tok.bin in the
138              current directory.
139              If  the --immed option is given this utility will exit after the
140              PT command finishes. To  complete  the  operation  this  utility
141              should  be  invoked  again  with  the --poll option and the same
142              DEVICE.
143
144       -y, --readonly
145              open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
146              The default is to open it read-write.
147
148       -R, --receive
149              send  the  RECEIVE  ROD TOKEN INFORMATION SCSI command (RRTI) to
150              the DEVICE using the LID (i.e. from the  --list_id=LID  option).
151              If  the  --list_id=LID  option is not given then a LID of 257 is
152              assumed.
153              If the originating xcopy command was POPULATE TOKEN and the RRTI
154              command  indicates  that  it has completed successfully then the
155              associated ROD Token (returned in the RRTI response) is  written
156              to  the  RTF file. If the --rtf=RTF option is not given then the
157              ROD token is written to a file called ddptctl_rod_tok.bin in the
158              current directory.
159
160       -r, --rtf=RTF
161              when  RTF is a file containing an ODX ROD Token or the name of a
162              file the ROD Token is to be written to. A ROD Token used by  ODX
163              is  512  bytes  long.  If  the RTF file was produced by the ddpt
164              utility then it might contain multiple ROD Tokens, each  option‐
165              ally  followed  by  an  8 byte integer containing the "number of
166              bytes represented" by the preceding ROD Token.
167              If an RTF file with multiple ROD Tokens is given to this utility
168              with  --wut=SL  then only the first ROD Token is used. If an RTF
169              file is being decoded (i.e. no DEVICE argument given)  then  all
170              ROD Tokens are decoded.
171
172       -t, --rtype=RTYPE
173              where  RTYPE  is  the ROD Type, a field in the PT command (apart
174              from "zero"). The default value (0) indicates that the copy man‐
175              ager  (in  the DEVICE) decides. RTYPE can be a decimal number, a
176              hex number (prefixed by 0x or with a "h"  appended)  or  one  of
177              "pit-def",  "pit-vuln",  "pit-pers",  "pit-any"  or  "zero". The
178              final truncated word can be spelt out  (e.g.  "pit-vulnerable").
179              The "pit-" lead-in stands for "point in time" copy.
180              The  "zero"  is a special case and is not given to a PT command.
181              Instead it causes a special Block Device Zero Token to  be  cre‐
182              ated  that  can be used with the --wut=SL option to write blocks
183              of zeros to the given DEVICE.
184
185       -s, --size
186              prints the number of blocks and the size of each block  for  the
187              given DEVICE. Protection information is printed if available. By
188              default uses the pass-through interface and  the  READ  CAPACITY
189              command  to  obtain  this  information. If the --block option is
190              given then the block layer in the OS is query for size  informa‐
191              tion (and protection information is not reported).
192
193       -T, --timeout=ITO[,CMD]
194              where  ITO  is  the inactivity timeout (units: seconds) given to
195              the PT command. The default is 0 in which case the copy  manager
196              uses  its own default which is shown in the Third party Copy VPD
197              page.
198              CMD is the SCSI command timeout (units: seconds) applied to SCSI
199              commands  issued  by  this utility; default is 0 which is trans‐
200              lated to 600 seconds for originating xcopy commands (e.g. PT and
201              WUT) and 60 seconds for other commands. Best not to trigger com‐
202              mand timeouts.
203
204       -v, --verbose
205              increase the level of verbosity, (i.e. debug output).
206
207       -V, --version
208              print the version string and then exit.
209
210       -w, --wut=SL
211              send a WRITE USING TOKEN (WUT) command with  the  given  scatter
212              list.  The  format  of  SL  is  given in the NOTES section. This
213              option requires the --rtf=RTF option to supply the ROD Token. If
214              used  without the --immed option then after the WUT command fin‐
215              ishes successfully this utility will call the RRTI command. When
216              the RRTI command finishes this utility will exit.
217              If  the --immed option is given this utility will exit after the
218              WUT command finishes. To complete  the  operation  this  utility
219              should  be  invoked  again  with  the --poll option and the same
220              DEVICE.
221

NOTES

223       The scatter gather list given to the --pt=GL and  --wut=SL  options  in
224       the  simplest case contains a pair a numbers, separated by a comma. The
225       first number is the starting LBA and the second number is the number of
226       blocks  (no bigger than 32 bits) to read to or write from that starting
227       LBA. Another pair of numbers can appear after that forming  the  second
228       element of a scatter gather list. Starting LBAs can be in any order but
229       T10 prohibits any logical block appearing more than once in  a  scatter
230       gather list.
231
232       Scatter gather lists can be placed in a file or read from stdin. A file
233       name referring to a file containing a scatter gather list  must  follow
234       the  "@"  character (e.g. --pt=@my_sgl.txt"). Reading a list from stdin
235       is indicated by "@-" or "-" (e.g. "--pt=-"). Scatter gather lists in  a
236       file  have  a  looser  format and can take spaces and tabs as well as a
237       comma as separators. Anything from and including a "#"  on  a  line  is
238       ignored.
239
240       Both  the  PT  and WUT commands are issued "as is" without checking the
241       Third Party Copy VPD page. The copy manager may well reject these  com‐
242       mands  (with  exit  status  51: invalid field in parameter list) if the
243       maximum range descriptors field or  the  maximum  token  transfer  size
244       field are exceeded.
245
246       There  is  a  web  page  discussing  ddptctl and ddpt, XCOPY and ODX at
247       http://sg.danny.cz/sg/ddpt_xcopy_odx.html
248

EXIT STATUS

250       The exit status of ddptctl is 0 when it is  successful.  Otherwise  the
251       exit status for this utility is the same as that for ddpt. See the EXIT
252       STATUS section in the ddpt man page.
253

EXAMPLES

255       First issue a PT command without the --immed option so RRTI  is  called
256       to complete the operation:
257
258         # ddptctl --pt=0x0,10k,20k,5k --rtf=aa.rt /dev/sdb
259         PT completes with a transfer count of 15360 [0x3c00]
260
261       The transfer count (10k + 5k == 15360) indicates the operation was suc‐
262       cessful and the ROD Token is in the aa.rt file. Now use that ROD  Token
263       to write to the same locations on /dev/sdc:
264
265         # ddptctl --rtf=aa.rt --wut=0x0,10k,20k,5k /dev/sdc
266         WUT completes with a transfer count of 15360 [0x3c00]
267
268       So the copy was successful. Now taking a closer look at the ROD token:
269
270         # ddptctl --info --rtf=aa.rt
271         Decoding information from ROD Token:
272           ROD type: point in time copy - default [0x800000]
273           Copy manager ROD Token identifier: 0x520000710000000c
274           Creator Logical Unit descriptor:
275             Peripheral Device type: 0x0
276             Relative initiator port identifier: 0x0
277             designator_type: NAA,  code_set: Binary
278             associated with the addressed logical unit
279               0x60002ac0000000000000000c00009502
280           Number of bytes represented: 0 [0x0]
281           Device  type specific data (for disk) has block size of 0; unlikely
282       so skip
283           Target device descriptor: unexpected designator type [0x0]
284
285       T10 does not require implementations to supply much of the above  (only
286       the ROD type and the token length) so expect to see some empty fields.
287
288       To see information about /dev/sdb relevant to ODX, try:
289
290         # ddptctl --info /dev/sdb
291           /dev/sdb  [readcap]:  num_blks=209715200 [0xc800000], blk_size=512,
292       107 GB
293         3PC (third party copy) bit set in standard INQUIRY response
294          Third Party Copy VPD page:
295          Block Device ROD Token Limits:
296           Maximum Range Descriptors: 8
297           Maximum Inactivity Timeout: 60 seconds
298           Default Inactivity Timeout: 30 seconds
299           Maximum Token Transfer Size: 524288
300           Optimal Transfer Count: 524288
301
302       That maximum token transfer size [524288 blocks each  512  bytes  gives
303       256  MB]  is the largest size a ROD Token created by /dev/sdb can hold.
304       Use that and show the --immed option on the destination:
305
306         # ddptctl --pt=0x0,0x80000 --rtf=aa.rt /dev/sdb
307         PT completes with a transfer count of 524288 [0x80000]
308
309         # ddptctl --rtf=aa.rt --wut=0x0,0x80000 --immed /dev/sdc
310         Started ODX Write Using Token command in immediate mode.
311         User may need --list_id=257 on following invocation with --receive or
312         --poll for completion
313
314         # ddptctl --poll --rtf=aa.rt /dev/sdc
315         RRTI for Write using token: Operation completed without errors
316           transfer count of 524288 [0x80000]
317
318       To copy larger amounts and/or with a larger number  of  scatter  gather
319       elements  (than 8 "range descriptors") use one of the four ODX variants
320       in the ddpt utility.
321

AUTHORS

323       Written by Douglas Gilbert.
324

REPORTING BUGS

326       Report bugs to <dgilbert at interlog dot com>.
327
329       Copyright © 2014 Douglas Gilbert
330       This software is distributed under a FreeBSD license. There is NO  war‐
331       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
332       POSE.
333

SEE ALSO

335       ddpt
336
337
338
339ddpt-0.95                        December 2014                      DDPTCTL(8)
Impressum