scsi_ctl.7 (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

scsi_ctl(7) scsi_ctl(7)

NAME

scsi_ctl - SCSI pass-through driver (esctl/sctl)

DESCRIPTION

SCSI devices are controlled by a device-speciﬁc driver, when one exists. Device-speciﬁc drivers, such as

those for SCSI direct access (disk) and sequential access (tape) devices, coordinate device and driver

states to accomplish correct logical device behavior. The SCSI pass-through driver enables use of SCSI

devices and commands not normally supported by these device-speciﬁc drivers.

esctl is the SCSI pass-through driver and works with persistent device ﬁles (see intro (7)).

sctl is the

SCSI pass-through driver already used on HP-UX releases prior to HP-UX 11i v3. It is maintained here

for backward compatibility, and works with legacy device ﬁles. In this document

scsi_ctl refers to

both

esctl and sctl.

Once the device is opened through

scsi_ctl driver, ioctl calls can be used to change SCSI communica-

tion parameters or to attempt SCSI commands and other SCSI operations. Since the pass-through driver

does not attempt to logically understand the target device,

read() and write() calls are not sup-

ported.

Except where noted, the ioctls described here are available through all SCSI device drivers (including

device-speciﬁc drivers). All

reserved ﬁelds in the data structures associated with these ioctls must be

zero-ﬁlled.

The following ioctls which are speciﬁc to parallel SCSI, are deprecated for issuance on LUN device special

ﬁles (DSF). They are not supported on persistent device special ﬁles. They continue to be supported on

legacy device special ﬁles for backward compatibility. However, HP now recommends to issue these ioctls

(or equivalent ioctls introduced with HP-UX 11i v3) directly on the parallel SCSI HBA device special ﬁle

(DSF).

SIOC_GET_TGT_PARMS

SIOC_GET_BUS_PARMS

SIOC_GET_TGT_LIMITS

SIOC_GET_BUS_LIMITS

SIOC_SET_TGT_LIMITS

SIOC_SET_BUS_LIMITS

The following parallel SCSI speciﬁc ioctls introduced with HP-UX 11i v3 should be issued directly on the

parallel SCSI HBA DSF. These ioctls replace some existing ioctls, which can no longer be issued on LUN

persistent device ﬁles starting with HP-UX 11i v3:

PSIOC_GET_TGT_LIMITS

replaces SIOC_GET_TGT_PARMS

PSIOC_GET_TGT_PARMS

replaccs SIOC_GET_BUS_PARMS

PDIOC_RSTCLR replaces DIOC_RSTCLR

PSIOC_RESET_DEV replaces

SIOC_RESET_DEV

Legacy device ﬁles are deprecated with HP-UX release 11i v3. They are maintained for backward compa-

tibility, and may be obsolete in a future release (see intro (7) for details about legacy device ﬁles and per-

sistent device ﬁles). It is recommended to use persistent device ﬁles for new applications.

Most of the ioctls described here can be issued either on persistent device ﬁles or legacy device ﬁles. The

behavior of some ioctls may differ depending on whether they are issued on persistent or legacy device

ﬁles, and whether multi-pathing is enabled on legacy device ﬁles. Typically ioctls issuing SCSI commands

to a device may use any available LUN path to the device to send the commands. However, when multi-

pathing is disabled on legacy device ﬁles (see the

leg_mpath_enable attribute in scsimgr (1M)), the

ioctl only attempts to use the LUN path corresponding to the legacy device ﬁle. If this LUN path is not

available, the ioctl will fail even if there are other LUN paths available. This behavior corresponds to the

legacy behavior.

Device Special File Minor Number

The pass-through driver (

esctl/sctl) is the preferred method to perform the ioctls SIOC_IO_EXT

(esctl only) and SIOC_IO ioctls, rather than going through a device-speciﬁc driver (such as esdisk).

To do this, you must create the device special ﬁle for the pass-through driver. mksf (1M) is the recom-

mended method to create a pass-through device ﬁle for esctl. To create a device ﬁle for the legacy

pass-through driver sctl, use mknod(1M), substituting the values in the minor number as noted:

/usr/sbin/mknod name c 203 0xiitl 0o

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (10 pages)

PAGE 1
scsi_ctl(7) scsi_ctl(7) NAME scsi_ctl - SCSI pass-through driver (esctl/sctl) DESCRIPTION SCSI devices are controlled by a device-specific driver, when one exists. Device-specific drivers, such as those for SCSI direct access (disk) and sequential access (tape) devices, coordinate device and driver states to accomplish correct logical device behavior. The SCSI pass-through driver enables use of SCSI devices and commands not normally supported by these device-specific drivers.
PAGE 2
scsi_ctl(7) scsi_ctl(7) where component parts of the minor number are constructed as follows: ii Two hexadecimal digits, identifying the controlling interface card by its "Instance" number. The Instance value is displayed in ioscan (1M) output, under column I for the "Interface" hardware type. t One hexadecimal digit identifying the drive (target) address. l One hexadecimal digit identifying the logical unit number (LUN) within the device.
PAGE 3
scsi_ctl(7) The current scsi_ctl(7) operating communication parameters may be determined by use of the: SIOC_GET_LUN_PARMS, PSIOC_GET_TGT_PARMS (recommended) or SIOC_GET_TGT_PARMS (for backward compatibility), and SIOC_GET_BUS_PARMS ioctls. Occasionally, it is desirable to limit SCSI communication parameters to work around a communication problem or to provide external insight in determining optimal parameters.
PAGE 4
scsi_ctl(7) scsi_ctl(7) The max_reqack_offset field specifies the maximum number of outstanding REQs that should be attempted during data transfers to any target device connected to the associated bus. The max_xfer_rate field specifies the maximum synchronous "burst" data transfer rate that should be attempted for data transfers to any target device connected to the associated bus. The SIOC_GET_BUS_LIMITS ioctl indicates the current bus communication parameter limit suggestions.
PAGE 5
scsi_ctl(7) scsi_ctl(7) unsigned int max_reqack_offset; unsigned int max_xfer_rate; unsigned int reserved[4]; /* bytes/sec */ /* reserved for future * use */ } sioc_bus_parms_t; struct sioc_bus_limits { unsigned int flags; unsigned unsigned unsigned unsigned int int int int /* reserved for future * use */ max_width; max_reqack_offset; max_xfer_rate; reserved[4]; /* bytes/sec */ /* reserved for future * use */ } sioc_bus_limits_t; The following is included from
PAGE 6
scsi_ctl(7) scsi_ctl(7) abort, and device and bus reset operations. A zero value in the max_msecs field indicates that the timeout period is infinite and the system should wait indefinitely for command completion. When the SIO_IO_EXT or SIOC_IO ioctl call returns, all command processing has been completed. Most SIOC_IO_EXT/SIOC_IO ioctl calls will return zero (success). The resulting detailed ioctl data should be used to evaluate "success" or "failure" from the caller’s perspective.
PAGE 7
scsi_ctl(7) scsi_ctl(7) is issued on a persistent device file, target and bus exclusive access requests result to a LUN exclusive access being performed.
PAGE 8
scsi_ctl(7) unsigned unsigned char unsigned char } sctl_io_t; scsi_ctl(7) sense_status; sense_xfer; reserved[64]; Security Restrictions Superuser or DEVOPS privilege, or device write permissions are required to use these ioctls. See privileges (5) for more information about privileged access on systems that support fine-grained privileges.
PAGE 9
scsi_ctl(7) scsi_ctl(7) esctl_io.cdb[2] = 0x00; esctl_io.cdb[3] = 0x00; esctl_io.cdb[4] = MAX_LEN; /* allocation length */ esctl_io.cdb[5] = 0x00; esctl_io.cdb_length = 6; /* 6 byte command */ esctl_io.data = &inquiry_data[0]; /* data buffer location */ esctl_io.data_length = MAX_LEN; /* maximum transfer length */ esctl_io.max_msecs = 10000; /* allow 10 seconds for cmd */ if (ioctl(fildes, SIOC_IO_EXT, &esctl_io) < 0) { /* request is invalid */ } else { if ( esctl_io.cdb_status == S_GOOD) { /* success.
PAGE 10
scsi_ctl(7) scsi_ctl(7) Most SCSI commands have a logical unit number (LUN) field. Parallel SCSI implementations on the HP-UX operating system select logical units via the SCSI IDENTIFY message. The LUN portion of the cdb should normally be set to zero, even when the LUN being accessed is not zero. Use of linked commands is not supported. Most SCSI commands with a data phase expect the data length information to be included somewhere in the command bytes.