Manual Pages for UNIX Operating System command usage for man tran_setup_pkt

Driver Entry Points                            tran_setup_pkt(9E)



NAME
     tran_setup_pkt,   tran_teardown_pkt,   tran_pkt_constructor,
     tran_pkt_destructor - SCSI HBA packet allocation and deallo-
     cation

SYNOPSIS
     #include 

     struct scsi_pkt *prefix_tran_setup_pkt(struct scsi_pkt *pkt,
          int (*callback) (caddr_t), caddr_t arg);


     void prefix_tran_teardown_pkt(struct scsi_pkt *pkt);


     int prefix_tran_pkt_constructor(struct scsi_pkt *pkt,
          scsi_hba_tran_t *tranp, int kmflags);


     void prefix_tran_pkt_destructor(struct scsi_pkt *pkt,
          struct scsi_hba_tran_t *tranp);


INTERFACE LEVEL
     Solaris architecture specific (Solaris DDI).

PARAMETERS
     pkt         Pointer to the scsi_pkt(9S) structure.


     flags       Flags for associating  DMA  resources  with  the
                 packet.


     callback    Pointer to either NULL_FUNC or SLEEP_FUNC.


     arg         Always NULL.


     kmflags     Either KM_SLEEP or KM_NOSLEEP.


DESCRIPTION
     The tran_setup_pkt() and tran_destroy_pkt() vectors  in  the
     scsi_hba_tran(9S)   structure   are   alternatives   to  the
     tran_init_pkt() and tran_destroy_pkt()  entry  points.  They
     are  initialized during the HBA driver's attach(9E) and they
     are used when a target driver  calls  scsi_init_pkt(9F)  and
     scsi_destroy_pkt(9F).





SunOS 5.11          Last change: 29 Jan 2009                    1






Driver Entry Points                            tran_setup_pkt(9E)



  tran_setup_pkt()
     The tran_setup_pkt() vector is the entry point into the  HBA
     which  is  used  to initialize HBA specific information in a
     scsi_pkt structure on behalf of a SCSI  target  driver.  All
     fields documented in scsi_pkt(9S) are initialized.


     If the HBA  driver  chose  not  to  preallocate  memory  for
     pkt_cdbp  and/or  pkt_scbp,  it  must allocate the requested
     memory at this time and point pkt_cdbp and pkt_scbp  to  the
     allocated memory.


     An HBA driver which provides a  tran_setup_pkt  entry  point
     inspects   the  pkt_numcookies  and  pkt_cookies  fields  at
     tran_start time to set up the transfer. If pkt_numcookies is
     zero,  there  are  no  DMA  resources  associated  with this
     packet. If pkt_numcookies is  not  zero,  it  indicates  the
     number of DMA cookies that pkt_cookies points to.


     The pkt_tgtlen field  contains  the  length  of  the  packet
     private  area pointed to by pkt_private, allocated on behalf
     of the SCSI target driver.


     The pkt_scblen field contains the length of the SCSI  status
     completion  block  pointed  to  by  pkt_scbp.  If the status
     length  is  greater  than  or  equal   to   sizeof   (struct
     scsi_arq_status)  and  the  auto_rqsensecapability  has been
     set, automatic request  sense  (ARS)  is  enabled  for  this
     packet.   If   the   status  lengthislessthansizeof  (struct
     scsi_arq_status), automatic request sense should be disabled
     for  this  pkt if the HBA driver is capable of disabling ARQ
     on a per-packet basis.


     The pkt_cdblen field contains the length of the SCSI command
     descriptor block.


     The callback argument indicates what the allocator  routines
     should do when resources are not available:

     NULL_FUNC     Do not  wait  for  resources.  Return  a  NULL
                   pointer.


     SLEEP_FUNC    Wait indefinitely for resources.






SunOS 5.11          Last change: 29 Jan 2009                    2






Driver Entry Points                            tran_setup_pkt(9E)



  tran_teardown_pkt()
     The tran_teardown_pkt() is the entry point into the HBA that
     must  free  all  of the resources that were allocated to the
     scsi_pkt(9S) structure during tran_setup_pkt().

  tran_pkt_constructor() tran_pkt_destructor()
     When   using   tran_pkt_setup()   and   tran_pkt_teardown(),
     tran_pkt_constructor()  and  tran_pkt_destructor() are addi-
     tional optional entry points that perform the actions  of  a
     constructor  and destructor. The constructor is called after
     the following fields in the  scsi_pkt  structure  have  been
     initialized:

         o    pkt_address

         o    pkt_ha_private

         o    pkt_cdbp

         o    pkt_private

         o    pkt_scbp

         o    pkt_cdblen

         o    pkt_tgtlen

         o    pkt_scblen


     Allocating and freeing a DMA handle are  examples  of  some-
     thing  that could be done in the constructor and destructor.
     See kmem_cache_create(9F)  for  additional  restrictions  on
     what  actions can be performed in a constructor and destruc-
     tor.


     HBA drivers  that  implement  tran_setup_pkt()  must  signal
     scsi_pkt(9S)  completion  by  calling scsi_hba_pkt_comp(9F).
     Direct use of  the scsi_pkt pkt_comp field is not  permitted
     and results in undefined behavior.

RETURN VALUES
     tran_setup_pkt() must return zero  on  success,  and  -1  on
     failure.

SEE ALSO
     attach(9E),         tran_sync_pkt(9E),         bioerror(9F),
     ddi_dma_buf_bind_handle(9F),          kmem_cache_create(9F),
     scsi_alloc_consistent_buf(9F),         scsi_destroy_pkt(9F),
     scsi_hba_attach(9F),                 scsi_hba_pkt_alloc(9F),
     scsi_hba_pkt_comp(9F),                scsi_hba_pkt_free(9F),



SunOS 5.11          Last change: 29 Jan 2009                    3






Driver Entry Points                            tran_setup_pkt(9E)



     scsi_init_pkt(9F),         buf(9S),        scsi_address(9S),
     scsi_hba_tran(9S), scsi_pkt(9S)


     Writing Device Drivers


















































SunOS 5.11          Last change: 29 Jan 2009                    4