scsi_ifgetcap(9F)




NAME

     scsi_ifgetcap, scsi_ifsetcap - get/set SCSI transport  capa-
     bility


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

     Solaris DDI specific (Solaris 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 target drivers use scsi_ifsetcap() to set the  capabili-
     ties  of the host adapter driver. A cap is a name-value pair
     whose name is a null terminated character string  and  whose
     value  is  an integer. The current value of a capability can
     be retrieved using scsi_ifgetcap(). If whom is 0 all targets
     are  affected, else the target specified by the scsi_address
     structure pointed to by ap is affected.

     A device may support  only  a  subset  of  the  capabilities
     listed below. It is the responsibility of the driver to make
     sure that these functions are called with a cap supported by
     the device.

     The following capabilities have been defined:

          dma-max
                Maximum  dma  transfer  size  supported  by  host
                adapter.

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

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

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

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

          parity
                Parity checking by host adapter:  0  disables,  1
                enables.

          initiator-id
                The host's bus address is returned.

          untagged-qing
                The host adapter's capability to support internal
                queueing  of  commands without tagged queueing: 0
                disables, 1 enables.

          tagged-qing
                The host adapter's capability to  support  tagged
                queuing: 0 disables, 1 enables.

          auto-rqsense
                The host adapter's  capability  to  support  auto
                request  sense on check conditions: 0 disables, 1
                enables.

          sector-size
                The target driver sets this capability to  inform
                the  HBA  of  the  granularity,  in bytes, of DMA
                breakup; the HBA's DMA limit  structure  will  be
                set     to     reflect     this     limit    (see
                ddi_dma_lim_sparc(9S) or ddi_dma_lim_x86(9S)). It
                should  be  set to the physical disk sector size.
                This capability defaults to 512.

          total-sectors
                The target driver sets this capability to  inform
                the  HBA  of  the  total number of sectors on the
                device, as returned from the  SCSI  get  capacity
                command.  This  capability must be set before the
                target driver ``gets'' the geometry capability.

          geometry
                This capability returns the  HBA  geometry  of  a
                target  disk.  The  target  driver  must  set 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
                this  target  disk, because (for example) the HBA
                BIOS supports Logical Block Addressing  for  this
                drive,  it  is  acceptable for scsi_ifgetcap() to
                return -1, indicating that the  geometry  is  not
                defined.  This  will cause failure of attempts to
                retreive the "virtual geometry" from  the  target
                driver (the DKIOCG_VIRTGEOM ioctl will fail). See
                dkio(7I)    for    more     information     about
                DKIOCG_VIRTGEOM.

          reset-notification
                The host  adapter's  capability  to  support  bus
                reset  notification: 0 disables, 1 enables. Refer
                to scsi_reset_notify(9F).

          linked -cmds
                The host adapter's capability to  support  linked
                commands: 0 disables, 1 enables.

          qfull-retries
                This capability enables/disables QUEUE FULL  han-
                dling.  If  0,  the  HBA will not retry a command
                when a QUEUE FULL status is returned. If  greater
                than  0,  then the HBA driver will retry the com-
                mand at specified number of times at an  interval
                determined  by  the  "qfull-retry-interval".  The
                range for qfull-retries is 0-255.

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

          lun-reset
                This capability is created with a value  of  zero
                by HBA drivers that support the RESET_LUN flag in
                their tran_reset(9E) routine. If it  exists,  its
                value can be set to 1 by target drivers that want
                to allow 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  the  HBA
                driver's  tran_reset()  routine.   If   lun-reset
                exists  and  has  a  value  of  1,  then  the HBA
                driver's tran_reset() routine can be called  with
                the RESET_LUN flag.


RETURN VALUES

     scsi_ifsetcap() 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.

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

          -1    If the capability was not defined.


CONTEXT

     These functions can be called from user  or  interrupt  con-
     text.


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;
     }


SEE ALSO

     tran_reset(9E), scsi_hba_lookup_capstr(9F),  scsi_reset(9F),
     scsi_reset_notify(9F),                ddi_dma_lim_sparc(9S),
     ddi_dma_lim_x86(9S), scsi_address(9S), scsi_arq_status(9S)

     Writing Device Drivers


Man(1) output converted with man2html