2 May, 2014 13-054r3 SBC-4 Add Force bit to UNMAP

To: T10 Technical Committee

From: Rob Elliott, HP (elliott@hp.com); Curtis Ballard, HP (curtis.ballard@hp.com)
Date: 2 May, 2014
Subject: 13-054r3 SBC-4 Add Force bit to UNMAP

Revision history
Revision 0 (23 January 2013) First revision. This is an SBC-3 letter ballot comment prompted by discussion of
12-414r0.
Revision 1 (5 May 2013) Incorporated comments from Fred Knight (NetApp) and Curtis Ballard (HP),
including:
a) created two additional sense codes for use with the ABORTED COMMAND sense key for no unmap
operations occurred vs. some unmap operations occurred
b) changed any unmap operations to one or more unmap operations in FORCE bit paragraph
c) added sentence that the command timeouts must be based on the FORCE bit being set to one
d) removed the requested changes in 4.7.3.4.1. Upgraded base text for that section to sbc3r35c
Revision 2 (1 November 2013) Incorporated comments from July 2013 CAP WG (see 13-054), including:
a) renamed the unmap requests model section to unmap mechanisms and deleted text about unmap
operations being optional. That is command dependent; each command has its own nuances. Made
the section a summary referencing all the commands that perform unmap operations.
b) in unmap operations section, added an e.g. that an unmap operation on an unmapped LBA might be
to upgrade the LBA from deallocated to anchored. Its not necessarily a NOP.
c) reworded the FORCE bit paragraph so it doesnt step on the ANCHOR bit rules
d) reworded the ANCHOR bit rules in the UNMAP CDB description to cover thin provisioned with anchor
support, thin provisioned without anchor support, and resource provisioned; deleted redundant, more
complex descriptions of the ANCHOR bit in the UNMAP parameter list
Revision 3(2 May, 2014) Curtis Ballard incorporated comments from January 2014 CAP WG, including:
a) moved all proposed text refinements that do not have to do with the requested force functionality into
a new document.
b) provided new text for failing a command requesting force if granularity requirements are not met.
c) updated to reference sbc4r01

Related documents
sbc4r01 SCSI Block Commands - 4 (SBC-4)
12-414r0 SBC-4 Simplified SCSI - base and maintenance feature sets (HP, Dell, Intel, Microsoft)

Description
The UNMAP command is only a suggestion; the device server may or may not unmap the specified LBA
ranges. The same is true for the DATA SET MANAGEMENT/Trim command in ATA.
This makes the command unusable for drives in RAID-5 and RAID-6 arrays even if they implement the LBPRZ
bit set to one, since it is critical to know that the logical block was zeroed out to calculate the proper parity
values. Some readers do not realize this problem; the linux dm included discard support for RAID-5 and
RAID-6, assuming that the drive always unmaps as requested.
The WRITE SAME command with the UNMAP bit set to one can be used to ensure that the drive gets zeroed
one way or another (by writing zeros if it is not able to unmap), but:
a) that command does not support multiple discontiguous LBA ranges like UNMAP;
b) the ATA version of WRITE SAME does not have an UNMAP bit, so the command cannot be translated
by a SCSI to ATA translation layer.
A FORCE bit is proposed to be added to the UNMAP CDB to require the device server to return an error if it
does not unmap all specified LBA ranges. Support for this bit can be detected with the REPORT
SUPPORTED OPERATION CODES command.

Suggested changes to sbc4r01

1
13-054r3 SBC-4 Add Force bit to UNMAP 2 May, 2014

5.28 UNMAP command

5.28.1 UNMAP command overview

The UNMAP command (see table 95) requests that the device server cause one or more LBAs to be
unmapped (see 4.7.3) perform unmap operations (see 4.7.3.4.2) for each specified LBA.

Table 95 UNMAP command

Bit
7 6 5 4 3 2 1 0
Byte

0 OPERATION CODE (42h)

Reserved
1 Reserved ANCHOR
FORCE

2
Reserved
5
6 Reserved GROUP NUMBER

7 (MSB)
PARAMETER LIST LENGTH
8 (LSB)
9 CONTROL

The OPERATION CODE byte is defined in SPC-4 and shall be set to the value shown in table 95 for an UNMAP
command.
A FORCE bit set to one specifies that the device server shall perform an unmap operation (see 4.7.3.4.1) for
every specified LBA. The device server shall terminate the command with CHECK CONDITION status with
the sense key set to ILLEGAL REQUEST and the additional sense code set to:
a) GRANULARITY ERROR if the number of logical blocks in any unmap descriptor is not a multiple of
the optimal unmap granularity (see 6.6.3), if any;
b) GRANULARITY ALIGNMENT ERROR if the UNMAP LOGICAL BLOCK ADDRESS field value in any
unmap descriptor does not align with the required unmap granularity alignment (see 6.6.3), if any; or
c) UNMAP OPERATIONS NOT PERFORMED if the unmap granularity and alignment requirements are
met but the device server does not perform any of the requested unmap operations.
The device server shall terminate the command with CHECK CONDITION status with the sense key set to
ABORTED COMMAND and the additional sense code set to UNMAP OPERATIONS PARTIALLY
PERFORMED if the device server has performed one or more of the requested unmap operations and is not
able to perform all of the requested unmap operations.

Editors Note 1: Ask the SPC-4 editor to assign additional sense codes for GRANULARITY
ERROR, GRANULARITY ALIGNMENT ERROR, UNMAP OPERATIONS NOT PERFORMED and
UNMAP OPERATIONS PARTIALLY PERFORMED

A FORCE bit set to zero specifies that the device server, for each specified LBA:
a) should perform an unmap operation; or
b) may make no changes to the logical block provisioning state.
If the FORCE bit is set to zero, then the device server does not indicate whether or not it performed any, all, or
none of the requested unmap operations.

2
2 May, 2014 13-054r3 SBC-4 Add Force bit to UNMAP

For a thin provisioned logical unit (see 4.7.3.3):

a) an ANCHOR bit set to zero specifies that any LBA on which an unmap operation (see 4.7.3.4) is
performed shall either become deallocated or anchored and should become deallocated; and
a) an ANCHOR bit set to one specifies that any LBA on which an unmap operation is performed shall
become anchored.
For a resource provisioned logical unit (see 4.7.3.2), any LBA on which an unmap operation is performed shall
become anchored (i.e., the command is processed as if the ANCHOR bit is set to one).
If the ANCHOR bit is set to one, and the ANC_SUP bit in the Logical Block Provisioning VPD page (see 6.6.4) is
set to zero, then the device server shall terminate the command with CHECK CONDITION status with the
sense key set to ILLEGAL REQUEST and the additional sense code set to INVALID FIELD IN CDB.
See the PRE-FETCH (10) command (see 5.8) and 4.23 for the definition of the GROUP NUMBER field.
The PARAMETER LIST LENGTH field specifies the length in bytes of the UNMAP parameter list that is available to
be transferred from the Data-Out Buffer. If the parameter list length is greater than zero and less than eight,
then the device server shall terminate the command with CHECK CONDITION status with the sense key set
to ILLEGAL REQUEST and the additional sense code set to PARAMETER LIST LENGTH ERROR. A
PARAMETER LIST LENGTH set to zero specifies that no data shall be transferred.

The CONTROL byte is defined in SAM-5.

5.28.2 UNMAP parameter list

The UNMAP parameter list (see table 96) contains an UNMAP parameter list header and UNMAP block
descriptors for LBA extents for which unmap requests (see 4.7.3.4.1) are to be processed by the device
server. The LBAs specified in the block descriptors may contain overlapping LBA extents, and may be in any
order.
If the ANCHOR bit in the CDB is set to zero and the logical unit is thin provisioned (see 4.7.3.3), then the logical
block provisioning state for each specified LBA:
a) should become deallocated;
b) may become anchored; or
c) may remain unchanged.
If:
a) the ANCHOR bit in the CDB is set to one and the ANC_SUP field in the Logical Block Provisioning VPD
page (see 6.6.4) is set to one; or
b) the logical unit is resource provisioned,
then, for each specified LBA:
a) if the LBA is mapped, then the LBA shall not become deallocated, and:
A) that LBA should become anchored (see 4.7.4.6.3); or
B) the logical block provisioning state of that LBA remains unchanged;
b) if the LBA is deallocated, then that LBA shall become anchored (see 4.7.4.7.3). If a lack of LBA
mapping resources prevents the LBA from becoming anchored, then the device server shall terminate
the command as described in 4.7.3.6; or

3
13-054r3 SBC-4 Add Force bit to UNMAP 2 May, 2014

c) if the LBA is anchored, then that LBA shall remain anchored.

Table 96 UNMAP parameter list

Bit
7 6 5 4 3 2 1 0
Byte

0 (MSB)
UNMAP DATA LENGTH (n - 1)
1 (LSB)
2 (MSB)
UNMAP BLOCK DESCRIPTOR DATA LENGTH (n - 7)
3 (LSB)
4
Reserved
7
UNMAP block descriptor list
8
UNMAP block descriptor [first] (see table 97)
23



n - 15
UNMAP block descriptor [last] (see table 97)
n

The UNMAP DATA LENGTH field specifies the length in bytes of the following data that is available to be trans-
ferred from the Data-Out Buffer. The unmap data length does not include the number of bytes in the UNMAP
DATA LENGTH field.

The UNMAP BLOCK DESCRIPTOR DATA LENGTH field specifies the length in bytes of the UNMAP block descriptors
that are available to be transferred from the Data-Out Buffer. The unmap block descriptor data length should
be a multiple of 16. If the unmap block descriptor data length is not a multiple of 16, then the last unmap block
descriptor is incomplete and shall be ignored. If the UNMAP BLOCK DESCRIPTOR DATA LENGTH is set to zero, then
no unmap block descriptors are included in the UNMAP parameter list. This condition shall not be considered
an error.
If any UNMAP block descriptors in the UNMAP block descriptor list are truncated due to the parameter list
length in the CDB, then that UNMAP block descriptor shall be ignored.

4
2 May, 2014 13-054r3 SBC-4 Add Force bit to UNMAP

Table 97 defines the UNMAP block descriptor.

Table 97 UNMAP block descriptor

Bit
7 6 5 4 3 2 1 0
Byte

0 (MSB)
UNMAP LOGICAL BLOCK ADDRESS
7 (LSB)
8 (MSB)
NUMBER OF LOGICAL BLOCKS
11 (LSB)
12
Reserved
15

The UNMAP LOGICAL BLOCK ADDRESS field specifies the first LBA that is requested to be unmapped (see
4.7.3.4.1) for this UNMAP block descriptor.
The NUMBER OF LOGICAL BLOCKS field specifies the number of LBAs that are requested to be unmapped
beginning with the LBA specified by the UNMAP LOGICAL BLOCK ADDRESS field.
If the NUMBER OF LOGICAL BLOCKS is set to zero, then no LBAs shall be unmapped for this UNMAP block
descriptor. This condition shall not be considered an error.
If the specified LBA and the specified number of logical blocks exceeds the capacity of the medium (see 4.5),
then the device server shall terminate the command with CHECK CONDITION status with the sense key set
to ILLEGAL REQUEST and the additional sense code set to LOGICAL BLOCK ADDRESS OUT OF RANGE.
If the total number of logical blocks specified in the UNMAP block descriptor data exceeds the value indicated
in the MAXIMUM UNMAP LBA COUNT field in the Block Limits VPD page (see 6.6.3), or if the number of UNMAP
block descriptors exceeds the value of the MAXIMUM UNMAP BLOCK DESCRIPTOR COUNT field in the Block Limits
VPD page, then the device server shall terminate the command with CHECK CONDITION status with the
sense key set to ILLEGAL REQUEST and the additional sense code set to INVALID FIELD IN PARAMETER
LIST.

5
13-054r3 SBC-4 Add Force bit to UNMAP 2 May, 2014

6.6.3 Block Limits VPD page

The Block Limits VPD page (see table 212) provides the application client with the means to obtain certain
operating parameters of the logical unit.

Table 212 Block Limits VPD page

Bit
7 6 5 4 3 2 1 0
Byte

0 PERIPHERAL QUALIFIER PERIPHERAL DEVICE TYPE (00000b)

1 PAGE CODE (B0h)
2 (MSB)
PAGE LENGTH (003Ch)
3 (LSB)
4 Reserved WSNZ

5 MAXIMUM COMPARE AND WRITE LENGTH

6 (MSB)
OPTIMAL TRANSFER LENGTH GRANULARITY
7 (LSB)
8 (MSB)
MAXIMUM TRANSFER LENGTH
11 (LSB)
12 (MSB)
OPTIMAL TRANSFER LENGTH
15 (LSB)
16 (MSB)
MAXIMUM PREFETCH LENGTH
19 (LSB)
20 (MSB)
MAXIMUM UNMAP LBA COUNT
23 (LSB)
24 (MSB)
MAXIMUM UNMAP BLOCK DESCRIPTOR COUNT
27 (LSB)
28 (MSB)
OPTIMAL UNMAP GRANULARITY
31 (LSB)
32 UGAVALID (MSB)
UNMAP GRANULARITY ALIGNMENT
35 (LSB)
36 (MSB)
MAXIMUM WRITE SAME LENGTH
43 (LSB)
44
Reserved
63

6
2 May, 2014 13-054r3 SBC-4 Add Force bit to UNMAP

The PERIPHERAL QUALIFIER field is defined in SPC-4.

The PAGE CODE field, PERIPHERAL DEVICE TYPE field, and PAGE LENGTH field are defined in SPC-4 and shall be
set to the values shown in table 212.
A write same non-zero (WSNZ) bit set to one indicates that the device server does not support a value of zero
in the NUMBER OF LOGICAL BLOCKS field in the WRITE SAME command CDBs (see 5.43, 5.44, and 5.45). A
WSNZ bit set to zero indicates that the device server may or may not support a value of zero in the NUMBER OF
LOGICAL BLOCKS field of the WRITE SAME commands.

A MAXIMUM COMPARE AND WRITE LENGTH field set to a non-zero value indicates the maximum value that the
device server accepts in the NUMBER OF LOGICAL BLOCKS field in the COMPARE AND WRITE command (see
5.2). A MAXIMUM COMPARE AND WRITE LENGTH field set to zero indicates that the device server does not support
the COMPARE AND WRITE command. If the MAXIMUM TRANSFER LENGTH field is not set to zero, then the
device server shall set the MAXIMUM COMPARE AND WRITE LENGTH field to a value less than or equal to the value
in the MAXIMUM TRANSFER LENGTH field.
An OPTIMAL TRANSFER LENGTH GRANULARITY field set to a non-zero value indicates the optimal transfer length
granularity size in logical blocks for a single command shown in the command column of table 213. If a device
server receives one of these commands with a transfer size that is not equal to a multiple of this value, then
the device server may incur delays in processing the command. An OPTIMAL TRANSFER LENGTH GRANULARITY
field set to 0000h indicates that the device server does not report optimal transfer length granularity.

Table 213 Transfer limits for commands

Block Limits VPD Additional sense code if

Field that specifies page field(s) that the value in the
Command
the transfer size indicate maximum specified field exceeds
limits the maximum limit

CDB NUMBER OF MAXIMUM COMPARE AND

COMPARE AND WRITE
field
LOGICAL BLOCKS WRITE LENGTH field
CDB TRANSFER MAXIMUM TRANSFER
ORWRITE (16) / (32)
LENGTH field LENGTH field
CDB PREFETCH MAXIMUM PREFETCH
PRE-FETCH (10) / (16)
LENGTH field LENGTH field
READ (10) / (12) / (16) / CDB TRANSFER
(32) LENGTH field

VERIFY (10) / (12) / (16) / CDB VERIFICATION

(32) LENGTH field INVALID FIELD IN CDB

WRITE (10) / (12) / (16) / MAXIMUM TRANSFER

(32) LENGTH field
WRITE AND VERIFY (10) / CDB TRANSFER
(12) / (16) / (32) LENGTH field
XDWRITEREAD (10) / (32)
XPWRITE (10) / (32)
Any individual block device
range descriptor in a
POPULATE TOKEN Block device range
command (see 5.7) descriptor NUMBER MAXIMUM TRANSFER INVALID FIELD IN
Any individual block device OF LOGICAL BLOCKS LENGTH field PARAMETER LIST
range descriptor in a field
WRITE USING TOKEN
command (see 5.46)

7
13-054r3 SBC-4 Add Force bit to UNMAP 2 May, 2014

A MAXIMUM TRANSFER LENGTH field set to a non-zero value indicates the maximum transfer length in logical
blocks that the device server accepts for a single command shown in table 213. If a device server receives
one of these commands with a transfer size greater than this value, then the device server shall terminate the
command with CHECK CONDITION status with the sense key set to ILLEGAL REQUEST and the additional
sense code set to the value shown in table 213. A MAXIMUM TRANSFER LENGTH field set to 0000_0000h
indicates that the device server does not report a limit on the transfer length.
An OPTIMAL TRANSFER LENGTH field set to a non-zero value indicates the optimal transfer size in logical blocks
for a single command shown in table 213. If a device server receives one of these commands with a transfer
size greater than this value, then the device server may incur delays in processing the command. An OPTIMAL
TRANSFER LENGTH field set to 0000_0000h indicates that the device server does not report an optimal transfer
size.
The MAXIMUM PREFETCH LENGTH field indicates the maximum prefetch length in logical blocks that the device
server accepts for a single PRE-FETCH command. If the MAXIMUM TRANSFER LENGTH field is not set to zero,
then the device server should set the MAXIMUM PREFETCH LENGTH field to a value less than or equal to thefalue
in the MAXIMUM TRANSFER LENGTH field.
A MAXIMUM UNMAP LBA COUNT field set to a non-zero value indicates the maximum number of LBAs that may
be unmapped by an UNMAP command (see 5.28). If the number of LBAs that may be unmapped by an
UNMAP command is constrained only by the amount of data that may be contained in the UNMAP parameter
list (see 5.28.2), then the device server shall set the MAXIMUM UNMAP LBA COUNT field to FFFF_FFFFh. If the
device server implements the UNMAP command, then the value in this field shall be greater than or equal to
one. A MAXIMUM UNMAP LBA COUNT field set to 0000_0000h indicates that the device server does not
implement the UNMAP command.
A MAXIMUM UNMAP BLOCK DESCRIPTOR COUNT field set to a non-zero value indicates the maximum number of
UNMAP block descriptors (see 5.28.2) that shall be contained in the parameter data transferred to the device
server for an UNMAP command (see 5.28). If there is no limit on the number of UNMAP block descriptors
contained in the parameter data, then the device server shall set the MAXIMUM UNMAP BLOCK DESCRIPTOR
COUNT field to FFFF_FFFFh. If the device server implements the UNMAP command, then the value in the
MAXIMUM UNMAP BLOCK DESCRIPTOR COUNT field shall be greater than or equal to one. A MAXIMUM UNMAP BLOCK
DESCRIPTOR COUNT field set to 0000_0000h indicates that the device server does not implement the UNMAP
command.
An OPTIMAL UNMAP GRANULARITY field set to a non-zero value indicates the optimal granularity in logical blocks
for unmap requests (e.g., an UNMAP command, or a WRITE SAME (16) command with the UNMAP bit set to
one). An unmap request with a number of logical blocks that is not a multiple of this value may result in unmap
operations on fewer LBAs than requested or result in the UNMAP command being terminated. An OPTIMAL
UNMAP GRANULARITY field set to 0000_0000h indicates that the device server does not report an optimal
unmap granularity.

Editors Note 2: Used UNMAP command here as it is only a UNMAP command with the new
FORCE bit that can terminate for not meeting these requirements. The lower case unmap
command can refer to any command that is an unmap type command.

An unmap granularity alignment valid ( UGAVALID ) bit set to one indicates that the UNMAP GRANULARITY
ALIGNMENT field is valid. A UGAVALID bit set to zero indicates that the UNMAP GRANULARITY ALIGNMENT field is not
valid.
The UNMAP GRANULARITY ALIGNMENT field indicates the LBA of the first logical block to which the OPTIMAL
UNMAP GRANULARITY field applies. The unmap granularity alignment is used to calculate an optimal unmap
request starting LBA as follows:
optimal unmap request starting LBA = (n optimal unmap granularity) + unmap granularity alignment
where:
n is zero or any positive integer value

8
2 May, 2014 13-054r3 SBC-4 Add Force bit to UNMAP

optimal unmap granularity is the value in the OPTIMAL UNMAP GRANULARITY field
unmap granularity alignment is the value in the UNMAP GRANULARITY ALIGNMENT field
An unmap request with a starting LBA that is not optimal may result in unmap operations on fewer LBAs than
requested or result in the UNAMP command being terminated.
A MAXIMUM WRITE SAME LENGTH field set to a non-zero value indicates the maximum value that the device
server accepts in the NUMBER OF LOGICAL BLOCKS field for a WRITE SAME command. A MAXIMUM WRITE SAME
LENGTH field set to zero indicates that the device server does not report a limit on the number of logical blocks
that may be requested for a single WRITE SAME command.