| .TH SG_FORMAT "8" "May 2005" "sg3_utils-1.15" SG3_UTILS |
| .SH NAME |
| sg_format \- format or resize a SCSI disk (perhaps change its block size) |
| .SH SYNOPSIS |
| .B sg_format |
| [\fI--count=<n>\fR] [\fI--early\fR] [\fI--format\fR] [\fI--help\fR] |
| [\fI--long\fR] [\fI--resize\fR] [\fI--size=<n>\fR] [\fI--verbose\fR] |
| [\fI--version\fR] [\fI--wait\fR] |
| \fI<scsi_device>\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. Recent changes to the |
| SBC-2 draft standard (see www.t10.org) have 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 |
| A recent addition in the SBC-2 is "protection information". See |
| the section of that name (section 4.16 in draft SBC-2 rev 16). It adds |
| an extra 8 bytes of protection information 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 |
| are associated with protection information and can be set by this |
| utility. |
| .TP |
| --count=<n> | -c <n> |
| count of blocks to be formatted or media to be resized to. Can be |
| used with either "--format" or "--resize". With "--format" this |
| option need not be given in which case it is assumed to be zero. |
| With "--format" the interpretation of <n> is: |
| .br |
| (n > 0) : only format the first <n> blocks and READ |
| .br |
| CAPACITY will report <n> blocks after format |
| .br |
| (n = 0) and block size unchanged : use existing block count |
| .br |
| (n = 0) and block size changed : recommended maximum block |
| .br |
| count for new block size |
| .br |
| (n = -1) : use recommended maximum block count |
| .br |
| (n < -1) : illegal |
| .br |
| With "--resize" this option must be given and <n> has this |
| interpretation: |
| .br |
| (n > 0) : after resize READ CAPACITY will report <n> |
| .br |
| blocks |
| .br |
| (n = 0) : after resize READ CAPACITY will report 0 blocks |
| .br |
| (n = -1) : after resize READ CAPACITY will report its |
| .br |
| maximum number of blocks |
| .br |
| (n < -1) : illegal |
| .br |
| In both cases if the given <n> exceeds the maximum number of |
| blocks (for the block size) then the disk reports an error. |
| See NOTES section below. |
| .TP |
| --early | -e |
| this option is active when "--format" 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 or sg_requests). This option and "--wait" cannot |
| both be given. |
| .TP |
| --format | -F |
| 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. |
| See NOTES section for implementation details and EXAMPLES |
| section for typical use. |
| .TP |
| --help | -h |
| print out the usage information then exit. |
| .TP |
| --long | -l |
| 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 |
| --pinfo | -p |
| instructs a '--format' to add an extra 8 bytes of protection information. |
| Default action is not to format with protection information. Has no action |
| unless '--format' is given. |
| .TP |
| --resize | -r |
| 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 '--count=<new_blk_count>' 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 "--format" |
| or a "--size" whose argument is different to the existing block size. |
| .TP |
| --rto_req | -R |
| instructs a format to enable application client ownership of |
| the "logical block reference tag" field. The default action is to |
| disable application client ownership of that field. Has no action |
| unless both '--format' and '--pinfo' are given. |
| .TP |
| --size=<n> | -s <n> |
| 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 "--format" |
| 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). |
| .TP |
| --verbose | -v |
| increase the level of verbosity, (i.e. debug output). "-vvv" gives |
| the maximum debug output. |
| .TP |
| --version | -V |
| print the version string and then exit. |
| .TP |
| --wait | -w |
| this option only has an effect when used together with the "--format" |
| 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. "--wait") 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 NOTES |
| The format command is still quite complicated and a large set |
| of variables in the format command itself and associated parameters |
| are set to default values by this utility. These include: LONGLIST, |
| CMPLIST and the defect list format (in the command) and all flags within |
| the parameter header apart from IMMED (as explained in the "--wait" option). |
| .PP |
| The SBC-2 draft standard (revision 16) says 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 to the current |
| draft. |
| .PP |
| When the "--format" 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 FORMAT UNIT SCSI command being issued. If the "--wait" option is not |
| given then the FORMAT UNIT SCSI command is issued with the IMMED bit set |
| which causes the SCSI command to return after it has started the format |
| operation. The "--early" option will cause sg_format to exit at that |
| point. Otherwise the given device 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 can be terminated (e.g. with control-C) without effecting 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 "--format" and "--wait" 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 draft 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 "--count" argument of '-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 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 (or sginfo) utility can be |
| used to access and potentially change the now obsolete format mode page. |
| .PP |
| The argument to "--count" 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". 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, executing the format command in IMMED mode and |
| polling 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 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 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, sg_requests, sg_inq, sg_modes, sginfo, sg_wr_mode |
| .B (all in sg3_utils), sdparm |