Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DDPTCTL(8)			     DDPT			    DDPTCTL(8)

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 com-
       mand 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 docu-
       ments 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  op-
	      tion  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 de-
	      fault  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  op-
	      tionally followed	by an 8	byte "number of	bytes represented" in-
	      teger. 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 originat-
	      ing xcopy	command	(e.g. PT or WUT) with a	follow-up command that
	      retrieves	 information or	aborts the operation. T10 requires ac-
	      tive 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 logi-
	      cal  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 "op-
	      eration 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  fin-
	      ishes  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 DE-
	      VICE.

       -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  option-
	      ally  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 man-
	      ager  (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 fi-
	      nal 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  cre-
	      ated  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  informa-
	      tion (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	trans-
	      lated to 600 seconds for originating xcopy commands (e.g.	PT and
	      WUT) and 60 seconds for other commands. Best not to trigger com-
	      mand 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 op-
	      tion requires the	--rtf=RTF option to supply the ROD  Token.  If
	      used  without the	--immed	option then after the WUT command fin-
	      ishes 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 DE-
	      VICE.

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

       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  com-
       mands  (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 suc-
       cessful 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 (C) 2014 Douglas Gilbert
       This software is	distributed under a FreeBSD license. There is NO  war-
       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-
       POSE.

SEE ALSO
       ddpt

ddpt-0.95			 December 2014			    DDPTCTL(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NOTES | EXIT STATUS | EXAMPLES | AUTHORS | REPORTING BUGS | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ddptctl&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help