usb_get_dev_data(9F) 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 information
SYNOPSIS
#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);
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.
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
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 rep-
resented 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 dif-
ferent 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 USB_PARSE_LVL_ALL.
USB_PARSE_LVL_CFG Parse entire configuration of configured interface only. Behaves similarly to USB_PARSE_LVL_IF, except that entire
configuration is returned.
USB_PARSE_LVL_ALL Parse entire device (all configurations), even when driver is bound to a single interface of a single configuration.
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 informa-
tion 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 ver-
bose 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.
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
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 attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Architecture |PCI-based systems |
+-----------------------------+-----------------------------+
|Interface stability |Committed |
+-----------------------------+-----------------------------+
|Availability |SUNWusb |
+-----------------------------+-----------------------------+
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 5 Jan 2004 usb_get_dev_data(9F)