114 lines
5.7 KiB
Plaintext
114 lines
5.7 KiB
Plaintext
README for sg3_utils
|
|
====================
|
|
Introduction
|
|
------------
|
|
sg3_utils is a package of utilities originally written to send individual
|
|
SCSI commands to storage devices that used one of the SCSI command sets.
|
|
These utilities can be divided into three groups:
|
|
- sg_raw: the user supplies the cdb (command descriptor block) and
|
|
optionally the size of the data-in and data-out buffers
|
|
- one command utilities: the majority of the utilities in this package
|
|
send one SCSI command. Their names start with "sg_" while the
|
|
remaining part of their name alludes to the command which is sent. For
|
|
example, "sg_inq" sends the SCSI INQUIRY command. Some utilities in
|
|
this group send one of a selection of commands, typically those
|
|
commands have a lot it common (e.g. sg_write_x).
|
|
- copy type utilities: sg_dd, sgp_dd and sgm_dd use the Unix dd command
|
|
as a template. sg_xcopy sends the SCSI EXTENDED COPY command which in
|
|
some cases can do offloaded copies. As well as copying some of these
|
|
utilities can compare if two data segments held on disks are the same.
|
|
|
|
Platforms
|
|
---------
|
|
These utilities were written on Linux and should work from Linux kernel
|
|
(lk) 2.4 through to the current series 5. The third group ("copy type")
|
|
are only implemented on Linux, but a separate portable package/utility
|
|
called ddpt implements similar functionality. The first two groups are
|
|
implemented (i.e. ported) to Android, FreeBSD, Solaris and Windows. The
|
|
Windows port uses either a Cygwin or MinGW (plus Msys) build environment
|
|
(rather than Visual Studio).
|
|
|
|
Library
|
|
-------
|
|
Many of these utilities share a lot of code (e.g. SCSI error messages)
|
|
so a lot of repetition (potentially error prone) is saved by having a
|
|
library called libsgutils or some variation on that name. Distributions
|
|
(especially of Linux) have differing policies on how a library (and a
|
|
package) should be named. For that reason this package is sometimes
|
|
known as "sg3-utils" (i.e. the underscore is turned into a hyphen).
|
|
Various other packages use libsgutils. The library interface is not
|
|
altered from one package release, to the next, but the library interface
|
|
may be expanded. If a utility from one release is used with a libsgutils
|
|
from an earlier release, then the runtime linking may fail. Typically
|
|
package managers take care of these details so that runtime linking
|
|
errors should be rare.
|
|
|
|
Command Sets
|
|
------------
|
|
SCSI command sets are not the only storage command sets in wide use, there
|
|
are also ATA and NVMe command sets. There is a SCSI command set to
|
|
translate SCSI commands to ATA commands (called SAT: SCSI to ATA
|
|
Translation). SAT includes an ATA PASS-THROUGH SCSI command and sg_sat_*
|
|
utilities (there are four) are examples of using SAT. The SAS transport
|
|
(Serial Attached SCSI) can convey ATA commands through a SCSI/SAS domain
|
|
via its Serial ATA Tunnelled Protocol (STP).
|
|
|
|
NVMe command sets (e.g. Admin, NVM and MI) are relatively new. There was an
|
|
early paper on a SCSI to NVMe Translation Layer (SNTL) but it hasn't been
|
|
standardized. The sg_inq utility will send (and decode the response of) a
|
|
SCSI INQUIRY command if the underlying device is a SCSI device. If the
|
|
underlying device is a NVMe controller or namespace, then sg_inq will send
|
|
a NVMe Admin Identify command and decode the response. The sg_ses utility
|
|
(for SCSI Enclosure Services) also checks whether its underlying device is
|
|
SCSI or NVME. In the NVMe case, sg_ses translates the SCSI SEND DIAGNOSTIC
|
|
and READ DIAGNOSTIC RESULTS commands to the NVMe Management Interface (MI)
|
|
SES Send and SES Receive commands respectively. The output of the sg_ses
|
|
utility should be similar, irrespective of whether the "SES" device is
|
|
SCSI or NVMe.
|
|
|
|
The sg_raw utility may send NVMe Admin or NVM commands (as well as SCSI
|
|
commands). One difficulty with a command-line utility invoking NVME
|
|
commands is that those commands contain memory addresses for data-in (from
|
|
the storage device) or data-out (toward the storage device) transfers. See
|
|
the sg_raw manpage for how this difficulty is addressed.
|
|
|
|
Documentation
|
|
-------------
|
|
Manual pages ("manpages") are the primary method of utility documentation.
|
|
All utilities and scripts that are installed by this package have a
|
|
manpage. There are utilities in the examples, testing and utils
|
|
directories that are not installed and do not have manpages. Nearly
|
|
all utilities have runtime help, usually invoked with either the '-h'
|
|
short option or the '--help' long option. There is also an overarching
|
|
manpage called "sg3_utils". All manpages are placed in chapter 8 which
|
|
is for system administration commands/utilities.
|
|
|
|
The sg3_utils package and some more complex utilities have html pages:
|
|
sg3_utils: https://sg.danny.cz/sg/sg3_utils.html
|
|
sg_ses: https://sg.danny.cz/sg/sg_ses.html
|
|
sg_dd: https://sg.danny.cz/sg/sg_dd.html
|
|
|
|
A tarball (and zip) of all the manpages from the previous release are
|
|
here:
|
|
https://sg.danny.cz/sg/p/sg3_utils_man_html.tgz
|
|
https://sg.danny.cz/sg/p/sg3_utils_man_html.zip
|
|
|
|
There is a html rendering of the sg3_utils manpage in the same directory
|
|
as this README file called sg3_utils.man8.html .
|
|
|
|
The previous README file is now called README.details plus there are
|
|
these OS specific files: README.freebsd , README.solaris , README.tru64
|
|
and README.win32 . To know the current state of the package the ChangeLog
|
|
file is the good reference.
|
|
|
|
The author's primary source code repository uses subversion and is on
|
|
the author's equipment (a RPi). One advantage of subversion is its
|
|
revision numbers which are simply integers starting at 1 and ascending.
|
|
For this package the current revision is 928 . The subversion repository
|
|
is mirrored in git (using "git svn" tools) here:
|
|
https://github.com/doug-gilbert/sg3_utils
|
|
|
|
|
|
Douglas Gilbert
|
|
31st December 2021
|