Kernel Functions for Drivers                    scsipktalloc(9F)



NAME
     scsipktalloc, scsiresalloc, scsipktfree,  scsiresfree  -
     SCSI packet utility routines

SYNOPSIS
     #include 

     struct scsipkt *scsipktalloc (struct scsiaddress* ap, int cmdlen,
          int statuslen, int (*callback)(void));


     struct scsipkt *scsiresalloc (struct scsiaddress* ap, int cmdlen,
          int statuslen, opaquet dmatoken, int (*callback)(void));


     void scsipktfree (struct scsipkt* pkt);


     void scsiresfree (struct scsipkt* pkt);


INTERFACE LEVEL
     The scsipktalloc(),  scsipktfree(),  scsiresalloc(),  and
     scsiresfree()  functions  are obsolete. The scsipktalloc()
     and  scsiresalloc()  functions  have   been   replaced   by
     scsiinitpkt(9F).  The  scsipktfree()  and  scsiresfree()
     functions have been replaced by scsidestroypkt(9F).

PARAMETERS
     ap           Pointer to a scsiaddress structure.


     cmdlen       The  required  length  for  the  SCSI   command
                  descriptor block (CDB) in bytes.


     statuslen    The required length for the SCSI status comple-
                  tion block (SCB) in bytes.


     dmatoken     Pointer to an implementation-dependent object.


     callback     A pointer to a callback function, or  NULFUNC
                  or SLEPFUNC.


     pkt          Pointer to a scsipkt(9S) structure.


DESCRIPTION




SunOS 5.11          Last change: 16 Jan 2006                    1






Kernel Functions for Drivers                    scsipktalloc(9F)



     The  scsipktalloc()  function  requests  the  host  adapter
     driver  to allocate a command packet. For commands that have
     a data transfer associated with them, scsiresalloc() should
     be used.


     ap is a pointer to a scsiaddress structure. Allocator  rou-
     tines use it to determine the associated host adapter.


     The cmdlen parameter is the required  length  for  the  SCSI
     command  descriptor block. This block is allocated such that
     a kernel virtual address  is  established  in  the  pktcdbp
     field of the allocated scsipkt structure.


     statuslen is the required length for the SCSI status comple-
     tion  block.  The  address  of the allocated block is placed
     into the pktscbp field of the scsipkt structure.


     The dmatoken parameter is a  pointer  to  an  implementation
     dependent  object  which  defines the length, direction, and
     address of the  data  transfer  associated  with  this  SCSI
     packet  (command).  The  dmatoken  must  be  a  pointer to a
     buf(9S) structure. If dmatoken is NUL, no DMA resources are
     required  by  this SCSI command, so none are allocated. Only
     one transfer direction is allowed per command. If  there  is
     an  unexpected  data transfer phase (either no data transfer
     phase expected, or the  wrong  direction  encountered),  the
     command   is   terminated   with   the   pktreason  set  to
     CMDMADER. dmatoken provides the information to determine
     if the transfer count is correct.


     callback 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.


     Other Values    callback  points  to  a  function  which  is
                     called when resources may have become avail-
                     able. callback must return either  0  (indi-
                     cating   that   it   attempted  to  allocate
                     resources but again failed  to  do  so),  in
                     which  case  it  is put back on a list to be
                     called again later, or 1  indicating  either



SunOS 5.11          Last change: 16 Jan 2006                    2






Kernel Functions for Drivers                    scsipktalloc(9F)



                     success  in allocating resources or indicat-
                     ing that it no longer cares for a retry.



     The scsipktfree() function frees the packet.


     The scsiresfree() function free all resources held  by  the
     packet and the packet itself.

RETURN VALUES
     Both allocation routines return  a  pointer  to  a  scsipkt
     structure on success, or NUL on failure.

CONTEXT
     If callback is SLEPFUNC, then this routine can  be  called
     only  from  user  or  kernel  context.  Otherwise, it can be
     called from user, kernel, or interrupt context. The callback
     function  may  not  block  or call routines that block. Both
     deallocation routines can be called from  user,  kernel,  or
     interrupt context.

ATRIBUTES
     See attributes(5) for a description of the following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Stability Level              Obsolete                    
    


SEE ALSO
     attributes(5), scsidmafree(9F),  scsidmaget(9F),  buf(9S),
     scsipkt(9S)


     Writing Device Drivers

NOTES
     The scsipktalloc(),  scsipktfree(),  scsiresalloc(),  and
     scsiresfree() functions are obsolete and will be discontin-
     ued  in  a   future   release.   The   scsipktalloc()   and
     scsiresalloc()    functions    have    been   replaced   by
     scsiinitpkt(9F).  The  scsipktfree()  and  scsiresfree()
     functions have been replaced by scsidestroypkt(9F).





SunOS 5.11          Last change: 16 Jan 2006                    3