illumos: manual page: scsi

SCSI_IFGETCAP(9F) Kernel Functions for Drivers SCSI_IFGETCAP(9F)

NAME

scsi_ifgetcap, scsi_ifsetcap - get/set SCSI transport capability

SYNOPSIS

#include <sys/scsi/scsi.h>

int scsi_ifgetcap(struct scsi_address *ap, char *cap, int whom);

int scsi_ifsetcap(struct scsi_address *ap, char *cap, int value,
int whom);

INTERFACE LEVEL

illumos DDI specific (illumos DDI).

PARAMETERS

ap
Pointer to the scsi_address structure.

cap
Pointer to the string capability identifier.

value
Defines the new state of the capability.

whom
Determines if all targets or only the specified target is
affected.

DESCRIPTION

The scsi_ifsetcap() function is used by target drivers to set the
capabilities of the host adapter driver. The cap pointer is a name-value
pair identified by a null-terminated character string and the integer
value of the cap. The current value of the capability can be retrieved
with the scsi_ifgetcap() function. If the whom value is 0, all target
drivers are affected. Otherwise, the scsi_address structure pointed to by
ap is the only target that is affected.

The driver should confirm that scsi_ifsetcap() and scsi_ifsetcap()
functions are called with a cap that points to a capability which is
supported by the device.

The following capabilities have been defined:

dma-max
Maximum dma transfer size that is supported by
the host adapter.

dma-max-arch
Maximum dma transfer size that is supported by
system. Takes the host adapter and system
architecture into account. This is useful for
target drivers which do not support partial DMAs
on systems which do not have an IOMMU. In this
case, the DMA can also be limited by the host
adapters "scatter/gather" list constraints.

The "dma-max-arch" capability can not be set. It
is implemented with this command and does not
rely on a tran_getcap(9E) response from the HBA.

msg-out
Message out capability that is supported by the
host adapter: 0 disables, 1 enables.

disconnect
Disconnect capability that is supported by the
host adapter: 0 disables, 1 enables.

synchronous
Synchronous data transfer capability that is
supported by the host adapter: 0 disables, 1
enables.

wide-xfer
Wide transfer capability that is supported by the
host adapter: 0 disables, 1 enables.

parity
Parity checking capability that is supported by
host adapter: 0 disables, 1 enables.

initiator-id
Host bus address that is returned.

untagged-qing
Host adapter capability that supports internal
queueing of commands without tagged queueing: 0
disables, 1 enables.

tagged-qing
Host adapter capability that supports queuing: 0
disables, 1 enables.

auto-rqsense
Host adapter capability that supports auto
request sense on check conditions: 0 disables, 1
enables.

sector-size
Capability that is set by the target driver to
inform the HBA of the granularity, in bytes, of
the DMA breakup. The HBA DMA attributes structure
is set to reflect the byte total of this setting.
See ddi_dma_attr(9S). The sector-size should be
set to the size of the physical disk sector. The
capability defaults to 512 bytes.

total-sectors
Capability that is set by the target driver to
inform the HBA of the total number of sectors on
the device returned by the SCSI get capacity
command. This capability must be set before the
target driver ``gets'' the geometry capability.

geometry
Capability that returns the HBA geometry of a
target disk. The target driver sets the total-
sectors capability before ``getting'' the
geometry capability. The geometry is returned as
a 32-bit value. The upper 16 bits represent the
number of heads per cylinder. The lower 16 bits
represent the number of sectors per track. The
geometry capability cannot be ``set''.

If geometry is not relevant or appropriate for
the target disk, scsi_ifgetcap() can return -1 to
indicate that the geometry is not defined. For
example, if the HBA BIOS supports Logical Block
Addressing for the target disk, scsi_ifgetcap()
returns -1. Attempts to retrieve the "virtual
geometry" from the target driver, such as the
DKIOCG_VIRTGEOM ioctl, will fail. See dkio(4I)
for more information about DKIOCG_VIRTGEOM.

reset-notification
Host adapter capability that supports bus reset
notification: 0 disables, 1 enables. See
scsi_reset_notify(9F).

linked-cmds
Host adapter capability that supports linked
commands: 0 disables, 1 enables.

qfull-retries
Capability that enables or disables QUEUE FULL
handling. If 0, the HBA will not retry a command
when a QUEUE FULL status is returned. If the
value is greater than 0, the HBA driver retries
the command a specified number of times at an
interval determined by the qfull-retry-interval.
The range for qfull-retries is 0-255.

qfull-retry-interval
Capability that sets the retry interval in
milliseconds (ms) for commands completed with a
QUEUE FULL status. The range for qfull-retry-
intervals is 0-1000 ms.

lun-reset
Capability that is created with a value of zero
by HBA drivers that support the RESET_LUN flag in
the tran_reset(9E) function. If it exists, the
lun-reset value can be set to 1 by target drivers
to allow the use of LOGICAL UNIT RESET on a
specific target instance. If lun-reset does not
exist or has a value of zero, scsi_reset(9F) is
prevented from passing the RESET_LUN flag to
tran_reset() function of the HBA driver. If lun-
reset exists and has a value of 1, the
tran_reset() function of the HBA driver can be
called with the RESET_LUN flag.

interconnect-type
Capability held in the tran_interconnect_type
element of struct scsi_hba_tran that indicates
the HBA transport interconnect type . The
integer value of the interconnect type of the
transport is defined in the services.h header
file.

max-cdb-length
Host adapter capability of the maximum supported
CDB (Command Descriptor Block) length. The target
driver asks for the capability at attach time. If
the HBA driver supports the capability, the
maximum length of the CDB is returned in bytes.
The target driver can then use that value to
determine which CDB is used for the HBA.

If the HBA driver does not support the max-cdb-
length capability, the default value of the
target driver is used for the CDB determination.

RETURN VALUES

The scsi_ifsetcap() function returns:

1
If the capability was successfully set to the new value.

0
If the capability is not variable.

-1
If the capability was not defined, or setting the capability to
a new value failed.

The scsi_ifgetcap() function returns the current value of a capability,
or:

-1
If the capability was not defined.

EXAMPLES

Example 1: Using scsi_ifgetcap()

if (scsi_ifgetcap(&sd->sd_address, "auto-rqsense", 1) == 1) {
un->un_arq_enabled = 1;
} else {
un->un_arq_enabled =
((scsi_ifsetcap(&sd->sd_address, "auto-rqsense", 1, 1) == 1) ?
1 : 0);
}

if (scsi_ifsetcap(&devp->sd_address, "tagged-qing", 1, 1) == 1) {
un->un_dp->options |= SD_QUEUEING;
un->un_throttle = MAX_THROTTLE;
} else if (scsi_ifgetcap(&devp->sd_address, "untagged-qing", 0) == 1) {
un->un_dp->options |= SD_QUEUEING;
un->un_throttle = 3;
} else {
un->un_dp->options &= ~SD_QUEUEING;
un->un_throttle = 1;
}

CONTEXT

These functions can be called from user, interrupt, or kernel context.

ATTRIBUTES