Manual Pages for UNIX Operating System command usage for man usb_alloc_request

Kernel Functions for Drivers                usb_alloc_request(9F)



NAME
     usb_alloc_request,  usb_alloc_ctrl_req,   usb_free_ctrl_req,
     usb_alloc_bulk_req,  usb_free_bulk_req,  usb_alloc_intr_req,
     usb_free_intr_req, usb_alloc_isoc_req,  usb_free_isoc_req  -
     Allocate and free USB transfer requests

SYNOPSIS
     #include 

     usb_ctrl_req_t *usb_alloc_ctrl_req(dev_info_t *dip, size_t len,
          usb_flags_t flags);


     void usb_free_ctrl_req(usb_ctrl_req_t *request);


     usb_bulk_req_t *usb_alloc_bulk_req(dev_info_t dip, size_t len,
          usb_flags_t flags);


     void usb_free_bulk_req(usb_bulk_req_t *request);


     usb_intr_req_t *usb_alloc_intr_req(dev_info_t *dip, size_t len,
          usb_flags_t flags);


     void usb_free_intr_req(usb_intr_req_t *request);


     usb_isoc_req_t *usb_alloc_isoc_req(dev_info_t *dip,
          uint_t isoc_pkts_count, size_t len, usb_flags_t flags);


     void usb_free_isoc_req(usb_isoc_req_t *request);


INTERFACE LEVEL
     Solaris DDI specific (Solaris DDI)

PARAMETERS
     For    usb_alloc_ctrl_req(),    usb_alloc_bulk_req()     and
     usb_alloc_intr_req():

     dip      Pointer to the device's dev_info structure.


     len      Length of data for this request.


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



SunOS 5.11          Last change: 25 July 2004                   1






Kernel Functions for Drivers                usb_alloc_request(9F)



     For usb_alloc_isoc_req():

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


     isoc_pkts_count    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 USB_FLAGS_SLEEP is recognized.  Wait
                        for  resources  if not immediately avail-
                        able.



     For        usb_free_ctrl_req(),         usb_free_bulk_req(),
     usb_free_intr_req() and usb_free_isoc_req():

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


DESCRIPTION
     The       usb_alloc_ctrl_req(),        usb_alloc_bulk_req(),
     usb_alloc_intr_req(),   and  usb_alloc_isoc_req()  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 usb_alloc_isoc_req() function also allocates a number of
     isochronous packet descriptors (usb_isoc_pkt_descr_t) speci-
     fied by isoc_pkts_count to the end  of  the  request  proper
     (usb_isoc_req_t).   See usb_isoc_request(9S) for more infor-
     mation on isochronous packet descriptors.


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


     The        usb_free_ctrl_req(),         usb_free_bulk_req(),
     usb_free_intr_req(),  and usb_free_isoc_req() functions free



SunOS 5.11          Last change: 25 July 2004                   2






Kernel Functions for Drivers                usb_alloc_request(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       usb_alloc_ctrl_req(),        usb_alloc_bulk_req(),
     usb_alloc_intr_req() and usb_alloc_isoc_req():


     On  success:  returns   a   pointer   to   the   appropriate
     usb_xxx_request_t.


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


     For        usb_free_ctrl_req(),         usb_free_bulk_req(),
     usb_free_intr_req() and usb_free_isoc_req(): None.

CONTEXT
     The allocation routines can always be called from kernel and
     user context. They may be called from interrupt context only
     if USB_FLAGS_SLEEP 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.
            */

           usb_ctrl_req_t *ctrl_req;

           if ((ctrl_req = usb_alloc_ctrl_req(dip, 0, 0)) == NULL) {
                   return (FAILURE);
           }

           /* Now initialize. */
           ctrl_req->ctrl_bmRequestType = USB_DEV_REQ_DEV_TO_HOST |
               USB_DEV_REQ_STANDARD | USB_DEV_REQ_RCPT_DEV;

           ctrl_req->ctrl_bRequest      = (uint8_t)USB_REQ_GET_STATUS;
           ...
           ...
           ctrl_req->ctrl_callback     = normal_callback;
           ctrl_req->ctrl_exc_callback = exception_callback;



SunOS 5.11          Last change: 25 July 2004                   3






Kernel Functions for Drivers                usb_alloc_request(9F)



           ...
           ...



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



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Architecture                | PCI-based systems           |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | Availability                | driver/usb                  |
    |_____________________________|_____________________________|


SEE ALSO
     attributes(5),             usb_get_current_frame_number(9F),
     usb_get_max_pkts_per_isoc_request(9F),
     usb_pipe_get_max_bulk_transfer_size(9F),
     usb_pipe_bulk_xfer(9F),              usb_pipe_ctrl_xfer(9F),
     usb_pipe_intr_xfer(9F),              usb_pipe_isoc_xfer(9F),
     usb_bulk_request(9S),                  usb_ctrl_request(9S),
     usb_intr_request(9S), usb_isoc_request(9S)

























SunOS 5.11          Last change: 25 July 2004                   4