Manual Pages for UNIX Operating System command usage for man usb_print_descr_tree

Kernel Functions for Drivers                 usb_get_dev_data(9F)



NAME
     usb_get_dev_data,  usb_free_dev_data,   usb_free_descr_tree,
     usb_print_descr_tree  - Retrieve device configuration infor-
     mation

SYNOPSIS
     #include 

     int usb_get_dev_data(dev_info_t *dip, usb_client_dev_data_t **dev_data,
          usb_reg_parse_lvl_t parse_level, usb_flags_t flags);


     void usb_free_dev_data(dev_info_t *dip, usb_client_dev_data_t *dev_data);


     void usb_free_descr_tree(dev_info_t *dip, usb_client_dev_data_t *dev_data);


     int usb_print_descr_tree(dev_info_t *dip, usb_client_dev_data_t *dev_data);


INTERFACE LEVEL
     Solaris DDI specific (Solaris DDI)

PARAMETERS
     For usb_get_dev_data():

     dip            Pointer to device's dev_info structure.


     dev_data       Address in which pointer to info is returned.


     parse_level    Portion of device represented in the tree  of
                    parsed  descriptors.  See  below for possible
                    usb_reg_parse_lvl_t values and explanations.


     flags          Not used.



     For usb_free_dev_data():

     dip         Pointer to device's dev_info structure.


     dev_data    Pointer to usb_client_dev_data_t to be freed.







SunOS 5.11           Last change: 5 Jan 2004                    1






Kernel Functions for Drivers                 usb_get_dev_data(9F)



     For usb_free_descr_tree():

     dip         Pointer to device's dev_info structure.


     dev_data    Pointer to usb_client_dev_data_t containing  the
                 descriptor tree to free.



     For usb_print_descr_tree():

     dip         Pointer to device's dev_info structure.


     dev_data    Pointer to usb_client_dev_data_t containing  the
                 descriptor tree to display on-screen.


DESCRIPTION
     The usb_get_dev_data() function interrogates  a  device  and
     returns     its     configuration     information    in    a
     usb_client_dev_data_t structure. Most USBA functions require
     information  which  comes  from a usb_client_dev_data_t, and
     all other functions in this man page operate on this  struc-
     ture.  Please see usb_client_dev_data(9S) for a full content
     description. Pass  the  usb_client_dev_data_t  structure  to
     usb_client_detach(9F) to completely deallocate it.


     A descriptor tree is included in the  information  returned.
     The  usb_reg_parse_lvl_t  type  represents the extent of the
     device to be     represented by the returned tree  (2nd  arg
     to  usb_get_dev_data) or what is actually represented in the
     returned  tree  (dev_parse_level  field  of   the   returned
     usb_client_dev_data_t).   It   has  the  following  possible
     values:

     USB_PARSE_LVL_NONE    Build no tree. dev_n_cfg   returns  0,
                           dev_cfg and dev_curr_cfg  are returned
                           NULL, and  the dev_curr_xxx fields are
                           invalid.


     USB_PARSE_LVL_IF      If configuration number and  interface
                           properties  are set (as when different
                           interfaces are viewed  by  the  OS  as
                           different   device  instances),  parse
                           configured interface only.  If  an  OS
                           device instance is set up to represent
                           an     entire     physical     device,
                           USB_PARSE_LVL_IF       works      like



SunOS 5.11           Last change: 5 Jan 2004                    2






Kernel Functions for Drivers                 usb_get_dev_data(9F)



                           USB_PARSE_LVL_ALL.


     USB_PARSE_LVL_CFG     Parse entire configuration of  config-
                           ured interface only. Behaves similarly
                           to   USB_PARSE_LVL_IF,   except   that
                           entire configuration is returned.


     USB_PARSE_LVL_ALL     Parse entire  device  (all  configura-
                           tions), even when driver is bound to a
                           single interface of  a  single  confi-
                           guration.



     The     usb_free_dev_data()     function     undoes     what
     usb_get_dev_data()  set  up.   It  releases  memory  for all
     strings,    descriptors,    and    trees    set    up     by
     usb_get_dev_data().


     The usb_free_descr_tree() function frees the descriptor tree
     of  its  usb_client_dev_data_t  argument,  while leaving the
     rest of the information intact. The intent is for drivers to
     free memory after copying needed descriptor information from
     the tree. Upon return, the  following  usb_client_dev_data_t
     fields   are modified as follows: dev_cfg is NULL, dev_n_cfg
     is zero and dev_parse_level   is  USB_PARSE_LVL_NONE.  Addi-
     tionally, dev_curr_cfg is NULL and dev_curr_if is invalid.


     The usb_print_descr_tree() function is an easy-to-use  diag-
     nostic  aid  which  dumps  the descriptor tree to the screen
     when the system is  verbose  booted  (boot  -v).  Output  is
     spaced  with  blank  lines  for readability and provides you
     with an on-screen look at what a device has to offer.

RETURN VALUES
     For usb_get_dev_data():

     USB_SUCCESS            Registration is successful.


     USB_INVALID_ARGS       dip or dev_data is NULL.  parse_level
                            is invalid.


     USB_INVALID_CONTEXT    Called from interrupt context.






SunOS 5.11           Last change: 5 Jan 2004                    3






Kernel Functions for Drivers                 usb_get_dev_data(9F)



     USB_INVALID_VERSION    usb_client_attach(9F) was not  called
                            first.


     USB_FAILURE            Bad descriptor info or other internal
                            error.



     For usb_free_dev_data(): None


     For usb_free_descr_tree(): None, but no operation occurs  if
     dip and/or dev_data are NULL.


     For usb_print_descr_tree():

     USB_SUCCESS            Descriptor tree dump is successful.


     USB_INVALID_ARGS       dev_data or dip are NULL.


     USB_INVALID_CONTEXT    Called from interrupt context.


     USB_FAILURE            Other error.


CONTEXT
     The usb_get_dev_data() and usb_print_descr_tree()  functions
     may be called from user or kernel context.


     The usb_free_dev_data() and usb_free_descr_tree()  functions
     may be called from user, kernel or interrupt context.

EXAMPLES
       In this example, assume a device has the configuration shown
       below, and the endpoint of config 2, iface 1, alt 1
       which supports intr IN transfers needs to be found.
       Config 2, iface 1 is the "default" config/iface for the
       current OS device node.

             config 1
                 iface 0
                     endpt 0
             config 2
                 iface 0
                 iface 1
                     alt 0



SunOS 5.11           Last change: 5 Jan 2004                    4






Kernel Functions for Drivers                 usb_get_dev_data(9F)



                         endpt 0
                             cv 0
                     alt 1
                         endpt 0
                         endpt 1
                             cv 0
                         endpt 2
                     alt 2
                         endpt 0
                             cv 0

             usb_client_dev_data_t *dev_data;
             usb_ep_descr_t ep_descr;
             usb_ep_data_t *ep_tree_node;
             uint8_t interface = 1;
             uint8_t alternate = 1;
             uint8_t first_ep_number = 0;

             /*
              * We want default config/iface, so specify USB__PARSE_LVL_IF.
              * Default config will be returned as dev_cfg[0].
             /
               if (usb_get_dev_data(dip, &dev_data,
                 USB_PARSE_LVL_IF, 0) != USB_SUCCESS) {
                     cmn_err (CE_WARN,
                         "%s%d: Couldn't get USB configuration descr tree",
                         ddi_driver_name(dip), ddi_get_instance(dip));

                     return (USB_FAILURE);
             }

             ep_tree_node = usb_lookup_ep_data(dip, dev_data, interface,
                  alternate, first_ep_number, USB_EP_ATTR_INTR, USB_EP_DIR_IN);
             if (ep_tree_node != NULL) {
                 ep_descr = ep_tree_node->ep_descr;
             } else {
                     cmn_r (CE_WARN,
                         "%s%d: Device is missing intr-IN endpoint",
                         ddi_driver_name(dip), ddi_get_instance(dip));

                     usb_free_descr_tree(dip, &dev_data);

                     return (USB_FAILURE);
             }



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





SunOS 5.11           Last change: 5 Jan 2004                    5






Kernel Functions for Drivers                 usb_get_dev_data(9F)



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


SEE ALSO
     attributes(5),  usb_client_attach(9F),   usb_get_alt_if(9F),
     usb_get_cfg(9F),                   usb_get_string_descr(9F),
     usb_lookup_ep_data(9F),                  usb_parse_data(9F),
     usb_pipe_open(9F),                        usb_cfg_descr(9S),
     usb_client_dev_data(9S), usb_ep_descr(9S), usb_if_descr(9S),
     usb_string_descr(9S)





































SunOS 5.11           Last change: 5 Jan 2004                    6