Driver Entry Points                            transetuppkt(9E)



NAME
     transetuppkt,   tranteardownpkt,   tranpktconstructor,
     tranpktdestructor - SCSI HBA packet allocation and deallo-
     cation

SYNOPSIS
     #include 

     struct scsipkt *prefixtransetuppkt(struct scsipkt *pkt,
          int (*callback) (caddrt), caddrt arg);


     void prefixtranteardownpkt(struct scsipkt *pkt);


     int prefixtranpktconstructor(struct scsipkt *pkt,
          scsihbatrant *tranp, int kmflags);


     void prefixtranpktdestructor(struct scsipkt *pkt,
          struct scsihbatrant *tranp);


INTERFACE LEVEL
     Solaris architecture specific (Solaris DI).

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


     flags       Flags for associating  DMA  resources  with  the
                 packet.


     callback    Pointer to either NULFUNC or SLEPFUNC.


     arg         Always NUL.


     kmflags     Either KMSLEP or KMNOSLEP.


DESCRIPTION
     The transetuppkt() and trandestroypkt() vectors  in  the
     scsihbatran(9S)   structure   are   alternatives   to  the
     traninitpkt() and trandestroypkt()  entry  points.  They
     are  initialized during the HBA driver's attach(9E) and they
     are used when a target driver  calls  scsiinitpkt(9F)  and
     scsidestroypkt(9F).





SunOS 5.11          Last change: 29 Jan 2009                    1






Driver Entry Points                            transetuppkt(9E)



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


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


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


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


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


     The pktcdblen 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:

     NULFUNC     Do not  wait  for  resources.  Return  a  NUL
                   pointer.


     SLEPFUNC    Wait indefinitely for resources.






SunOS 5.11          Last change: 29 Jan 2009                    2






Driver Entry Points                            transetuppkt(9E)



  tranteardownpkt()
     The tranteardownpkt() is the entry point into the HBA that
     must  free  all  of the resources that were allocated to the
     scsipkt(9S) structure during transetuppkt().

  tranpktconstructor() tranpktdestructor()
     When   using   tranpktsetup()   and   tranpktteardown(),
     tranpktconstructor()  and  tranpktdestructor() 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  scsipkt  structure  have  been
     initialized:

         o    pktaddress

         o    pkthaprivate

         o    pktcdbp

         o    pktprivate

         o    pktscbp

         o    pktcdblen

         o    pkttgtlen

         o    pktscblen


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


     HBA drivers  that  implement  transetuppkt()  must  signal
     scsipkt(9S)  completion  by  calling scsihbapktcomp(9F).
     Direct use of  the scsipkt pktcomp field is not  permitted
     and results in undefined behavior.

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

SEE ALSO
     attach(9E),         transyncpkt(9E),         bioerror(9F),
     ddidmabufbindhandle(9F),          kmemcachecreate(9F),
     scsiallocconsistentbuf(9F),         scsidestroypkt(9F),
     scsihbaattach(9F),                 scsihbapktalloc(9F),
     scsihbapktcomp(9F),                scsihbapktfree(9F),



SunOS 5.11          Last change: 29 Jan 2009                    3






Driver Entry Points                            transetuppkt(9E)



     scsiinitpkt(9F),         buf(9S),        scsiaddress(9S),
     scsihbatran(9S), scsipkt(9S)


     Writing Device Drivers


















































SunOS 5.11          Last change: 29 Jan 2009                    4