1 README for sg3_utils 2 ==================== 3Introduction 4------------ 5sg3_utils is a package of utilities originally written to send individual 6SCSI commands to storage devices that used one of the SCSI command sets. 7These utilities can be divided into three groups: 8 - sg_raw: the user supplies the cdb (command descriptor block) and 9 optionally the size of the data-in and data-out buffers 10 - one command utilities: the majority of the utilities in this package 11 send one SCSI command. Their names start with "sg_" while the 12 remaining part of their name alludes to the command which is sent. For 13 example, "sg_inq" sends the SCSI INQUIRY command. Some utilities in 14 this group send one of a selection of commands, typically those 15 commands have a lot it common (e.g. sg_write_x). 16 - copy type utilities: sg_dd, sgp_dd and sgm_dd use the Unix dd command 17 as a template. sg_xcopy sends the SCSI EXTENDED COPY command which in 18 some cases can do offloaded copies. As well as copying some of these 19 utilities can compare if two data segments held on disks are the same. 20 21Platforms 22--------- 23These utilities were written on Linux and should work from Linux kernel 24(lk) 2.4 through to the current series 5. The third group ("copy type") 25are only implemented on Linux, but a separate portable package/utility 26called ddpt implements similar functionality. The first two groups are 27implemented (i.e. ported) to Android, FreeBSD, Solaris and Windows. The 28Windows port uses either a Cygwin or MinGW (plus Msys) build environment 29(rather than Visual Studio). 30 31Library 32------- 33Many of these utilities share a lot of code (e.g. SCSI error messages) 34so a lot of repetition (potentially error prone) is saved by having a 35library called libsgutils or some variation on that name. Distributions 36(especially of Linux) have differing policies on how a library (and a 37package) should be named. For that reason this package is sometimes 38known as "sg3-utils" (i.e. the underscore is turned into a hyphen). 39Various other packages use libsgutils. The library interface is not 40altered from one package release, to the next, but the library interface 41may be expanded. If a utility from one release is used with a libsgutils 42from an earlier release, then the runtime linking may fail. Typically 43package managers take care of these details so that runtime linking 44errors should be rare. 45 46Command Sets 47------------ 48SCSI command sets are not the only storage command sets in wide use, there 49are also ATA and NVMe command sets. There is a SCSI command set to 50translate SCSI commands to ATA commands (called SAT: SCSI to ATA 51Translation). SAT includes an ATA PASS-THROUGH SCSI command and sg_sat_* 52utilities (there are four) are examples of using SAT. The SAS transport 53(Serial Attached SCSI) can convey ATA commands through a SCSI/SAS domain 54via its Serial ATA Tunnelled Protocol (STP). 55 56NVMe command sets (e.g. Admin, NVM and MI) are relatively new. There was an 57early paper on a SCSI to NVMe Translation Layer (SNTL) but it hasn't been 58standardized. The sg_inq utility will send (and decode the response of) a 59SCSI INQUIRY command if the underlying device is a SCSI device. If the 60underlying device is a NVMe controller or namespace, then sg_inq will send 61a NVMe Admin Identify command and decode the response. The sg_ses utility 62(for SCSI Enclosure Services) also checks whether its underlying device is 63SCSI or NVME. In the NVMe case, sg_ses translates the SCSI SEND DIAGNOSTIC 64and READ DIAGNOSTIC RESULTS commands to the NVMe Management Interface (MI) 65SES Send and SES Receive commands respectively. The output of the sg_ses 66utility should be similar, irrespective of whether the "SES" device is 67SCSI or NVMe. 68 69The sg_raw utility may send NVMe Admin or NVM commands (as well as SCSI 70commands). One difficulty with a command-line utility invoking NVME 71commands is that those commands contain memory addresses for data-in (from 72the storage device) or data-out (toward the storage device) transfers. See 73the sg_raw manpage for how this difficulty is addressed. 74 75Documentation 76------------- 77Manual pages ("manpages") are the primary method of utility documentation. 78All utilities and scripts that are installed by this package have a 79manpage. There are utilities in the examples, testing and utils 80directories that are not installed and do not have manpages. Nearly 81all utilities have runtime help, usually invoked with either the '-h' 82short option or the '--help' long option. There is also an overarching 83manpage called "sg3_utils". All manpages are placed in chapter 8 which 84is for system administration commands/utilities. 85 86The sg3_utils package and some more complex utilities have html pages: 87 sg3_utils: https://sg.danny.cz/sg/sg3_utils.html 88 sg_ses: https://sg.danny.cz/sg/sg_ses.html 89 sg_dd: https://sg.danny.cz/sg/sg_dd.html 90 91A tarball (and zip) of all the manpages from the previous release are 92here: 93 https://sg.danny.cz/sg/p/sg3_utils_man_html.tgz 94 https://sg.danny.cz/sg/p/sg3_utils_man_html.zip 95 96There is a html rendering of the sg3_utils manpage in the same directory 97as this README file called sg3_utils.man8.html . 98 99The previous README file is now called README.details plus there are 100these OS specific files: README.freebsd , README.solaris , README.tru64 101and README.win32 . To know the current state of the package the ChangeLog 102file is the good reference. 103 104The author's primary source code repository uses subversion and is on 105the author's equipment (a RPi). One advantage of subversion is its 106revision numbers which are simply integers starting at 1 and ascending. 107For this package the current revision is 928 . The subversion repository 108is mirrored in git (using "git svn" tools) here: 109 https://github.com/doug-gilbert/sg3_utils 110 111 112Douglas Gilbert 11331st December 2021 114