README.win32 - platform/external/sg3_utils - Git at Google

 Introduction
 ============
 The win32 port of sg3_utils contains those utilities that are _not_ specific
 to Linux. One utility for listing available devices, sg_scan, has a
 Windows-specific version for this port.

 The dd variants from the sg3_utils package (e.g. sg_dd) rely on too many
 Linux idiosyncrasies to be easily ported. A new package called 'ddpt'
 contains a utility with similar functionality to sg_dd and is available
 for Windows.

 The Windows port uses the Microsoft SCSI Pass Through (SPT) interface.
 It has two variants: "SPT" where data is double buffered; and "SPTD"
 where data pointers to the user space are passed to the OS. Only Windows
 2000 and later (i.e. not 95, 98 or ME) support SPT.

 Two build environments are catered for: cygwin (see www.cygwin.com) and
 MinGW ("Minimalist GNU for Windows", see www.mingw.org). Both are based in
 the gcc compiler (although other C compilers should have little problem with
 the source code). Cygwin is a more sophisticated, commercial product that
 results in executables that depend on cygwin1.dll . No licensing is required
 since sg3_utils is open source (with either BSD or GPL licenses) but users
 will need to fetch that dll. On the other hand MinGW (and its companion MSYS
 shell) builds freestanding console executables. The Unix library support is
 not as advanced with MinGW which has led to some timing functions being
 compiled out when sg3_utils is built for MinGW.

 In later versions of Windows these utilities may need to be "run as
 Administrator" for disks and other devices to be seen. If not those devices
 will simply not be found as calls to query them fail with access permission
 problems.

 Supported Utilities
 ===================
 Here is a list of utilities that have been ported:
     sg_bg_ctl
     sg_compare_and_write
     sg_decode_sense
     sg_format
     sg_get_config
     sg_get_elem_status
     sg_get_lba_status
     sg_ident
     sg_inq          [dropped ATA IDENTIFY DEVICE capability]
     sg_logs
     sg_luns
     sg_modes
     sg_opcodes
     sg_persist
     sg_prevent
     sg_raw
     sg_rdac
     sg_read_attr
     sg_read_block_limits
     sg_read_buffer
     sg_read_long
     sg_readcap
     sg_reassign
     sg_referrals
     sg_rep_pip
     sg_rep_zones
     sg_requests
     sg_reset_wp
     sg_rmsn
     sg_rtpg
     sg_safte
     sg_sanitize
     sg_sat_identify
     sg_sat_phy_event
     sg_sat_read_gplog
     sg_sat_set_features
     sg_scan         [this is Windows specific]
     sg_seek
     sg_senddiag
     sg_ses
     sg_ses_microcode
     sg_start
     sg_stpg
     sg_stream_ctl
     sg_sync
     sg_timestamp
     sg_turs
     sg_unmap
     sg_verify
     sg_vpd
     sg_wr_mode
     sg_write_buffer
     sg_write_long
     sg_write_same
     sg_write_verify
     sg_write_x
     sg_zone

 Most utility names are indicative of the main SCSI command that they execute.
 Some utilities are slightly higher level, for example sg_ses fetches SCSI
 Enclosure Services (SES) status pages and can send control pages. Each
 utility has a man page (placed in section 8). There is summary of the mapping
 between utility names and the SCSI commands they execute in the COVERAGE
 file. An overview of sg3_utils can be found at:
 https://sg.danny.cz/sg/sg3_utils.html .
 A copy of the "sg3_utils.html" file is in the "doc" subdirectory.

 Some man pages have examples which use Linux device names which hopefully
 will not confuse Windows users.

 Two pass-through variants
 =========================
 The sg_pt_win32.c file uses the Windows SCSI Pass Through interface.
 That is often shortened to SPT or SPTI. There are two DeviceIoControl()
 ioctl variants provided: IOCTL_SCSI_PASS_THROUGH and
 IOCTL_SCSI_PASS_THROUGH_DIRECT. The former involves double handling of
 data (and perhaps an upper limit on the data length associated with
 one SCSI command; MS documentation mentions 16 KB). The "direct"
 variant passes a pointer from the user space and to be faster looks
 and more versatile.

 However the "direct" variant has potentially (unquantified) alignment
 requirements and may not be (well) implemented by the hardware driver.
 In practice some users have reported errors (e.g. 1117: a non-descript
 IO error) when the direct variant is used.

 Hence the non-direct variant is the default. The default size limit
 on the data buffer is set at 16 KB but if the user asks for more
 the data buffer will be extended. The OS or the hardware drivers
 may reject the extended data buffer but we tried.

 The package can be built using the direct variant with:
    ./configure --enable-win32-spt-direct
 rather than:
    ./configure
 prior to the 'make' call.

 In sg3_utils version 1.31 run-time selection of the direct or indirect
 interface was added with the scsi_pt_win32_direct(int state_direct)
 function declared in sg_pt.h. The default is indirect unless
 './configure --enable-win32-spt-direct' was used in the build. If
 'state_direct' is 1 then the direct interface is used and if it is 0
 the indirect interface is used.

 Both sg_read_buffer and sg_write_buffer can transfer buffers larger
 than 16 KB. So in sg3_utils version 1.31, they use this new function
 to set direct interface mode. This is regardless of whether or
 not "--enable-win32-spt-direct" is given to ./configure .

 Details
 =======
 Most of the ported utilities listed above use SCSI command functions
 declared in sg_cmds_*.h headers . Those SCSI command functions are
 implemented in the corresponding ".c" files. The ".c" files pass SCSI
 commands to the host operating system via an interface declared in sg_pt.h .
 There are currently five implementations of that interface depending on
 the host operating system:
   - sg_pt_linux.c
   - sg_pt_freebsd.c
   - sg_pt_osf1.c  [Tru64]
   - sg_pt_solaris.c
   - sg_pt_win32.c

 The ASPI32 interface which requires a dll from Adaptec is not supported.

 The sg_scan utility is a special version for Windows and it attempts to show
 the various available storage device names, one per line. Here is an example
 of sg_scan's output:

 # sg_scan
 PD0     [C]     FUJITSU   MHY2160BH         0000
 PD1     [DF]    WD        2500BEV External  1.05  WD-WXE90
 CDROM0  [E]     MATSHITA DVD/CDRW UJDA775  CB03

 Here is an example with added bus type:

 # sg_scan -b
 PD0     [C]     <Ata  >  FUJITSU   MHY2160BH         0000
 PD1     [DF]    <Usb  >  WD        2500BEV External  1.05  WD-WXE90
 CDROM0  [E]     <Atapi>  MATSHITA DVD/CDRW UJDA775  CB03

 Here is an example with added SCSI adapter scan:

 # sg_scan -b -s
 PD0     [C]     <Ata  >  ST380011A  8.01
 PD1             <Scsi >  SEAGATE   ST373455SS        2189
 PD2             <Scsi >  ATA       ST3160812AS       D
 PD3             <Scsi >  SEAGATE   ST336754SS        0003
 CDROM0  [F]     <Atapi>  HL-DT-ST DVDRAM GSA-4163B  A103
 TAPE0           <Scsi >  SONY      SDT-7000          0192

 SCSI0:0,0,0   claimed=1 pdt=0h dubious  ST380011  A                 8.01
 SCSI1:0,0,0   claimed=1 pdt=5h          HL-DT-ST  DVDRAM GSA-4163B  A103
 SCSI2:0,6,0   claimed=1 pdt=1h          SONY      SDT-7000          0192
 SCSI5:0,17,0  claimed=1 pdt=0h          SEAGATE   ST373455SS        2189
 SCSI5:0,19,0  claimed=1 pdt=0h          ATA       ST3160812AS       D
 SCSI5:0,21,0  claimed=1 pdt=0h          SEAGATE   ST336754SS        0003
 SCSI5:0,112,0 claimed=0 pdt=10h         LSI       PSEUDO DEVICE     2.34

 The storage devices scanned are PhysicalDrive<n> (shortened form PD<n> used),
 CDROM<n> (which includes DVD and BD drives) and TAPE<n>. There is also an
 optional SCSI adapter scan with device names of the form SCSI<n>:<b>:<t>:<l> .
 These only come into play for devices that are not claimed by one of the
 storage class drivers. The "LSI PSEUDO DEVICE" device above is an example
 of an unclaimed device. The SCSI adapter scan does not show USB and IEEE
 1394 connected devices.

 Volume names (e.g. "C:") that match a storage device (or perhaps a
 partition within that device) are shown in brackets. Notice there can be
 zero, one or more volume names for each storage device. Up to four volume
 names are listed in brackets, if there are more a "+" is added after the
 fourth.

 Several utilities have conditional compilation sections based on
 the SG_LIB_MINGW define. For those who want to try native C compilers
 on Windows setting the SG_LIB_MINGW define may help.

 Build environments
 ==================
 This package uses autotools infrastructure with the now common
 "./configure ; make ; make install" sequence needed to build and install
 from the source found in the tarball. Two Windows environments for building
 Unix code are supported: cygwin and MinGW. If the "./configure" sequence
 fails try using the ./autogen.sh prior to that sequence. The executables
 produced are console applications that can be executed in either a cygwin,
 MSYS or "cmd" shell. Various build options are available by giving
 command line options to "./configure", see the INSTALL file for generic
 information about the build infrastructure.

 MinGW can be used to cross built on some Redhat (Linux) platforms. After
 loading the cross build packages, the ./configure call in the normal
 autotools sequence should be replaced by either mingw32-configure or
 mingw64-configure. These scripts will set up the environment for
 the cross build and then call ./configure (so this invocation should be
 made in the top level of the untarred source). Options given to either
 script (e.g. --enable-win32-spt-direct) will be passed through to
 ./configure .

 Binary and Text files
 =====================
 A problem has been reported with binary output being written in a MinGW
 environment (or executables build by MinGW). Windows has a concept of text
 and binary files which is not found in Unix. Recent versions of MinGW
 default to opening files in text mode. This can lead to binary output
 (such as when the '--raw' option is given) having 0xa (i.e. LF) translated
 to 0xd,0xa (i.e. CR,LF). sg3_utils version 1.26 attempts to fix this
 problem by changing what it knows to be binary output files to "binary
 mode" with the setmode() Windows command.


 Douglas Gilbert
 6th June 2020
	Introduction
	============
	The win32 port of sg3_utils contains those utilities that are _not_ specific
	to Linux. One utility for listing available devices, sg_scan, has a
	Windows-specific version for this port.

	The dd variants from the sg3_utils package (e.g. sg_dd) rely on too many
	Linux idiosyncrasies to be easily ported. A new package called 'ddpt'
	contains a utility with similar functionality to sg_dd and is available
	for Windows.

	The Windows port uses the Microsoft SCSI Pass Through (SPT) interface.
	It has two variants: "SPT" where data is double buffered; and "SPTD"
	where data pointers to the user space are passed to the OS. Only Windows
	2000 and later (i.e. not 95, 98 or ME) support SPT.

	Two build environments are catered for: cygwin (see www.cygwin.com) and
	MinGW ("Minimalist GNU for Windows", see www.mingw.org). Both are based in
	the gcc compiler (although other C compilers should have little problem with
	the source code). Cygwin is a more sophisticated, commercial product that
	results in executables that depend on cygwin1.dll . No licensing is required
	since sg3_utils is open source (with either BSD or GPL licenses) but users
	will need to fetch that dll. On the other hand MinGW (and its companion MSYS
	shell) builds freestanding console executables. The Unix library support is
	not as advanced with MinGW which has led to some timing functions being
	compiled out when sg3_utils is built for MinGW.

	In later versions of Windows these utilities may need to be "run as
	Administrator" for disks and other devices to be seen. If not those devices
	will simply not be found as calls to query them fail with access permission
	problems.

	Supported Utilities
	===================
	Here is a list of utilities that have been ported:
	sg_bg_ctl
	sg_compare_and_write
	sg_decode_sense
	sg_format
	sg_get_config
	sg_get_elem_status
	sg_get_lba_status
	sg_ident
	sg_inq [dropped ATA IDENTIFY DEVICE capability]
	sg_logs
	sg_luns
	sg_modes
	sg_opcodes
	sg_persist
	sg_prevent
	sg_raw
	sg_rdac
	sg_read_attr
	sg_read_block_limits
	sg_read_buffer
	sg_read_long
	sg_readcap
	sg_reassign
	sg_referrals
	sg_rep_pip
	sg_rep_zones
	sg_requests
	sg_reset_wp
	sg_rmsn
	sg_rtpg
	sg_safte
	sg_sanitize
	sg_sat_identify
	sg_sat_phy_event
	sg_sat_read_gplog
	sg_sat_set_features
	sg_scan [this is Windows specific]
	sg_seek
	sg_senddiag
	sg_ses
	sg_ses_microcode
	sg_start
	sg_stpg
	sg_stream_ctl
	sg_sync
	sg_timestamp
	sg_turs
	sg_unmap
	sg_verify
	sg_vpd
	sg_wr_mode
	sg_write_buffer
	sg_write_long
	sg_write_same
	sg_write_verify
	sg_write_x
	sg_zone

	Most utility names are indicative of the main SCSI command that they execute.
	Some utilities are slightly higher level, for example sg_ses fetches SCSI
	Enclosure Services (SES) status pages and can send control pages. Each
	utility has a man page (placed in section 8). There is summary of the mapping
	between utility names and the SCSI commands they execute in the COVERAGE
	file. An overview of sg3_utils can be found at:
	https://sg.danny.cz/sg/sg3_utils.html .
	A copy of the "sg3_utils.html" file is in the "doc" subdirectory.

	Some man pages have examples which use Linux device names which hopefully
	will not confuse Windows users.

	Two pass-through variants
	=========================
	The sg_pt_win32.c file uses the Windows SCSI Pass Through interface.
	That is often shortened to SPT or SPTI. There are two DeviceIoControl()
	ioctl variants provided: IOCTL_SCSI_PASS_THROUGH and
	IOCTL_SCSI_PASS_THROUGH_DIRECT. The former involves double handling of
	data (and perhaps an upper limit on the data length associated with
	one SCSI command; MS documentation mentions 16 KB). The "direct"
	variant passes a pointer from the user space and to be faster looks
	and more versatile.

	However the "direct" variant has potentially (unquantified) alignment
	requirements and may not be (well) implemented by the hardware driver.
	In practice some users have reported errors (e.g. 1117: a non-descript
	IO error) when the direct variant is used.

	Hence the non-direct variant is the default. The default size limit
	on the data buffer is set at 16 KB but if the user asks for more
	the data buffer will be extended. The OS or the hardware drivers
	may reject the extended data buffer but we tried.

	The package can be built using the direct variant with:
	./configure --enable-win32-spt-direct
	rather than:
	./configure
	prior to the 'make' call.

	In sg3_utils version 1.31 run-time selection of the direct or indirect
	interface was added with the scsi_pt_win32_direct(int state_direct)
	function declared in sg_pt.h. The default is indirect unless
	'./configure --enable-win32-spt-direct' was used in the build. If
	'state_direct' is 1 then the direct interface is used and if it is 0
	the indirect interface is used.

	Both sg_read_buffer and sg_write_buffer can transfer buffers larger
	than 16 KB. So in sg3_utils version 1.31, they use this new function
	to set direct interface mode. This is regardless of whether or
	not "--enable-win32-spt-direct" is given to ./configure .

	Details
	=======
	Most of the ported utilities listed above use SCSI command functions
	declared in sg_cmds_*.h headers . Those SCSI command functions are
	implemented in the corresponding ".c" files. The ".c" files pass SCSI
	commands to the host operating system via an interface declared in sg_pt.h .
	There are currently five implementations of that interface depending on
	the host operating system:
	- sg_pt_linux.c
	- sg_pt_freebsd.c
	- sg_pt_osf1.c [Tru64]
	- sg_pt_solaris.c
	- sg_pt_win32.c

	The ASPI32 interface which requires a dll from Adaptec is not supported.

	The sg_scan utility is a special version for Windows and it attempts to show
	the various available storage device names, one per line. Here is an example
	of sg_scan's output:

	# sg_scan
	PD0 [C] FUJITSU MHY2160BH 0000
	PD1 [DF] WD 2500BEV External 1.05 WD-WXE90
	CDROM0 [E] MATSHITA DVD/CDRW UJDA775 CB03

	Here is an example with added bus type:

	# sg_scan -b
	PD0 [C] <Ata > FUJITSU MHY2160BH 0000
	PD1 [DF] <Usb > WD 2500BEV External 1.05 WD-WXE90
	CDROM0 [E] <Atapi> MATSHITA DVD/CDRW UJDA775 CB03

	Here is an example with added SCSI adapter scan:

	# sg_scan -b -s
	PD0 [C] <Ata > ST380011A 8.01
	PD1 <Scsi > SEAGATE ST373455SS 2189
	PD2 <Scsi > ATA ST3160812AS D
	PD3 <Scsi > SEAGATE ST336754SS 0003
	CDROM0 [F] <Atapi> HL-DT-ST DVDRAM GSA-4163B A103
	TAPE0 <Scsi > SONY SDT-7000 0192

	SCSI0:0,0,0 claimed=1 pdt=0h dubious ST380011 A 8.01
	SCSI1:0,0,0 claimed=1 pdt=5h HL-DT-ST DVDRAM GSA-4163B A103
	SCSI2:0,6,0 claimed=1 pdt=1h SONY SDT-7000 0192
	SCSI5:0,17,0 claimed=1 pdt=0h SEAGATE ST373455SS 2189
	SCSI5:0,19,0 claimed=1 pdt=0h ATA ST3160812AS D
	SCSI5:0,21,0 claimed=1 pdt=0h SEAGATE ST336754SS 0003
	SCSI5:0,112,0 claimed=0 pdt=10h LSI PSEUDO DEVICE 2.34

	The storage devices scanned are PhysicalDrive<n> (shortened form PD<n> used),
	CDROM<n> (which includes DVD and BD drives) and TAPE<n>. There is also an
	optional SCSI adapter scan with device names of the form SCSI<n>:<b>:<t>:<l> .
	These only come into play for devices that are not claimed by one of the
	storage class drivers. The "LSI PSEUDO DEVICE" device above is an example
	of an unclaimed device. The SCSI adapter scan does not show USB and IEEE
	1394 connected devices.

	Volume names (e.g. "C:") that match a storage device (or perhaps a
	partition within that device) are shown in brackets. Notice there can be
	zero, one or more volume names for each storage device. Up to four volume
	names are listed in brackets, if there are more a "+" is added after the
	fourth.

	Several utilities have conditional compilation sections based on
	the SG_LIB_MINGW define. For those who want to try native C compilers
	on Windows setting the SG_LIB_MINGW define may help.

	Build environments
	==================
	This package uses autotools infrastructure with the now common
	"./configure ; make ; make install" sequence needed to build and install
	from the source found in the tarball. Two Windows environments for building
	Unix code are supported: cygwin and MinGW. If the "./configure" sequence
	fails try using the ./autogen.sh prior to that sequence. The executables
	produced are console applications that can be executed in either a cygwin,
	MSYS or "cmd" shell. Various build options are available by giving
	command line options to "./configure", see the INSTALL file for generic
	information about the build infrastructure.

	MinGW can be used to cross built on some Redhat (Linux) platforms. After
	loading the cross build packages, the ./configure call in the normal
	autotools sequence should be replaced by either mingw32-configure or
	mingw64-configure. These scripts will set up the environment for
	the cross build and then call ./configure (so this invocation should be
	made in the top level of the untarred source). Options given to either
	script (e.g. --enable-win32-spt-direct) will be passed through to
	./configure .

	Binary and Text files
	=====================
	A problem has been reported with binary output being written in a MinGW
	environment (or executables build by MinGW). Windows has a concept of text
	and binary files which is not found in Unix. Recent versions of MinGW
	default to opening files in text mode. This can lead to binary output
	(such as when the '--raw' option is given) having 0xa (i.e. LF) translated
	to 0xd,0xa (i.e. CR,LF). sg3_utils version 1.26 attempts to fix this
	problem by changing what it knows to be binary output files to "binary
	mode" with the setmode() Windows command.


	Douglas Gilbert
	6th June 2020