xref: /aosp_15_r20/external/sg3_utils/README.solaris (revision 44704f698541f6367e81f991ef8bb54ccbf3fc18)

Please Note:
>>> Up to and including sg3_utils-1.33 the Solaris code was built
>>> and tested on an OpenSolaris VM run with VirtualBox on Ubuntu
>>> 11.10 . Now with Ubuntu 12.04 those VMs crash immediately when
>>> started with VirtualBox. Further, Oracle (who owns SUN and thus
>>> Solaris) no longer supports OpenSolaris and its package
>>> repository has been withdrawn. The author can find no generic VMs
>>> for Oracle Solaris 11 that run on VirtualBox or VMWare. The author
>>> is also displeased with the withdrawal of the Open Software
>>> OS and is disinclined to build a Solaris 11 system just to
>>> virtualize it.
>>> So as of sg3_utils-1.34 the Solaris port is provided "as-is" without
>>> testing on a Solaris platform.

Douglas Gilbert
13th October 2012



Introduction
============
The Solaris port of sg3_utils contains those utilities that are
_not_ specific to Linux.

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

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_persist
    sg_opcodes
    sg_prevent
    sg_raw
    sg_rdac
    sg_read_block_limts
    sg_read_buffer
    sg_read_long
    sg_readcap
    sg_reassign
    sg_referrals
    sg_rep_pip
    sg_rep_zones
    sg_requests
    sg_rmsn
    sg_rtpg
    sg_safte
    sg_sanitize
    sg_sat_identify
    sg_sat_phy_event
    sg_sat_set_features
    sg_seek
    sg_senddiag
    sg_ses
    sg_start
    sg_stpg
    sg_stream_ctl
    sg_sync
    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). 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.


The executables and library can be built from the source code in
the tarball and installed with the familiar
"./configure ; make ; make install" sequence. If this fails try
running the "./autogen.sh" script prior to that sequence. There
are generic instruction on configure and friend in the INSTALL file.

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

Device naming
=============
In Solaris, SCSI device names below the '/dev' directory have a
form like: c5t4d3s2 where the number following "c" is the controller
(HBA) number, the number following "t" is the target number (from
the SCSI parallel interface days) and the number following "d" is
the LUN. Following the "s" is the slice number which is related to
a partition and by convention "s2" is the whole disk.

OpenSolaris also has a c5t4d3p2 form where the number following
the "p" is the partition number apart from "p0" which is the whole
disk. So a whole disk may be referred to as either:
  - c5t4d3
  - c5t4d3s2
  - c5t4d3p0

And these device names are duplicated in the /dev/dsk and /dev/rdsk
directories. The former is the block device name and the latter
is for "raw" (or char device) access which is what sg3_utils needs.
So in OpenSolaris something of the form:
   sg_inq /dev/rdsk/c5t4d3p0
should work. If it doesn't add a '-vvv' option. If that is attempted
on the /dev/dsk/c5t4d3p0 variant an inappropriate ioctl for device
error will result.

The device names within the /dev directory are typically symbolic
links to much longer topological names in the /device directory.

In Solaris cd/dvd/bd players seem to be treated as disks and so are
found in the /dev/rdsk directory. Tape drives appear in the /dev/rmt
directory.

There is also a sgen (SCSI generic) driver which by default does not
attach to any device. See the /kernel/drv/sgen.conf file to control
what is attached. Any attached device will have a device name of
the form /dev/scsi/c5t4d3 .

Listing available SCSI devices in Solaris seems to be a challenge.
"Use the 'format' command" advice works but seems a very dangerous
way to list devices. [It does prompt again before doing any damage.]
'devfsadm -Cv' cleans out the clutter in the /dev/rdsk directory,
only leaving what is "live". The "cfgadm -v" command looks promising.

Details
=======
The ported utilities listed above, all use SCSI command functions
declared in sg_cmds_basic.h and sg_cmds_extra.h . 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 sg_pt_solaris.c file uses the "uscsi" SCSI pass through mechanism. There
seems to be no corresponding ATA pass through and recent SATA disks do not
seem to have a SAT layer in front of them (within Solaris). If SAT is
present (perhaps externally or within a HBA) then that would allow SATA
disks to accept SCSI commands including the SCSI ATA PASS THROUGH commands.


Douglas Gilbert
5th June 2020