te
Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
usb_get_dev_data, usb_free_dev_data, usb_free_descr_tree, usb_print_descr_tree - Retrieve device configuration information

#include <sys/usb/usba.h>



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);

Solaris DDI specific (Solaris DDI)

For usb_get_dev_data():

dip

dev_data

parse_level

flags

For usb_free_dev_data():

dip

dev_data

For usb_free_descr_tree():

dip

dev_data

For usb_print_descr_tree():

dip

dev_data

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

USB_PARSE_LVL_IF

USB_PARSE_LVL_CFG

USB_PARSE_LVL_ALL

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. Additionally, dev_curr_cfg is NULL and dev_curr_if is invalid.

The usb_print_descr_tree() function is an easy-to-use diagnostic 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.

For usb_get_dev_data():

USB_SUCCESS

USB_INVALID_ARGS

USB_INVALID_CONTEXT

USB_INVALID_VERSION

USB_FAILURE

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

USB_INVALID_ARGS

USB_INVALID_CONTEXT

USB_FAILURE

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.

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
 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);
 }
 

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Architecture	PCI-based systems
Interface stability	Committed

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)