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 the 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.
    - 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 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, 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. 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 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 922 . The subversion repository
 is mirrored in git (using "git svn" tools) here:
     https://github.com/doug-gilbert/sg3_utils


 Douglas Gilbert
 20th November 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 the 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.
	- 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 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, 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. 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 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 922 . The subversion repository
	is mirrored in git (using "git svn" tools) here:
	https://github.com/doug-gilbert/sg3_utils


	Douglas Gilbert
	20th November 2021