1DDPTCTL(8) DDPT DDPTCTL(8)
2
6 ddptctl - helper/auxiliary utility for ddpt
7
9 ddptctl [--abort] [--all_toks] [--block] [--del_tkn] [--flexible]
10 [--help] [--immed] [--info] [--list_id=LID] [--oir=OIR] [--poll]
11 [--pt=GL] [--readonly] [--prefer_rcs] [--receive] [--rtf=RTF]
12 [--rtype=RTYPE] [--size] [--timeout=ITO[,CMD]] [--verbose] [--version]
13 [--wut=SL] [DEVICE]
14
16 This utility is a helper/auxiliary for the ddpt utility which copies
17 data between or within SCSI devices (logical units). While ddpt's com‐
18 mand line syntax is modelled on that of the POSIX dd command, this
19 utility has a more standard Unix command line syntax with both short
20 and long variants of each option.
21 The T10 committee defines a family of SCSI commands for offloaded copy.
23 The central (but not the only) command is EXTENDED COPY often shortened
24 to XCOPY or xcopy. There are now two generations of xcopy, the older
25 one is given the suffix "LID1" and the newer one: "LID4". There is a
26 subset of XCOPY(LID4) that supports disk to disk copies and is based on
27 the SBC-3 commands: POPULATE TOKEN (PT) and WRITE USING TOKEN (WUT).
28 ODX is a market name that has become associated with this subset. This
29 utility can issue PT, WUT and related commands, read the Third Party
30 Copy VPD page and perform several other housekeeping tasks.
31 The xcopy family of commands are described in the SPC-4,5 and SBC-3,4
33 documents found at https://www.t10.org .
34 Apart from PT and WUT, other command abbreviations used below are RRTI
36 for the RECEIVE ROD TOKEN INFORMATION command and RCS for the RECEIVE
37 COPY STATUS(LID4) command.
38
40 Arguments to long options are mandatory for short options as well.
41 -A, --abort
43 this option will issue the COPY OPERATION ABORT command with the
44 LID given in the --list_id=LID option. If the --list_id=LID op‐
45 tion is not given then its default LID (257) is used. If there
46 is an xcopy operation ongoing on this I-T nexus (i.e. issued by
47 this machine to any LU sharing the same target) using that LID
48 then the copy is aborted. Note there is a sense key (COPY
49 ABORTED) indicating some but not all data has been copied due to
50 this action.
51 -a, --all_toks
53 send the REPORT ALL ROD TOKENS SCSI command to DEVICE and decode
54 the response. An ODX implementation is not required to support
55 this command.
56 -B, --block
58 treat DEVICE as a block device when checking its --size. The de‐
59 fault action of this utility is to treat DEVICE as a SCSI
60 pass-through device.
61 -D, --del_tkn
63 set the DEL_TKN bit in a WUT command (default: clear the DEL_TKN
64 bit). Since an ODX copy manager deletes the ROD Token when its
65 inactivity time-out is reached, this option is typically not
66 needed. It may be useful for long-lived ROD Tokens that are no
67 longer needed.
68 To delete an unused ROD Token a degenerate scatter list seems to
69 be acceptable (e.g. '--wut=0,0 --del_tkn').
70 -f, --flexible
72 this option currently only effects the parsing of sgl_s in files
73 that are in hexadecimal plus they have a leading line with 'HEX'
74 in them. Without this option any such line must be invoked with
75 'H@' before the filename; in other words the 'H' in the invoca‐
76 tion needs to match the HEX in the file. With this option a sgl
77 in a file can be invoked with '@' and if a line with HEX is
78 parsed before any LBA,NUM pairs then it switches to hexadecimal
79 mode; so all the parsed LBA,NUM pairs are assumed to be in hexa‐
80 decimal.
81 -h, --help
83 outputs the usage message summarizing command line options then
84 exits.
85 -I, --immed
87 set the IMMED bit in the PT or WUT command. When given the PT
88 and WUT commands return promptly before the data transfer is
89 complete; then this utility exits. The user should then invoke
90 the utility again with the --poll option and the same LID and
91 DEVICE to await completion and receive the final transfer count.
92 The default action of PT and WUT (i.e. without this option) is
93 to wait for completion (i.e. all data transferred or an error
94 occurs) before exiting this utility.
95 -i, --info
97 when the DEVICE argument is given then check its Third Party
98 Copy VPD page and print out anything found. Also check if the
99 3PC bit is set in the standard INQUIRY response.
100 If the DEVICE argument is not given and the --rtf=RTF option is
101 given then decode part of the ROD Token held in the --RTF file.
102 SPC-4 defines some parts of a ROD Token that can be decoded but
103 does not require the copy manager to set these fields; so many
104 fields may appear as zeros. A --RTF file that has been generated
105 by the ddpt utility may contain multiple ROD Tokens, each op‐
106 tionally followed by an 8 byte "number of bytes represented" in‐
107 teger. They are all decoded, based on --RTF file length which
108 should either be a multiple of 512 or 520 bytes.
109 -l, --list_id=LID
111 LID is a list identifier which is used to associate an originat‐
112 ing xcopy command (e.g. PT or WUT) with a follow-up command that
113 retrieves associated information or aborts the operation. T10
114 requires each active LID to be unique on a given I-T nexus. An
115 I-T nexus is the current machine (more precisely a HBA if a ma‐
116 chine has two or more) and a specific target which will contain
117 one or more logical units (LUs) of which DEVICE is one. If the
118 DEVICE's copy manager feels that rather complex condition has
119 not been met then an error is generated with sense data that de‐
120 codes to "operation in progress". Rather than try to work out
121 who is doing what elsewhere, try another LID value.
122 The default value for LID is 257.
123 -O, --oir=OIR
125 OIR is the Offset In ROD, a field in the WUT command. It may be
126 be used together with the --wut=SL option. Its default value is
127 0 and its units are the logical block size of DEVICE.
128 -p, --poll
130 send RRTI (or RCS) command to the DEVICE using the LID (i.e.
131 from the --list_id=LID option). If a copy status is received in‐
132 dicating the operation is ongoing, then this SCSI command is
133 sent periodically (as suggested by the previous RRTI (or RCS)
134 command or every 500 milliseconds) until some other copy status
135 is detected. If the --list_id=LID option is not given then a LID
136 of 257 is assumed.
137 If the originating xcopy command was POPULATE TOKEN and the RRTI
138 command indicates that it has completed successfully then the
139 associated ROD Token (returned in the RRTI response) is written
140 to the RTF file. If the --rtf=RTF option is not given then the
141 ROD token is written to a file called ddptctl_rod_tok.bin in the
142 current directory.
143 -q, --prefer_rcs
145 prefers using the RECEIVE COPY STATUS (RCS) command over the
146 RRTI command which is the default. This only should be done fol‐
147 lowing a WUT command since after a PT command, the RRTI command
148 is needed to fetch the ROD tokane.
149 -P, --pt=GL
151 send a POPULATE TOKEN (PT) command with the given gather list.
152 The format of GL is given in the NOTES section. If used without
153 the --immed option then this utility, after the PT command fin‐
154 ishes successfully, will call the RRTI command. When the RRTI
155 command finishes, potentially with a new ROD Token, this utility
156 will exit. Prior to that exit, if a new ROD Token is available
157 and the --rtf=RTF option is given then that ROD Token is written
158 to the RTF file. If the --rtf=RTF option is not given then the
159 ROD token is written to a file called ddptctl_rod_tok.bin in the
160 current directory.
161 If the --immed option is given this utility will exit after the
162 PT command finishes. To complete the operation this utility
163 should be invoked again with the --poll option and the same DE‐
164 VICE.
165 -y, --readonly
167 open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
168 The default is to open it read-write.
169 -R, --receive
171 send the RRTI (or RCS) SCSI command to the DEVICE using the LID
172 (i.e. from the --list_id=LID option). If the --list_id=LID op‐
173 tion is not given then a LID of 257 is assumed.
174 If the originating xcopy command was POPULATE TOKEN and the RRTI
175 command indicates that it has completed successfully then the
176 associated ROD Token (returned in the RRTI response) is written
177 to the RTF file. If the --rtf=RTF option is not given then the
178 ROD token is written to a file called ddptctl_rod_tok.bin in the
179 current directory.
180 -r, --rtf=RTF
182 when RTF is a file containing an ODX ROD Token or the name of a
183 file the ROD Token is to be written to. A ROD Token used by ODX
184 is 512 bytes long. If the RTF file was produced by the ddpt
185 utility then it might contain multiple ROD Tokens, each option‐
186 ally followed by an 8 byte integer containing the "number of
187 bytes represented" by the preceding ROD Token.
188 If an RTF file with multiple ROD Tokens is given to this utility
189 with --wut=SL then only the first ROD Token is used. If an RTF
190 file is being decoded (i.e. no DEVICE argument given) then all
191 ROD Tokens are decoded.
192 -t, --rtype=RTYPE
194 where RTYPE is the ROD Type, a field in the PT command (apart
195 from "zero"). The default value (0) indicates that the copy man‐
196 ager (in the DEVICE) decides. RTYPE can be a decimal number, a
197 hex number (prefixed by 0x or with a "h" appended) or one of
198 "pit-def", "pit-vuln", "pit-pers", "pit-cow", "pit-any" or
199 "zero". The final truncated word can be spelt out (e.g.
200 "pit-vulnerable"). The "pit-" lead-in stands for "point in
201 time" copy.
202 The "zero" is a special case and is not given to a PT command.
203 Instead it causes a special Block Device Zero Token to be cre‐
204 ated that can be used with the --wut=SL option to write blocks
205 of zeros to the given DEVICE.
206 -s, --size
208 prints the number of blocks and the size of each block for the
209 given DEVICE. Protection information is printed if available. By
210 default uses the pass-through interface and the READ CAPACITY
211 command to obtain this information. If the --block option is
212 given then the block layer in the OS is query for size informa‐
213 tion (and protection information is not reported).
214 -T, --timeout=ITO[,CMD]
216 where ITO is the inactivity timeout (units: seconds) given to
217 the PT command. The default is 0 in which case the copy manager
218 uses its own default which is shown in the Third party Copy VPD
219 page.
220 CMD is the SCSI command timeout (units: seconds) applied to SCSI
221 commands issued by this utility; default is 0 which is trans‐
222 lated to 600 seconds for originating xcopy commands (e.g. PT and
223 WUT) and 60 seconds for other commands. Best not to trigger com‐
224 mand timeouts.
225 -v, --verbose
227 increase the level of verbosity, (i.e. debug output).
228 -V, --version
230 print the version string and then exit.
231 -w, --wut=SL
233 send a WRITE USING TOKEN (WUT) command with the given scatter
234 list. The format of SL is given in the NOTES section. This op‐
235 tion requires the --rtf=RTF option to supply the ROD Token. If
236 used without the --immed option then after the WUT command fin‐
237 ishes successfully this utility will call the RRTI command. When
238 the RRTI command finishes this utility will exit.
239 If the --immed option is given this utility will exit after the
240 WUT command finishes. To complete the operation this utility
241 should be invoked again with the --poll option and the same DE‐
242 VICE.
243
245 The scatter gather list given to the --pt=GL and --wut=SL options in
246 the simplest case contains a pair a numbers, separated by a comma. The
247 first number is the starting LBA and the second number is the number of
248 blocks (no bigger than 32 bits) to read to or write from that starting
249 LBA. Another pair of numbers can appear after that forming the second
250 element of a scatter gather list. Starting LBAs can be in any order but
251 T10 prohibits any logical block appearing more than once in a scatter
252 gather list.
253 Scatter gather lists can be placed in a file or read from stdin. A file
255 name referring to a file containing a scatter gather list must follow
256 the "@" character (e.g. --pt=@my_sgl.txt"). Reading a list from stdin
257 is indicated by "@-" or "-" (e.g. "--pt=-"). Scatter gather lists in a
258 file have a looser format and can take spaces and tabs as well as a
259 comma as separators. Anything from and including a "#" on a line is ig‐
260 nored.
261 Both the PT and WUT commands are issued "as is" without checking the
263 Third Party Copy VPD page. The copy manager may well reject these com‐
264 mands (with exit status 51: invalid field in parameter list) if the
265 maximum range descriptors field or the maximum token transfer size
266 field are exceeded.
267 There is a web page discussing ddptctl and ddpt, XCOPY and ODX at
269 https://sg.danny.cz/sg/ddpt_xcopy_odx.html
270
272 The exit status of ddptctl is 0 when it is successful. Otherwise the
273 exit status for this utility is the same as that for ddpt. See the EXIT
274 STATUS section in the ddpt man page.
275
277 First issue a PT command without the --immed option so RRTI is called
278 to complete the operation:
279 # ddptctl --pt=0x0,10k,20k,5k --rtf=aa.rt /dev/sdb
281 PT completes with a transfer count of 15360 [0x3c00]
282 The transfer count (10k + 5k == 15360) indicates the operation was suc‐
284 cessful and the ROD Token is in the aa.rt file. Now use that ROD Token
285 to write to the same locations on /dev/sdc:
286 # ddptctl --rtf=aa.rt --wut=0x0,10k,20k,5k /dev/sdc
288 WUT completes with a transfer count of 15360 [0x3c00]
289 So the copy was successful. Now taking a closer look at the ROD token:
291 # ddptctl --info --rtf=aa.rt
293 Decoding information from ROD Token:
294 ROD type: point in time copy - default [0x800000]
295 Copy manager ROD Token identifier: 0x520000710000000c
296 Creator Logical Unit descriptor:
297 Peripheral Device type: 0x0
298 Relative initiator port identifier: 0x0
299 designator_type: NAA, code_set: Binary
300 associated with the addressed logical unit
301 0x60002ac0000000000000000c00009502
302 Number of bytes represented: 0 [0x0]
303 Device type specific data (for disk) has block size of 0; unlikely
304 so skip
305 Target device descriptor: unexpected designator type [0x0]
306 T10 does not require implementations to supply much of the above (only
308 the ROD type and the token length) so expect to see some empty fields.
309 To see information about /dev/sdb relevant to ODX, try:
311 # ddptctl --info /dev/sdb
313 /dev/sdb [readcap]: num_blks=209715200 [0xc800000], blk_size=512,
314 107 GB
315 3PC (third party copy) bit set in standard INQUIRY response
316 Third Party Copy VPD page:
317 Block Device ROD Token Limits:
318 Maximum Range Descriptors: 8
319 Maximum Inactivity Timeout: 60 seconds
320 Default Inactivity Timeout: 30 seconds
321 Maximum Token Transfer Size: 524288
322 Optimal Transfer Count: 524288
323 That maximum token transfer size [524288 blocks each 512 bytes gives
325 256 MB] is the largest size a ROD Token created by /dev/sdb can hold.
326 Use that and show the --immed option on the destination:
327 # ddptctl --pt=0x0,0x80000 --rtf=aa.rt /dev/sdb
329 PT completes with a transfer count of 524288 [0x80000]
330 # ddptctl --rtf=aa.rt --wut=0x0,0x80000 --immed /dev/sdc
332 Started ODX Write Using Token command in immediate mode.
333 User may need --list_id=257 on following invocation with --receive or
334 --poll for completion
335 # ddptctl --poll --rtf=aa.rt /dev/sdc
337 RRTI for Write using token: Operation completed without errors
338 transfer count of 524288 [0x80000]
339 To copy larger amounts and/or with a larger number of scatter gather
341 elements (than 8 "range descriptors") use one of the four ODX variants
342 in the ddpt utility.
343
345 Written by Douglas Gilbert.
346
348 Report bugs to <dgilbert at interlog dot com>.
349
351 Copyright © 2014-2021 Douglas Gilbert
352 This software is distributed under a FreeBSD license. There is NO war‐
353 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
354 POSE.
355
357 ddpt(8), ddpt_sgl(8)
358ddpt-0.97 April 2021 DDPTCTL(8)