Manual Pages for UNIX Operating System command usage for man usb_get_cfg

Kernel Functions for Drivers                      usb_get_cfg(9F)



NAME
     usb_get_cfg, usb_set_cfg - Get and set  current  USB  device
     configuration

SYNOPSIS
     #include 

     int usb_get_cfg(dev_info_t *dip, uint_t cfgval, usb_flags_t flags);


     int usb_set_cfg(dev_info_t *dip, uint_t cfg_index, usb_flags_t flags,
          void (*callback)(usb_pipe_handle_t pipe_handle, usb_opaque_t
          callback_arg, int  rval, usb_cb_flags_t flags), usb_opaque_t
          callback_arg);


INTERFACE LEVEL
     Solaris DDI specific (Solaris DDI)

PARAMETERS
     For usb_get_cfg():

     dip       Pointer to device's dev_info structure.


     cfgval    Pointer to returned configuration value.


     flags     Not used.  Always waits for completion.



     For usb_set_cfg():

     dip             Pointer to device's dev_info structure.


     cfg_index       Desired device configuration index.  Set  to
                     USB_DEV_DEFAULT_CONFIG_INDEX    to   restore
                     default configuration.


     flags           Only USB_FLAGS_SLEEP is recognized. Wait for
                     completion and do not call callback.


     callback        Callback handler to notify  of  asynchronous
                     completion.


     callback_arg    Second argument passed to callback handler.




SunOS 5.11           Last change: 5 Jan 2004                    1






Kernel Functions for Drivers                      usb_get_cfg(9F)



DESCRIPTION
     The usb_get_cfg() function retrieves the current  configura-
     tion.  It ignores the flags argument and always blocks while
     contacting the device.


     The usb_set_cfg() function sets a new configuration. Because
     this call changes the device's mode of operation, the device
     must be quiescent and have all pipes, with the exception  of
     the  default control pipe, closed. The driver must have con-
     trol over the entire device and cannot  own  just  a  single
     interface  on  a  composite device. Additionally, its device
     node must not be a parent to other device nodes that can  be
     operated  by  other  drivers. The driver must own the device
     exclusively, otherwise drivers managing other parts  of  the
     device would be affected without their knowledge or control.


     This call updates all internal USBA  framework  data  struc-
     tures,  whereas issuing a raw USB_REQ_SET_CFG device request
     does not.  The usb_set_cfg() function is the only  supported
     programmatic way to change device configuration.


     This call blocks if USB_FLAGS_SLEEP is  set  in  flags.   It
     returns  immediately and calls the callback on completion if
     USB_FLAGS_SLEEP is not set.

RETURN VALUES
     For usb_get_cfg():

     USB_SUCCESS         New configuration is retrieved.


     USB_INVALID_ARGS    cfgval or dip is NULL.


     USB_FAILURE         Configuration cannot be retrieved.



     For usb_set_cfg():

     USB_SUCCESS            New configuration is set.


     USB_INVALID_ARGS       dip is NULL.

                            USB_FLAGS_SLEEP is clear and callback
                            is NULL.





SunOS 5.11           Last change: 5 Jan 2004                    2






Kernel Functions for Drivers                      usb_get_cfg(9F)



     USB_INVALID_CONTEXT    Called from  interrupt  context  with
                            USB_FLAGS_SLEEP specified.


     USB_INVALID_PERM       Caller does not own entire device  or
                            device is a parent to child devices.


     USB_BUSY               One or  more  pipes  other  than  the
                            default  control pipe are open on the
                            device.


     USB_INVALID_PIPE       Pipe handle is NULL  or  invalid,  or
                            pipe is closing or closed.


     USB_FAILURE            An illegal  configuration  is  speci-
                            fied.

                            One or  more  pipes  other  than  the
                            default  control pipe are open on the
                            device.


CONTEXT
     The usb_get_cfg() function may be called from user or kernel
     context.


     The usb_set_cfg() function may be called from user or kernel
     context always. It may be called from interrupt context only
     if USB_FLAGS_SLEEP is not set in flags.


     If   the   USB_CB_ASYNC_REQ_FAILED   bit   is    clear    in
     usb_cb_flags_t, the callback, if supplied, can block because
     it is executing in kernel context.  Otherwise  the  callback
     cannot  block.  Please  see  usb_callback_flags(9S) for more
     information on callbacks.

EXAMPLES
        Setting the configuration to the one at index 1 (in the
         array of usb_cfg_data_t configuration nodes as returned
         by usb_get_dev_data()), and verifying what the configuration
         is at that index. (See usb_get_dev_data(9F)).

         uint_t cfg_index = 1;

         /*
          * Assume all pipes other than the default control pipe
          * are closed and make sure all requests to the default



SunOS 5.11           Last change: 5 Jan 2004                    3






Kernel Functions for Drivers                      usb_get_cfg(9F)



          * control pipe have completed. /
          */


         if (usb_set_cfg(dip, cfg_index, USB_FLAGS_SLEEP, NULL, 0)
                 != USB_SUCCESS) {
                 cmn_err (CE_WARN,
                     "%s%d: Error setting USB device to configuration #%d",
                     ddi_driver_name(dip), ddi_get_instance(dip), cfg_index);
         }

         if (usb_get_cfg(dip, &bConfigurationValue, 0) == USB_SUCCESS) {
                 cmn_err (CE_WARN, "%s%d: USB device active configuration is %d",
                     ddi_driver_name(dip), ddi_get_instance(dip),
                     bConfigurationValue);
         } else {
                 ...
                 ...
         }



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_alt_if(9F),   usb_get_dev_data(9F),
     usb_get_string_descr(9F),                 usb_pipe_open(9F),
     usb_callback_flags(9S), usb_cfg_descr(9S), usb_ep_descr(9S),
     usb_if_descr(9S)











SunOS 5.11           Last change: 5 Jan 2004                    4