| .TH SG_FORMAT "8" "May 2007" "sg3_utils\-1.24" SG3_UTILS |
| .SH NAME |
| sg_format \- format or resize a SCSI disk (perhaps change its block size) |
| .SH SYNOPSIS |
| .B sg_format |
| [\fI\-\-cmplst=\fR0|1] [\fI\-\-count=COUNT\fR] [\fI\-\-dcrt\fR] |
| [\fI\-\-early\fR] [\fI\-\-format\fR] [\fI\-\-help\fR] [\fI\-\-long\fR] |
| [\fI\-\-pfu=PFU\fR] [\fI\-\-pinfo\fR] [\fI\-\-resize\fR] [\fI\-\-rto_req\fR] |
| [\fI\-\-security\fR] [\fI\-\-six\fR] [\fI\-\-size=SIZE\fR] [\fI\-\-verbose\fR] |
| [\fI\-\-version\fR] [\fI\-\-wait\fR] \fIDEVICE\fR |
| .SH DESCRIPTION |
| .\" Add any additional description here |
| .PP |
| Not all SCSI direct access devices need to be formatted and some have |
| vendor specific formatting procedures. SCSI disks with rotating media are |
| probably the largest group that do support a 'standard' format operation. |
| They are typically factory formatted to a block size of 512 bytes with the |
| largest number of blocks that the manufacturer recommends. That number of |
| blocks typically leaves aside a certain number of tracks and sectors for |
| reassignment of logical block addresses during the life of the disk. |
| .PP |
| This utility can format modern SCSI disks and potentially change their |
| block size (if permitted) and the block count (i.e. number of accessible |
| blocks on the media also known as "resizing"). Resizing a disk to less |
| than the manufacturer's recommended block count is sometimes called "short |
| stroking" (see NOTES section). Resizing the block count while not changing |
| the block size may not require a format operation. The SBC\-2 standard (see |
| www.t10.org) has obsoleted the "format device" mode page. Many of the low |
| level details found in that mode page are now left up to the discretion of |
| the manufacturer. |
| .PP |
| When this utility is used without options (apart from a device name) |
| then it prints out the existing block size and block count derived |
| from two sources. These two sources are a block descriptor in the response |
| to a MODE SENSE command and the response to a READ CAPACITY command. |
| The reason for this double check is to detect a "format corrupt" |
| state (see NOTES section). |
| .PP |
| Recent SBC\-3 drafts add several "protection types" to the "protection |
| information" introduced in the SBC\-2 standard. See the "protection |
| information" section (section 4.17 in draft SBC\-3 rev 8). 8 bytes of |
| protection information are added to each block (a 2 byte "logical block |
| guard" (CRC), a 2 byte "logical block application guard", and a 4 |
| byte "logical block reference tag"). A device that supports protection |
| information sets the "protect" bit in a standard INQUIRY response. |
| The "FMTPINFO" and "RTO_REQ" bits in the FORMAT command cdb plus |
| the "Protection Field Usage" in the parameter header are associated with |
| protection information and can be set by this utility. |
| .SH OPTIONS |
| Arguments to long options are mandatory for short options as well. |
| .TP |
| \fB\-C\fR, \fB\-\-cmplst\fR=0 | 1 |
| sets the CMPLST ("complete list") bit in the FORMAT cdb to 0 or 1. |
| The default is 1 in which case the existing GLIST (grown list) is ignored. |
| If the value is 0 then the existing GLIST is taken into account. See the |
| LISTS section below. Active when the \fI\-\-format\fR option is given. In |
| most cases this bit should be left set; some MO disk drives need this bit |
| cleared. The SCSI to ATA Translation (SAT) standard (prior draft: sat\-r09) |
| requires this bit to be cleared. |
| .TP |
| \fB\-c\fR, \fB\-\-count\fR=\fICOUNT\fR |
| where \fICOUNT\fR is the number of blocks to be formatted or media to be |
| resized to. Can be used with either \fI\-\-format\fR or \fI\-\-resize\fR. |
| With \fI\-\-format\fR this option need not be given in which case it is |
| assumed to be zero. With \fI\-\-format\fR the interpretation of \fICOUNT\fR |
| is: |
| .br |
| (\fICOUNT\fR > 0) : only format the first \fICOUNT\fR blocks and READ |
| .br |
| CAPACITY will report \fICOUNT\fR blocks after format |
| .br |
| (\fICOUNT\fR = 0) and block size unchanged : use existing block count |
| .br |
| (\fICOUNT\fR = 0) and block size changed : recommended maximum block |
| .br |
| count for new block size |
| .br |
| (\fICOUNT\fR = \-1) : use recommended maximum block count |
| .br |
| (\fICOUNT\fR < \-1) : illegal |
| .br |
| With \fI\-\-resize\fR this option must be given and \fICOUNT\fR has this |
| interpretation: |
| .br |
| (\fICOUNT\fR > 0) : after resize READ CAPACITY will report \fICOUNT\fR |
| .br |
| blocks |
| .br |
| (\fICOUNT\fR = 0) : after resize READ CAPACITY will report 0 blocks |
| .br |
| (\fICOUNT\fR = \-1) : after resize READ CAPACITY will report its |
| .br |
| maximum number of blocks |
| .br |
| (\fICOUNT\fR < \-1) : illegal |
| .br |
| In both cases if the given \fICOUNT\fR exceeds the maximum number of |
| blocks (for the block size) then the disk reports an error. |
| See NOTES section below. |
| .TP |
| \fB\-D\fR, \fB\-\-dcrt\fR |
| this option sets the DCRT bit in the FORMAT command's parameter list header. |
| It will "disable certification" which is the verification step used to check |
| during the format process that blocks are usable. Using this option may |
| speed the format. The default action of this utility (i.e. when this option |
| is not given) is to clear the DCRT bit thereby requesting "media |
| certification". When the DCRT bit is set, the FOV bit must also be set hence |
| sg_format does that. |
| .TP |
| \fB\-e\fR, \fB\-\-early\fR |
| this option is active when \fI\-\-format\fR is given. The default action of |
| this utility is to poll the disk every 30 seconds to determine the progress |
| of the format operation until it is finished. When this option is given this |
| utility will exit "early" as soon as the format has commenced. Then the |
| user can monitor the progress of the ongoing format operation with other |
| utilities (e.g. sg_turs(8) or sg_requests(8)). This option and |
| \fI\-\-wait\fR cannot both be given. |
| .TP |
| \fB\-F\fR, \fB\-\-format\fR |
| issue a SCSI FORMAT command. |
| .B This will destroy all the data held on the media. |
| This option is required to change the block size of a disk. |
| The user is given a 10 second count down to ponder the wisdom |
| of doing this, during which time control\-C (amongst other |
| Unix commands) can be used to kill this process before it |
| does any damage. See NOTES section for implementation details and |
| EXAMPLES section for typical use. |
| .TP |
| \fB\-h\fR, \fB\-\-help\fR |
| print out the usage information then exit. |
| .TP |
| \fB\-l\fR, \fB\-\-long\fR |
| the default action of this utility is to assume 32 bit logical block |
| addresses. With 512 byte block size this permits almost 2 |
| terabytes (almost 2 ** 41 bytes) on a single disk. This option selects |
| commands and parameters that allow for 64 bit logical block addresses. |
| Specifically this is the "longlba" flag in the MODE SENSE (10) command |
| and READ CAPACITY (16) rather than READ CAPACITY (10). When a disk |
| supports "protection information" then this option may also be useful. |
| .TP |
| \fB\-P\fR, \fB\-\-pfu\fR=\fIPFU\fR |
| sets the "Protection Field Usage" field in the parameter block associated |
| with a FORMAT command to \fIPFU\fR. The default value is 0, the only other |
| defined value currently is 1. Used together with \fI\-\-pinfo\fR and |
| \fI\-\-rto_req\fR to specify the "protection type" to format the disk |
| to (see SBC\-3). |
| .TP |
| \fB\-p\fR, \fB\-\-pinfo\fR |
| instructs a format operation to add an extra 8 bytes of protection |
| information by setting the FMTPINFO bit in the FORMAT command cdb. Default |
| action is not to format with protection information. Has no action |
| unless \fI\-\-format\fR is given. |
| .TP |
| \fB\-r\fR, \fB\-\-resize\fR |
| rather than format the disk, it can be resized. This means changing the |
| number of blocks on the device reported by the READ CAPACITY command. |
| This option should be used with the \fI\-\-count=COUNT\fR option. |
| The contents of all logical blocks on the media remain unchanged when |
| this option is used. This means that any resize operation can be |
| reversed. This option cannot be used together with either \fI\-\-format\fR |
| or a \fI\-\-size=SIZE\fR whose argument is different to the existing block |
| size. |
| .TP |
| \fB\-R\fR, \fB\-\-rto_req\fR |
| instructs a format to enable application client ownership of |
| the "logical block reference tag" field (i.e. the RTO_REQ bit in the |
| FORMAT cdb). The default action is to disable application client |
| ownership of that field. Has no action unless both \fI\-\-format\fR |
| and \fI\-\-pinfo\fR are given. |
| .TP |
| \fB\-S\fR, \fB\-\-security\fR |
| sets the "Security Initialization" (SI) bit in the FORMAT command's |
| initialization pattern descriptor within the parameter list. According |
| to SBC\-3 the default initialization pattern "shall be written using a |
| security erasure write technique". |
| .TP |
| \fB\-6\fR, \fB\-\-six\fR |
| Use 6 byte variants of MODE SENSE and MODE SELECT. The default action |
| is to use the 10 byte variants. Some MO drives need this option set |
| when doing a format. |
| .TP |
| \fB\-s\fR, \fB\-\-size\fR=\fISIZE\fR |
| where \fISIZE\fR is the block size (i.e. number of bytes in each block) to |
| format the device to. The default value is whatever is currently reported |
| by the block descriptor in a MODE SENSE command. This option is only active |
| when the \fI\-\-format\fR option is also given. If the block size given by |
| this option is different from the current value then a MODE SELECT command |
| is used to change it prior to the FORMAT command being started (as |
| recommended in the draft standard). Recent SCSI disks usually have 512 byte |
| sectors by default and allow up to 16 bytes extra in a sector (i.e. 528 byte |
| sectors). If the given size in unacceptable to the disk, most likely |
| an "Invalid field in parameter list" message will appear in sense |
| data (requires the use of '\-v' to decode sense data). |
| .TP |
| \fB\-v\fR, \fB\-\-verbose\fR |
| increase the level of verbosity, (i.e. debug output). "\-vvv" gives |
| the maximum debug output. |
| .TP |
| \fB\-V\fR, \fB\-\-version\fR |
| print the version string and then exit. |
| .TP |
| \fB\-w\fR, \fB\-\-wait\fR |
| this option only has an effect when used together with the \fI\-\-format\fR |
| option. The default format action is to set the "IMMED" bit in the FORMAT |
| UNIT command's (short) parameter header. If this option (i.e. \fI\-\-wait\fR) |
| is given then the "IMMED" bit is not set. Then the FORMAT UNIT command waits |
| until the format operation completes before returning its response. This |
| can be several hours on large disks. This utility sets a four hour timeout |
| on such a FORMAT UNIT command. |
| .SH LISTS |
| The SBC\-3 draft (revision 8) defines PLIST, CLIST, DLIST and GLIST in |
| section 4.8 on "Medium defects". Briefly, the PLIST is the "primary" |
| list of manufacturer detected defects, the CLIST ("certification" list) |
| are those detected during the format operation, the DLIST is a list of |
| defects that can be given to the format operation. The GLIST is the grown |
| list which starts in the format process as CLIST+DLIST and can "grow" later |
| due to automatic reallocation (see the ARRE and AWRE bits in the |
| read\-write error recovery mode page (see sdparm(8))) and use of the |
| SCSI REASSIGN BLOCKS command (see sg_reassign(8)). |
| .PP |
| The CMPLST bit (controlled by the \fI\-\-cmplst=\fR0|1 option) determines |
| whether the existing GLIST, when the format operation is invoked, |
| is taken into account. The sg_format utility sets the FOV bit to zero |
| which causes the DPRY=0, so the PLIST is taken into account, and |
| DCRT=0, so the CLIST is generated and used during the format process. |
| .PP |
| The sg_format utility does not permit a user to provide a defect |
| list (i.e. DLIST). All protection information options are |
| defaulted to off. |
| .SH NOTES |
| The SBC\-2 standard states that the REQUEST SENSE command should be used |
| for obtaining a progress indication when the format command returns prior |
| to the completion of the format operation. However, tests on a selection |
| of recent disks shows that TEST UNIT READY commands yield progress |
| indications (but not REQUEST SENSE commands). A new option may be required |
| to handle this when disks catch up. |
| .PP |
| When the \fI\-\-format\fR option is given then there is a 10 second window |
| during which the user is invited to abort sg_format. This is just prior the |
| SCSI FORMAT UNIT command being issued. If the \fI\-\-wait\fR option is not |
| given then the SCSI FORMAT UNIT command is issued with the IMMED bit set |
| which causes the SCSI command to return after it has started the format |
| operation. The \fI\-\-early\fR option will cause sg_format to exit at that |
| point. Otherwise the \fIDEVICE\fR is polled every 30 seconds with |
| TEST UNIT READY commands until it reports an "all clear" (i.e. the |
| format operation has completed). Normally these polling commands will |
| result in a progress indicator (expressed as a percentage) being output |
| to the screen. If the user gets bored watching the progress report then |
| sg_format process can be terminated (e.g. with control\-C) without |
| affecting the format operation which continues. However a bus or device |
| reset (or a power cycle) may well cause the device to become "format |
| corrupt". |
| .PP |
| When the \fI\-\-format\fR and \fI\-\-wait\fR options are both given then |
| this utility may take a long time to return. In this case care should be |
| taken not to send any other SCSI commands to the disk as it may not respond |
| leaving those commands queued behind the active format command. This may |
| cause a timeout in the OS driver (in a lot shorter period than 4 hours |
| applicable to the format command). This may result in the OS resetting |
| the disk leaving the format operation incomplete. This may leave the |
| disk in a "format corrupt" state requiring another format to remedy |
| the situation. |
| .PP |
| When the block size (i.e. the number of bytes in each block) is changed |
| on a disk two SCSI commands must be sent: a MODE SELECT to change the block |
| size followed by a FORMAT command. If the MODE SELECT command succeeds and |
| the FORMAT fails then the disk may be in a state that the draft standard |
| calls "format corrupt". A block descriptor in a subsequent MODE SENSE |
| will report the requested new block size while a READ CAPACITY command |
| will report the existing (i.e. different) block size. Alternatively |
| the READ CAPACITY command may fail, reporting the device is not ready, |
| potentially requiring a format. The solution to this situation is to |
| do a format again (and this time the new block size does not have to |
| be given) or change the block size back to the original size. |
| .PP |
| The SBC\-2 standard states that the block count can be set back |
| to the manufacturer's maximum recommended value in a format or resize |
| operation. This can be done by placing an address of 0xffffffff (or the |
| 64 bit equivalent) in the appropriate block descriptor field to a MODE |
| SELECT command. In signed (two's complement) arithmetic that value |
| corresponds to '\-1'. So a \fI\-\-count=\fR-1 causes the block count |
| to be set back to the manufacturer's maximum recommended value. To see |
| exactly which SCSI commands are being executed and parameters passed |
| add "\-vvv" to the sg_format command line. |
| .PP |
| Short stroking is a technique to trade off capacity for performance. |
| Disk performance is usually highest on the outer tracks (i.e. lower |
| logical block addresses) so by resizing or reformatting a disk to |
| a smaller capacity, average performance will usually be increased. |
| .PP |
| Other utilities may be useful in finding information associated with |
| formatting. These include sg_inq(8) to fetch standard INQUIRY |
| information (e.g. the PROTECT bit) and to fetch the extended INQUIRY |
| VPD page (e.g. RTO and GRD_CHK bits). The sdparm(8) utility can be |
| used to access and potentially change the now obsolete format mode page. |
| .PP |
| scsiformat is another utility available for formatting SCSI disks |
| with linux. It dates from 1997 (most recent update) and may be useful for |
| disks whose firmware is of that vintage. |
| .PP |
| The \fICOUNT\fR value is a number which may be followed by one of |
| these multiplicative suffixes: c C *1; w W *2; b B *512; k K KiB *1,024; |
| KB *1,000; m M MiB *1,048,576; MB *1,000,000 . This pattern continues |
| for "G", "T" and "P". Also a suffix of the form "x<n>" multiplies the |
| leading number by <n>. Alternatively numerical values can be given in |
| hexadecimal preceded by either "0x" or "0X" (or with a trailing "h" |
| or "H"). When hex numbers are given, multipliers cannot be used. |
| .SH EXAMPLES |
| First, do not alter anything but print out the existing block count and size |
| derived from two sources: a block descriptor in a MODE SELECT command |
| response and from the response of a READ CAPACITY commands: |
| .PP |
| sg_format /dev/sdm |
| .PP |
| Now a simple format, leaving the block count and size as they |
| were previously. The FORMAT command is executed in IMMED mode |
| and the device is polled every 30 seconds to print out a progress |
| indication: |
| .PP |
| sg_format \-\-format /dev/sdm |
| .PP |
| Now the same format, but waiting (passively) until the format |
| operation is complete: |
| .PP |
| sg_format \-\-format \-\-wait /dev/sdm |
| .PP |
| Next is a format in which the block size is changed to 520 bytes |
| and the block count is set to the manufacturer's maximum |
| value (for that block size). Note, not all disks support changing |
| the block size: |
| .PP |
| sg_format \-\-format \-\-size=520 /dev/sdm |
| .PP |
| Now a resize operation so that only the first 0x10000 (65536) |
| blocks on a disk are accessible. The remaining blocks remain |
| unaltered. |
| .PP |
| sg_format \-\-resize \-\-count=0x10000 /dev/sdm |
| .PP |
| Now resize the disk back to its normal (maximum) block count: |
| .PP |
| sg_format \-\-resize \-\-count=\-1 /dev/sdm |
| .PP |
| .SH EXIT STATUS |
| The exit status of sg_format is 0 when it is successful. Otherwise see |
| the sg3_utils(8) man page. Unless the \fI\-\-wait\fR option is given, the |
| exit status may not reflect to success of otherwise of the format. |
| Using sg_turs(8) and sg_readcap(8) after the format operation may be wise. |
| .SH AUTHORS |
| Written by Grant Grundler, James Bottomley and Douglas Gilbert. |
| .SH "REPORTING BUGS" |
| Report bugs to <dgilbert at interlog dot com>. |
| .SH COPYRIGHT |
| Copyright \(co 2005\-2007 Grant Grundler, James Bottomley and Douglas Gilbert |
| .br |
| This software is distributed under the GPL version 2. There is NO |
| warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| .SH "SEE ALSO" |
| .B sg_turs(8), sg_requests(8), sg_inq(8), sg_modes(8), sg_vpd(8) |
| .B sg_reassign(8) [all in sg3_utils], sdparm(8), scsiformat (old) |