README - platform/external/sg3_utils - Git at Google

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