xref: /illumos-gate/usr/src/uts/common/io/usb/usba/usbai_register.c (revision 0d2006e4)

/*
 * CDDL HEADER START
 *
 * 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]
 *
 * CDDL HEADER END
 */
/*
 * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 *
 * Copyright 2014 Garrett D'Amore <garrett@damore.org>
 * Copyright 2019, Joyent, Inc.
 */

/*
 * USBA: Solaris USB Architecture support
 *
 * This module builds a tree of parsed USB standard descriptors and unparsed
 * Class/Vendor specific (C/V) descriptors.  Routines are grouped into three
 * groups: those which build the tree, those which take it down, and those which
 * dump it.
 *
 * The tree built hangs off of the dev_cfg field of the usb_client_dev_data_t
 * structure returned by usb_get_dev_data().  The tree consists of different
 * kinds of tree nodes (usb_xxx_data_t) each containing a standard USB
 * descriptor (usb_xxx_descr_t) and pointers to arrays of other nodes.
 *
 * Arrays are dynamically sized, as the descriptors coming from the device may
 * lie, but the number of descriptors from the device is a more reliable
 * indicator of configuration.	This makes the code more robust.  After the raw
 * descriptor data has been parsed into a non-sparse tree, the tree is ordered
 * and made sparse with a bin-sort style algorithm.
 *
 * dev_cfg is an array of configuration tree nodes. Each contains space for one
 * parsed standard USB configuration descriptor, a pointer to an array of c/v
 * tree nodes and a pointer to an array of interface tree nodes.
 *
 * Each interface tree node represents a group of interface descriptors, called
 * alternates, with the same interface number.	Thus, each interface tree node
 * has a pointer to an array of alternate-interface tree nodes each containing a
 * standard USB interface descriptor. Alternate-interface tree nodes also
 * contain a pointer to an array of c/v tree nodes and a pointer to an array of
 * endpoint tree nodes.
 *
 * Endpoint tree nodes contain a standard endpoint descriptor, plus a pointer to
 * an array of c/v tree nodes.
 *
 * Each array in the tree contains elements ranging from 0 to the largest key
 * value of it's elements.  Endpoints are a special case.  The direction bit is
 * right shifted over three unused bits before the index is determined, leaving
 * a range of 0..31 instead of a sparsely-populated range of 0..255.
 *
 * The indices of tree elements coincide with their USB key values.  For
 * example, standard USB devices have no configuration 0;  if they have one
 * configuration it is #1.  dev_cfg[0] is zeroed out;  dev_cfg[1] is the root
 * of configuration #1.
 *
 * The idea here is for a driver to be able to parse the tree to easily find a
 * desired descriptor.	For example, the interval of endpoint 2, alternate 3,
 * interface 1, configuration 1 would be:
 *  dv->dev_cfg[1].cfg_if[1].if_alt[3].altif_ep[2].ep_descr.bInterval
 *
 * How the tree is built:
 *
 * usb_build_descr_tree() is responsible for the whole process.
 *
 * Next, usba_build_descr_tree() coordinates parsing this byte stream,
 * descriptor by descriptor.  usba_build_descr_tree() calls the appropriate
 * usba_process_xx_descr() function to interpret and install each descriptor in
 * the tree, based on the descriptor's type.  When done with this phase, a
 * non-sparse tree exists containing tree nodes with descriptors in the order
 * they were found in the raw data.
 *
 * All levels of the tree, except alternates, remain non-sparse.  Alternates are
 * moved, possibly, within their array, so that descriptors are indexed by their
 * alternate ID.
 *
 * The usba_reg_state_t structure maintains state of the tree-building process,
 * helping coordinate all routines involved.
 */
#define	USBA_FRAMEWORK
#include <sys/usb/usba.h>
#include <sys/usb/usba/usba_impl.h>
#include <sys/usb/usba/usba_private.h>
#include <sys/usb/usba/hcdi_impl.h>
#include <sys/usb/hubd/hub.h>

#include <sys/usb/usba/usbai_register_impl.h>

/*
 * Header needed for use by this module only.
 * However, function may be used in V0.8 drivers so needs to be global.
 */
int usb_log_descr_tree(usb_client_dev_data_t *, usb_log_handle_t,
				uint_t, uint_t);

/* Debug stuff */
usb_log_handle_t	usbai_reg_log_handle;
uint_t			usbai_register_errlevel = USB_LOG_L2;
uint_t			usbai_register_dump_errlevel = USB_LOG_L2;
uint_t			usbai_register_errmask = (uint_t)-1;

/* Function prototypes */
static int usba_build_descr_tree(dev_info_t *, usba_device_t *,
				usb_client_dev_data_t *);
static void usba_process_cfg_descr(usba_reg_state_t *);
static int usba_process_if_descr(usba_reg_state_t *, boolean_t *);
static int usba_process_ep_descr(usba_reg_state_t *);
static int usba_process_ss_ep_comp_descr(usba_reg_state_t *);
static int usba_process_cv_descr(usba_reg_state_t *);
static int usba_set_parse_values(dev_info_t *dip, usba_device_t *usba_device,
    usba_reg_state_t *state);
static void* usba_kmem_realloc(void *, int, int);
static void usba_augment_array(void **, uint_t, uint_t);
static void usba_make_alts_sparse(usb_alt_if_data_t **, uint_t *);

static void usba_order_tree(usba_reg_state_t *);

static void usba_free_if_array(usb_if_data_t *, uint_t);
static void usba_free_ep_array(usb_ep_data_t *, uint_t);
static void usba_free_cv_array(usb_cvs_data_t *, uint_t);

static int usba_dump_descr_tree(dev_info_t *, usb_client_dev_data_t *,
				usb_log_handle_t, uint_t, uint_t);
static void usba_dump_if(usb_if_data_t *, usb_log_handle_t,
				uint_t, uint_t, char *);
static void usba_dump_ep(uint_t, usb_ep_data_t *, usb_log_handle_t, uint_t,
				uint_t, char *);
static void usba_dump_cv(usb_cvs_data_t *, usb_log_handle_t, uint_t, uint_t,
				char *, int);
static void usba_dump_bin(uint8_t *, int, int, usb_log_handle_t,
				uint_t,  uint_t, char *, int);

/* Framework initialization. */
void
usba_usbai_register_initialization()
{
	usbai_reg_log_handle = usb_alloc_log_hdl(NULL, "usbreg",
	    &usbai_register_errlevel,
	    &usbai_register_errmask, NULL,
	    0);

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usba_usbai_register_initialization");
}


/* Framework destruction. */
void
usba_usbai_register_destroy()
{
	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usba_usbai_register destroy");

	usb_free_log_hdl(usbai_reg_log_handle);
}


/*
 * usb_client_attach:
 *
 * Arguments:
 *	dip		- pointer to devinfo node of the client
 *	version 	- USBA registration version number
 *	flags		- None used
 *
 * Return Values:
 *	USB_SUCCESS		- attach succeeded
 *	USB_INVALID_ARGS	- received null dip
 *	USB_INVALID_VERSION	- version argument is incorrect.
 *	USB_FAILURE		- other internal failure
 */
/*ARGSUSED*/
int
usb_client_attach(dev_info_t *dip, uint_t version, usb_flags_t flags)
{
	int rval;
	usba_device_t *usba_device;

	if (dip == NULL) {

		return (USB_INVALID_ARGS);
	}

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usb_client attach:");

	usba_device = usba_get_usba_device(dip);

	/*
	 * Allow exact match for legacy (DDK 0.8/9) drivers, or same major
	 * VERSion and smaller or same minor version for non-legacy drivers.
	 */
	if ((version !=
	    USBA_MAKE_VER(USBA_LEG_MAJOR_VER, USBA_LEG_MINOR_VER)) &&
	    ((USBA_GET_MAJOR(version) != USBA_MAJOR_VER) ||
	    (USBA_GET_MINOR(version) > USBA_MINOR_VER))) {
		USB_DPRINTF_L1(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
		    "Incorrect USB driver version for %s%d: found: %d.%d, "
		    "expecting %d.%d",
		    ddi_driver_name(dip), ddi_get_instance(dip),
		    USBA_GET_MAJOR(version), USBA_GET_MINOR(version),
		    USBA_MAJOR_VER, USBA_MINOR_VER);

		return (USB_INVALID_VERSION);
	}

	if (version == USBA_MAKE_VER(USBA_LEG_MAJOR_VER, USBA_LEG_MINOR_VER)) {
		USB_DPRINTF_L2(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
		    "Accepting legacy USB driver version %d.%d for %s%d",
		    USBA_LEG_MAJOR_VER, USBA_LEG_MINOR_VER,
		    ddi_driver_name(dip), ddi_get_instance(dip));
	}

	rval = ndi_prop_update_int(DDI_DEV_T_NONE, dip, "driver-major",
	    USBA_GET_MAJOR(version));
	if (rval != DDI_PROP_SUCCESS) {

		return (USB_FAILURE);
	}
	rval = ndi_prop_update_int(DDI_DEV_T_NONE, dip, "driver-minor",
	    USBA_GET_MINOR(version));
	if (rval != DDI_PROP_SUCCESS) {

		return (USB_FAILURE);
	}

	mutex_enter(&usba_device->usb_mutex);
	if (strcmp(ddi_driver_name(dip), "usb_mid") != 0) {
		usba_device->usb_client_flags[usba_get_ifno(dip)] |=
		    USBA_CLIENT_FLAG_ATTACH;
		usba_device->usb_client_attach_list->dip = dip;
	}
	mutex_exit(&usba_device->usb_mutex);

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usb_client attach: done");

	return (USB_SUCCESS);
}


/*
 * usb_client_detach:
 *	free dev_data is reg != NULL, not much else to do
 *
 * Arguments:
 *	dip		- pointer to devinfo node of the client
 *	reg		- return registration data at this address
 */
void
usb_client_detach(dev_info_t *dip, usb_client_dev_data_t *reg)
{
	usba_device_t *usba_device = usba_get_usba_device(dip);

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usb_client_detach:");

	if (dip) {
		USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
		    "Unregistering usb client %s%d: reg=0x%p",
		    ddi_driver_name(dip), ddi_get_instance(dip), (void *)reg);

		usb_free_dev_data(dip, reg);

		mutex_enter(&usba_device->usb_mutex);
		if (strcmp(ddi_driver_name(dip), "usb_mid") != 0) {
			usba_device->usb_client_flags[usba_get_ifno(dip)] &=
			    ~USBA_CLIENT_FLAG_ATTACH;
		}
		mutex_exit(&usba_device->usb_mutex);
	}

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usb_client_detach done");
}


/*
 * usb_register_client (deprecated):
 *	The client registers with USBA during attach.
 */
/*ARGSUSED*/
int
usb_register_client(dev_info_t *dip, uint_t version,
    usb_client_dev_data_t **reg, usb_reg_parse_lvl_t parse_level,
    usb_flags_t flags)
{
	int rval = usb_client_attach(dip, version, flags);

	if (rval == USB_SUCCESS) {
		rval = usb_get_dev_data(dip, reg, parse_level, flags);

		if (rval != USB_SUCCESS) {
			usb_client_detach(dip, NULL);
		}
	}

	return (rval);
}


/*
 * usb_unregister_client (deprecated):
 *	Undo the makings of usb_get_dev_data().  Free memory if allocated.
 *
 * Arguments:
 *	dip	- pointer to devinfo node of the client
 *	reg	- pointer to registration data to be freed
 */
void
usb_unregister_client(dev_info_t *dip, usb_client_dev_data_t *reg)
{
	usb_client_detach(dip, reg);
}


/*
 * usb_get_dev_data:
 *	On completion, the registration data has been initialized.
 *	Most data items are straightforward.
 *	Among the items returned in the data is the tree of
 *	parsed descriptors, in dev_cfg;	 the number of configurations parsed,
 *	in dev_n_cfg; a pointer to the current configuration in the tree,
 *	in dev_curr_cfg; the index of the first valid interface in the
 *	tree, in dev_curr_if, and a parse level that accurately reflects what
 *	is in the tree, in dev_parse_level.
 *
 *	This routine sets up directly-initialized fields, and calls
 *	usb_build_descr_tree() to parse the raw descriptors and initialize the
 *	tree.
 *
 *	Parse_level determines the extent to which the tree is built.  It has
 *	the following values:
 *
 *	USB_PARSE_LVL_NONE - Build no tree.  dev_n_cfg will return 0, dev_cfg
 *			     and dev_curr_cfg will return NULL.
 *	USB_PARSE_LVL_IF   - Parse configured interface only, if configuration#
 *			     and interface properties are set (as when different
 *			     interfaces are viewed by the OS as different device
 *			     instances). If an OS device instance is set up to
 *			     represent an entire physical device, this works
 *			     like USB_PARSE_LVL_ALL.
 *	USB_PARSE_LVL_CFG  - Parse entire configuration of configured interface
 *			     only.  This is like USB_PARSE_LVL_IF except 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.
 *
 *	No tree is built for root hubs, regardless of parse_level.
 *
 * Arguments:
 *	dip		- pointer to devinfo node of the client
 *	version		- USBA registration version number
 *	reg		- return registration data at this address
 *	parse_level	- See above
 *	flags		- None used
 *
 * Return Values:
 *	USB_SUCCESS		- usb_get_dev_data succeeded
 *	USB_INVALID_ARGS	- received null dip or reg argument
 *	USB_INVALID_CONTEXT	- called from callback context
 *	USB_FAILURE		- bad descriptor info or other internal failure
 *
 * Note: The non-standard USB descriptors are returned in RAW format.
 *	returns initialized registration data.	Most data items are clear.
 *	Among the items returned is the tree of parsed descriptors in dev_cfg;
 *	and the number of configurations parsed in dev_n_cfg.
 *
 *	The registration data is not shared. each client receives its own
 *	copy.
 */
/*ARGSUSED*/
int
usb_get_dev_data(dev_info_t *dip,
    usb_client_dev_data_t **reg, usb_reg_parse_lvl_t parse_level,
    usb_flags_t flags)
{
	usb_client_dev_data_t	*usb_reg = NULL;
	char			*tmpbuf = NULL;
	usba_device_t		*usba_device;
	int			rval = USB_SUCCESS;

	if ((dip == NULL) || (reg == NULL)) {

		return (USB_INVALID_ARGS);
	}

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usb_get_dev_data: %s%d",
	    ddi_driver_name(dip), ddi_get_instance(dip));

	*reg = NULL;

	/* did the client attach first? */
	if (ddi_prop_get_int(DDI_DEV_T_ANY, dip, DDI_PROP_DONTPASS,
	    "driver-major", -1) == -1) {

		return (USB_INVALID_VERSION);
	}
	if (ddi_prop_get_int(DDI_DEV_T_ANY, dip, DDI_PROP_DONTPASS,
	    "driver-minor", -1) == -1) {

		return (USB_INVALID_VERSION);
	}

	usb_reg = kmem_zalloc(sizeof (usb_client_dev_data_t), KM_SLEEP);
	usba_device = usba_get_usba_device(dip);
	usb_reg->dev_descr = usba_device->usb_dev_descr;
	usb_reg->dev_default_ph = usba_get_dflt_pipe_handle(dip);
	if (usb_reg->dev_default_ph == NULL) {
		kmem_free(usb_reg, sizeof (usb_client_dev_data_t));

		return (USB_FAILURE);
	}

	usb_reg->dev_iblock_cookie = usba_hcdi_get_hcdi(
	    usba_device->usb_root_hub_dip)->hcdi_soft_iblock_cookie;

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "cookie = 0x%p", (void *)usb_reg->dev_iblock_cookie);

	tmpbuf = (char *)kmem_zalloc(USB_MAXSTRINGLEN, KM_SLEEP);

	if (usba_device->usb_mfg_str != NULL) {
		usb_reg->dev_mfg = kmem_zalloc(
		    strlen(usba_device->usb_mfg_str) + 1, KM_SLEEP);
		(void) strcpy(usb_reg->dev_mfg, usba_device->usb_mfg_str);
	}

	if (usba_device->usb_product_str != NULL) {
		usb_reg->dev_product = kmem_zalloc(
		    strlen(usba_device->usb_product_str) + 1,
		    KM_SLEEP);
		(void) strcpy(usb_reg->dev_product,
		    usba_device->usb_product_str);
	}

	if (usba_device->usb_serialno_str != NULL) {
		usb_reg->dev_serial = kmem_zalloc(
		    strlen(usba_device->usb_serialno_str) + 1,
		    KM_SLEEP);
		(void) strcpy(usb_reg->dev_serial,
		    usba_device->usb_serialno_str);
	}

	if ((usb_reg->dev_parse_level = parse_level) == USB_PARSE_LVL_NONE) {
		rval = USB_SUCCESS;

	} else if ((rval = usba_build_descr_tree(dip, usba_device, usb_reg)) !=
	    USB_SUCCESS) {
		usb_unregister_client(dip, usb_reg);
		usb_reg = NULL;
	} else {

		/* Current tree cfg is always zero if only one cfg in tree. */
		if (usb_reg->dev_n_cfg == 1) {
			usb_reg->dev_curr_cfg = &usb_reg->dev_cfg[0];
		} else {
			mutex_enter(&usba_device->usb_mutex);
			usb_reg->dev_curr_cfg =
			    &usb_reg->dev_cfg[usba_device->usb_active_cfg_ndx];
			mutex_exit(&usba_device->usb_mutex);
			ASSERT(usb_reg->dev_curr_cfg != NULL);
			ASSERT(usb_reg->dev_curr_cfg->cfg_descr.bLength ==
			    USB_CFG_DESCR_SIZE);
		}

		/*
		 * Keep dev_curr_if at device's single interface only if that
		 * particular interface has been explicitly defined by the
		 * device.
		 */
		usb_reg->dev_curr_if = usba_get_ifno(dip);
#ifdef DEBUG
		(void) usb_log_descr_tree(usb_reg, usbai_reg_log_handle,
		    usbai_register_dump_errlevel, (uint_t)-1);
#endif
		/*
		 * Fail if interface and configuration of dev_curr_if and
		 * dev_curr_cfg don't exist or are invalid.  (Shouldn't happen.)
		 * These indices must be reliable for tree traversal.
		 */
		if ((usb_reg->dev_curr_cfg->cfg_n_if <= usb_reg->dev_curr_if) ||
		    (usb_reg->dev_curr_cfg->cfg_descr.bLength == 0) ||
		    (usb_reg->dev_curr_cfg->cfg_if[usb_reg->dev_curr_if].
		    if_n_alt == 0)) {
			USB_DPRINTF_L2(DPRINT_MASK_ALL, usbai_reg_log_handle,
			    "usb_get_dev_data: dev_curr_cfg or "
			    "dev_curr_if have no descriptors");
			usb_unregister_client(dip, usb_reg);
			usb_reg = NULL;
			rval = USB_FAILURE;
		}
	}

	*reg = usb_reg;
	kmem_free(tmpbuf, USB_MAXSTRINGLEN);

	if (rval == USB_SUCCESS) {
		usb_client_dev_data_list_t *entry = kmem_zalloc(
		    sizeof (*entry), KM_SLEEP);
		mutex_enter(&usba_device->usb_mutex);

		usba_device->usb_client_flags[usba_get_ifno(dip)] |=
		    USBA_CLIENT_FLAG_DEV_DATA;

		entry->cddl_dip = dip;
		entry->cddl_dev_data = usb_reg;
		entry->cddl_ifno = usba_get_ifno(dip);

		entry->cddl_next =
		    usba_device->usb_client_dev_data_list.cddl_next;
		if (entry->cddl_next) {
			entry->cddl_next->cddl_prev = entry;
		}
		entry->cddl_prev = &usba_device->usb_client_dev_data_list;
		usba_device->usb_client_dev_data_list.cddl_next = entry;

		mutex_exit(&usba_device->usb_mutex);
	}

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usb_get_dev_data rval=%d", rval);

	return (rval);
}


/*
 * usb_free_dev_data
 *	undoes what usb_get_dev_data does
 *
 * Arguments:
 *	dip		- pointer to devinfo node of the client
 *	reg		- return registration data at this address
 */
void
usb_free_dev_data(dev_info_t *dip, usb_client_dev_data_t *reg)
{
	if (dip == NULL) {

		return;
	}

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usb_free_dev_data %s%d: reg=0x%p",
	    ddi_driver_name(dip), ddi_get_instance(dip), (void *)reg);

	if (reg != NULL) {
		usba_device_t *usba_device = usba_get_usba_device(dip);
		usb_client_dev_data_list_t *next, *prev, *entry;
		int	matches = 0;

		if (reg->dev_serial != NULL) {
			kmem_free((char *)reg->dev_serial,
			    strlen((char *)reg->dev_serial) + 1);
		}

		if (reg->dev_product != NULL) {
			kmem_free((char *)reg->dev_product,
			    strlen((char *)reg->dev_product) + 1);
		}

		if (reg->dev_mfg != NULL) {
			kmem_free((char *)reg->dev_mfg,
			    strlen((char *)reg->dev_mfg) + 1);
		}

		/* Free config tree under reg->dev_cfg. */
		if (reg->dev_cfg != NULL) {
			usb_free_descr_tree(dip, reg);
		}

		mutex_enter(&usba_device->usb_mutex);
		prev = &usba_device->usb_client_dev_data_list;
		entry = usba_device->usb_client_dev_data_list.cddl_next;

		/* free the entries in usb_client_data_list */
		while (entry) {
			next = entry->cddl_next;
			if ((dip == entry->cddl_dip) &&
			    (reg == entry->cddl_dev_data)) {
				prev->cddl_next = entry->cddl_next;
				if (entry->cddl_next) {
					entry->cddl_next->cddl_prev = prev;
				}
				kmem_free(entry, sizeof (*entry));
			} else {
				/*
				 * any other entries for this interface?
				 */
				if (usba_get_ifno(dip) == entry->cddl_ifno) {
					matches++;
				}
				prev = entry;
			}
			entry = next;
		}

		USB_DPRINTF_L3(DPRINT_MASK_REGISTER,
		    usbai_reg_log_handle,
		    "usb_free_dev_data: next=0x%p flags[%d]=0x%x",
		    (void *)usba_device->usb_client_dev_data_list.cddl_next,
		    usba_get_ifno(dip),
		    usba_device->usb_client_flags[usba_get_ifno(dip)]);

		if (matches == 0) {
			usba_device->
			    usb_client_flags[usba_get_ifno(dip)] &=
			    ~USBA_CLIENT_FLAG_DEV_DATA;
		}
		mutex_exit(&usba_device->usb_mutex);

		kmem_free(reg, sizeof (usb_client_dev_data_t));
	}

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usb_free_dev_data done");
}

/*
 * usba_build_descr_tree:
 *	This builds the descriptor tree.  See module header comment for tree
 *	description.
 *
 * Arguments:
 *	dip		- devinfo pointer - cannot be NULL.
 *	usba_device	- pointer to usba_device structure.
 *	usb_reg		- pointer to area returned to client describing device.
 *			  number of configuration (dev_n_cfg) and array of
 *			  configurations (dev_cfg) are initialized here -
 *			  dev_parse_level used and may be modified to fit
 *			  current configuration.
 * Return values:
 *	USB_SUCCESS	 - Tree build succeeded
 *	USB_INVALID_ARGS - dev_parse_level in usb_reg is invalid.
 *	USB_FAILURE	 - Bad descriptor info or other internal failure
 */
static int
usba_build_descr_tree(dev_info_t *dip, usba_device_t *usba_device,
    usb_client_dev_data_t *usb_reg)
{
	usba_reg_state_t state;			/* State of tree construction */
	int		cfg_len_so_far = 0;	/* Bytes found, this config. */
	uint8_t 	*last_byte;	/* Ptr to the end of the cfg cloud. */
	uint_t		this_cfg_ndx;		/* Configuration counter. */
	uint_t		high_cfg_bound;		/* High config index + 1. */
	uint_t		low_cfg_bound;		/* Low config index. */
	boolean_t	process_this_if_tree = B_FALSE; /* Save alts, eps, */
							/* of this interface. */

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usba_build_descr_tree starting");

	bzero(&state, sizeof (usba_reg_state_t));
	state.dip = dip;

	/*
	 * Set config(s) and interface(s) to parse based on parse level.
	 * Adjust parse_level according to which configs and interfaces are
	 * made available by the device.
	 */
	state.st_dev_parse_level = usb_reg->dev_parse_level;
	if (usba_set_parse_values(dip, usba_device, &state) != USB_SUCCESS) {

		return (USB_INVALID_ARGS);
	}
	usb_reg->dev_parse_level = state.st_dev_parse_level;

	/* Preallocate configurations based on parse level. */
	if (usb_reg->dev_parse_level == USB_PARSE_LVL_ALL) {
		usb_reg->dev_n_cfg = usba_device->usb_n_cfgs;
		low_cfg_bound = 0;
		high_cfg_bound = usba_device->usb_n_cfgs;
	} else {
		usb_reg->dev_n_cfg = 1;
		mutex_enter(&usba_device->usb_mutex);
		low_cfg_bound = usba_device->usb_active_cfg_ndx;
		high_cfg_bound = usba_device->usb_active_cfg_ndx + 1;
		mutex_exit(&usba_device->usb_mutex);
	}
	usb_reg->dev_cfg = state.st_dev_cfg = kmem_zalloc(
	    (usb_reg->dev_n_cfg * sizeof (usb_cfg_data_t)),
	    KM_SLEEP);
	/*
	 * this_cfg_ndx loops through all configurations presented;
	 * state.st_dev_n_cfg limits the cfgs checked to the number desired.
	 */
	state.st_dev_n_cfg = 0;
	for (this_cfg_ndx = low_cfg_bound; this_cfg_ndx < high_cfg_bound;
	    this_cfg_ndx++) {

		state.st_curr_raw_descr =
		    usba_device->usb_cfg_array[this_cfg_ndx];
		ASSERT(state.st_curr_raw_descr != NULL);

		/* Clear the following for config cloud sanity checking. */
		last_byte = NULL;
		state.st_curr_cfg = NULL;
		state.st_curr_if = NULL;
		state.st_curr_alt = NULL;
		state.st_curr_ep = NULL;

		do {
			/* All descr have length and type at offset 0 and 1 */
			state.st_curr_raw_descr_len =
			    state.st_curr_raw_descr[0];
			state.st_curr_raw_descr_type =
			    state.st_curr_raw_descr[1];

			/* First descr in cloud must be a config descr. */
			if ((last_byte == NULL) &&
			    (state.st_curr_raw_descr_type !=
			    USB_DESCR_TYPE_CFG)) {

				return (USB_FAILURE);
			}

			/*
			 * Bomb if we don't find a new cfg descr when expected.
			 * cfg_len_so_far = total_cfg_length = 0 1st time thru.
			 */
			if (cfg_len_so_far > state.st_total_cfg_length) {
				USB_DPRINTF_L2(DPRINT_MASK_ALL,
				    usbai_reg_log_handle,
				    "usba_build_descr_tree: Configuration (%d) "
				    "larger than wTotalLength (%d).",
				    cfg_len_so_far, state.st_total_cfg_length);

				return (USB_FAILURE);
			}

			USB_DPRINTF_L3(DPRINT_MASK_REGISTER,
			    usbai_reg_log_handle,
			    "usba_build_descr_tree: Process type %d descr "
			    "(addr=0x%p)", state.st_curr_raw_descr_type,
			    (void *)state.st_curr_raw_descr);

			switch (state.st_curr_raw_descr_type) {
			case USB_DESCR_TYPE_CFG:
				cfg_len_so_far = 0;
				process_this_if_tree = B_FALSE;

				state.st_curr_cfg_str = usba_device->
				    usb_cfg_str_descr[this_cfg_ndx];
				usba_process_cfg_descr(&state);
				state.st_last_processed_descr_type =
				    USB_DESCR_TYPE_CFG;
				last_byte = state.st_curr_raw_descr +
				    (state.st_total_cfg_length *
				    sizeof (uchar_t));

				break;

			case USB_DESCR_TYPE_IF:
				/*
				 * process_this_if_tree == TRUE means this
				 * interface, plus all eps and c/vs in it are
				 * to be processed.
				 */
				if (usba_process_if_descr(&state,
				    &process_this_if_tree) != USB_SUCCESS) {

					return (USB_FAILURE);
				}
				state.st_last_processed_descr_type =
				    USB_DESCR_TYPE_IF;

				break;

			case USB_DESCR_TYPE_EP:
				/*
				 * Skip if endpoints of a specific interface are
				 * desired and this endpoint is associated with
				 * a different interface.
				 */
				if (process_this_if_tree) {
					if (usba_process_ep_descr(&state) !=
					    USB_SUCCESS) {

						return (USB_FAILURE);
					}
					state.st_last_processed_descr_type =
					    USB_DESCR_TYPE_EP;
				}

				break;

			case USB_DESCR_TYPE_SS_EP_COMP:

				/*
				 * These entries should always follow an
				 * endpoint description. If an endpoint
				 * description wasn't the last
				 * thing that we found, then we shouldn't
				 * process this descriptor.
				 */
				if (state.st_last_processed_descr_type ==
				    USB_DESCR_TYPE_EP) {
					if (usba_process_ss_ep_comp_descr(
					    &state) != USB_SUCCESS) {

						return (USB_FAILURE);
					}

					state.st_last_processed_descr_type =
					    USB_DESCR_TYPE_SS_EP_COMP;

					break;
				}
				break;

			case USB_DESCR_TYPE_STRING:
				USB_DPRINTF_L2(DPRINT_MASK_ALL,
				    usbai_reg_log_handle,
				    "usb_get_dev_data: "
				    "Found unexpected str descr at addr 0x%p",
				    (void *)state.st_curr_raw_descr);

				break;	/* Shouldn't be any here.  Skip. */

			default:
				/*
				 * Treat all other descr as class/vendor
				 * specific.  Skip if c/vs of a specific
				 * interface are desired and this c/v is
				 * associated with a different one.
				 * Device level c/vs should always be
				 * processed, e.g., the security descrs
				 * for the Host Wire Adapter.
				 */
				if ((state.st_last_processed_descr_type ==
				    USB_DESCR_TYPE_CFG) ||
				    (process_this_if_tree == B_TRUE)) {
					if (usba_process_cv_descr(&state) !=
					    USB_SUCCESS) {

						return (USB_FAILURE);
					}
				}
			}

			state.st_curr_raw_descr += state.st_curr_raw_descr_len;
			cfg_len_so_far += state.st_curr_raw_descr_len;

		} while (state.st_curr_raw_descr < last_byte);
	}

	/* Make tree sparse, and put elements in order. */
	usba_order_tree(&state);

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usba_build_descr_tree done");

	return (USB_SUCCESS);
}


/*
 * usba_process_cfg_descr:
 *	Set up a configuration tree node based on a raw config descriptor.
 *
 * Arguments:
 *	state		- Pointer to this module's state structure.
 *
 * Returns:
 *	B_TRUE: the descr processed corresponds to a requested configuration.
 *	B_FALSE: the descr processed does not correspond to a requested config.
 */
static void
usba_process_cfg_descr(usba_reg_state_t *state)
{
	usb_cfg_data_t *curr_cfg;

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usba_process_cfg_descr starting");

	curr_cfg = state->st_curr_cfg =
	    &state->st_dev_cfg[state->st_dev_n_cfg++];

	/* Parse and store config descriptor proper in the tree. */
	(void) usb_parse_data("2cs5c",
	    state->st_curr_raw_descr, state->st_curr_raw_descr_len,
	    &curr_cfg->cfg_descr,
	    sizeof (usb_cfg_descr_t));

	state->st_total_cfg_length = curr_cfg->cfg_descr.wTotalLength;

	if (state->st_curr_cfg_str != NULL) {
		curr_cfg->cfg_strsize = strlen(state->st_curr_cfg_str) + 1;
		curr_cfg->cfg_str = kmem_zalloc(curr_cfg->cfg_strsize,
		    KM_SLEEP);
		(void) strcpy(curr_cfg->cfg_str, state->st_curr_cfg_str);
	}

	curr_cfg->cfg_n_if = curr_cfg->cfg_descr.bNumInterfaces;
	curr_cfg->cfg_if = kmem_zalloc((curr_cfg->cfg_n_if *
	    sizeof (usb_if_data_t)), KM_SLEEP);

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usba_process_cfg_descr done");
}


/*
 * usba_process_if_descr:
 *	This processes a raw interface descriptor, and sets up an analogous
 *	interface node and child "alternate" nodes (each containing an
 *	interface descriptor) in the descriptor tree.
 *
 *	It groups all descriptors with the same bInterfaceNumber (alternates)
 *	into an array.	It makes entries in an interface array, each of which
 *	points to an array of alternates.
 *
 * Arguments:
 *	state		- Pointer to this module's state structure.
 *	requested_if	- Address into which the following is returned:
 *	    B_TRUE	- the processed descr is of a requested interface.
 *	    B_FALSE	- the processed descr if of a non-requested interface.
 *
 * Returns:
 *	USB_SUCCESS:	Descriptor is successfully parsed.
 *	USB_FAILURE:	Descriptor is inappropriately placed in config cloud.
 */
static int
usba_process_if_descr(usba_reg_state_t *state, boolean_t *requested_if)
{
	char *string;
	usb_if_descr_t *new_if_descr;
	usba_device_t *usba_device = usba_get_usba_device(state->dip);
	int is_root_hub = (usba_device->usb_addr == ROOT_HUB_ADDR);

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usba_process_if_descr starting");

	/* No config preceeds this interface. */
	if (state->st_curr_cfg == NULL) {
		USB_DPRINTF_L2(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
		    "usba_process_if_descr found interface after no config.");

		return (USB_FAILURE);
	}

	new_if_descr = kmem_zalloc(sizeof (usb_if_descr_t), KM_SLEEP);

	/* Strictly speaking, unpacking is not necessary.  Could use bcopy. */
	(void) usb_parse_data("9c", state->st_curr_raw_descr,
	    state->st_curr_raw_descr_len,
	    new_if_descr, sizeof (usb_if_descr_t));

	/* Check the interface number in case of a malfunction device */
	if (new_if_descr->bInterfaceNumber >= state->st_curr_cfg->cfg_n_if) {
		USB_DPRINTF_L2(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
		    "usba_process_if_descr: bInterfaceNumber=%d is not "
		    "a valid one", new_if_descr->bInterfaceNumber);
		kmem_free(new_if_descr, sizeof (usb_if_descr_t));

		*requested_if = B_FALSE;

		return (USB_SUCCESS);
	}
	*requested_if = B_TRUE;

	/* Not a requested interface. */
	if ((state->st_if_to_build != new_if_descr->bInterfaceNumber) &&
	    (state->st_if_to_build != USBA_ALL)) {
		*requested_if = B_FALSE;

	} else {
		usb_alt_if_data_t *alt_array;
		uint_t		alt_index;

		/* Point to proper interface node, based on num in descr. */
		state->st_curr_if =
		    &state->st_curr_cfg->cfg_if[new_if_descr->bInterfaceNumber];

		/* Make room for new alternate. */
		alt_index = state->st_curr_if->if_n_alt;
		alt_array = state->st_curr_if->if_alt;
		usba_augment_array((void **)(&alt_array), alt_index,
		    sizeof (usb_alt_if_data_t));

		/* Ptr to the current alt, may be used to attach a c/v to it. */
		state->st_curr_alt = &alt_array[alt_index];

		bcopy(new_if_descr, &(alt_array[alt_index++].altif_descr),
		    sizeof (usb_if_descr_t));
		state->st_curr_if->if_alt = alt_array;
		state->st_curr_if->if_n_alt = alt_index;

		string = kmem_zalloc(USB_MAXSTRINGLEN, KM_SLEEP);
		if (!is_root_hub) {
			(void) usb_get_string_descr(state->dip, USB_LANG_ID,
			    state->st_curr_alt->altif_descr.iInterface,
			    string, USB_MAXSTRINGLEN);
		}
		if (string[0] == '\0') {
			(void) strcpy(string, "<none>");
		}
		state->st_curr_alt->altif_strsize = strlen(string) + 1;
		state->st_curr_alt->altif_str = kmem_zalloc(
		    state->st_curr_alt->altif_strsize, KM_SLEEP);
		(void) strcpy(state->st_curr_alt->altif_str, string);
		kmem_free(string, USB_MAXSTRINGLEN);
	}

	kmem_free(new_if_descr, sizeof (usb_if_descr_t));

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usba_process_if_descr done");

	return (USB_SUCCESS);
}


/*
 * usba_process_ep_descr:
 *	This processes a raw endpoint descriptor, and sets up an analogous
 *	endpoint descriptor node in the descriptor tree.
 *
 * Arguments:
 *	state		- Pointer to this module's state structure.
 *
 * Returns:
 *	USB_SUCCESS:	Descriptor is successfully parsed.
 *	USB_FAILURE:	Descriptor is inappropriately placed in config cloud.
 */
static int
usba_process_ep_descr(usba_reg_state_t *state)
{
	usb_alt_if_data_t *curr_alt = state->st_curr_alt;

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usba_process_ep_descr starting");

	/* No interface preceeds this endpoint. */
	if (state->st_curr_alt == NULL) {
		USB_DPRINTF_L2(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
		    "usba_process_ep_descr: no requested alt before endpt.");

		return (USB_FAILURE);
	}

	usba_augment_array((void **)(&curr_alt->altif_ep),
	    curr_alt->altif_n_ep, sizeof (usb_ep_data_t));

	/* Ptr to the current endpt, may be used to attach a c/v to it. */
	state->st_curr_ep = &curr_alt->altif_ep[curr_alt->altif_n_ep++];

	(void) usb_parse_data("4csc", state->st_curr_raw_descr,
	    state->st_curr_raw_descr_len,
	    &state->st_curr_ep->ep_descr, sizeof (usb_ep_descr_t));

	USB_DPRINTF_L4(DPRINT_MASK_REGISTER, usbai_reg_log_handle,
	    "usba_process_ep_descr done");

	return (USB_SUCCESS);
}

/*
 * usba_process_ss_ep_comp_descr:
 * 	This processes a raw endpoint companion descriptor and associates it
 * 	inside of an existing endpoint's entry.
 *
 * Arguments:
 *	state		- Pointer to this module's state structure.
 *
 * Returns:
 *	USB_SUCCESS:	Descriptor is successfully parsed.
 *	USB_FAILURE:	Descriptor is inappropriately placed in config cloud.
 */
static int
usba_process_ss_ep_comp_descr(usba_reg_state_t *state)
{
	if (state->st_curr_ep == NULL)
		return (USB_FAILURE);

	(void) usb_parse_data("4cs", state->st_curr_raw_descr,
	    state->st_curr_raw_descr_len,
	    &state->st_curr_ep->ep_ss_comp,
	    sizeof (usb_ep_ss_comp_descr_t));
	state->st_curr_ep->ep_ss_valid = B_TRUE;