title: sg_sat_read_gplog(8)

text:
# sg_sat_read_gplog(8)

## NAME
sg_sat_read_gplog - use ATA READ LOG EXT or SMART READ LOG command via a SCSI to ATA Translation (SAT) layer

## SYNOPSIS
sg_sat_read_gplog [--address=LA_L] [--ck_cond] [--count=CO] [--dma] [--help] [--hex] [--len=CMD_LEN] [--log=LA_L] [--page=PN] [--ppt=PPT] [--readonly] [--smart] [--verbose] [--version] DEVICE

## DESCRIPTION
This utility sends an ATA READ LOG EXT, an ATA READ LOG DMA EXT, or an ATA SMART READ LOG command to the DEVICE. The default is to send one of the first two commands to read "general purpose log" page(s). Only (S)ATA devices (e.g. disks) but not ATAPI devices (e.g. DVD readers) support the general purpose log pages. Rather than send the READ LOG (DMA) EXT command directly to the device it is sent via a SCSI transport which is assumed to contain a SCSI to ATA Translation (SAT) Layer (SATL). The SATL may be in an operating system driver, in host bus adapter (HBA) firmware or in some external enclosure.

This utility does not currently attempt to decode the response from the ATA disk, rather it outputs the response in ASCII hexadecimal grouped in 8 bit bytes or 16 bit words. Following ATA conventions those words are decoded little endian (note that SCSI commands use a big endian representation). Log address 0, page number 0 is the 'directory' log page and it is decoded if no --hex option is given. In the future this utility may attempt to decode other log pages. Perhaps other ATA utility will be able to decode these log pages given hex output from this utility.

Fetching all log pages seems as simple as reading the directory log page then accessing those log addresses that have more than zero associated page numbers. Unfortunately it is not that simple. Some log addresses (looking specifically at 0xe1 ("SCT Data transfer")) need a SCT command executed prior to fetching the log page at that log address. Other log addresses might be problematic (e.g. it has been suggested that the "Device vendor specific logs" 0xa0:0xdf) so maybe they also should be avoided. That is the reason the --address=LA_L and --log=LA_L options are designed to take a list of ranges.

The SAT-4 standard (SAT ANSI INCITS 491-201r7 prior draft: sat4r06.pdf at www.t10.org) defines three SCSI "ATA PASS-THROUGH" commands: one using a 12 byte "cdb", another using a 16 bytes cdb, and the third a 32 byte cdb. This utility defaults to using the 16 byte cdb variant.

## OPTIONS
Arguments to long options are mandatory for short options as well.

-a, --address=LA_L

where LA_L is as single "log address", a range of log addresses, or a list of (ranges of) log addresses. A log address is a number between 0 and 255 (0xff) where log address 0, page number 0, is a directory. A range of log addresses has the form "lo:hi" where log address "hi" must be greater than or equal to "lo". A log address list is a comma separated list of log addresses or log address ranges.

Each log address contain up to 256 (SMART log) or 65536 (General purpose log) page numbers, starting at page number 0. The number of page numbers available for each log address is enumerated in the log directory page.

Summary of LA_L syntax: lo:hi,lo2:hi2,lo3:hi3 ...

-C, --ck_cond

sets the CK_COND bit in the ATA PASS-THROUGH SCSI cdb. The default setting is clear (i.e. 0). When set the SATL should yield a sense buffer containing a ATA Result descriptor irrespective of whether the ATA command succeeded or failed. When clear the SATL should only yield a sense buffer containing an ATA Result descriptor if the ATA command failed.

-c, --count=CO

the number CO is placed in the "count" field in the ATA READ LOG EXT command. This specified the number of 512-byte log pages of data to be read from the specified log address. The given page address starting at the given page number is read. The last page number read will be (PN + CO - 1) if it exists.

The maximum value of CO is 0xffff (65,535) for general purpose log pages and 0xff (255) for SMART log pages.

An error is typically reported if the given --page=PN (default 0) plus CO exceeds the number shown in the log directory (log address 0) for the given log address.

Note that the CO only applies to the current log address; in other words there is no wrap around to the beginning of the next log address.

-d, --dma

use the ATA READ LOG DMA EXT command instead of ATA READ LOG EXT command. Some devices require this to return valid log data.

-h, --help

outputs the usage message summarizing command line options then exits. Ignores DEVICE if given.

-H, --hex

when given once, the response is output in ASCII hexadecimal bytes. When given twice, then the response is grouped into 16 bit words using ATA conventions (i.e. little endian); this is the default output (i.e. when this option is not given). When given thrice (i.e. '-HHH') the output is in hex, grouped in 16 bit words (without a leading offset and trailing ASCII on each line), in a format that is acceptable for 'hdparm --Istdin' to process.

If this option is invoked four times (e.g. '-HHHH') log pages are output as hex bytes, with no leading address at the start of each line. That makes the hex easier for computers to decode (but not humans). If this option is invoked five times then a comment line, starting with a '#' character is output before each 512 byte log page. The comment describes the following log page.

-l, --len=CMD_LEN

where CMD_LEN is the command (cdb) length of the SCSI ATA PASS-THROUGH command that is used to tunnel ATA commands. Three values are permitted: 12, 16 and 32 (bytes long). The 12 byte variant has the most restrictions (e.g. its 'count' field is a single byte) but older systems may not permit 16 or 32 byte commands.

-L, --log=LA_L

see the --address=LA_L option.

-p, --page=PN

the number PN is the page number (within the log address) and is placed in bits 32:16 of the "lba" field of the ATA READ LOG (DMA) EXT command. The default value placed in the "lba" field is 0.

The maximum value of PN is 0xffff (65,535) for general purpose log pages and 0xff (255) for SMART log pages. In the latter case PN must be 0 and CO is 255.

When multiple log addresses are specified (via the LA_L argument) then this option is treated differently. With multiple log addresses and if PN is greater than 0 then it acts as an upper limit of the number of page numbers that will be output for each log address. The actual number of 512 byte log pages output will also depend on the number of page numbers shown in the directory log page for the current log address.

-P, --ppt=PPT

where PPT is the number of pages to transfer from the DEVICE per ATA READ LOG EXT or an ATA READ LOG DMA EX command invocation. The default value is 128 (or 64 kibiBytes) which is chosen because most OSes have an upper limit on the size of transfers to and from a device with a single command. When the number of log pages given with the --count=CO option is large , it can exceed what an OS will allow in a single command invocation. Hence the need for this option.

-l, --len={32|16|12}

this is the length of the SCSI cdb used for the ATA PASS-THROUGH commands. The argument can either be 32, 16 or 12. The default is 16. Some SCSI transports cannot convey SCSI commands longer than 12 bytes.

-r, --readonly

causes the DEVICE to be opened with the read-only flag (O_RDONLY in Unix). The default action is to open DEVICE with the read-write flag (O_RDWR in Unix). In some cases sending power management commands to ATA disks are defeated by OS actions on the close() if the DEVICE was opened with the read-write flag (e.g. the OS might think it needs to flush something to disk).

-s, --smart

in the ATA SMART feature set, "SMART" log pages have been present for a long time and pre-date the later addition of the "general purpose" log pages. So this utility can be easily be extended to read "SMART" log pages instead of the general purpose log pages. That is exactly what this option does.

The ATA SMART READ LOG command has no page number field, all fetches start from page number 0. Also the number of page numbers (in it log address) is limited to a single byte (so 255). The general purpose log directory page and the SMART log directory page have the same format (given the single byte restriction on the number of page numbers in each SMART log address).

-v, --verbose

increases the level or verbosity.

-V, --version

print out version string

## NOTES
Prior to Linux kernel 2.6.29 USB mass storage limited sense data to 18 bytes which made the --ck_cond option yield strange (truncated) results.

There are slight differences in handling when a single log address is being fetched, and when multiple log pages are being fetched. In the single log address case the log address, the page number and the count going into the corresponding fields in the ATA READ LOG EXT or ATA SMART READ LOG command. When multiple log addresses are given, the 'directory' log page (log_address=0, page_number=0) is first loaded. Then only log addresses which the directory indicates have more than zero log page numbers, are fetched. The count of log page numbers accessed may be further restricted by the --page=PN option if PN is greater than zero.

## EXAMPLES
First here is an example avoiding the problematic log addresses noted in the DESCRIPTION section above.

sg_sat_read_gplog -a 0:0xb,0xd:0x9f,0xe0,0xe2:255 /dev/sdc

The above is using the short form of the --address=LA_L option with a list that avoids log addresses 0xc, 0xa0 to 0xdf and 0xe1 . The output will include all log addresses, apart from those exclusions, that the directory indicates have more than 0 page numbers.

The following invocation uses the SMART READ LOG command instead of the READ LOG EXT command:

sg_sat_read_gplog --smart -a 0:0xb,0xd:0x9f,0xe0,0xe2:255 /dev/sdc

## EXIT STATUS
The exit status of sg_sat_read_gplog is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHOR
Written by Hannes Reinecke and Douglas Gilbert

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2014-2023 Hannes Reinecke, SUSE Linux GmbH

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_sat_identify(sg3_utils), sg_inq(sg3_utils), sdparm(sdparm), hdparm(hdparm), smartctl(smartmontools)


title: sg_sat_set_features(8)

text:
# sg_sat_set_features(8)

## NAME
sg_sat_set_features - use ATA SET FEATURES command via a SCSI to ATA Translation (SAT) layer

## SYNOPSIS
sg_sat_set_features [--count=CO] [--ck_cond] [--extended] [--feature=FEA] [--help] [--lba=LBA] [--len={16|12}] [--readonly] [--verbose] [--version] DEVICE

## DESCRIPTION
This utility sends an ATA SET FEATURES command to the DEVICE. This command is used to change settings of ATA non-packet (i.e. disks) and packet devices (e.g. cd/dvd drives). Rather than send the SET FEATURES command directly to the device it is sent via a SCSI transport which is assumed to contain a SCSI to ATA Translation (SAT) Layer (SATL). The SATL may be in an operating system driver, in host bus adapter firmware or in some external enclosure.

The SAT standard (SAT ANSI INCITS 431-2007, prior draft: sat-r09.pdf at www.t10.org) defines two SCSI "ATA PASS-THROUGH" commands: one using a 16 byte "cdb" and the other with a 12 byte cdb. This utility defaults to using the 16 byte cdb variant. SAT-2 is also a standard: SAT-2 ANSI INCITS 465-2010 and the draft prior to that is sat2r09.pdf . The SAT-3 project has started and the most recent draft is sat3r05b.pdf .

The features can be read using the sg_sat_identify utility which uses either the ATA IDENTIFY DEVICE (for non-packet devices) or the IDENTIFY PACKET DEVICE (for packet devices) command.

## OPTIONS
Arguments to long options are mandatory for short options as well.

-c, --count=CO

the number CO is placed in the "count" field in the ATA SET FEATURES command. Only some subcommands (a term used for the value placed in the "feature" field) require the count field to be set. The default value placed in the "count" field is 0.

-C, --ck_cond

sets the CK_COND bit in the ATA PASS-THROUGH SCSI cdb. The default setting is clear (i.e. 0). When set the SATL should yield a sense buffer containing a ATA Result descriptor irrespective of whether the ATA command succeeded or failed. When clear the SATL should only yield a sense buffer containing a ATA Result descriptor if the ATA command failed.

-e, --extended

allow for extended LBA numbers (i.e. larger than 32 bits). This value is enabled automatically for large LBA numbers, but can be enabled explicitly even for low LBA numbers with this option.

-f, --feature=FEA

the value FEA is placed in the "feature" field in the ATA SET FEATURES command. The term "subcommand" is sometimes used for this value. The default value placed in the "feature" field is 0 which is reserved and hence should not change anything. Two common examples are 2h to enable the write cache and 82h to disable it.

-h, --help

outputs the usage message summarizing command line options then exits. Ignores DEVICE if given.

-L, --lba=LBA

the number LBA is placed in the "lba" field of the ATA SET FEATURES command. Only some sub-commands (a term used for the value placed in the "feature" field) require the lba field to be set. This value is typically not a "logical block address" as the acronym might imply. The default value placed in the "lba" field is 0. The maximum value allowed for LBA is 0xfffffffe (or 0xffffff if --len=12).

-l, --len={16|12}

this is the length of the SCSI cdb used for the ATA PASS-THROUGH commands. The argument can either be 16 or 12. The default is 16. Some SCSI transports cannot convey SCSI commands longer than 12 bytes.

-r, --readonly

causes the DEVICE to be opened with the read-only flag (O_RDONLY in Unix). The default action is to open DEVICE with the read-write flag (O_RDWR in Unix). In some cases sending power management commands to ATA disks are defeated by OS actions on the close() if the DEVICE was opened with the read-write flag (e.g. the OS might think it needs to flush something to disk).

-v, --verbose

increases the level or verbosity.

-V, --version

print out version string

## NOTES
In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 and 3 series block devices (e.g. disks and ATAPI DVDs) can also be specified. For example "sg_inq /dev/sda" will work in the 2.6 series kernels. From lk 2.6.6 other SCSI "char" device names may be used as well (e.g. "/dev/st0m"). Prior to lk 2.6.29 USB mass storage limited sense data to 18 bytes which made the --ck_cond option yield strange (truncated) results.

## EXIT STATUS
The exit status of sg_sat_set_features is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHOR
Written by Douglas Gilbert

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2007-2014 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_sat_identify(sg3_utils), sg_inq(sg3_utils), sdparm(sdparm), hdparm(hdparm)


title: sg_scan(8)

text:
# sg_scan(8)

## NAME
sg_scan - scans sg devices (or SCSI/ATAPI/ATA devices) and prints results

## SYNOPSIS
sg_scan [-a] [-i] [-n] [-w] [-x] [DEVICE]*

## DESCRIPTION
If no DEVICE names are given, sg_scan does a scan of the sg devices and outputs a line of information for each sg device that is currently bound to a SCSI device. If one or more DEVICEs are given only those devices are scanned. Each device is opened with the O_NONBLOCK flag so that the scan will not "hang" on any device that another process holds an O_EXCL lock on.

Any given DEVICE name is expected to comply with (to some extent) the Storage Architecture Model (SAM see www.t10.org). Any device names associated with the Linux SCSI subsystem (e.g. /dev/sda and /dev/st0m) are suitable. Devices names associated with ATAPI devices (e.g. most CD/DVD drives and ATAPI tape drives) are also suitable. If the device does not fall into the above categories then an ATA IDENTIFY command is tried.

In Linux 2.6 and 3 series kernels, the lsscsi utility may be helpful. Apart from providing more information (by data-mining in the sysfs pseudo file system), it does not need root permissions to execute, as this utility would typically need.

## OPTIONS
-a

do alphabetical scan (i.e. sga, sgb, sgc). Note that sg device nodes with an alphabetical index have been deprecated since the Linux kernel 2.2 series.

-i

do a SCSI INQUIRY, output results in a second (indented) line. If the device is an ATA disk then output information from an ATA IDENTIFY command

-n

do numeric scan (i.e. sg0, sg1...) [default]

-w

use a read/write flag when opening sg device (default is read-only)

-x

extra information output about queueing

## NOTES
This utility was written at a time when hotplugging of SCSI devices was not supported in Linux. It used a simple algorithm to scan sg device nodes in ascending numeric or alphabetical order, stopping after there were 4 consecutive errors.

In the Linux kernel 2.6 series, this utility uses sysfs to find which sg device nodes are active and only checks those. Hence there can be large "holes" in the numbering of sg device nodes (e.g. after an adapter has been removed) and still all active sg device nodes will be listed. This utility assumes that sg device nodes are named using the normal conventions and searches from /dev/sg0 to /dev/sg4095 inclusive.

## EXIT STATUS
The exit status of sg_scan is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHORS
Written by D. Gilbert and F. Jansen

## COPYRIGHT
Copyright © 1999-2013 Douglas Gilbert

This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
lsscsi(8)


title: sg_seek(8)

text:
# sg_seek(8)

## NAME
sg_seek - send SCSI SEEK, PRE-FETCH(10) or PRE-FETCH(16) command

## SYNOPSIS
sg_seek [--10] [--count=NC] [--grpnum=GN] [--help] [--immed] [--lba=LBA] [--num-blocks=NUM] [--pre-fetch] [--readonly] [--skip=SB] [--time] [--verbose] [--version] [--wrap-offset=WO] DEVICE

## DESCRIPTION
Sends a SCSI SEEK(10), PRE-FETCH(10) or PRE-FETCH(16) command to the DEVICE. The SEEK command has been obsolete since SBC-2 (2005) but still is supported on some hard disks and even some SSDs (solid state disks). The PRE-FETCH command can be viewed as SEEK's modern replacement. Instead of talking about moving the disk heads to the track containing the sort after LBA, it talks about bringing the sort after LBA (and a given number of blocks) into the disk's cache. Also the PRE-FETCH commands have an IMMED field.

The PRE-FETCH commands can report "real" errors but usually they will report one of two "good" statuses. To do this they return the rarely used CONDITION MET status. If the number of blocks does actually fit in the cache (when IMMED=0) or there is enough room in the cache when the command arrives (when IMMED=1) then a CONDITION MET status is returned. If the requested number of blocks did not fit (IMMED=0) or would not fit (IMMED=1) then status GOOD is returned. So if a disk has a large cache and PRE-FETCH is used sparingly then the command is more likely to return CONDITION MET than GOOD. This presents some SCSI sub-systems with problems as due to its rareness they mishandle CONDITION MET and treat it as an error (see NOTES section below).

## OPTIONS
Arguments to long options are mandatory for short options as well.

-T, --10

use a 10 byte cdb command, either SEEK(10) or PRE-FETCH(10) command. In the absence of the --pre-fetch option, the SEEK(10) command is used. If the --pre-fetch option is given without this option then a PRE-FETCH(16) command is used.

-c, --count=NC

NC is the number of commands (one of SEEK(10), PRE-FETCH(10) or PRE-FETCH(16)) that will be executed. The default value is 1. If an error occurs it is noted and the program continues until NC is exhausted. If NC is 0 then options are checked and the DEVICE is opened but no commands are sent.

-g, --grpnum=GN

GN is the group number, a value between 0 and 63 (in hex: 0x3f). The default value is 0. This option is ignored if the selected command is SEEK(10).

-h, --help

output the usage message then exit.

-i, --immed

this option only applies to PRE-FETCH(10) and PRE-FETCH(16), setting the IMMED bit. Without this option, the DEVICE returns after it has completed transferring all, or part of, the requested blocks into the cache. If this option is given the DEVICE returns after it has done sanity checks on the cdb (e.g. making sure the LBA is greater than the number of available blocks) and before it does the transfer into the cache.

Note that even when this option is given, the return status from the PRE-FETCH commands is still either CONDITION MET status (if the cache seems to have enough free space for the transfer) or a GOOD status (if the cache does not seem to have enough free space).

-l, --lba=LBA

LBA is the starting logical block address that is placed in the command descriptor block (cdb) of the selected command. Note that the LBA field in SEEK(10) and PRE-FETCH(10) is a 32 bit quantity, while with PRE-FETCH(16) it is a 64 bit quantity. The default value is 0 .

-n, --num-blocks=NUM

NUM is the number of blocks, starting at and including LBA, to place in the DEVICE's cache. The SEEK(10) command does not use the NUM value. For PRE-FETCH(10) NUM is a 16 bit quantity, while for PRE-FETCH(16) it is a 32 bit quantity. The default value is 1 . If NUM is 0 then the DEVICE will attempt to transfer all blocks from the given LBA to the end of the medium.

-p, --pre-fetch

this option selects either PRE-FETCH(10) or PRE-FETCH(16) commands. With the --10 also given, the PRE-FETCH(10) command is selected; without that option PRE-FETCH(16) is selected. The default (in the absence of this and other 'selecting' options) the SEEK(10) command is selected.

-r, --readonly

this option sets a 'read-only' flag when the underlying operating system opens the given DEVICE. This may not work since operating systems can not easily determine whether a pass-through is a logical read or write operation so they take a risk averse stance and require read-write type DEVICE opens irrespective of what is performed by the pass-through.

-s, --skip=SB

SB is the number of logical block addresses to skip, between repeated commands when NC is greater than 1. The default value of SB is 1 . SB may be set to 0 so that all NC PRE-FETCH commands use the same LBA.

-t, --time

if given the elapsed time to execute NC commands is recorded. This is printed out before this utility exits. If NC is greater than 1 then the the "per command" time is also printed.

-v, --verbose

increase the level of verbosity, (i.e. debug output).

-V, --version

print the version string and then exit.

-w, --wrap-offset=WO

WO is the number of blocks, relative to LBA, that when exceeded, set the next command's logical block address back to LBA. Whether this "reset-to-LBA" action occurs depends on the values NC and SB.

## NOTES
Prior to Linux kernel 4.17 the CONDITION MET status was logged as an error. Recent versions of FreeBSD handle the CONDITION MET status properly.

If either the --count=NC or --verbose option is given then a summary line like the following is output:

Command count=5, number of condition_mets=3, number of goods=2

before the utility exits.

## EXIT STATUS
The exit status of sg_seek is 0 (GOOD) or 25 (CONDITION_MET) when this utility is successful. If multiple commands are executed (e.g. when NC is greater than 1) then the result of the last executed SEEK or PRE-FETCH command sets the exit status. Otherwise see the sg3_utils(8) man page.

## AUTHORS
Written by Douglas Gilbert.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2018 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_vpd(sg3_utils); sdparm(sdparm)


title: sg_senddiag(8)

summary: performs a SCSI SEND DIAGNOSTIC command

text:
# sg_senddiag(8)

## NAME
sg_senddiag - performs a SCSI SEND DIAGNOSTIC command

## SYNOPSIS
sg_senddiag [--doff] [--extdur] [--help] [--hex] [--list] [--maxlen=LEN] [--page=PG] [--pf] [--raw=H,H...] [--raw=-] [--selftest=ST] [--test] [--timeout=SECS] [--uoff] [--verbose] [--version] DEVICE

sg_senddiag [-doff] [-e] [-h] [-H] [-l] [-pf] [-raw=H,H...] [-raw=-] [-s=ST] [-t] [-T=SECS] [-uoff] [-v] [-V] [-?] DEVICE

## DESCRIPTION
This utility sends a SCSI SEND DIAGNOSTIC command to the DEVICE. It can issue self-tests, find supported diagnostic pages or send arbitrary diagnostic pages.

When the --list option and a DEVICE are given then the utility sends a SCSI RECEIVE DIAGNOSTIC RESULTS command to fetch the response (i.e. the page numbers of supported diagnostic pages).

When the --list option is given without a DEVICE then a list of diagnostic page names and their numbers, known by this utility, are listed.

This utility supports two command line syntax-es, the preferred one is shown first in the synopsis and explained in this section. A later section on the old command line syntax outlines the second group of options.

## OPTIONS
Arguments to long options are mandatory for short options as well.

-d, --doff

set the Device Offline (DevOffL) bit (default is clear). Only significant when --test option is set for the default self-test. When set other operations on any logical units controlled by the this device server (target) may be affected (delayed) while a default self-test is underway.

-e, --extdur

outputs the expected extended self-test duration. The duration is given in seconds (and minutes in parentheses). This figure is obtained from mode page 0xa (i.e. the control mode page).

-h, --help

print usage message then exit.

-H, --hex

outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode it. Only the Supported Diagnostic Pages diagnostic page (i.e. page_code=0) is decoded; other pages (e.g. those used by SES) are output in hex.

If --hex is used once, the hex output has a relative address at the start of each line. If --hex is used twice, then ASCII is shown to the right of each line of hex. If --hex is used three time or more, only the hex is output, in two character pairs (i.e. a byte) space separated and up to 16 bytes per line. This latter form, if placed in a file or piped through to another invocation, is suitable for the --raw=- option.

-l, --list

when a DEVICE is also given lists the names of all diagnostic pages supported by this device. The request is sent via a SEND DIAGNOSTIC command (with the "pF" bit set) and the response is fetched by a RECEIVE DIAGNOSTIC RESULTS command. When used in the absence of a --list argument then a list of diagnostic page names and their numbers, known by this utility, are listed.

-m, --maxlen=LEN

where LEN is the value placed in the parameter list length field of a SEND DIAGNOSTIC command or in the allocation length field of a RECEIVE DIAGNOSTIC RESULTS command. This only occurs when the other options imply there will be data sent or received by the command. The default value is 4096 bytes. LEN cannot exceed 65535 or 0xffff in hexadecimal.

-O, --old

Switch to older style options. Please use as first option.

-P, --page=PG

where PG is the RECEIVE DIAGNOSTIC RESULTS command page code field. If this option is given the PCV bit in that command is set. When this option is given then no SEND DIAGNOSTIC command is sent (unlike --list). If PG is 0 then the response is decoded as if it is the SPC Supported Diagnostic pages diagnostic page. Other PG values (i.e. 1 to 255) have their responses output in hex.

-p, --pf

set Page Format (PF) bit. By default it is clear (i.e. 0) unless the list --list option is given in which case the Page Format bit is set (as required by SPC-3).

-r, --raw=H,H...

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 bytes is also allowed but the list needs to be in quotes. This sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the --pf option should also be given.

-r, --raw=-

reads sequence of bytes from stdin. The sequence 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 sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the --pf option should also be given.

-s, --selftest=ST

where ST is the self-test code. The default value is 0 which is inactive. Some other values:

1 : background short self-test

2 : background extended self-test

4 : aborts a (background) self-test that is in progress

5 : foreground short self-test

6 : foreground extended self-test

This option is mutually exclusive with default self-test (i.e. can't have (ST > 0) and --test).

-t, --test

sets the _default_ Self Test (SelfTest) bit. By default this is clear (0). The --selftest=ST option should not be active together with this option. Both the --doff and/or --uoff options can be used with this option.

-T, --timeout=SECS

where SECS is a timeout value (in seconds) for foreground self-test operations. The default value is 7200 seconds (2 hours) and any values of SECS less than the default are ignored.

-u, --uoff

set the Unit Offline (UnitOffL) bit (default is clear). Only significant when --test option is set for the default self-test. When set other operations on this logical unit may be affected (delayed) while a default self-test is underway. Some devices (e.g. Fujitsu disks) do more tests when this bit is set.

-v, --verbose

increase level of verbosity. Can be used multiple times.

-V, --version

print out version string then exit.

## NOTES
All devices should support the default self-test. The 'short' self-test codes should complete in 2 minutes or less. The 'extended' self-test codes' maximum duration is vendor specific (e.g. a little over 10 minutes with the author's disks). The foreground self-test codes wait until they are completed while the background self-test codes return immediately. The results of both foreground and background self-test codes are placed in the 'self-test results' log page (see sg_logs(8)). The SCSI command timeout for this utility is set to 60 minutes to allow for slow foreground extended self-tests.

If the DEVICE is a disk then no file systems residing on that disk should be mounted during a foreground self-test. The reason is that other SCSI commands may become queued behind the foreground self-test and timeout.

When the --raw=H,H... option is given then self-tests should not be selected. However the --pf (i.e. "page format") option should be given. The length of the diagnostic page to be sent is derived from the number of bytes given to the --raw=H,H... option. The diagnostic page code (number) should be the first byte of the sequence (i.e. as dictated by SPC-3 diagnostic page format). See the EXAMPLES section below.

Arbitrary diagnostic pages can be read (in hex) with the sg_ses(8) utility (not only those defined in SES-2).

If the utility is used with no options (e.g. "sg_senddiag /dev/sg1") Then a degenerate SCSI SEND DIAGNOSTIC command is sent with zero in all its fields apart from the opcode. Some devices report this as an error while others ignore it. It is not entirely clear from SPC-3 if it is invalid to send such a command.

In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. SCSI disks and DVD drives) can also be specified.

To access SCSI enclosures see the sg_ses(8) utility. sg_ses uses the SCSI SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS commands as outlined in the SES-2 (draft) standard.

## EXIT STATUS
The exit status of sg_senddiag is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## OLDER COMMAND LINE OPTIONS
The options in this section were the only ones available prior to sg3_utils version 1.23 . Since then this utility defaults to the newer command line options which can be overridden by using --old (or -O) as the first option. See the ENVIRONMENT VARIABLES section for another way to force the use of these older command line options.

-doff

set the Device Offline (DevOffL) bit (default is clear). Only significant when -t option is set for the default self-test. Equivalent to --doff in the main description.

-e

outputs the expected extended self-test duration. Equivalent to --extdur in the main description.

-h

outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode it.

-H

outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode it.

-l

when a DEVICE is also given lists the names of all diagnostic pages supported by this device. The request is sent via a SEND DIAGNOSTIC command (with the "pf" bit set) and the response is fetched by a RECEIVE DIAGNOSTIC RESULTS command. When used in the absence of a DEVICE argument then a list of diagnostic page names and their numbers, known by this utility, are listed.

-N, --new

Switch to the newer style options.

-pf

set Page Format (PF) bit. By default it is clear (i.e. 0) unless the -l option is given in which case the Page Format bit is set (as required by SPC-3).

-raw=H,H...

string of comma separated hex numbers each of which should resolve to a byte value (i.e. 0 to ff inclusive). This sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the -pf option should also be given.

-raw=-

reads sequence of bytes from stdin. The sequence 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 sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the -pf option should also be given.

-s=ST

where ST is the self-test code. The default value is 0 which is inactive. A value of 1 selects a background short self-test; 2 selects a background extended self-test; 5 selects a foreground short self-test; 6 selects a foreground extended test. A value of 4 will abort a (background) self-test that is in progress. This option is mutually exclusive with default self-test (i.e. -t).

-t

sets the _default_ Self Test (SelfTest) bit. By default this is clear (0). The -s=ST option should not be active together with this option. Both the -doff and/or -uoff options can be used with this option.

-T=SECS

where SECS is a timeout value (in seconds) for foreground self-test operations. See the --timeout=SECS option above.

-uoff

set the Unit Offline (UnitOffL) bit (default is clear). Equivalent to --uoff in the main description.

-v

increase level of verbosity. Can be used multiple times.

-V

print out version string then exit.

-?

output usage message. Ignore all other parameters.

## EXAMPLES
The examples sub-directory in the sg3_utils packages contains two example scripts that turn on the CJTPAT (jitter pattern) on some SAS disks (one script for each phy). One possible invocation for phy 1 is:

sg_senddiag --pf --raw=- /dev/sg2 < sdiag_sas_p1_cjtpat.txt

There is also an example script that turns on the IDLE pattern. Once a test pattern has been started it can be turned off by resetting the phy or with the STOP phy pattern function:

sg_senddiag --pf --raw=- /dev/sg2 < sdiag_sas_p1_stop.txt

## ENVIRONMENT VARIABLES
Since sg3_utils version 1.23 the environment variable SG3_UTILS_OLD_OPTS can be given. When it is present this utility will expect the older command line options. So the presence of this environment variable is equivalent to using --old (or -O) as the first command line option.

## AUTHOR
Written by Douglas Gilbert

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2003-2018 Douglas Gilbert

This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_ses(8), sg_logs(8), smartmontools(see net)


title: sg_ses(8)

text:
# sg_ses(8)

## NAME
sg_ses - access a SCSI Enclosure Services (SES) device

## SYNOPSIS
sg_ses [--all] [--ALL] [--descriptor=DES] [--dev-slot-num=SN] [--eiioe=A_F] [--filter] [--get=STR] [--hex] [--index=IIA | --index=TIA,II] [--inner-hex] [--join] [--json[=JO]] [--js-file=JFN] [--maxlen=LEN] [--no-config] [--no-time] [--page=PG] [--quiet] [--raw] [--readonly] [--sas-addr=SA] [--status] [--verbose] [--warn] DEVICE

sg_ses --control [--byte1=B1] [--clear=STR] [--data=H,H...] [--data=@FN] [--descriptor=DES] [--dev-slot-num=SN] [--index=IIA | --index=TIA,II] [--mask] [--maxlen=LEN] [--nickname=SEN] [--nickid=SEID] [--page=PG] [--readonly] [--sas-addr=SA] [--set=STR] [--verbose] DEVICE

sg_ses --data=@FN --status [--raw --raw] [<all options from first form>]

sg_ses --inhex=FN --status [--raw --raw] [<all options from first form>]

sg_ses [--enumerate] [--index=IIA] [--list] [--help] [--version]

## DESCRIPTION
Fetches management information from a SCSI Enclosure Service (SES) device. This utility can also modify the state of a SES device. The DEVICE should be a SES device which may be a dedicated enclosure services processor in which case an INQUIRY response's Peripheral Device Type is 13 [0xd]. Alternatively it may be attached to another type of SCSI device (e.g. a disk) in which case the EncServ bit is set in its INQUIRY response.

If the DEVICE argument is given with no options then the names of all SES diagnostic pages (dpages) supported are listed. Most of the named dpages are defined in the SES standards and drafts. The most recent reference for this utility is the draft SCSI Enclosure Services 4 document T10/BSR INCITS 555 Revision 5 at https://www.t10.org . Existing standards for SES, SES-2 and SES-3 are ANSI INCITS 305-1998 and ANSI INCITS 448-2008 and ANSI INCITS 518-2017 respectively.

SAS expanders typically have a SES device attached via a virtual port. Some HBAs (SCSI initiators) choose to expose a SES device internally. That means the SCSI subsystem on the host machine can see the SES device, but devices connected to that HBA (e.g. a SAS expander) cannot see the HBA's SES device. That internal SES device might report on the temperature(s) of the HBA and whether anything is connected to its SCSI ports.

The first form shown in the SYNOPSIS is for fetching and decoding dpages or fields from the SES DEVICE. A SCSI RECEIVE DIAGNOSTIC RESULTS command is sent to the DEVICE to obtain each dpage response. Rather than decoding a fetched dpage, its contents may be output in hex or binary with the --hex or --raw --raw options.

The second form in the SYNOPSIS is for modifying dpages or fields held in the SES DEVICE. A SCSI SEND DIAGNOSTIC command containing a "control" dpage is sent to the DEVICE to cause changes. Changing the state of an enclosure (e.g. requesting the "ident" (locate) LED to flash on a disk tray in an array) is typically done using a read-modify-write cycle. See the section on CHANGING STATE below.

The third form in the SYNOPSIS has two equivalent invocations shown. They decode the contents of a file (named FN) that holds a hexadecimal or binary representation of one, or many, SES dpage responses. Typically an earlier invocation of the first form of this utility with the '-HHHH' option would have generated that file. Since no SCSI commands are sent; the DEVICE argument, if given, will be ignored.

The last form in the SYNOPSIS shows the options for providing command line help (i.e. usage information), listing out dpage and field information tables held by the utility (--enumerate), or printing the version string of this utility.

There is a web page discussing this utility at https://sg.danny.cz/sg/sg_ses.html . Support for downloading microcode to a SES device has been placed in a separate utility called sg_ses_microcode.

In the following sections "dpage" refers to a diagnostic page, either fetched with a SCSI RECEIVE DIAGNOSTIC RESULTS command, sent to the DEVICE with a SCSI SEND DIAGNOSTIC command, or fetched from data supplied by the --data= or the --inhex=FN option.

## 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.

-a, --all

shows the output of the --join option followed by the other SES dpages. Since a single --join option does not include the Threshold In dpage, it is listed separately in the "other SES dpages" section. In this context, "other" means all SES dpages that have not (explicitly) been output by the --join option.

To output all pages without attempting a join, use the --page=all option rather than this option.

If this option is used twice, the Threshold In dpage (if available) is included in the --join option output. Note that now the Threshold In dpage is not listed separately in the "other SES dpages" section. Using this option twice is equivalent to invoking the --ALL option.

This option implies the --status option as long as the --control option has not been given.

Using this option together with the -HHH, -HHHH or -HHHHH options is considered an error as it produces confusing output. To force the issue use -H times (as discouragement). Instead using the --page=all option together with the -HHH, -HHHH or -HHHHH options will more likely produce the desired output: a dump of all SES diagnostics pages in hex suitable for later parsing or visual inspection with a text editor.

-z, --ALL

shows the output of the --join option invoked twice, followed by the other SES dpages. Since two --join options does include the Threshold In dpage, that dpage is not listed separately in the "other SES dpages" section.

This option implies the --status option as long as the --control option has not been given.

-b, --byte1=B1

some modifiable dpages may need byte 1 (i.e. the second byte) set. In the Enclosure Control dpage, byte 1 contains the INFO, NON-CRIT, CRIT and UNRECOV bits. In the Subenclosure String Out, Subenclosure Nickname Control and Download Microcode Control dpages, byte 1 is the Subenclosure identifier. Active when the --control and --data=H,H... options are used and the default value is 0. If the --clear=STR or --set=STR option is used then the value read from byte 1 is written back to byte 1. B1 is in decimal unless it is prefixed by '0x' or '0X' (or has a trailing 'h' or 'H').

-C, --clear=STR

Used to clear an element field in the Enclosure Control or Threshold Out dpage. Must be used together with an indexing option to specify which element is to be changed. The Enclosure Control dpage is assumed if the --page=PG option is not given. See the STR FORMAT and the CLEAR, GET, SET sections below.

-c, --control

will send control information to the DEVICE via a SCSI SEND DIAGNOSTIC command. Cannot give both this option and --status. The Enclosure Control, String Out, Threshold Out, Array Control (obsolete in SES-2), Subenclosure String Out, Subenclosure Nickname Control and Download Microcode dpages can be set currently. This option is assumed if either the --clear=STR or --set=STR option is given.

-d, --data=H,H...

permits a string of comma separated (ASCII) hex bytes to be specified (limit 1024). A (single) space separated string of hex bytes is also allowed but the list needs to be in quotes. This option allows the parameters to a control dpage to be specified. The string given should not include the first 4 bytes (i.e. page code and length). See the DATA SUPPLIED section below.

-d, --data=-

reads one or more data strings from stdin, limit almost 2**16 bytes. stdin may provide ASCII hex as a comma separated list (i.e. as with the --data=H,H... option). Additionally spaces, tabs and line feeds are permitted as separators from stdin . Stops reading stdin when an EOF is detected. See the DATA SUPPLIED section below.

-d, --data=@FN

reads one or more data strings from the file called FN, limit almost 2**16 bytes. The contents of the file is decoded in the same fashion as stdin described in the previous option. See the DATA SUPPLIED section below.

-D, --descriptor=DES

where DES is a descriptor name (string) as found in the Element Descriptor dpage. This is a medium level indexing alternative to the low level --index= options. If the descriptor name contains a space then DES needs to be surrounded by quotes (single or double) or the space escaped (e.g. preceded by a backslash). See the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section below.

-x, --dev-slot-num=SN, --dsn=SN

where SN is a device slot number found in the Additional Element Status dpage. Only entries for FCP and SAS devices (with EIP=1) have device slot numbers. SN must be a number in the range 0 to 255 (inclusive). 255 is used to indicate there is no corresponding device slot. This is a medium level indexing alternative to the low level --index= options. See the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section below.

-E, --eiioe=A_F

A_F is either the string 'auto' or 'force'. There was some fuzziness in the interpretation of the 'element index' field in the Additional Element Status (AES) dpage between SES-2 and SES-3. The EIIOE bit was introduced to resolve the problem but not all enclosures have caught up. In the SES-3 revision 12 draft the EIIOE bit was expanded to a 2 bit EIIOE field. Using '--eiioe=force' will decode the AES dpage as if the EIIOE field is set to 1. Using '--eiioe=auto' will decode the AES dpage as if the EIIOE field is set to 1 if the first AES descriptor has its EIP bit set and its element index field is 1 (in other words a heuristic to guess whether the EIIOE field should be set to 1 or 0).

If the enclosure sets the actual EIIOE field to 1 or more then this option has no effect. It is recommended that HP JBOD users set --eiioe=auto .

-e, --enumerate

enumerate all known diagnostic page (dpage) names and SES elements that this utility recognizes plus the abbreviations accepted by this utility. Ignores DEVICE if it is given. Essentially it is dumping out tables held internally by this utility.

If --enumerate is given twice, then the recognized acronyms for the --clear=STR, --get=STR and --set=STR options are listed. The utility exits after listing this information, so most other options and DEVICE are ignored. Since there are many acronyms for the Enclosure Control/Status dpage then the output can be further restricted by giving the --index=IIA option (e.g. "sg_ses -ee -I ts" to only show the acronyms associated with the Enclosure Control/Status dpage's Temperature Sensor Element Type).

-f, --filter

cuts down on the amount of output from the Enclosure Status dpage and the Additional Element Status dpage. When this option is given, any line which has all its binary flags cleared (i.e. 0) is filtered out (i.e. ignored). If a line has some other value on it (e.g. a temperature) then it is output. When this option is used twice only elements associated with the "status=ok" field (in the Enclosure status dpage) are output. The --filter option is useful for reducing the amount of output generated by the --join option.

-G, --get=STR

Used to read a field in a status element. Must be used together with a an indexing option to specify which element is to be read. By default the Enclosure Status dpage is read, the only other dpages that can be read are the Threshold In and Additional Element Status dpages. If a value is found it is output in decimal to stdout (by default) or in hexadecimal preceded by "0x" if the --hex option is also given. See the STR FORMAT and the CLEAR, GET, SET sections below.

-h, --help

output the usage message then exit. Since there is a lot of information, it is split into two pages. The most important is shown on the first page. Use this option twice (e.g. '-hh') to output the second page. Note: the --enumerate option might also be viewed as a help or usage type option. And like this option it has a "given twice" form: '-ee'.

-H, --hex

If the --get=STR option is given then output the value found (if any) in hexadecimal, with a leading "0x". Otherwise output the response in hexadecimal; with a leading hex address/index at the start of each line. If given twice an ASCII rendering is given to the right of each line. If given three or more times, the hexadecimal bytes only are output, 16 bytes (or less) on each line.

Ignored when all elements from several dpages are being accessed (e.g. when the --join option is used). Also see the --raw option which may be used with this option.

To dump one of more dpage responses to stdout in ASCII parsable hexadecimal use -HHH or -HHHH. The triple H form only outputs hexadecimal which is fine for a single dpage response. When all dpages are dumped (e.g. with --page=all) then the quad H form adds the name of each dpage preceded by a hash mark ('#'). Hence the output of the quad H form is still parsable plus it is easier for users to view and possibly edit. Using this option 5 times (e.g. -HHHHH) adds the page code in hex after the page's name in the comment before the hex rendering of that mode page.

If the --inner-hex option is also given it changes the action of this option. See the description of the --inner-hex option. Giving both -HHHH (or greater) and the --inner-hex option is reported as an error.

Note that the meaning of '-H' and '-HH' have been swapped in version "2.72 20230130" for compatibility with other utilities in this package and the description of this option in the sg3_utils(8) manpage.

-I, --index=IIA

where IIA is either an individual index (II) or an Element type abbreviation (A). See the INDEXES section below. If the --page=PG option is not given then the Enclosure Status (or Control) dpage is assumed. May be used with the --join option or one of the --clear=STR, --get=STR or --set=STR options. To enumerate the available Element type abbreviations use the --enumerate option.

-I, --index=TIA,II

where TIA,II is an type header index (TI) or Element type abbreviation (A) followed by an individual index (II). See the INDEXES section below. If the --page=PG option is not given then the Enclosure Status (or Control) dpage is assumed. May be used with the --join option or one of the --clear=STR, --get=STR or --set=STR options. To enumerate the available Element type abbreviations use the --enumerate option.

-X, --inhex=FN

where FN is a filename. It has the equivalent action of the --data=@FN option. If FN is '-' then stdin is read. This option has been given for compatibility with other utilities in this package that use --inhex=FN (or --in=FN) is a similar way. See the "HEX, BINARY AND JSON FORMATS" section in the sg3_utils manpage for more information.

-i, --inner-hex

the outer levels of a status dpage are decoded and printed out but the innermost level(s) (e.g. the Element Status Descriptor) is output in hex. For dpages that depend on the Configuration dpage, its structure is taken into account with this option, while when the --no-config option is used, its structure is ignored. Can be used with an indexing option and/or --join options. This option is mainly for debugging.

This option may also be used with the --json[=JO] option to lessen the decoding dependency on other dpages. This option may be used twice in this context. See the JSON INFORMATION section below.

The --hex option may be given with this option to control whether ASCII appears to the right of each hex line of bytes, or not. Without a --hex option, ASCII appears to the right of each hex line of bytes; if the --hex option appear once, no ASCII rendering appears.

-j, --join

group elements from the Element Descriptor, Enclosure Status and Additional Element Status dpages. If this option is given twice then elements from the Threshold In dpage are also grouped. The order is dictated by the Configuration dpage but that dpage is not explicitly shown.

There can be a bewildering amount of information in the "join" output. The default is to output everything. Several additional options are provided to cut down the amount displayed. If the indexing options is given, only the matching elements and their associated fields are output. The --filter option (see its description) can be added to reduce the amount of output. Also "--page=aes" (or "-p 0xa") can be added to suppress the output of rows that don't have a "aes" dpage component. See the INDEXES and DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS sections below.

This option implies the --status option. Giving the --control option with this option is an error.

-J[=JO], --json[=JO]

output is in JSON format instead of plain text form. Note that arguments to the short and long form are themselves optional and if present start with "=" and no whitespace is permitted around that "=".

See sg3_utils_json manpage or use '?' for JO to get a summary. For more specific information about JSON output with this utility, see the JSON INFORMATION section below.

-Q, --js-file=JFN

output is in JSON format and it is sent to a file named JFN. If that file exists then it is truncated. By default, the JSON output is sent to stdout.

When this option is given, the --json[=JO] option is implied and need not be given. The --json[=JO] option may still be needed to set the JO parameter to non-default values.

-l, --list

This option is equivalent to --enumerate. See that option.

-M, --mask

When modifying elements, the default action is a read (status element), mask, modify (based on --clear=STR or --set=STR) then write back as the control element. The mask step is new in sg_ses version 1.98 and is based on what is allowable (and in the same location) in draft SES-3 revision 6. Those masks may evolve, as they have in the past. This option re-instates the previous logic which was to ignore the mask step. The default action (i.e. without this option) is to perform the mask step in the read-mask-modify-write sequence.

-m, --maxlen=LEN

LEN is placed in the ALLOCATION LENGTH field of the SCSI RECEIVE DIAGNOSTIC RESULTS commands sent by the utility. It represents the maximum size of data the SES device can return (in bytes). It cannot exceed 65535 and defaults to 65532 (bytes). Some systems may not permit such large sizes hence the need for this option. If LEN is less than 0 or greater than 65535 then an error is generated. If LEN is 0 then the default value is used, otherwise if it is less than 4 then it is ignored (and a warning is sent to stderr).

-n, --nickname=SEN

where SEN is the new Subenclosure Nickname. Only the first 32 characters (bytes) of SEN are used, if more are given they are ignored. See the SETTING SUBENCLOSURE NICKNAME section below.

-N, --nickid=SEID

where SEID is the Subenclosure identifier that the new Nickname (SEN) will be applied to. So SEID must be an existing Subenclosure identifier. The default value is 0 which is the main enclosure.

-F, --no-config

the Element status, Array status (obsolete), Element Descriptor, Additional element status and Threshold In dpages all depend on the Configuration dpage for decoding. For debugging purposes, when there is something wrong with the relationship between these dpages, it may be useful to look at those pages without using the configuration dpage. That is what this option does. Those dpages still have some structure that can be output without the Configuration dpage, but the inner parts are typically output in hex when this option is given. This option is somewhat related to the --inner-hex option which is also useful for debugging.

This option is ignored on dpages that don't depend on the Configuration dpage, including the Configuration dpage itself.

-y, --no-time

this utility now issues a SCSI REPORT TIMESTAMP command just after an INQUIRY command at the start of its execution. This enables the utility to output a date-time stamp or an uptime duration. The time value returned is in illiseconds from some epoch. If the value corresponds to a period of less than 3 years then it is considered to be an uptime duration and is output in days, hours, minutes, seconds and milliseconds. Unix systems including Linux, FreeBSD and Solaris use 00:00 on 1st January 1970 UTC as their epoch. The date-time stamp output is in RFC 2822 date format on two adjacent lines, one in UTC and the other in local time.

If for some reason calling the REPORT TIMESTAMP command causes a problem, then this option will disable this feature.

Note that the time returned is from the enclosure, not the machine that the utility is executed from. This utility can use modern SCSI disks as the DEVICE to fetch that disk't timestamp; this utility will then find thet the DEVICE is not an enclosure and exit without doing any harm.

-p, --page=PG

where PG is a dpage abbreviation or code (a number). If PG starts with a digit it is assumed to be in decimal unless prefixed by 0x for hex. Valid range is 0 to 255 (0x0 to 0xff) inclusive. Default is dpage 'sdp' which is page_code 0 (i.e. "Supported Diagnostic Pages") if no other options are given.

Page code 0xff or abbreviation "all" is not a real dpage (as the highest real dpage is 0x3f) but instead causes all SES dpages whose page code is 0x2f or less to be output. This can be used with either the -HHHH or -rr to send either hexadecimal ASCII or binary respectively to stdout. If an error is detected fetching or decoding a diagnostic page it is noted, the rest of the pages are processed then the deferred error is reported in the exit status. If the --warn option is also given then --page=all will exit immediately when an error is detected.

To list the available dpage abbreviations give "xxx" for PG; the same information can also be found with the --enumerate option.

-q, --quiet

this suppresses the number of warnings and messages output. The exit status of the utility is unaffected by this option.

-r, --raw

outputs the chosen status dpage in ASCII hex in a format suitable for a later invocation using the --data= option. A dpage less its first 4 bytes (page code and length) is output. When used twice (e.g. -rr) the full dpage contents is output in binary to stdout.

Note that the use of a single --raw option is different from most other utilities in the sg3_utils package.

When -rr is used together with the --data=-, --data=@FN, or --inhex=FN then stdin or file FN is decoded as a binary stream that continues to be read until an end of file (EOF). Once that data is read then the internal raw option is cleared to 0 so the output is not effected. So the -rr option either changes how the input or output is treated, but not both in a single invocation.

-R, --readonly

open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to open it read-write.

-A, --sas-addr=SA

this is an indexing method for SAS end devices (e.g. SAS disks). The utility will try to find the element or slot in the Additional Element Status dpage whose SAS address matches SA. For a SAS disk or tape that SAS address is its target port identifier for the port connected to that element or slot. Most SAS disks and tapes have two such target ports, usually numbered consecutively.

SATA devices in a SAS enclosure often receive "manufactured" target port identifiers from a SAS expander; typically will have a SAS address close to, but different from, the SAS address of the expander itself. Note that this manufactured target port identifier is different from a SATA disk's WWN.

SA is a hex number that is up to 8 digits long. It may have a leading '0x' or '0X' or a trailing 'h' or 'H'. This option is a medium level indexing alternative to the low level --index= options. See the DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS section below.

-S, --set=STR

Used to set an element field in the Enclosure Control or Threshold Out dpage. Must be used together with an indexing option to specify which element is to be changed. The Enclosure Control dpage is assumed if the --page=PG option is not given. See the STR FORMAT and CLEAR, GET, SET sections below.

-s, --status

will fetch dpage from the DEVICE via a SCSI RECEIVE DIAGNOSTIC RESULTS command (or from --data=@FN). In the absence of other options that imply modifying a dpage (e.g. --control or --set=STR) then --status is assumed, except when the --data= option is given. When the --data= option is given there is no default action: either the --control or this option must be given to distinguish between the two different ways that data will be treated.

-v, --verbose

increase the level of verbosity. For example when this option is given four times (in which case the short form is more convenient: '-vvvv') then if the internal join array has been generated then it is output to stderr in a form suitable for debugging.

-V, --version

print the version string and then exit.

-w, --warn

warn about certain irregularities with warnings sent to stderr. The join is a complex operation that requires fields from several dpages to be synchronized. The quality of SES devices vary and to be fair, the descriptions from T10 drafts and standards have been tweaked several times (see the EIIOE field) in order to clear up confusion.

This option will cause fetching all dpages with the --page=all option to exit immediately when an error is detected.

## INDEXES
An enclosure can have information about its disk and tape drives plus other supporting components like power supplies spread across several dpages. Addressing a specific element (overall or individual) within a dpage is complicated. This section describes low level indexing (i.e. choosing a single element (or a group of related elements) from a large number of elements). If available, the medium level indexing described in the following section (DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS) might be simpler to use.

The Configuration dpage is key to low level indexing: it contains a list of "type headers", each of which contains an Element type (e.g. Array Device Slot), a Subenclosure identifier (0 for the primary enclosure) and a "Number of possible elements". Corresponding to each type header, the Enclosure Status dpage has one "overall" element plus "Number of possible elements" individual elements all of which have the given Element type. For some Element types the "Number of possible elements" will be 0 so the Enclosure Status dpage has only one "overall" element corresponding to that type header. The Element Descriptor dpage and the Threshold (In and Out) dpages follow a similar pattern as the Enclosure Status dpage.

The numeric index corresponding to the overall element is "-1". If the Configuration dpage indicates a particular element type has "n" elements then its indexes range from -1 to n-1 .

The Additional Element Status dpage is a bit more complicated. It has entries for "Number of possible elements" of certain Element types. It does not have entries corresponding to the "overall" elements. To make the correspondence a little clearer each descriptor in this dpage optionally contains an "Element Index Present" (EIP) indicator. If EIP is set then each element's "Element Index" field refers to the position of the corresponding element in the Enclosure Status dpage.

Addressing a single overall element or a single individual element is done with two indexes: TI and II. TI=0 corresponds to the first type header entry which must be a Device Slot or Array Device Slot Element type (according to the SES-2 standard). To address the corresponding overall instance, II is set to -1, otherwise II can be set to the individual instance index. As an alternative to the type header index (TI), an Element type abbreviation (A) (e.g. "ps" for Power Supply Element type) optionally followed by a number (e.g. "ps" refers to the first Power Supply Element type; "ps1" refers to the second) can be given.

One of two command lines variants can be used to specify indexes: --index=TIA,II where TIA is either an type header index (TI) or an Element type abbreviation (A) (e.g. "ps" or "ps1"). II is either an individual index or "-1" to specify the overall element. The second variant is --index=IIA where IIA is either an individual index (II) or an Element type abbreviation (A). When IIA is an individual index then the option is equivalent to --index=0,II. When IIA is an Element type abbreviation then the option is equivalent to --index=A,-1.

Wherever an individual index is applicable, it can be replaced by an individual index range. It has the form: <first_ii>:<last_ii>. For example: '3:5' will select individual indexes 3, 4 and 5 . Note that the range -1:255 represents all possible elements of an element type and is not an error, only those element that exist will be selected. Previously '-' was used as an index range separator but that leads to awkward syntax like -1-1 for indexes: -1 (overall element), 0 and 1 (individual elements).

To cope with vendor specific Element types (whose type codes should be in the range 128 to 255) the Element type code can be given as a number with a leading underscore. For example these are equivalent: --index=arr and --index=_23 since the Array Device Slot Element type code is 23. Also --index=ps1 and --index=_2_1 are equivalent.

Another example: if the first type header in the Configuration dpage has has Array Device Slot Element type then --index=0,-1 is equivalent to --index=arr. Also --index=arr,3 is equivalent to --index=3.

The --index= option is used to reduce the amount of output (e.g. only showing the element associated with the second 12 volt power supply). It may also be used together with with the --clear=STR, --get=STR and --set=STR options which are described in the STR section below.

## DESCRIPTOR NAME, DEVICE SLOT NUMBER AND SAS ADDRESS
The three options: --descriptor=DES, --dev-slot-num=SN and --sas-addr=SA allow medium level indexing, as an alternative to the low level --index= option. Only one of the three options can be used in an invocation. When either of these three option is used a join operation is performed (but not displayed) before element selection takes place.

These medium level indexing options need support from the SES device and that support is optional. For example the --descriptor=DES needs the Element Descriptor dpage provided by the SES device however that is optional. Also the provided descriptor names need to be useful, and having descriptor names which are all "0" is not very useful. Also some elements (e.g. overall elements) may not have descriptor names.

These medium level indexing options can be used to reduce the amount of output (e.g. only showing the elements related to device slot number 3). They may also be used together with with the --clear=STR, --get=STR and --set=STR options which are described in the following section. Note that even if a field can be set (e.g. "do not remove" (dnr)) and that field can be read back with --get=STR confirming that change, the disk array may still ignore it (e.g. because it does not have the mechanism to lock the disk drawer).

## STR FORMAT
The STR operands of the --clear=STR, --get=STR and --set=STR options all have the same structure. There are two forms:

<acronym>[=<value>]

<start_byte>:<start_bit>[:<num_bits>][=<value>]

The <acronym> is one of a list of common fields (e.g. "ident" and "fault") that the utility converts internally into the second form. The <start_byte> is usually in the range 0 to 3, the <start_bit> must be in the range 0 to 7 and the <num_bits> must be in the range 1 to 64 (default 1). The number of bits are read in the left to right sense of the element tables shown in the various SES draft documents. For example the 8 bits of byte 2 would be represented as 2:7:8 with the most significant bit being 2:7 and the least significant bit being 2:0 .

The <value> is optional but is ignored if provided to --get=STR. For --set=STR the default <value> is 1 while for --clear=STR the default value is 0 . <value> is assumed to be decimal, hexadecimal values can be given in the normal fashion.

The supported list of <acronym>s can be viewed by using the --enumerate option twice (or "-ee").

## CLEAR, GET, SET
The --clear=STR, --get=STR and --set=STR options can be used up to 8 times in the same invocation. Any <acronym>s used in the STR operands must refer to the same dpage.

When multiple of these options are used (maximum: 8), they are applied in the order in which they appear on the command line. So if options contradict each other, the last one appearing on the command line will be enforced. When there are multiple --clear=STR and --set=STR options, then the dpage they refer to is only written after the last one.

## DATA SUPPLIED
This section describes the two scenarios that can occur when the --data= option is given. These scenarios are the same irrespective of whether the argument to the --data= option is a string of hex bytes on the command line, stdin (indicated by --data=-) or names a file (e.g. --data=@thresh_in_dpage.hex).

The first scenario is flagged by the --control option. It uses the supplied data to build a 'control' dpage that will be sent to the DEVICE using the SCSI SCSI SEND DIAGNOSTIC command. The supplied dpage data should not include its first 4 bytes. Those 4 bytes are added by this utility using the --page=PG option with PG placed at byte offset 0). If needed, the --byte1=B1 option sets byte offset 1, else 0 is placed in that position. The number of bytes decoded from the data provided (i.e. its length) goes into byte offsets 2 and 3.

The second scenario is flagged by the --status option (or the absence of the --control option). It decodes the supplied data assuming that it represents the response to one or more SCSI RECEIVE DIAGNOSTIC RESULTS commands. Those responses have typically been captured from some earlier invocation(s) of this utility. Those earlier invocations could use the '-HHH' or '-HHHH' option and file redirection to capture that response (or responses) in hexadecimal. The supplied dpage response data is decoded according to the other command line options. For example the --join option could be given and that would require the data from multiple dpages typically: Configuration, Enclosure status, Element descriptor and Additional element status dpages. If in doubt use --page=all in the capture phase; having more dpages than needed is not a problem.

By default the user supplied data is assumed to be ASCII hexadecimal in lines that don't exceed 512 characters. Anything on a line from and including a hash mark ('#') to the end of line is ignored. An end of line can be a LF or CR,LF and blank lines are ignored. Each separated pair (or single) hexadecimal digits represent a byte (and neither a leading '0x' nor a trailing 'h' should be given). Separators are either space, tab, comma or end of line.

Alternatively binary can be used and this is flagged by the '-rr' option. The --data=H,H... form cannot use binary values for the 'H's, only ASCII hexadecimal. The other two forms (--data=- and --data=@FN) may contain binary data. Note that when the '-rr' option is used with --data=@FN that it only changes the interpretation of the input data, it does not change the decoding and output representation.

## CHANGING STATE
This utility has various techniques for changing the state of a SES device. As noted above this is typically a read-modify-write type operation. Most modifiable dpages have a "status" (or "in") page that can be read, and a corresponding "control" (or "out") dpage that can be written back to change the state of the enclosure.

The lower level technique provided by this utility involves outputting a "status" dpage in hex with --raw. Then a text editor can be used to edit the hex (note: to change an Enclosure Control descriptor the SELECT bit needs to be set). Next the control dpage data can fed back with the --data=H,H... option together with the --control option; the --byte1=B1 option may need to be given as well.

Changes to the Enclosure Control dpage (and the Threshold Out dpage) can be done at a higher level. This involves choosing a dpage (the default in this case is the Enclosure Control dpage). Next choose an individual or overall element index (or name it with its Element Descriptor string). Then give the element's name (e.g. "ident" for RQST IDENT) or its position within that element (e.g. in an Array Device Slot Control element RQST IDENT is byte 2, bit 1 and 1 bit long ("2:1:1")). Finally a value can be given, if not the value for --set=STR defaults to 1 and for --clear=STR defaults to 0.

## SETTING SUBENCLOSURE NICKNAME
The format of the Subenclosure Nickname control dpage is different from its corresponding status dpage. The status dpage reports all Subenclosure Nicknames (and Subenclosure identifier 0 is the main enclosure) while the control dpage allows only one of them to be changed. Therefore using the --data option technique to change a Subenclosure nickname is difficult (but still possible).

To simplify changing a Subenclosure nickname the --nickname=SEN and --nickid=SEID options have been added. If the SEN string contains spaces or other punctuation, it should be quoted: surrounded by single or double quotes (or the offending characters escaped). If the --nickid=SEID is not given then a Subenclosure identifier of 0 is assumed. As a guard the --control option must also be given. If the --page=PG option is not given then --page=snic is assumed.

When --nickname=SEN is given then the Subenclosure Nickname Status dpage is read to obtain the Generation Code field. That Generation Code together with no more than 32 bytes from the Nickname (SEN) and the Subenclosure Identifier (SEID) are written to the Subenclosure Nickname Control dpage.

There is an example of changing a nickname in the EXAMPLES section below.

## NVME ENCLOSURES
Support has been added to sg_ses (actually, its underlying library) for NVMe (also known as NVM Express) Enclosures. It can be considered experimental in sg3_utils package version 1.43 and sg_ses version 2.34 .

This support is based on a decision by NVME-MI (Management Interface) developers to support the SES-3 standard. This was facilitated by adding NVME-MI SES Send and SES Receive commands that tunnel dpage contents as used by SES.

## JSON INFORMATION
The approach taken with JSON output (i.e. when the --json[=JO] option is given) is to output diagnostic page information unless the --join option is given. A problem specific to SES is that many diagnostic pages depend on other diagnostic pages (e.g. decoding the Enclosure Status and the Element Descriptor dpages both depend on the Configuration dpage).

When the --json[=JO] and --page=PG options are used in the same invocation, then if PG has any dependencies on other diagnostic pages, then those other pages are fetched. For example the Element Descriptor dpage depends on the Configuration dpage. In some cases (e.g. dpages misconfigured or in the process of being changed) it may be useful to decode whatever is possible, without fetching other dpages. The --inner-hex option may be used for this. Some dpages (e.g. Enclosure Status dpage) cannot be decoded at all, without fetching the Configuration dpage, so each 4 byte element will be output in hex. In the case of the Element Descriptor dpage, the descriptors may be output in ASCII and are when the --inner-hex option is given once. If the --inner-hex option is given twice, then each descriptor will be output in hex.

When the --json[=JO] and --page=PG options are used in the same invocation, then the top level object name is the name of PG in snake notation. This includes the "_diagnostic_page" suffix.

When the --json[=JO] and --join options are used in the same invocation (and the --page=PG option is _not_ given), then the top level object name is "join_of_diagnostic_pages" which contain a (JSON) array named "element_list". Each element in that array starts with an "element_type" field followed by "descriptor" and "element_number" fields. The "descriptor" field's value is a string. All elements with the same "element_type" are grouped together starting with the "overall_element" first. The "overall_element" has an "element_number" value of -1. Individual elements of the same "element_type" are in the following "element_list" array elements start with an "element_number" value of 0. After the "element_number" field there is a "overall" field with an integer value of 0 (for an "individual" element) or a value of 1 (for "overall" element). To reinforce that point there is a "individual" field with a boolean value of true (for an "individual" element) or false. Next there is an object named "status_descriptor" that contains the corresponding "Enclosure Status" dpage's Enclosure status element. As required, the corresponding Additional element status, Element descriptor by type element, and Threshold status descriptors may also appear.

The plain text output (which is output by default) tends to trim output when a line of element values are all 0. On the other hand when JSON output is chosen, all fields, that meet the requirements of the command line options, are output.

## NOTES
This utility can be used to fetch arbitrary (i.e. non SES) dpages (using the SCSI READ DIAGNOSTIC command). To this end the --page=PG and --hex options would be appropriate. Non-SES dpages can be sent to a device with the sg_senddiag utility.

The most troublesome part of the join operation is associating Additional Element Status descriptors correctly. At least one SES device vendor has misinterpreted the SES-2 standard, specifically with its "element index" field interpretation. The code in this utility interprets the "element index" field as per the SES-2 standard and if that yields an inappropriate Element type, adjusts its indexing to follow that vendor's misinterpretation. The SES-3 drafts have introduced the EIIOE (Element Index Includes Overall Elements) bit which later became a 2 bit field to resolve this ambiguity. See the --eiioe=A_F option.

In draft SES-3 revision 5 the "Door Lock" element name was changed to the "Door" (and an OPEN field was added to the status element). As a consequence the former 'dl' element type abbreviation has been changed to 'do'.

Some RAID controllers hide SES device nodes from the host Operating System. It has been reported that some MegaRAID controllers do this and the following command is needed to expose them:

perccli /cx set backplane expose=<on/off>

where perccli is Dell's version of BroadCom's (LSI) storcli utility.

There is a related command set called SAF-TE (SCSI attached fault-tolerant enclosure) for enclosure (including RAID) status and control. SCSI devices that support SAF-TE report "Processor" peripheral device type (0x3) in their INQUIRY response. See the sg_safte utility in this package or the safte-monitor utility on the Internet.

The internal join array is statically allocated and its size is controlled by the MX_JOIN_ROWS define. Its current value is 520.

## EXAMPLES
Examples can also be found at https://sg.danny.cz/sg/sg_ses.html

The following examples use Linux device names. For suitable device names in other supported Operating Systems see the sg3_utils(8) man page.

To view the supported dpages:

sg_ses /dev/bsg/6:0:2:0

To view the Configuration Diagnostic dpage:

sg_ses --page=cf /dev/bsg/6:0:2:0

To view the Enclosure Status dpage:

sg_ses --page=es /dev/bsg/6:0:2:0

To get the (attached) SAS address of that device (which is held in the Additional Element Sense dpage (dpage 10)) printed on hex:

sg_ses -p aes -D ArrayDevice07 -G at_sas_addr -H /dev/sg3

To collate the information in the Enclosure Status, Element Descriptor and Additional Element Status dpages the --join option can be used:

sg_ses --join /dev/sg3

This will produce a lot of output. To filter out lines that don't contain much information add the --filter option:

sg_ses --join --filter /dev/sg3

Fields in the various elements of the Enclosure Control and Threshold dpages can be changed with the --clear=STR and --set=STR options. [All modifiable dpages can be changed with the --raw and --data=H,H... options.] The following example looks at making the "ident" LED (also called "locate") flash on "ArrayDevice07" which is a disk (or more precisely the carrier drawer the disk is in):

sg_ses --index=7 --set=2:1:1 /dev/sg3

In the above invocation, the --set= option implies --control so the latter does not need to be given. The same applies to --clear=. On the other hand the --get= option implies --status .

If the Element Descriptor diagnostic dpage shows that "ArrayDevice07" is the descriptor name associated with element index 7 then this invocation is equivalent to the previous one:

sg_ses --descriptor=ArrayDevice07 --set=2:1:1 /dev/sg3

Further the byte 2, bit 1 (for 1 bit) field in the Array Device Slot Control element is RQST IDENT for asking a disk carrier to flash a LED so it can be located. In this case "ident" (or "locate") is accepted as an acronym for that field:

sg_ses --descriptor=ArrayDevice07 --set=ident /dev/sg3

To stop that LED flashing:

sg_ses --dev-slot-num=7 --clear=ident /dev/sg3

The above assumes the descriptor name 'ArrayDevice07' corresponds to device slot number 7.

Now for an example of a more general but lower level technique for changing a modifiable diagnostic dpage. The String (In and Out) diagnostics dpage is relatively simple (compared with the Enclosure Status/Control dpage). However the use of this lower level technique is awkward involving three steps: read, modify then write. First check the current String (In) dpage contents:

sg_ses --page=str /dev/bsg/6:0:2:0

Now the "read" step. The following command will send the contents of the String dpage (from byte 4 onwards) to stdout. The output will be in ASCII hex with pairs of hex digits representing a byte, 16 pairs per line, space separated. The redirection puts stdout in a file called "t":

sg_ses --page=str --raw /dev/bsg/6:0:2:0 > t

Then with the aid of the SES-3 document (in revision 3: section 6.1.6) use your favourite editor to change t. The changes can be sent to the device with:

sg_ses --page=str --control --data=- /dev/bsg/6:0:2:0 < t

If the above is successful, the String dpage should have been changed. To check try:

sg_ses --page=str /dev/bsg/6:0:2:0

To change the nickname on the main enclosure:

sg_ses --nickname='1st enclosure' --control /dev/bsg/6:0:2:0

To capture the whole state of an enclosure (from a SES perspective) for later analysis, this can be done:

sg_ses --page=all -HHHH /dev/sg5 > enc_sg5_all.hex

Note that if there are errors or warnings they will be sent to stderr so they will appear on the command line (since only stdout is redirected). A text editor could be used to inspect enc_sg5_all.hex . If all looks in order at some later time, potentially on a different machine where enc_sg5_all.hex has been copied, a "join" could be done. Note that join reflects the state of the enclosure when the capture was done.

sg_ses --data=@enc_sg5_all.hex --status --join

The above invocation can also be expressed as:

sg_ses --inhex=enc_sg5_all.hex --join

The --join option implies --status .

## EXIT STATUS
The exit status of sg_ses is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHORS
Written by Douglas Gilbert.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2004-2023 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_inq, sg_safte, sg_senddiag, sg_ses_microcode, sg3_utils (sg3_utils); safte-monitor (Internet)


title: sg_ses_microcode(8)

summary: send microcode to a SCSI enclosure

text:
# sg_ses_microcode(8)

## NAME
sg_ses_microcode - send microcode to a SCSI enclosure

## SYNOPSIS
sg_ses_microcode [--bpw=CS] [--dry-run] [--ealsd] [--help] [--id=ID] [--in=FILE] [--length=LEN] [--mode=MO] [--non] [--offset=OFF] [--skip=SKIP] [--subenc=MS] [--tlength=TLEN] [--verbose] [--version] DEVICE

## DESCRIPTION
This utility attempts to download microcode to an enclosure (or one of its sub-enclosures) associated with the DEVICE. The process for doing this is defined in the SCSI Enclosure Services (SES) standards and drafts maintained by the T10 committee.

The process is to send one or more sequences containing a SCSI SEND DIAGNOSTIC command followed optionally by a RECEIVE DIAGNOSTIC RESULTS command. The former sends a Download microcode Control diagnostic page (dpage) and the latter fetches a Download microcode status dpage which can be viewed as a report on the former command.

The default action (i.e. when the --mode=MO option is not given) is to fetch the Download microcode status dpage and decode it. This does not require the microcode (firmware) itself so the --in=FILE option is not required.

The most recent reference for this utility is the draft SCSI Enclosure Services 3 (SES-3) document T10/2149-D Revision 7 at http://www.t10.org . Existing standards for SES and SES-2 are ANSI INCITS 305-1998 and ANSI INCITS 448-2008 respectively.

Most other support for SES in this package (apart from downloading microcode) can be found in the sg_ses utility. Another way of downloading firmware to a SCSI device is with the WRITE BUFFER command defined in SPC-4, see the sg_write_buffer utility.

## OPTIONS
Arguments to long options are mandatory for short options as well.

-b, --bpw=CS

where CS is the chunk size in bytes and should be a multiple of 4. This will be the maximum number of bytes sent per SEND DIAGNOSTIC command. So if CS is less than the effective length of the microcode then multiple SEND DIAGNOSTIC commands are sent, each taking the next chunk from the read data and increasing the buffer offset field in the Download microcode control dpage by the appropriate amount. The default is a chunk size of 0 which is interpreted as a very large number hence only one SEND DIAGNOSTIC command will be sent.

The number in CS can optionally be followed by ",act" or ",activate". In this case after the microcode has been successfully sent to the DEVICE, an additional Download microcode control dpage with its mode set to "Activate deferred microcode" [0xf] is sent.

-d, --dry-run

the actual calls to perform SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS commands are skipped when this option is given. No SCSI commands are sent to the DEVICE but it is still opened and is required to be given. A dummy device such as /dev/null (in Unix) can be used.

This utility expects a "sensible" response to the RECEIVE DIAGNOSTIC RESULTS command it sends (and will abort if it doesn't receive one). So this option supplies dummy responses with one primary enclosure and three sub-enclosures. The dummy responses include good status values.

-e, --ealsd

exit after last SEND DIAGNOSTIC command. A SES device should not start its firmware update immediately after the last received "chunk" of its firmware. Rather it should wait till at least one RECEIVE DIAGNOSTIC RESULTS command is sent to give the device a chance to report any error. However some devices do start the firmware update immediately which causes the trailing RECEIVE DIAGNOSTIC RESULTS command to be held up and often be aborted with a "target reset" error.

This option causes the trailing RECEIVE DIAGNOSTIC RESULTS command to be skipped. This option would be typically used with the --bpw=CS option.

Prior to version 1.10 of this utility [20180112] this (i.e. skipping the last RECEIVE DIAGNOSTIC RESULTS command) was the default action.

-h, --help

output the usage message then exit. If used multiple times also prints the mode names and their acronyms.

-i, --id=ID

this option sets the BUFFER ID field in the Download microcode control dpage. ID is a value between 0 (default) and 255 inclusive.

-I, --in=FILE

read data from file FILE that will be sent with the SEND DIAGNOSTIC command. If FILE is '-' then stdin is read until an EOF is detected (this is the same action as --raw). Data is read from the beginning of FILE except in the case when it is a regular file and the --skip=SKIP option is given.

-l, --length=LEN

where LEN is the length, in bytes, of data to be written to the device. If not given (and the length cannot be deduced from --in=FILE or --raw) then defaults to zero. If the option is given and the length deduced from --in=FILE or --raw is less (or no data is provided), then bytes of 0xff are used as fill bytes.

-m, --mode=MO

this option sets the MODE. MO is a value between 0 (which is dmc_status and the default) and 255 inclusive. Alternatively an abbreviation can be given. See the MODES section below. To list the available mode abbreviations at run time give an invalid one (e.g. '--mode=xxx') or use the '-h' option.

-N, --non

allow for non-standard implementations that reset their Download microcode engine after a RECEIVE DIAGNOSTIC RESULTS command with the Download microcode status dpage is sent. When this option is given sending that command and dpage combination is avoided unless an error has already occurred.

-o, --offset=OFF

this option sets the BUFFER OFFSET field in the Download microcode control dpage. OFF is a value between 0 (default) and 2**32-1 . It is a byte offset. This option is ignored (and a warning sent to stderr) if the --bpw=CS option is also given.

-s, --skip=SKIP

this option is only active when --in=FILE is given and FILE is a regular file, rather than stdin. Data is read starting at byte offset SKIP to the end of file (or the amount given by --length=LEN). If not given the byte offset defaults to 0 (i.e. the start of the file).

-S, --subenc=SEID

SEID is the sub-enclosure identify. It defaults to 0 which is the primary enclosure identifier.

-t, --tlength=TLEN

TLEN is the total length in bytes of the microcode to be (or being) downloaded. It defaults to 0 which is okay in most cases. This option only comes into play when TLEN is greater than LEN. In this case TLEN is sent to the SES DEVICE so that it knows when it only receives LEN bytes from this invocation, that it should expect more to be sent in the near future (e.g. by another invocation). This option is only needed when sections of microcode are being sent in separate invocations of this utility (e.g. the microcode is spread across two files).

-v, --verbose

increase the level of verbosity, (i.e. debug output).

-V, --version

print the version string and then exit.

## MODES
Following is a list accepted by the MO argument of this utility. First shown is an acronym followed in square brackets by the corresponding decimal and hex values that may also be given for MO.

dmc_status [0, 0x0]

Use RECEIVE DIAGNOSTIC RESULTS to fetch the Download microcode status dpage and print it out.

dmc_offs [6, 0x6]

Download microcode with offsets and activate.

dmc_offs_save [7, 0x7]

Download microcode with offsets, save, and activate.

dmc_offs_defer [14, 0xe]

Download microcode with offsets, save, and defer activate.

activate_mc [15, 0xf]

Activate deferred microcode. There is no follow-up RECEIVE DIAGNOSTIC RESULTS to fetch the Download microcode status dpage since the DEVICE might be resetting.

Apart from dmc_status, these are placed in the Download microcode mode field in the Download microcode control dpage. In the case of dmc_status the Download microcode status dpage is fetched with the RECEIVE DIAGNOSTIC RESULTS command and decoded.

## WHEN THE DOWNLOAD FAILS
Firstly, if it succeeds, this utility should stay silent and return. Typically vendors will change the "revision" string (which is 4 characters long) whenever they release new firmware. That can be seen in the response to a SCSI INQUIRY command, for example by using the sg_inq utility. It is possible that the device needs to be power cycled before the new microcode becomes active. Also if mode dmc_offs_defer [0xe] is used to download the microcode, then another invocation with activate_mc may be needed.

If something goes wrong, there will typically be messages printed out by this utility. The first thing to check is the microcode (firmware) file itself. Is it designed for the device model; has it been corrupted, and if downgrading (i.e. trying to reinstate older firmware), does the vendor allow that?

Getting new firmware on a device is a delicate operation that is not always well defined by T10's standards and drafts. One might speculate that they are deliberately vague. In testing this utility one vendor's interpretation of the standard was somewhat surprising. The --non option was added to cope with their interpretation. So if the above suggestions don't help, try adding the --non option.

## NOTES
This utility can handle a maximum size of 128 MB of microcode which should be sufficient for most purposes. In a system that is memory constrained, such large allocations of memory may fail.

The user should be aware that most operating systems have limits on the amount of data that can be sent with one SCSI command. In Linux this depends on the pass through mechanism used (e.g. block SG_IO or the sg driver) and various setting in sysfs in the Linux lk 2.6/3 series (e.g. /sys/block/sda/queue/max_sectors_kb). Devices (i.e. logical units) also typically have limits on the maximum amount of data they can handle in one command. These two limitations suggest that modes containing the word "offset" together with the --bpw=CS option are required as firmware files get larger and larger. And CS can be quite small, for example 4096 bytes, resulting in many SEND DIAGNOSTIC commands being sent.

The exact error from the non-standard implementation was a sense key of ILLEGAL REQUEST and an asc/ascq code of 0x26,0x0 which is "Invalid field in parameter list". If that is seen try again with the --non option.

Downloading incorrect microcode into a device has the ability to render that device inoperable. One would hope that the device vendor verifies the data before activating it.

A long (operating system) timeout of 7200 seconds is set on each SEND DIAGNOSTIC command.

All numbers given with options are assumed to be decimal. Alternatively numerical values can be given in hexadecimal preceded by either "0x" or "0X" (or has a trailing "h" or "H").

## EXAMPLES
If no microcode/firmware file is given then this utility fetches and decodes the Download microcode status dpage which could possibly show another initiator in the process of updating the microcode. Even if that is happening, fetching the status page should not cause any problems:

$ sg_ses_microcode /dev/sg3

Download microcode status diagnostic page:

number of secondary sub-enclosures: 0

generation code: 0x0

sub-enclosure identifier: 0 [primary]

download microcode status: No download microcode operation in progress [0x0]

download microcode additional status: 0x0

download microcode maximum size: 1048576 bytes

download microcode expected buffer id: 0x0

download microcode expected buffer id offset: 0

The following sends new microcode/firmware to an enclosure. Sending a 1.5 MB file in one command caused the enclosure to lock up temporarily and did not update the firmware. Breaking the firmware file into 4 KB chunks (an educated guess) was more successful:

sg_ses_microcode -b 4k -m dmc_offs_save -I firmware.bin /dev/sg4

The firmware update occurred in the following enclosure power cycle. With a modern enclosure the Extended Inquiry VPD page gives indications in which situations a firmware upgrade will take place.

## EXIT STATUS
The exit status of sg_ses_microcode is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHORS
Written by Douglas Gilbert.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2014-2018 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_ses, sg_write_buffer, sg_inq(sg3_utils)