scsi_alloc(D3X)

NAME
     scsi_alloc - allocate communication channel to host adapter driver

SYNOPSIS
     #include <sys/types.h>
     #include <sys/scsi.h>

     int
     (*scsi_alloc)( vertex_hdl_t lun_vhdl,
                      int option,
                      void (*callback_function)(vertex_hdl_t, char *));

DESCRIPTION
     A kernel level SCSI device driver calls the host adapter scsi_alloc
     function to initialize a communication connection between itself and a
     host adapter driver, in preparation for issuing SCSI commands.

     There is no kernel object called scsi_alloc; rather, there is a pointer
     to each host adapter's scsi_alloc function in the sci_alloc field of the
     scsi_ctlr_info structure, which is attached to the vertex corresponding
     to the host adapter.

     The lun_vhdl argument specifies the hwgraph vertex for the device.  The
     option argument currently has two fields:

     o   SCSIALLOC_EXCLUSIVE indicates that the driver needs exclusive use
         with the device.

     o   SCSIALLOC_QDEPTH is an 8-bit mask specifying the maximum number of
         commands that the device driver will want to queue.  It is advisory
         only and may be ignored by the host adapter driver.

     The callback_function may be useful for drivers that don't use the
     SCSIALLOC_EXCLUSIVE option.  When callback_function is NULL, it is
     ignored.  When non-NULL, it specifies a function to call whenever there
     is sense data from device.  It can be useful when more than one device
     driver will talk to a SCSI device, but one of the drivers needs to know
     about things like media removals.  Only one device driver may specify a
     callback_function for a given device.  The callback function is called
     with two arguments, the vertex handle corresponding to the SCSI lun and
     the sense data.  The vertex handle allows a driver to know which device
     the callback pertains to.

DIAGNOSTICS
     scsi_alloc returns 0 if a communication connection could not be
     established, or if the arguments are invalid, or if the device was
     already allocated in exclusive use mode, or if this request was for
     exclusive use and the device is already allocated (including possibly
     earlier requests by the same driver).  Otherwise, it returns a positive
     value.
NOTES
     scsi_alloc is stored as a function pointer in the scsi_ctlr_info_t
     structure, which is associated with the scsi host adapter vertex in the
     hwgraph.  The information structure in the scsi target vertex also has a
     pointer to the scsi_ctlr_info_t of the host adapter that the target is
     connected to.  Given a lun_vhdl (vertex handle of the device) the
     scsi_alloc function can be called as follows:

              scsi_lun_info_t *scsi_lun_info;
            ...
              scsi_lun_info = scsi_lun_info_get(lun_vhdl);
              SLI_ALLOC(scsi_lun_info)(lun_vhdl,option,callback_function);


SEE ALSO
     comments in /usr/include/sys/scsi.h, hwgraph.intro(D4X), scsi_free(D3X),
     scsi_info(D3X), scsi_command(D3X), scsi_ioctl(D3X), scsi_abort(D3X), SCSI
     chapter of the IRIX Device Driver Programmer's Guide.