Kernel Functions for Drivers                usballocrequest(9F)



NAME
     usballocrequest,  usballocctrlreq,   usbfreectrlreq,
     usballocbulkreq,  usbfreebulkreq,  usballocintrreq,
     usbfreeintrreq, usballocisocreq,  usbfreeisocreq  -
     Allocate and free USB transfer requests

SYNOPSIS
     #include 

     usbctrlreqt *usballocctrlreq(devinfot *dip, sizet len,
          usbflagst flags);


     void usbfreectrlreq(usbctrlreqt *request);


     usbbulkreqt *usballocbulkreq(devinfot dip, sizet len,
          usbflagst flags);


     void usbfreebulkreq(usbbulkreqt *request);


     usbintrreqt *usballocintrreq(devinfot *dip, sizet len,
          usbflagst flags);


     void usbfreeintrreq(usbintrreqt *request);


     usbisocreqt *usballocisocreq(devinfot *dip,
          uintt isocpktscount, sizet len, usbflagst flags);


     void usbfreeisocreq(usbisocreqt *request);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI)

PARAMETERS
     For    usballocctrlreq(),    usballocbulkreq()     and
     usballocintrreq():

     dip      Pointer to the device's devinfo structure.


     len      Length of data for this request.


     flags    Only  USBFLAGSLEP  is  recognized.   Wait   for
              resources if not immediately available.



SunOS 5.11          Last change: 25 July 2004                   1






Kernel Functions for Drivers                usballocrequest(9F)



     For usballocisocreq():

     dip                Pointer to the device's  devinfo  struc-
                        ture.


     isocpktscount    Number of isochronous packet  descriptors
                        to  associate  with this request. Must be
                        greater than zero.


     len                Length  of  data  for  this   isochronous
                        request.


     flags              Only USBFLAGSLEP is recognized.  Wait
                        for  resources  if not immediately avail-
                        able.



     For        usbfreectrlreq(),         usbfreebulkreq(),
     usbfreeintrreq() and usbfreeisocreq():

     request    Pointer to the request structure to be freed. Can
                be NUL.


DESCRIPTION
     The       usballocctrlreq(),        usballocbulkreq(),
     usballocintrreq(),   and  usballocisocreq()  functions
     allocate  control,  bulk,  interrupt,   or       isochronous
     requests.  Optionally,  these functions can also allocate an
     mblk of the specified length to pass data  associated   with
     the  request.  (For  guidelines on mblk data allocation, see
     the manpage for the relevant transfer function).


     The usballocisocreq() function also allocates a number of
     isochronous packet descriptors (usbisocpktdescrt) speci-
     fied by isocpktscount to the end  of  the  request  proper
     (usbisocreqt).   See usbisocrequest(9S) for more infor-
     mation on isochronous packet descriptors.


     These functions always succeed when the USBFLAGSLEP flag
     is  set, provided that they are given valid args and are not
     called from interrupt context.


     The        usbfreectrlreq(),         usbfreebulkreq(),
     usbfreeintrreq(),  and usbfreeisocreq() functions free



SunOS 5.11          Last change: 25 July 2004                   2






Kernel Functions for Drivers                usballocrequest(9F)



     their corresponding request. If  the  request's  data  block
     pointer  is non-zero, the data block is also freed. For isoc
     requests, the array of packet descriptors is freed.

RETURN VALUES
     For       usballocctrlreq(),        usballocbulkreq(),
     usballocintrreq() and usballocisocreq():


     On  success:  returns   a   pointer   to   the   appropriate
     usbxxxrequestt.


     On failure: returns NUL. Fails because the dip argument  is
     invalid, USBFLAGSLEP is not set and memory is not avail-
     able or because USBFLAGSLEP is set but the call was made
     in interrupt context.


     For        usbfreectrlreq(),         usbfreebulkreq(),
     usbfreeintrreq() and usbfreeisocreq(): None.

CONTEXT
     The allocation routines can always be called from kernel and
     user context. They may be called from interrupt context only
     if USBFLAGSLEP is not specified.


     The free routines may  be  called  from  kernel,  user,  and
     interrupt context.

EXAMPLES
           /* This allocates and initializes an asynchronous control
            * request which will pass no data.  Asynchronous requests
            * are used when they cannot block the calling thread.
            */

           usbctrlreqt *ctrlreq;

           if ((ctrlreq = usballocctrlreq(dip, 0, 0)) == NUL) {
                   return (FAILURE);
           }

           /* Now initialize. */
           ctrlreq->ctrlbmRequestType = USBDEVREQDEVTOHOST 
               USBDEVREQSTANDARD  USBDEVREQRCPTDEV;

           ctrlreq->ctrlbRequest      = (uint8t)USBREQGETSTATUS;
           ...
           ...
           ctrlreq->ctrlcallback     = normalcallback;
           ctrlreq->ctrlexccallback = exceptioncallback;



SunOS 5.11          Last change: 25 July 2004                   3






Kernel Functions for Drivers                usballocrequest(9F)



           ...
           ...



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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Architecture                 PCI-based systems           
    
     Interface stability          Committed                   
    
     Availability                 SUNWusb                     
    


SEE ALSO
     attributes(5),             usbgetcurrentframenumber(9F),
     usbgetmaxpktsperisocrequest(9F),
     usbpipegetmaxbulktransfersize(9F),
     usbpipebulkxfer(9F),              usbpipectrlxfer(9F),
     usbpipeintrxfer(9F),              usbpipeisocxfer(9F),
     usbbulkrequest(9S),                  usbctrlrequest(9S),
     usbintrrequest(9S), usbisocrequest(9S)

























SunOS 5.11          Last change: 25 July 2004                   4