1DDPTCTL(8) DDPT DDPTCTL(8)
2
6 ddptctl - helper/auxiliary utility for ddpt
7
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
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 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 The xcopy family of commands are described in the SPC-4 and SBC-3 docu‐
32 ments found at http://www.t10.org .
33
35 Arguments to long options are mandatory for short options as well.
36 -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 -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 -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 -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 -h, --help
67 outputs the usage message summarizing command line options then
68 exits.
69 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -v, --verbose
205 increase the level of verbosity, (i.e. debug output).
206 -V, --version
208 print the version string and then exit.
209 -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
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 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 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 There is a web page discussing ddptctl and ddpt, XCOPY and ODX at
247 http://sg.danny.cz/sg/ddpt_xcopy_odx.html
248
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
255 First issue a PT command without the --immed option so RRTI is called
256 to complete the operation:
257 # ddptctl --pt=0x0,10k,20k,5k --rtf=aa.rt /dev/sdb
259 PT completes with a transfer count of 15360 [0x3c00]
260 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 # ddptctl --rtf=aa.rt --wut=0x0,10k,20k,5k /dev/sdc
266 WUT completes with a transfer count of 15360 [0x3c00]
267 So the copy was successful. Now taking a closer look at the ROD token:
269 # 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 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 To see information about /dev/sdb relevant to ODX, try:
289 # 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 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 # ddptctl --pt=0x0,0x80000 --rtf=aa.rt /dev/sdb
307 PT completes with a transfer count of 524288 [0x80000]
308 # 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 # ddptctl --poll --rtf=aa.rt /dev/sdc
315 RRTI for Write using token: Operation completed without errors
316 transfer count of 524288 [0x80000]
317 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
323 Written by Douglas Gilbert.
324
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
335 ddpt
336ddpt-0.95 December 2014 DDPTCTL(8)