diff options
Diffstat (limited to 'doc/sg_wr_mode.8')
| -rw-r--r-- | doc/sg_wr_mode.8 | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/doc/sg_wr_mode.8 b/doc/sg_wr_mode.8 new file mode 100644 index 00000000..e917c76e --- /dev/null +++ b/doc/sg_wr_mode.8 @@ -0,0 +1,225 @@ +.TH SG_WR_MODE "8" "April 2018" "sg3_utils\-1.43" SG3_UTILS +.SH NAME +sg_wr_mode \- write (modify) SCSI mode page +.SH SYNOPSIS +.B sg_wr_mode +[\fI\-\-contents=H,H...\fR] [\fI\-\-dbd\fR] [\fI\-\-force\fR] [\fI\-\-help\fR] +[\fI\-\-len=10|6\fR] [\fI\-\-mask=M,M...\fR] [\fI\-\-page=PG_H[,SPG_H]\fR] +[\fI\-\-rtd\fR] [\fI\-\-save\fR] [\fI\-\-six\fR] [\fI\-\-verbose\fR] +[\fI\-\-version\fR] \fIDEVICE\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +Writes a modified mode page to \fIDEVICE\fR. Uses the SCSI MODE SENSE (6 +or 10 byte variant) command to fetch the existing mode data which includes +a mode page (or subpage). It then combines that with the contents, +potentially masked, and writes the modified mode page with the SCSI MODE +SELECT (6 or 10 byte variant) command. This utility does not modify +the block descriptor(s); if any block descriptors are fetched by the MODE +SENSE command then the same block descriptors are written back with the +following MODE SELECT command. +.PP +If the \fI\-\-rtd\fR option is given then most other options apart from +\fI\-\-save\fR, \fI\-\-len=\fR10|6\fR and \fI\-\-six\fR are ignored. In this +case only a MODE SELECT command is sent to the \fIDEVICE\fR with the RTD +bit (Revert To Defaults) set. This bit was added to this command in SPC\-5 +revision 11, so older devices may not support it. The Extended Inquiry VPD +page has the RTD_SUP bit to indicate whether the \fIDEVICE\fR supports the +RTD bit in the MODE SELECT(6 and 10) commands. When the \fI\-\-rtd\fR option +is given the rest of this section can be ignored. +.PP +If a contents argument is not given then the various components (i.e. +header, block descriptor(s) and mode page) of the "current" values of +the existing mode page are printed out. In this case the mode page is +not altered on the device. +.PP +If the contents are specified, and a mask is not specified, then the contents +must match the existing mode page in various aspects unless the +\fI\-\-force\fR option is given. These include length, mode page code and +subpage code if applicable. If all is well then the contents string is +written to \fIDEVICE\fR as the new mode page. +.PP +If both contents and mask strings are specified then only bit positions +in the contents corresponding to set bits in the mask are taken while the +existing mode page supplies bit positions corresponding to clear bits. +When a mask is given then the mask and/or the contents may be shorter +than the existing mode page. If the mask is shorter than the contents then +the remaining bytes are taken from the contents. If the contents are shorter +than the existing mode page then the remaining bytes are taken from the +existing mod page. +.PP +The force option allows the contents string to be written as the new +mode page without any prior checks on the existing mode page. This should +only be required for vendor specific mode pages. The existing mode data +is ignored apart from the block descriptors which can be suppressed with +the \fI\-\-dbd\fR option if need be. +.PP +Changing individual fields in a mode page is probably more easily done +with the sdparm utility. Fields can be identified by acronym or by a +numerical descriptor. +.SH OPTIONS +Arguments to long options are mandatory for short options as well. +.TP +\fB\-c\fR, \fB\-\-contents\fR=\fIH,H...\fR +where \fIH,H...\fR is a string of comma separated hex numbers each of +which should resolve to a byte value (i.e. 0 to ff inclusive). A (single) +space separated string of hex numbers is also allowed but the list needs to +be in quotes. This is the new contents of the mode page to be written to +\fIDEVICE\fR, potentially filtered by the mask string. +.TP +\fB\-c\fR, \fB\-\-contents\fR=- +reads contents string from stdin. The hex numbers in the string may be comma, +space, tab or linefeed (newline) separated. If a line contains "#" then the +remaining characters on that line are ignored. Otherwise each non separator +character should resolve to a byte value (i.e. 0 to ff inclusive). This +forms the new contents of the mode page to be written to \fIDEVICE\fR, +potentially filtered by the mask string. +.TP +\fB\-d\fR, \fB\-\-dbd\fR +disable block descriptors (DBD flag in cdb). Some device types include +block descriptors in the mode data returned by a MODE SENSE command. If +so the same block descriptors are written by the MODE SELECT command. +This option instructs the MODE SENSE command not to return any block +descriptors. This would be a sensible default for this utility apart +from the fact that not all SCSI devices support the DBD bit in the cdb. +.TP +\fB\-f\fR, \fB\-\-force\fR +force the contents string to be taken as the new mode page, or at least +doesn't do checks on the existing mode page. Note that \fIDEVICE\fR may +still reject the new contents for the mode page. Cannot be given with +the \fI\-\-mask=M,M...\fR option. +.TP +\fB\-h\fR, \fB\-\-help\fR +output the usage message then exit. +.TP +\fB\-l\fR, \fB\-\-len\fR=10 | 6 +length of the SCSI commands (cdb) sent to \fIDEVICE\fR. The default is 10 +so 10 byte MODE SENSE and MODE SELECT commands are issued. Some old devices +don't support the 10 byte variants hence this option. +.TP +\fB\-m\fR, \fB\-\-mask\fR=\fIM,M...\fR +where \fIM,M...\fR is a string of comma separated hex numbers each of which +should resolve to a byte value (i.e. 0 to ff inclusive). A (single) space +separated string of hex numbers is also allowed but the list needs to be in +quotes. The mask chooses (bit by bit) whether the new mode page comes from +the contents (mask bit set) or from the existing mode page (mask bit clear). +If the mask string is shorter than the contents string then the remaining +bytes are taken from the contents string. If the contents string is shorter +than the existing mode page then the remaining bytes are taken from the +existing mode page (i.e. they are left unaltered). +.TP +\fB\-p\fR, \fB\-\-page\fR=\fIPG_H\fR +where \fIPG_H\fR is the page code value to fetch and modify. The page code +is in hex and should be between 0 and 3e inclusive. Notice that page code +3f to fetch all mode pages is disallowed. +.TP +\fB\-p\fR, \fB\-\-page\fR=\fIPG_H,SPG_H\fR +where \fIPG_H\fR is the page code value and \fISPG_H\fR is the subpage code +value to fetch and modify. Both values are in hex. The subpage code should +be between 0 and fe inclusive. Notice that subpage code ff to fetch all +mode subpages (for a given mode page or all mode pages in the case of 3f,ff) +is disallowed. +.TP +\fB\-R\fR, \fB\-\-rtd\fR +when this option is given most other actions are bypassed and a MODE +SELECT(6 or 10) command is sent to the \fIDEVICE\fR with the RTD bit set. +This will cause all current values (and saved values if the \fI\-\-save\fR +option is also given) of all mode pages to be reverted to their default +values. +.TP +\fB\-s\fR, \fB\-\-save\fR +changes the "saved" mode page when MODE SELECT is successful. By +default (i.e. when \fI\-\-save\fR is not used) only the "current" mode page +values are changed when MODE SELECT is successful. In this case the new mode +page will stay in effect until the device is reset (e.g. power cycled). +When it restarts the "saved" values for the mode page will be re\-instated. +So to make changes permanent use the \fI\-\-save\fR option. +.br +When used with the \fI\-\-rtd\fR option then both the current and saved +values in each mode page are reverted to their default values. In the +absence of \fI\-\-save\fR option only the current values in each mode page +are reverted to their default values. +.TP +\fB\-6\fR, \fB\-\-six\fR +this option will cause the 6 byte variants of MODE SENSE and MODE SELECT +commands to be used. The default is to use the 10 byte options. This option +is equivalent to using the \fI\-\-len=6\fR option. + +.TP +\fB\-v\fR, \fB\-\-verbose\fR +increase the level of verbosity, (i.e. debug output). +.TP +\fB\-V\fR, \fB\-\-version\fR +print the version string and then exit. +.SH NOTES +This utility does not check whether the contents string is trying to +modify parts of the mode page which are changeable. The device should +do that and if some part is not changeable then it should +report: "Invalid field in parameter list". +.PP +Some mode pages are not saveable. If so an attempt to use the \fI\-\-save\fR +option should cause an error to be reported from the device: "Illegal field +in cdb". +.PP +The device is required to do various checks before it accepts a new +mode page. If these checks fail then the mode page is not altered and +either a "parameter list length error" or an "invalid field in +parameter list" error is returned by the device in the sense data. +.PP +The recommended way to modify a mode page is to read it with a +MODE SENSE, modify some part of it then write it back to the +device with a MODE SELECT command. For example, reading an existing mode +page can be accomplished with 'sg_modes \-p=1a \-r /dev/sdb > mp_1a.txt' (the +power condition mode page). The mp_1a.txt file can be edited and then used +as the contents string to this +utility (e.g. 'sg_wr_mode \-p 1a \-s \-c \- /dev/sdb < mp_1a.txt'). +.PP +Two fields differ between what is read from the device with MODE SENSE and +what is written to the device with MODE SELECT: +the mode data length is reserved (i.e. zero(es)) in a MODE +SELECT command while the PS bit ((sub)page byte 0 bit 7) in each +mode (sub)page is reserved (zero) in a MODE SELECT command. +The PS bit given in the contents string is zeroed unless +the \fI\-\-force\fR option is selected. +.SH EXAMPLES +This utility can be used together with the sg_modes utility. To re\-instate +the default mode page values (i.e. the mode page values chosen by the +manufacturer of the device) as both the current and saved mode page +values the following sequence could be used: +.PP + $ sg_modes \-\-control=2 \-\-page=1a \-r /dev/sda > t +.br + $ sg_wr_mode \-\-page=1a \-\-contents=\- \-\-save /dev/sda < t +.PP +Next is an example of using a mask to modify the "idle condition counter" +of the "power condition" mode page (0x1a) from 0x28 to 0x37. Note that the +change is not saved so the "idle condition counter" will revert to 0x28 +after the next power cycle. The output from sg_modes is abridged. +.PP + $ sg_modes \-\-page=1a /dev/hdc +.br + >> Power condition (mmc), page_control: current +.br + 00 1a 0a 00 03 00 00 00 28 00 00 01 2c +.PP + $ sg_wr_mode \-p 1a \-c 0,0,0,0,0,0,0,37 \-m 0,0,0,0,0,0,0,ff /dev/hdc +.PP + $ sg_modes \-p 1a /dev/hdc +.br + >> Power condition (mmc), page_control: current +.br + 00 1a 0a 00 03 00 00 00 37 00 00 01 2c +.SH EXIT STATUS +The exit status of sg_wr_mode is 0 when it is successful. Otherwise see +the sg3_utils(8) man page. +.SH AUTHORS +Written by Douglas Gilbert. +.SH "REPORTING BUGS" +Report bugs to <dgilbert at interlog dot com>. +.SH COPYRIGHT +Copyright \(co 2004\-2018 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 sdparm(sdparm), sg_modes(sg3_utils), sginfo(sg3_utils) |