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 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 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 |Evolving |
+-----------------------------+-----------------------------+
|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.10 5 Jan 2004 usb_get_dev_data(9F)