unplugged-system/external/sg3_utils/doc/sg_write_same.8

.TH SG_WRITE_SAME "8" "June 2020" "sg3_utils\-1.45" SG3_UTILS
.SH NAME
sg_write_same \- send SCSI WRITE SAME command
.SH SYNOPSIS
.B sg_write_same
[\fI\-\-10\fR] [\fI\-\-16\fR] [\fI\-\-32\fR] [\fI\-\-anchor\fR]
[\fI\-\-ff\fR] [\fI\-\-grpnum=GN\fR] [\fI\-\-help\fR] [\fI\-\-in=IF\fR]
[\fI\-\-lba=LBA\fR] [\fI\-\-lbdata\fR] [\fI\-\-num=NUM\fR]
[\fI\-\-ndob\fR] [\fI\-\-pbdata\fR] [\fI\-\-timeout=TO\fR]
[\fI\-\-unmap\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
[\fI\-\-wrprotect=WPR\fR] [\fI\-\-xferlen=LEN\fR]
\fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
Send the SCSI WRITE SAME (10, 16 or 32 byte) command to \fIDEVICE\fR. This
command writes the given block \fINUM\fR times to consecutive blocks on
the \fIDEVICE\fR starting at logical block address \fILBA\fR.
.PP
The length of the block to be written multiple times is obtained from either
the \fILEN\fR argument, or the length of the given input file \fIIF\fR,
or by calling READ CAPACITY(16) on \fIDEVICE\fR. The contents of the
block to be written are obtained from the input file \fIIF\fR or
zeros are used. If READ CAPACITY(16) is called (which implies \fIIF\fR
was not given) and the PROT_EN bit is set then an extra 8 bytes (i.e.
more than the logical block size) of 0xff are sent. If READ CAPACITY(16)
fails then READ CAPACITY(10) is used to determine the block size.
.PP
If neither \fI\-\-10\fR, \fI\-\-16\fR nor \fI\-\-32\fR is given then
WRITE SAME(10) is sent unless one of the following conditions is met.
If \fILBA\fR (plus \fINUM\fR) exceeds 32 bits, \fINUM\fR exceeds 65535,
or the \fI\-\-unmap\fR option is given then WRITE SAME(16) is sent.
The \fI\-\-10\fR, \fI\-\-16\fR and \fI\-\-32\fR options are mutually
exclusive.
.PP
SBC\-3 revision 35d introduced a "No Data\-Out Buffer" (NDOB) bit which, if
set, bypasses the requirement to send a single block of data to the
\fIDEVICE\fR together with the command. Only WRITE SAME (16 and 32 byte)
support the NDOB bit. If given, a user block of zeros is assumed; if
required, protection information of 0xffs is assumed.
.PP
In SBC\-3 revision 26 the UNMAP and ANCHOR bits were added to the
WRITE SAME (10) command. Since the UNMAP bit has been in WRITE SAME (16)
and WRITE SAME (32) since SBC\-3 revision 18, the lower of the two (i.e.
WRITE SAME (16)) is the default when the \fI\-\-unmap\fR option is given.
To send WRITE SAME (10) use the \fI\-\-10\fR option.
.PP
.B Take care:
The WRITE SAME(10, 16 and 32) commands may interpret a \fINUM\fR of zero as
write to the end of \fIDEVICE\fR. This utility defaults \fINUM\fR to 1 .
The WRITE SAME commands have no IMMED bit so if \fINUM\fR is large (or
zero) then an invocation of this utility could take a long time, potentially
as long as a FORMAT UNIT command. In such situations the command timeout
value \fITO\fR may need to be increased from its default value of 60
seconds. In SBC\-3 revision 26 the WSNZ (write same no zero) bit was added
to the Block Limits VPD page [0xB0]. If set the WRITE SAME commands will not
accept a \fINUM\fR of zero. The same SBC\-3 revision added the "Maximum
Write Same Length" field to the Block Limits VPD page.
.PP
The Logical Block Provisioning VPD page [0xB2] contains the LBPWS and
LBPWS10 bits. If LBPWS is set then WRITE SAME (16) supports the UNMAP bit.
If LBPWS10 is set then WRITE SAME (10) supports the UNMAP bit. If either
LBPWS or LBPWS10 is set and the WRITE SAME (32) is supported then WRITE
SAME (32) supports the UNMAP bit.
.PP
As a precaution against an accidental 'sg_write_same /dev/sda' (for example)
overwriting LBA 0 on /dev/sda with zeros, at least one of the
\fI\-\-in=IF\fR, \fI\-\-lba=LBA\fR or \fI\-\-num=NUM\fR options must be
given. Obviously this utility can destroy a lot of user data so check the
options carefully.
.SH OPTIONS
Arguments to long options are mandatory for short options as well.
The options are arranged in alphabetical order based on the long
option name.
.TP
\fB\-R\fR, \fB\-\-10\fR
send a SCSI WRITE SAME (10) command to \fIDEVICE\fR. The ability to
set the \fI\-\-unmap\fR (and \fI\-\-anchor\fR) options to this command
was added in SBC\-3 revision 26.
.TP
\fB\-S\fR, \fB\-\-16\fR
send a SCSI WRITE SAME (16) command to \fIDEVICE\fR.
.TP
\fB\-T\fR, \fB\-\-32\fR
send a SCSI WRITE SAME (32) command to \fIDEVICE\fR.
.TP
\fB\-a\fR, \fB\-\-anchor\fR
sets the ANCHOR bit in the cdb. Introduced in SBC\-3 revision 22.
That draft requires the \fI\-\-unmap\fR option to also be specified.
.TP
\fB\-f\fR, \fB\-\-ff\fR
the data\-out buffer sent with this command is initialized with 0xff bytes
when this option is given.
.TP
\fB\-g\fR, \fB\-\-grpnum\fR=\fIGN\fR
sets the 'Group number' field to \fIGN\fR. Defaults to a value of zero.
\fIGN\fR should be a value between 0 and 63.
.TP
\fB\-h\fR, \fB\-\-help\fR
output the usage message then exit.
.TP
\fB\-i\fR, \fB\-\-in\fR=\fIIF\fR
read data (binary) from file named \fIIF\fR and use it as the data\-out
buffer for the SCSI WRITE SAME command. The length of the data\-out buffer
is \fI\-\-xferlen=LEN\fR or, if that is not given, the length of the \fIIF\fR
file. If \fIIF\fR is "\-" then stdin is read. If this option and the
\fI\-\-ff\fR are not given then 0x00 bytes are used as fill with the length
of the data\-out buffer obtained from \fI\-\-xferlen=LEN\fR or by calling
READ CAPACITY(16 or 10).  If the response to READ CAPACITY(16) has the
PROT_EN bit set then data\- out buffer size is modified accordingly with
the last 8 bytes set to 0xff.
.TP
\fB\-l\fR, \fB\-\-lba\fR=\fILBA\fR
where \fILBA\fR is the logical block address to start the WRITE SAME command.
Defaults to lba 0 which is a dangerous block to overwrite on a disk that is
in use. Assumed to be in decimal unless prefixed with '0x' or has a
trailing 'h'.
.TP
\fB\-L\fR, \fB\-\-lbdata\fR
sets the LBDATA bit in the WRITE SAME cdb. This bit was made obsolete in
sbc3r32 in September 2012.
.TP
\fB\-N\fR, \fB\-\-ndob\fR
sets the NDOB bit in the WRITE SAME (16 and 32 byte) commands. NDOB stands
for No Data\-Out Buffer. Default is to clear this bit. When this option
is given then \fI\-\-in=IF\fR is not allowed and \fI\-\-xferlen=LEN\fR can
only be given if \fILEN\fR is 0 .
.br
By default zeros are written in each block, but it is possible that
the "provisioning initialization pattern" is written depending on other
settings.
.TP
\fB\-n\fR, \fB\-\-num\fR=\fINUM\fR
where \fINUM\fR is the number of blocks, starting at \fILBA\fR, to write the
data\-out buffer to. The default value for \fINUM\fR is 1. The value
corresponds to the 'Number of logical blocks' field in the WRITE SAME cdb.
.br
Note that a value of 0 in \fINUM\fR may be interpreted as write the data\-out
buffer on every block starting at \fILBA\fR to the end of the \fIDEVICE\fR.
If the WSNZ bit (introduced in sbc3r26, January 2011) in the Block Limits VPD
page is set then the value of 0 is disallowed, yielding an Invalid request
sense key.
.TP
\fB\-P\fR, \fB\-\-pbdata\fR
sets the PBDATA bit in the WRITE SAME cdb. This bit was made obsolete in
sbc3r32 in September 2012.
.TP
\fB\-t\fR, \fB\-\-timeout\fR=\fITO\fR
where \fITO\fR is the command timeout value in seconds. The default value is
60 seconds. If \fINUM\fR is large (or zero) a WRITE SAME command may require
considerably more time than 60 seconds to complete.
.TP
\fB\-U\fR, \fB\-\-unmap\fR
sets the UNMAP bit in the WRITE SAME(10, 16 and 32) cdb. See UNMAP section
below.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase the degree of verbosity (debug messages).
.TP
\fB\-V\fR, \fB\-\-version\fR
output version string then exit.
.TP
\fB\-w\fR, \fB\-\-wrprotect\fR=\fIWPR\fR
sets the "Write protect" field in the WRITE SAME cdb to \fIWPR\fR. The
default value is zero. \fIWPR\fR should be a value between 0 and 7.
When \fIWPR\fR is 1 or greater, and the disk's protection type is 1 or
greater, then 8 extra bytes of protection information are expected or
generated (to place in the command's data\-out buffer).
.TP
\fB\-x\fR, \fB\-\-xferlen\fR=\fILEN\fR
where \fILEN\fR is the data\-out buffer length. Defaults to the length of
the \fIIF\fR file or, if that is not given, then the READ CAPACITY(16 or 10)
command is used to find the 'Logical block length in bytes'. That figure
may be increased by 8 bytes if the \fIDEVICE\fR's protection type is 1 or
greater and the WRPROTECT field (see \fI\-\-wrprotect=WPR\fR) is 1 or
greater. If both this option and the \fIIF\fR option are given and
\fILEN\fR exceeds the length of the \fIIF\fR file then \fILEN\fR is the
data\-out buffer length with zeros used as pad bytes.
.SH UNMAP
Logical block provisioning is a new term introduced in SBC\-3 revision 25
for the ability to mark blocks as unused. For large storage arrays, it is a
way to provision less physical storage than the READ CAPACITY command reports
is available, potentially allocating more physical storage when WRITE
commands require it. For flash memory (e.g. SSD drives) it is a way of
potentially saving power (and perhaps access time) when it is known large
sections (or almost all) of the flash memory is not in use. SSDs need wear
levelling algorithms to have acceptable endurance and typically over
provision to simplify those algorithms; hence they typically contain more
physical flash storage than their logical size would dictate.
.PP
Support for logical block provisioning is indicated by the LBPME bit being
set in the READ CAPACITY(16) command response (see the sg_readcap utility).
That implies at least one of the UNMAP or WRITE SAME(16) commands is
implemented. If the UNMAP command is implemented then
the "Maximum unmap LBA count" and "Maximum unmap block descriptor count"
fields in the Block Limits VPD page should both be greater than zero. The
READ CAPACITY(16) command response also contains a LBPRZ bit which if set
means that if unmapped blocks are read then zeros will be returned for the
data (and if protection information is active, 0xff bytes are returned for
that). In SBC\-3 revision 27 the same LBPRZ bit was added to the Logical
Block Provisioning VPD page.
.PP
In SBC\-3 revision 25 the LBPU and ANC_SUP bits where added to the
Logical Block Provisioning VPD page. When LBPU is set it indicates that
the device supports the UNMAP command (see the sg_unmap utility). When the
ANC_SUP bit is set it indicates the device supports anchored LBAs.
.PP
When the UNMAP bit is set in the cdb then the data\-out buffer is also sent.
Additionally the data section of that data\-out buffer should be full of 0x0
bytes while the data protection block, 8 bytes at the end if present, should
be set to 0xff bytes. If these conditions are not met and the LBPRZ bit is
set then the UNMAP bit is ignored and the data\-out buffer is written to the
\fIDEVICE\fR as if the UNMAP bit was zero. In the absence of the
\fI\-\-in=IF\fR option, this utility will attempt build a data\-out buffer
that meets the requirements for the UNMAP bit in the cdb to be acted on by
the \fIDEVICE\fR.
.PP
Logical blocks may also be unmapped by the SCSI UNMAP and FORMAT UNIT
commands (see the sg_unmap and sg_format utilities).
.PP
The unmap capability in SCSI is closely related to the ATA DATA SET
MANAGEMENT command with the "Trim" bit set. That ATA trim capability does
not interact well with SATA command queueing known as NCQ. T13 have
introduced a new command called the SFQ DATA SET MANAGEMENT command also
with a the "Trim" bit to address that problem. The SCSI WRITE SAME with
the UNMAP bit set and the UNMAP commands do not have any problems with
SCSI queueing.
.SH NOTES
Various numeric arguments (e.g. \fILBA\fR) may include multiplicative
suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
in the sg3_utils(8) man page.
.PP
In Linux, prior to lk 3.17, the sg driver did not support cdb sizes greater
than 16 bytes. Hence a device node like /dev/sg1 which is associated with
the sg driver would fail with this utility if the \fI\-\-32\fR option was
given (or implied by other options). The bsg driver with device nodes like
/dev/bsg/6:0:0:1 does support cdb sizes greater than 16 bytes since its
introduction in lk 2.6.28 .
.SH EXIT STATUS
The exit status of sg_write_same is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH EXAMPLES
BEWARE: all these examples will overwrite the data on one or more blocks,
potentially CLEARING the WHOLE DISK.
.PP
One simple usage is to write blocks of zero from (and including) a given LBA
for 63 blocks:
.PP
  sg_write_same \-\-lba=0x1234 \-\-num=63 /dev/sdc
.PP
Since \fI\-\-xferlen=LEN\fR has not been given, then this utility will
call the READ CAPACITY command on /dev/sdc to determine the number
of bytes in a logical block.  Let us assume that is 512 bytes. Since
\fI\-\-in=IF\fR is not given a block of zeros is assumed. So 63 blocks
of zeros (each block containing 512 bytes) will be written from (and
including) LBA 0x1234 . Note that only one block of zeros is passed
to the SCSI WRITE SAME command in the data\-out buffer (as required by
SBC\-3). Using the WRITE SAME SCSI command to write one or more blocks
blocks of zeros is equivalent to the NVMe command: Write Zeroes.
.br
Now we will write zero blocks to the WHOLE disk. [Note sanitize type commands
will also clear blocks and metadata that are not directly visible]:
.PP
  sg_write_same \-\-lba=0x0 \-\-num=0 /dev/sdc
.PP
Yes, in this context \-\-num=0 means the rest of the disk. The above
invocation may give an error due to the WSNZ bit in the Block Limits VPD
page being set. To get around that try:
.PP
  sg_write_same \-\-lba=0x0 \-\-ndob /dev/sdc
.PP
this invocation, if supported, has the added benefit of not sending a data
out buffer of zeros. Notes that it is possible that the "provisioning
initialization pattern" is written to each block instead of zeros.
.PP
A similar example follows but in this case the blocks
are "unmapped" ("trimmed" in ATA speak) rather than zeroed:
.PP
  sg_write_same \-\-unmap \-L 0x1234 \-n 63 /dev/sdc
.PP
Note that if the LBPRZ bit in the READ CAPACITY(16) response is set (i.e.
LPPRZ is an acronym for logical block provisioning read zeros) then these
two examples do the same thing, at least seen from the point of view of
subsequent reads.
.PP
This utility can also be used to write protection information (PI) on disks
formatted with a protection type greater than zero. PI is 8 bytes of extra
data appended to the user data of a logical block: the first two bytes are a
CRC (the "guard"), the next two bytes are the "application tag" and the last
four bytes are the "reference tag". With protection types 1 and 2 if the
application tag is 0xffff then the guard should not be checked (against the
user data).
.PP
In this example we assume the logical block size (of the user data) is 512
bytes and the disk has been formatted with protection type 1. Since we are
going to modify LBA 2468 then we take a copy of it first:
.PP
  dd if=/dev/sdb skip=2468 bs=512 of=2468.bin count=1
.PP
The following command line sets the user data to zeros and the PI to 8
0xFF bytes on LBA 2468:
.PP
  sg_write_same \-\-lba=2468 /dev/sdb
.PP
Reading back that block should be successful because the application tag
is 0xffff which suppresses the guard (CRC) check (which would otherwise be
wrong):
.PP
  dd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1
.PP
Now an attempt is made to create a binary file with zeros in the user data,
0x0000 in the application tag and 0xff bytes in the other two PI fields. It
is awkward to create 0xff bytes in a file (in Unix) as the "tr" command
below shows:
.PP
  dd if=/dev/zero bs=1 count=512 of=ud.bin
.br
  tr "\\000" "\\377" < /dev/zero | dd bs=1 of=ff_s.bin count=8
.br
  cat ud.bin ff_s.bin > lb.bin
.br
  dd if=/dev/zero bs=1 count=2 seek=514 conv=notrunc of=lb.bin
.PP
The resulting file can be viewed with 'hexdump \-C lb.bin' and should
contain 520 bytes. Now that file can be written to LBA 2468 as follows:
.PP
  sg_write_same \-\-lba=2468 wrprotect=3 \-\-in=lb.bin /dev/sdb
.PP
Note the \fI\-\-wrprotect=3\fR rather than being set to 1, since we want
the WRITE SAME command to succeed even though the PI data now indicates
the user data is corrupted. When an attempt is made to read the LBA, an
error should occur:
.PP
  dd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1
.PP
dd errors are not very expressive, if dmesg is checked there should be
a line something like this: "[sdb]  Add. Sense: Logical block guard check
failed". The block can be corrected by doing a "sg_write_same \-\-lba=1234
/dev/sdb" again or restoring the original contents of that LBA:
.PP
  dd if=2468.bin bs=512 seek=2468 of=/dev/sdb conv=notrunc count=1
.PP
Hopefully the dd command would never try to truncate the output file when
it is a block device.
.SH AUTHORS
Written by Douglas Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2009\-2020 Douglas Gilbert
.br
This software is distributed under a BSD\-2\-Clause license. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B sg_format,sg_get_lba_status,sg_readcap,sg_vpd,sg_unmap,
.B sg_write_x(sg3_utils)