7964 Want usba hcdi manual pages

7965 need xhci(7D) manual page
Reviewed by: Richard Lowe <richlowe@richlowe.net>
Reviewed by: Toomas Soome <tsoome@me.com>
Approved by: Gordon Ross <gordon.w.ross@gmail.com>

31 files changed, 4684 insertions, 139 deletions

diff --git a/usr/src/man/man7d/Makefile b/usr/src/man/man7d/Makefile
index dfbb721a81..f9fc43097b 100644
--- a/usr/src/man/man7d/Makefile
+++ b/usr/src/man/man7d/Makefile
@@ -12,7 +12,7 @@
 #
 # Copyright 2011, Richard Lowe
 # Copyright 2016 Garrett D'Amore <garrett@damore.org>
-# Copyright 2016 Joyent, Inc.
+# Copyright (c) 2017, Joyent, Inc.
 # Copyright 2016 Hans Rosenfeld <rosenfeld@grumpf.hope-2000.org>
 # Copyright 2016 Nexenta Systems, Inc.
 #
@@ -240,6 +240,7 @@ i386_MANFILES=	ahci.7d		\
 		ural.7d		\
 		urtw.7d		\
 		wpi.7d		\
+		xhci.7d		\
 		zyd.7d
 
 _MANLINKS=	1394.7d		\
diff --git a/usr/src/man/man7d/xhci.7d b/usr/src/man/man7d/xhci.7d
new file mode 100644
index 0000000000..e2822fd19c
--- /dev/null
+++ b/usr/src/man/man7d/xhci.7d
@@ -0,0 +1,107 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd October 17, 2016
+.Dt XHCI 7D
+.Os
+.Sh NAME
+.Nm xhci
+.Nd Extensible Host Controller Interface Driver
+.Sh SYNOPSIS
+.Sy usb@unit-address
+.Sh DESCRIPTION
+The
+.Nm
+driver supports PCI devices that implement versions 1.0 and 1.1 of the
+Extensible Host Controller Inteface Specification. These devices provide
+support for USB 3.0, USB 2.x, and USB 1.x devices and is integrated into
+the broader illumos USB Architecture (USBA).
+.Pp
+The
+.Nm
+driver supports all four USB transfer types:
+.Sy bulk transfers ,
+.Sy control transfers ,
+.Sy interrupt transfers ,
+and
+.Sy isochronous transfers .
+.Pp
+Administrators do not interact with the
+.Nm
+driver directly. USB devices are managed with
+.Xr cfgadm 1M .
+See
+.Xr cfgadm_usb 1M
+for more information on how to specifically manage USB devices and how
+they are laid out in the system.
+.Xr cfgadm 1M
+is only used to manage devices at a USB level. For example, a USB NIC
+would still be managed with
+.Xr dladm 1M
+at a networking level.
+.Pp
+On some x86 systems USB ports may be routed to either an instance of the
+.Nm
+driver or an instance of the
+.Xr ehci 7D
+driver. By default, all such ports are routed to the
+.Nm
+driver, allowing those devices to operate at USB 3.x speed by default.
+This is most common on Intel platforms and chipsets. While this is
+controlled with the
+.Sy xhci-reroute
+property discussed below, changing it may not be sufficient to change
+the behavior. The BIOS or ACPI data for many x86 systems may toggle this
+automatically.
+.Sh PROPERTIES
+The
+.Nm
+driver supports the following properties which may be tuned in the
+.Nm
+driver's
+.Xr driver.conf 4
+file.
+.Bl -tag -width Sy
+.It Sy xhci-reroute
+The
+.Sy xhci-reroute
+property determines whether or not USB ports are re-routed to the
+.Nm
+driver. The default behavior is to route such ports.  To disable this,
+the property should be set to
+.Sy 0 .
+Any other value, or the lack of the property, cause the default behavior
+to take place.
+.El
+.Sh ARCHITECTURE
+The
+.Nm
+driver is only supported on
+.Sy x86
+systems at this time.
+.Sh FILES
+.Bl -tag -width Pa
+.It Pa /kernel/drv/xhci
+32-bit device driver (x86).
+.It Pa /kernel/drv/amd64/xhci
+64-bit device driver (x86).
+.It Pa /kernel/drv/xhci.conf
+Driver configuration file.
+.El
+.Sh SEE ALSO
+.Xr cfgadm 1M ,
+.Xr cfgadm_usb 1M ,
+.Xr dladm 1M ,
+.Xr driver.conf 4 ,
+.Xr ehci 7D ,
+.Xr usba 7D
diff --git a/usr/src/man/man9e/Makefile b/usr/src/man/man9e/Makefile
index 24551bf655..2d32bfbe34 100644
--- a/usr/src/man/man9e/Makefile
+++ b/usr/src/man/man9e/Makefile
@@ -12,34 +12,35 @@
 #
 # Copyright 2011, Richard Lowe
 # Copyright 2013 Nexenta Systems, Inc.  All rights reserved.
+# Copyright (c) 2017, Joyent, Inc.
 #
 
 include		$(SRC)/Makefile.master
 
-MANSECT= 	9e
+MANSECT=	9e
 
-MANFILES= 	Intro.9e		\
+MANFILES=	Intro.9e		\
 		_fini.9e		\
-	 	aread.9e		\
-	 	attach.9e		\
-	 	awrite.9e		\
-	 	chpoll.9e		\
-	 	close.9e		\
-	 	csx_event_handler.9e	\
-	 	detach.9e		\
-	 	devmap.9e		\
-	 	devmap_access.9e	\
-	 	devmap_contextmgt.9e	\
-	 	devmap_dup.9e		\
-	 	devmap_map.9e		\
-	 	devmap_unmap.9e		\
-	 	dump.9e			\
-	 	getinfo.9e		\
-	 	gld.9e			\
-	 	identify.9e		\
-	 	ioctl.9e		\
-	 	ks_snapshot.9e		\
-	 	ks_update.9e		\
+		aread.9e		\
+		attach.9e		\
+		awrite.9e		\
+		chpoll.9e		\
+		close.9e		\
+		csx_event_handler.9e	\
+		detach.9e		\
+		devmap.9e		\
+		devmap_access.9e	\
+		devmap_contextmgt.9e	\
+		devmap_dup.9e		\
+		devmap_map.9e		\
+		devmap_unmap.9e		\
+		dump.9e			\
+		getinfo.9e		\
+		gld.9e			\
+		identify.9e		\
+		ioctl.9e		\
+		ks_snapshot.9e		\
+		ks_update.9e		\
 		mac.9e			\
 		mc_getcapab.9e		\
 		mc_getprop.9e		\
@@ -53,58 +54,76 @@ MANFILES= 	Intro.9e		\
 		mc_start.9e		\
 		mc_tx.9e		\
 		mc_unicst.9e		\
-	 	mmap.9e			\
-	 	open.9e			\
-	 	power.9e		\
-	 	print.9e		\
-	 	probe.9e		\
-	 	prop_op.9e		\
-	 	put.9e			\
-	 	quiesce.9e		\
-	 	read.9e			\
-	 	segmap.9e		\
-	 	srv.9e			\
-	 	strategy.9e		\
-	 	tran_abort.9e		\
-	 	tran_bus_reset.9e	\
-	 	tran_dmafree.9e		\
-	 	tran_getcap.9e		\
-	 	tran_init_pkt.9e	\
-	 	tran_quiesce.9e		\
-	 	tran_reset.9e		\
-	 	tran_reset_notify.9e	\
-	 	tran_setup_pkt.9e	\
-	 	tran_start.9e		\
-	 	tran_sync_pkt.9e	\
-	 	tran_tgt_free.9e	\
-	 	tran_tgt_init.9e	\
-	 	tran_tgt_probe.9e	\
-	 	write.9e
+		mmap.9e			\
+		open.9e			\
+		power.9e		\
+		print.9e		\
+		probe.9e		\
+		prop_op.9e		\
+		put.9e			\
+		quiesce.9e		\
+		read.9e			\
+		segmap.9e		\
+		srv.9e			\
+		strategy.9e		\
+		tran_abort.9e		\
+		tran_bus_reset.9e	\
+		tran_dmafree.9e		\
+		tran_getcap.9e		\
+		tran_init_pkt.9e	\
+		tran_quiesce.9e		\
+		tran_reset.9e		\
+		tran_reset_notify.9e	\
+		tran_setup_pkt.9e	\
+		tran_start.9e		\
+		tran_sync_pkt.9e	\
+		tran_tgt_free.9e	\
+		tran_tgt_init.9e	\
+		tran_tgt_probe.9e	\
+		usba_hcdi_cb_ops.9e	\
+		usba_hcdi_device_address.9e		\
+		usba_hcdi_device_init.9e		\
+		usba_hcdi_hub_update.9e			\
+		usba_hcdi_pipe_bulk_xfer.9e		\
+		usba_hcdi_pipe_ctrl_xfer.9e		\
+		usba_hcdi_pipe_intr_xfer.9e		\
+		usba_hcdi_pipe_isoc_xfer.9e		\
+		usba_hcdi_pipe_open.9e			\
+		usba_hcdi_pipe_reset.9e			\
+		usba_hcdi_pipe_stop_intr_polling.9e	\
+		usba_hcdi.9e		\
+		write.9e
 
 MANLINKS=	_info.9e		\
-	 	_init.9e		\
+		_init.9e		\
 		gldv3.9e		\
 		GLDv3.9e		\
-	 	gldm_get_stats.9e	\
-	 	gldm_intr.9e		\
-	 	gldm_ioctl.9e		\
-	 	gldm_reset.9e		\
-	 	gldm_send.9e		\
-	 	gldm_set_mac_addr.9e	\
-	 	gldm_set_multicast.9e	\
-	 	gldm_set_promiscuous.9e	\
-	 	gldm_start.9e		\
-	 	gldm_stop.9e		\
+		gldm_get_stats.9e	\
+		gldm_intr.9e		\
+		gldm_ioctl.9e		\
+		gldm_reset.9e		\
+		gldm_send.9e		\
+		gldm_set_mac_addr.9e	\
+		gldm_set_multicast.9e	\
+		gldm_set_promiscuous.9e	\
+		gldm_start.9e		\
+		gldm_stop.9e		\
 		MAC.9e			\
 		mc_close.9e		\
 		mc_stop.9e		\
 		intro.9e		\
-	 	tran_destroy_pkt.9e	\
-	 	tran_pkt_constructor.9e	\
-	 	tran_pkt_destructor.9e	\
-	 	tran_setcap.9e		\
-	 	tran_teardown_pkt.9e	\
-	 	tran_unquiesce.9e
+		tran_destroy_pkt.9e	\
+		tran_pkt_constructor.9e	\
+		tran_pkt_destructor.9e	\
+		tran_setcap.9e		\
+		tran_teardown_pkt.9e	\
+		tran_unquiesce.9e	\
+		usba_hcdi_cb_close.9e	\
+		usba_hcdi_cb_ioctl.9e	\
+		usba_hcdi_cb_open.9e	\
+		usba_hcdi_device_fini.9e	\
+		usba_hcdi_pipe_close.9e		\
+		usba_hcdi_pipe_stop_isoc_polling.9e
 
 intro.9e			:= LINKSRC = Intro.9e
 
@@ -139,6 +158,14 @@ tran_pkt_constructor.9e		:= LINKSRC = tran_setup_pkt.9e
 tran_pkt_destructor.9e		:= LINKSRC = tran_setup_pkt.9e
 tran_teardown_pkt.9e		:= LINKSRC = tran_setup_pkt.9e
 
+usba_hcdi_cb_close.9e		:= LINKSRC = usba_hcdi_cb_ops.9e
+usba_hcdi_cb_ioctl.9e		:= LINKSRC = usba_hcdi_cb_ops.9e
+usba_hcdi_cb_open.9e		:= LINKSRC = usba_hcdi_cb_ops.9e
+usba_hcdi_device_fini.9e	:= LINKSRC = usba_hcdi_device_init.9e
+usba_hcdi_pipe_close.9e		:= LINKSRC = usba_hcdi_pipe_open.9e
+usba_hcdi_pipe_stop_isoc_polling.9e	:= LINKSRC = usba_hcdi_pipe_stop_intr_polling.9e
+
+
 .KEEP_STATE:
 
 include		$(SRC)/man/Makefile.man
diff --git a/usr/src/man/man9e/usba_hcdi.9e b/usr/src/man/man9e/usba_hcdi.9e
new file mode 100644
index 0000000000..b14747861d
--- /dev/null
+++ b/usr/src/man/man9e/usba_hcdi.9e
@@ -0,0 +1,846 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd November 18, 2016
+.Dt USBA_HCDI 9E
+.Os
+.Sh NAME
+.Nm usba_hcdi
+.Nd USB Host Controller Driver Interface
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This describes private interfaces that are not part of the stable DDI.
+This may be removed or changed at any time.
+.Sh DESCRIPTION
+.Sy hcdi
+drivers are device drivers that support USB host controller hardware.
+USB host controllers provide an interface between the operating system
+and USB devices. They abstract the interface to the devices, often
+provide ways of performing DMA, and also act as the root hub.
+.Pp
+.Sy hcdi
+drivers are part of the illumos USB Architecture (USBA). The
+.Xr usba 7D
+driver provides support for many of the surrounding needs of an
+.Sy hcdi
+driver and requires that such drivers implement a specific operations
+vector,
+.Xr usba_hcdi_ops 9S .
+These functions cover everything from initialization to performing I/O
+to USB devices on behalf of client device drivers.
+.Ss USB Speed and Version Background
+USB devices are often referred to in two different ways. The first way
+is the USB version that they conform to. In the wild this looks like USB
+1.1, USB 2.0, USB 3.0, etc.. However, devices are also referred to as
+.Sq full- ,
+.Sq low- ,
+.Sq high- ,
+.Sq super-
+speed devices.
+.Pp
+The latter description describes the maximum theoretical speed of a
+given device. For example, a super-speed device theoretically caps out
+around 5 Gbit/s, whereas a low-speed device caps out at 1.5 Mbit/s.
+.Pp
+In general, each speed usually corresponds to a specific USB protocol
+generation. For example, all USB 3.0 devices are super-speed devices.
+All 'high-speed' devices are USB 2.x devices. Full-speed devices are
+special in that they can either be USB 1.x or USB 2.x devices. Low-speed
+devices are only a USB 1.x thing, they did not jump the fire line to USB
+2.x.
+.Pp
+USB 3.0 devices and ports generally have the wiring for both USB 2.0 and
+USB 3.0. When a USB 3.0 device is plugged into a USB 2.0 port or hub,
+then it will report its version as USB 2.1, to indicate that it is
+actually a USB 3.0 device.
+.Ss USB Endpoint Background
+To understand the organization of the functions that make up the hcdi
+operations vector, it helps to understand how USB devices are organized
+and work at a high level.
+.Pp
+A given USB device is made up of
+.Em endpoints .
+A request, or transfer, is made to a specific USB endpoint. These
+endpoints can provide different services and have different expectations
+around the size of the data that'll be used in a given request and the
+periodicity of requests. Endpoints themselves are either used to make
+one-shot requests, for example, making requests to a mass storage device
+for a given sector, or for making periodic requests where you end up
+polling on the endpoint, for example, polling on a USB keyboard for
+keystrokes.
+.Pp
+Each endpoint encodes two different pieces of information: a direction
+and a type. There are two different directions: IN and OUT. These refer
+to the general direction that data moves relative to the operating
+system. For example, an IN transfer transfers data in to the operating
+system, from the device. An OUT transfer transfers data from the
+operating system, out to the device.
+.Pp
+There are four different kinds of endpoints:
+.Bl -tag -width Sy -offset indent
+.It Sy BULK
+These transfers are large transfers of data to or from a device.  The
+most common use for bulk transfers is for mass storage devices.  Though
+they are often also used by network devices and more. Bulk endpoints do
+not have an explicit time component to them. They are always used for
+one-shot transfers.
+.It Sy CONTROL
+These transfers are used to manipulate devices themselves and are used
+for USB protocol level operations (whether device-specific,
+class-specific, or generic across all of USB). Unlike other transfers,
+control transfers are always bi-directional and use different kinds of
+transfers.
+.It Sy INTERRUPT
+Interrupt transfers are used for small transfers that happen
+infrequently, but need reasonable latency. A good example of interrupt
+transfers is to receive input from a USB keyboard. Interrupt-IN
+transfers are generally polled. Meaning that a client (device driver)
+opens up an interrupt-IN endpoint to poll on it, and receives periodic
+updates whenever there is information available. However, Interrupt
+transfers can be used as one-shot transfers both going IN and OUT.
+.It Sy ISOCHRONOUS
+These transfers are things that happen once per time-interval at a very
+regular rate. A good example of these transfers are for audio and video.
+A device may describe an interval as 10ms at which point it will read or
+write the next batch of data every 10ms and transform it for the user.
+There are no one-shot Isochronous-IN transfers. There are one-shot
+Isochronous-OUT transfers, but these are used by device drivers to
+always provide the system with sufficient data.
+.El
+.Pp
+To find out information about the endpoints, USB devices have a series
+of descriptors that cover different aspects of the device. For example,
+there are endpoint descriptors which cover the properties of endpoints
+such as the maximum packet size or polling interval.
+.Pp
+Descriptors exist at all levels of USB. For example, there are general
+descriptors for every device. The USB device descriptor is described in
+.Xr usb_dev_descr 9S .
+Host controllers will look at these descriptors to ensure that they
+program the device correctly; however, they are more often used by
+client device drivers. There are also descriptors that exist at a class
+level. For example, the hub class has a class-specific descriptor which
+describes properties of the hub. That information is requested for and
+used by the hub driver.
+.Pp
+All of the different descriptors are gathered by the system and placed
+into a tree, with device descriptors, configurations, endpoints, and
+more. Client device drivers gain access to this tree and then use them
+to then open endpoints, which are called pipes in USBA (and some
+revisions of the USB specification).
+.Pp
+Each pipe gives access to a specific endpoint on the device which can be
+used to perform transfers of a specific type and direction. For example,
+a mass storage device often has three different endpoints, the default
+control endpoint (which every device has), a Bulk-IN endpoint, and a
+Bulk-OUT endpoint. The device driver ends up with three open pipes. One
+to the default control endpoint to configure the device, and then the
+other two are used to perform I/O.
+.Pp
+These routines translate more or less directly into calls to a host
+controller driver. A request to open a pipe takes an endpoint descriptor
+that describes the properties of the pipe, and the host controller
+driver goes through and does any work necessary to allow the client
+device driver to access it. Once the pipe is open, it either makes
+one-shot transfers specific to the transfer type or it starts performing
+a periodic poll of an endpoint.
+.Pp
+All of these different actions translate into requests to the host
+controller. The host controller driver itself is in charge of making
+sure that all of the required resources for polling are allocated with a
+request and then proceed to give the driver's periodic callbacks.
+.Pp
+For each of the different operations described above, there is a
+corresponding entry in
+.Xr usba_hcdi_ops 9S .
+For example, open an endpoint, the host controller has to implement
+.Xr usba_hcdi_pipe_open 9E
+and for each transfer type, there is a different transfer function. One
+example is
+.Xr usba_hcdi_bulk_xfer 9E .
+See
+.Xr usba_hcdi_ops 9S
+for a full list of the different function endpoints.
+.Ss HCDI Initialization
+hcdi drivers are traditional character device drivers. To start with, an
+hcdi driver should define traditional
+.Xr dev_ops 9S
+and
+.Xr cb_ops 9S
+structures. To get started, the device driver should perform normal
+device initialization in an
+.Xr attach 9E
+entry point. For example, PCI devices should setup the device's
+registers and program them. In addition, all devices should
+configure interrupts, before getting ready to call into the USBA. Each
+instance of a device must be initialized and registered with the USBA.
+.Pp
+To initialize a device driver with the USBA, it must first call
+.Xr usba_alloc_hcdi_ops 9F .
+This provides a device driver with the
+.Xr usba_hcdi_ops 9S
+structure that it must fill out. Please see
+.Xr usba_hcdi_ops 9S
+for instructions on how it should be filled out. Once filled out, the
+driver should call
+.Xr usba_hcdi_register 9F .
+.Pp
+If the call to register fails for whatever reason, the device driver
+should fail its
+.Xr attach 9E
+entry point. After this call successfully completes, the driver should
+assume that any of the functions it registered with the call to
+.Xr usba_hcdi_register 9F
+will be called at this point.
+.Ss Binding the Root Hub
+Once this is set up, the hcdi driver must initialize its root hub by
+calling
+Xr usba_hcdi_bind_root_hub 9F .
+To bind the root hub, the device driver is responsible for providing a
+device descriptor that represents the hardware. Depending on the
+hardware, this descriptor may be either static or dynamic.
+.Pp
+This device descriptor should be a packed descriptor that is the same
+that would be read off of the device. The device descriptor should match
+a hub of a USB generation equivalent to the maximum speed of the device.
+For example, a USB 3.0 host controller would use a USB 3.0 hub's device
+descriptor.  Similarly, a USB 2.0 host controller would use a USB 2.0
+hub's device descriptor.
+.Pp
+The descriptor first starts with a USB configuration descriptor, as
+defined in
+.Xr usb_cfg_descr 9S .
+It is then followed by an interface descriptor. The definition for it
+can be found in
+.Xr usb_if_descr 9S .
+Next is the endpoint descriptor for the single Interrupt-IN endpoint
+that all hubs have as defined in
+.Xr usb_ep_descr 9S .
+Finally, any required companion descriptors should be used. For example,
+a USB 3.x hub will have a
+.Xr usb_ep_ss_comp_descr 9S
+appended to the structure.
+.Pp
+Note, that the structure needs to be packed, as though it were read from
+a device. The structures types referenced in
+.Xr usb_cfg_descr 9S ,
+.Xr usb_if_descr 9S ,
+.Xr usb_ep_descr 9S ,
+and
+.Xr usb_ep_ss_comp_descr 9S
+are not packed for this purpose. They should not be used as they have
+gaps added by the compiler for alignment.
+.Pp
+Once assembled, the device driver should call
+.Xr usb_hubdi_bind_root_hub 9F .
+This will cause an instance of the
+.Xr hubd 7D
+driver to be attached and associated with the root controller. As such,
+driver writers need to ensure that all initialization is done prior to
+loading the root hub. Once successfully loaded, driver writers should
+assume that they'll get other calls into the driver's operation vector
+before the call to
+.Xr usb_hcdi_bind_root_hub 9F.
+.Pp
+If the call to
+.Xr usb_hcdi_bind_root_hub 9F
+failed for whatever reason, the driver should unregister from USBA (see
+the next section), unwind all of the resources it has allocated, and
+return
+.Dv DDI_FAILURE .
+.Pp
+Otherwise, at this point it's safe to assume that the instance of the
+device has initialized successfully and the driver should return
+.Dv DDI_SUCCESS .
+.Ss Driver Teardown
+When a driver's
+.Xr detach 9E
+entry point has been called, before anything else is done, the device
+driver should unbind its instance of the root hub and then unregister
+from the USBA.
+.Pp
+To unbind the root hub, the instance of the driver should call
+.Xr usba_hubdi_unbind_root_hub 9F .
+If for some reason that function does not return
+.Sy USB_SUCESS ,
+then the device driver should fail the call to
+.Xr detach 9E
+and return
+.Dv DDI_FAILURE .
+.Pp
+Once the root hub has been unbound, the device driver can continue by
+removing its hcdi registration with USBA. To do this, the driver should
+call
+.Xr usba_hcdi_unregister 9F .
+As this call always succeeds, at this point, it is safe for the driver
+to tear down all the rest of its resources and successfully detach.
+.Ss State Tracking and Minors Numbers
+Because a host controller driver is also a root hub, there are a few
+constraints around how the device must store its per-instance state and
+how its minor numbers are used.
+.Pp
+hcdi drivers
+.Em must not
+store any data with
+.Xr ddi_get_driver_private 9F .
+This private data is used by USBA. If it has been called before the
+device registers, then it will fail to register successfully with the
+USBA. However, setting it after that point will corrupt the state of the
+USBA and likely lead to data corruption and crashes.
+.Pp
+Similarly, part of the minor number space is utilized to represent
+various devices like the root hub. Whenever a device driver is presented
+with a
+.Ft dev_t
+and it's trying to extract the minor number, it must take into account
+the constant
+.Dv HUBD_IS_ROOT_HUB .
+The following shows how to perform this, given a
+.Ft dev_t
+called
+.Ft dev :
+.Bd -literal -offset indent
+minor_t minor = getminor(dev) & ~HUBD_IS_ROOT_HUB;
+.Ed
+.Ss Required Character and Device Operations
+The USBA handles many character and device operations entry points for a
+device driver or has strict rules on what a device driver must do in
+them. This section summarizes those constraints.
+.Pp
+In the
+.Xr dev_ops 9S
+structure, the following members have special significance:
+.Bl -tag -offset indent -width Sy
+.It Sy devo_bus_ops
+The
+.Sy devo_bus_ops
+member should be set to the symbol
+.Sy usba_hubdi_busops .
+See
+.Xr usba_hubdi_devops 9F
+for more information.
+.It Sy devo_power
+The
+.Sy devo_power
+member should be set to the symbol
+.Sy usba_hubdi_root_hub_power .
+See
+.Xr usba_hubdi_Devops 9F
+for more information.
+.El
+.Pp
+The other standard entry points for character devices,
+.Sy devo_getinfo ,
+.Sy devo_attach ,
+and
+.Sy devo_detach
+should be implemented normally as per
+.Xr getinfo 9E ,
+.Xr attach 9E ,
+and
+.Xr detach 9E
+respectively.
+.Pp
+The following members of the
+.Xr cb_ops 9S
+operations vector must be implemented and set:
+.Bl -tag -offset indent -width Sy
+.It Sy cb_open
+The device driver should implement an
+.Xr open 9E
+entry point that obtains access to its
+.Sy dev_info_t
+and then calls
+.Xr usba_hubdi_open 9F . See
+.Xr usba_hcdi_cb_open 9E
+for more information.
+.It Sy cb_close
+The device driver should implement a
+.Xr close 9E
+entry point that obtains access to its
+.Sy dev_info_t
+and then calls
+.Xr usba_hubdi_close 9F . See
+.Xr usba_hcdi_cb_close 9E
+for more information.
+.It Sy cb_ioctl
+The device driver should implement a
+.Xr ioctl 9E
+entry point that obtains access to its
+.Sy dev_info_t
+and then calls
+.Xr usba_hubdi_ioctl 9F .
+.Pp
+If the device driver wishes to have private ioctls, it may check the
+ioctl command before calling
+.Xr usba_hubdi_ioctl 9F .
+Because the
+.Xr usba_hubdi_ioctl 9F
+function normally takes care of checking for the proper privileges,
+device drivers must verify that a caller has appropriate privileges
+before processing any private ioctls.
+.Pp
+See
+.Xr usba_hcdi_cb_ioctl 9E
+for more information.
+.It Sy cb_prop_op
+The
+.Sy cb_prop_op
+member should be set to
+.Xr ddi_prop_op 9F .
+.It Sy cb_flag
+The
+.Sy cb_flag
+member should be set to the bitwise-inclusive-OR of the
+.Sy D_MP
+flag
+and the
+.Sy D_HOTPLUG
+flag.
+.El
+.Pp
+All other members of the
+.Xr cb_ops 9S
+structure should not be implemented and set to the appropriate value,
+such as
+.Xr nodev 9F
+or
+.Xr nochpoll 9F .
+.Ss Locking
+In general, the USBA calls into a device driver through one of the
+functions that it has register in the
+.Xr usba_hcdi_ops 9S
+structure. However, in response to a data transfer, the device driver
+will need to call back into the USBA by calling
+.Xr usba_hcdi_cb 9F .
+.Pp
+A device driver must hold
+.Em no locks
+across the call to
+.Xr usba_hcdi_cb 9F .
+Returning an I/O to the USBA, particularly an error, may result in
+another call back to one of the
+.Xr usba_hcdi_cb 9F
+vectors.
+.Pp
+Outside of that constraint, the device driver should perform locking of
+its data structures. It should assume that many of its entry points will
+be called in parallel across the many devices that exist.
+.Pp
+There are certain occasions where a device driver may have to enter the
+.Sy p_mutex
+member of the
+.Xr usba_pipe_handle_data 9S
+structure when duplicating isochronous or interrupt requests. The USBA
+should in general, not hold this lock across calls to the HCD driver,
+and in turn, the HCD driver should not hold this lock across any calls
+back to the USBA. As such, the HCD driver should make sure to
+incorporate the lock ordering of this mutex into its broader lock
+ordering and operational theory. Generally, the
+.Sy p_mutex
+mutex will be entered after any HCD-specific locks.
+.Pp
+The final recommendation is that due to the fact that the host
+controller driver provides services to a multitude of USB devices at
+once, it should strive not to hold its own internal locks while waiting
+for I/O to complete, such as an issued command. This is particularly
+true if the device driver uses coarse grained locking. If the device
+driver does not pay attention to these conditions, it can easily lead to
+service stalls.
+.Ss Synchronous and Asynchronous Entry Points
+The majority of the entry points that a host controller driver has to
+implement are
+.Em synchronous .
+All actions that the entry point implies must be completed before the
+entry point returns. However, the various transfer routines:
+.Xr usba_hcdi_pipe_bulk_xfer 9E ,
+.Xr usba_hcdi_pipe_ctrl_xfer 9E ,
+.Xr usba_hcdi_pipe_intr_xfer 9E ,
+and
+.Xr usba_hcdi_pipe_isoc_xfer 9E ,
+are ultimately
+.Em asynchronous
+entry points.
+.Pp
+Each of the above entry points begins one-shot or periodic I/O. When the
+driver returns
+.Sy USB_SUCCESS
+from one of those functions, it is expected that it will later call
+.Xr usba_hcdi_cb 9F
+when the I/O completes, whether successful or not. It is the driver's
+responsibility to keep track of these outstanding transfers and time
+them out. For more information on timeouts, see the section
+.Sx Endpoint Timeouts .
+.Pp
+If for some reason, the driver fails to initialize the I/O transfer and
+indicates this by returning a value other than
+.Sy USB_SUCCESS
+from its entry point, then it must not call
+.Xr usba_hcdi_cb 9F
+for that transfer.
+.Ss Short Transfers
+Not all USB transfers will always return the full amount of data
+requested in the transfer. Host controller drivers need to be ready for
+this and report it. Each request structure has an attribute to indicate
+whether or not short transfers are OK. If a short transfer is OK, then
+the driver should update the transfer length. Otherwise, it should
+instead return an error. See the individual entry point pages for more
+information.
+.Ss Root Hub Management
+As was mentioned earlier, every host controller is also a root hub. The
+USBA interfaces with the root hub no differently than any other hub. The
+USBA will open pipes and issue both control and periodic interrupt-IN
+transfers to the root hub.
+.Pp
+In the host controller driver's
+.Xr usba_hcdi_pipe_open 9E
+entry point, it already has to look at the pipe handle it's been given
+to determine the attributes of the endpoint it's looking at. However,
+before it does that it needs to look at the USB address of the device
+the handle corresponds to. If the device address matches the macro
+.Sy ROOT_HUB_ADDR ,
+then this is a time where the USBA is opening one of the root hub's
+endpoints.
+.Pp
+Because the root hub is generally not a real device, the driver will
+likely need to handle this in a different manner from traditional pipes.
+.Pp
+The device driver will want to check for the presence of the device's
+address with the following major entry points and change its behavior as
+described:
+.Bl -tag -width Fn
+.It Fn usba_hcdi_pipe_ctrl_xfer
+The device driver needs to intercept control transfers to the root hub
+and translate them into the appropriate form for the device. For
+example, the device driver may be asked to get a port's status. It
+should determine the appropriate way to perform this, such as reading a
+PCI memory-mapped register, and then create the appropriate response.
+.Pp
+The device driver needs to implement all of the major hub specific
+request types. It is recommended that driver writers see what existing
+host controller drivers implement and what the hub driver currently
+requires to implement this.
+.Pp
+Aside from the fact that the request is not being issued to a specific
+USB device, a request to the root hub follows the normal rules for a
+transfer and the device driver will need to call
+.Xr usba_hcdi_cb 9F
+to indicate that it has finished.
+.It Fn usba_hcdi_pipe_bulk_xfer
+The root hub does not support bulk transfers. If for some reason one is
+requested on the root hub, the driver should return
+.Sy USB_NOT_SUPPORTED .
+.It Fn usba_hcdi_pipe_intr_xfer
+The root hub only supports periodic interrupt-IN transfers. If an
+interrupt-OUT transfer or an interrupt-IN transfer with the
+.Sy USB_ATTRS_ONE_XFER
+attribute is set, then the driver should return
+.Sy USB_NOT_SUPPORTED .
+.Pp
+Otherwise, this represents a request to begin polling on the status
+endpoint for a hub. This is a periodic request, see the section
+.Sx Device Addressing
+Every USB device has an address assigned to it. The addresses assigned
+to each controller are independent. The root hub of a given controller
+always has an address of
+.Dv ROOT_HUB_ADDR .
+.Pp
+In general, addresses are assigned by the USBA and stored in the
+.Sy usb_addr
+member of a
+.Xr usba_device_t 9S .
+However, some controllers, such as xHCI, require that they control the
+device addressing themselves to facilitate their functionality. In such
+a case, the USBA still assigns every device an address; however, the
+actual address on the bus will be different and assigned by the HCD
+driver.  An HCD driver that needs to address devices itself must
+implement the
+.Xr usba_hcdi_device_address 9E
+entry point.
+.Sx Endpoint Polling
+more on the semantics of polling and periodic requests.
+.Pp
+Here, the device driver will need to provide data and perform a callback
+whenever the state of one of the ports changes on its virtual hub.
+Different drivers have different ways to perform this. For example, some
+hardware will provide an interrupt to indicate that a change has
+occurred. Other hardware does not, so this must be simulated.
+.Pp
+The way that the status data responses must be laid out is based in the
+USB specification. Generally, there is one bit per port and the driver
+sets the bit for the corresponding port that has had a change.
+.It Fn usba_hcdi_pipe_isoc_xfer
+The root hub does not support isochronous transfers. If for some reason
+one is requested on the root hub, the driver should return
+.It Fn usba_hcdi_pipe_close
+When a pipe to the root hub is closed, the device driver should tear
+down whatever it created as part of opening the pipe. In addition, if
+the pipe was an interrupt-IN pipe, if it has not already had polling
+stop, it should stop the polling as part of closing the pipe.
+.It Fn usba_hcdi_pipe_stop_intr_polling
+When a request to stop interrupt polling comes in and it is directed
+towards the root hub, the device driver should cease delivering
+callbacks upon changes in port status being detected. However, it should
+continue keeping track of what changes have occurred for the next time
+that polling starts.
+.Pp
+The primary request that was used to start polling should be returned,
+as with any other request to stop interrupt polling.
+.It Fn usba_hcdi_pipe_stop_isoc_polling
+The root hub does not support isochronous transfers. If for some reason
+it calls asking to stop polling on an isochronous transfer, the device
+driver should log an error and return
+.Sy USB_NOT_SUPPORTED .
+.El
+.Ss Endpoint Polling
+Both interrupt-IN and isochronous-IN endpoints are generally periodic or
+polled endpoints. interrupt-IN polling is indicated by the lack of the
+.Sy USB_ATTRS_ONE_XFER
+flag being set. All isochronous-IN transfer requests are requests for
+polling.
+.Pp
+Polling operates in a different fashion from traditional transfers. With
+a traditional transfer, a single request is made and a single callback
+is made for it, no more and no less. With a polling request, things are
+different. A single transfer request comes in; however, the driver needs
+to keep ensuring that transfers are being made within the polling bounds
+until a request to stop polling comes in or a fatal error is
+encountered.
+.Pp
+In many cases, as part of initializing the request, the driver will
+prepare several transfers such that there is always an active transfer,
+even if there is some additional latency in the system. This ensures
+that even if there is a momentary delay in the device driver processing
+a given transfer, I/O data will not be lost.
+.Pp
+The driver must not use the original request structure until it is ready
+to return due to a request to stop polling or an error. To obtain new
+interrupt and isochronous request structures, the driver should use the
+.Xr usba_hcdi_dup_intr_req 9F
+and
+.Xr usba_hcdi_dup_isoc_req 9F
+functions. These functions also allocate the resulting message blocks
+that data should be copied into. Note, it is possible that memory will
+not be available to duplicate such a request. In this case, the driver
+should use the original request to return an error and stop polling.
+.Ss Request Memory and DMA
+Each of the four transfer operations,
+.Xr usba_hcdi_pipe_ctrl_xfer 9E ,
+.Xr usba_hcdi_pipe_bulk_xfer 9E ,
+.Xr usba_hcdi_pipe_intr_xfer 9E ,
+and
+.Xr usba_hcdi_pipe_isoc_xfer 9E
+give data to hcdi drivers in the form of
+.Xr mblk 9S
+structures. To perform the individual transfers, most systems devices
+will leverage DMA. Drivers should allocate memory suitable for DMA for
+each transfer that they need to perform and copy the data to and from
+the message blocks.
+.Pp
+Device drivers should not use
+.Xr desballoc 9F
+to try and bind the memory used for DMA transfers to a message block nor
+should they bind the message block's read pointer to a DMA handle using
+.Xr ddi_dma_addr_bind_handle 9F .
+.Pp
+While this isn't a strict rule, the general framework does not assume
+that there are going to be outstanding message blocks that may be in use
+by the controller or belong to the controller outside of the boundaries
+of a given call to one of the transfer functions and its corresponding
+callback.
+.Ss Endpoint Timeouts
+The host controller is in charge of watching I/Os for timeouts. For any
+request that's not periodic (an interrupt-IN or isochronous-IN)
+transfer, the host controller must set up a timeout handler. If that
+timeout expires, it needs to stop the endpoint, remove that request, and
+return to the caller.
+.Pp
+The timeouts are specified in seconds in the request structures. For
+bulk timeouts, the request is in the
+.Sy bulk_timeout
+member of the
+.Xr usb_bulk_req 9S
+structure. The interrupt and control transfers also have a similar
+member in their request structures, see
+.Xr usb_intr_req 9S
+and
+.Xr usb_ctrl_req 9S .
+If any of the times is set to zero, the default USBA timeout should be
+used. In that case, drivers should set the value to the macro
+.Sy HCDI_DEFAULT_TIMEOUT ,
+which is a time in seconds.
+.Pp
+Isochronous-OUT transfers do not have a timeout defined on their request
+structure, the
+.Xr usb_isoc_req 9S .
+Due to the periodic nature of even outbound requests, it is less likely
+that a timeout will occur; however, driver writers are encouraged to
+still set up the default timeout,
+.Sy HCDI_DEFAULT_TIMEOUT ,
+on those transfers.
+.Pp
+The exact means of performing the timeout is best left to the driver
+writer as the way that hardware exposes scheduling of different
+endpoints will vary. One strategy to consider is to use the
+.Xr timeout 9F
+function at a one second period while I/O is ongoing on a per-endpoint
+basis. Because the time is measured in seconds, a driver writer can
+decrement a counter for a given outstanding transfer once a second and
+then if it reaches zero, interject and stop the endpoint and clean up.
+.Pp
+This has the added benefit that when no I/O is scheduled, then there
+will be no timer activity, reducing overall system load.
+.Ss Notable Types and Structures
+The following are data structures and types that are used throughout
+host controller drivers:
+.Bl -tag -width Vt
+.It Sy usb_cfg_descr
+The configuration descriptor. A device may have one or more
+configurations that it supports that can be switched between. The
+descriptor is documented in
+.Xr usb_cfg_descr 9S .
+.It Sy usb_dev_descr
+The device descriptor. A device descriptor contains basic properties of
+the device such as the USB version, device and vendor information, and
+the maximum packet size. This will often be used when setting up a
+device for the first time. It is documented in
+.Xr usb_dev_descr 9S .
+.It Sy usb_ep_descr
+The endpoint descriptor. An endpoint descriptor contains the basic
+properties of an endpoints such as its type and packet size. Every
+endpoint on a given USB device has an endpoint descriptor. It is
+documented in
+.Xr usb_ep_descr 9S .
+.It Sy usb_xep_descr
+The extended endpoint descriptor. This structure is used to contain the
+endpoint descriptor, but also additional endpoint companion descriptors
+which are a part of newer USB standards. It is documented in
+.Xr usb_ep_xdescr 9S .
+.It Sy usb_bulk_req
+This structure is filled out by client device drivers that want to make
+a bulk transfer request. Host controllers use this and act on it to
+perform bulk transfers to USB devices. The structure is documented in
+.Xr usb_bulk_req 9S .
+.It Sy usb_ctrl_req
+This structure is filled out by client device drivers that want to make
+a control transfer request. Host controllers use this and act on it to
+perform bulk transfers to USB devices. The structure is documented in
+.Xr usb_ctrl_req 9S .
+.It Sy usb_intr_req
+This structure is filled out by client device drivers that want to make
+an interrupt transfer request. Host controllers use this and act on it to
+perform bulk transfers to USB devices. The structure is documented in
+.Xr usb_intr_req 9S .
+.It Sy usb_isoc_req
+This structure is filled out by client device drivers that want to make
+an isochronous transfer request. Host controllers use this and act on it to
+perform bulk transfers to USB devices. The structure is documented in
+.Xr usb_isoc_req 9S .
+.It Vt usb_flags_t
+These define a set of flags that are used on certain entry points. These
+generally determine whether or not the entry points should block for
+memory allocation. Individual manual pages indicate the flags that
+drivers should consult.
+.It Vt usb_port_status_t
+The
+.Sy usb_port_status_t
+determines the current negotiated speed of the device. The following are
+valid values that this may be:
+.Bl -tag -width Sy
+.It Sy USBA_LOW_SPEED_DEV
+The device is running as a low speed device. This may be a USB 1.x or
+USB 2.0 device.
+.It Sy USBA_FULL_SPEED_DEV
+The device is running as a full speed device. This may be a USB 1.x or
+USB 2.0 device.
+.It Sy USBA_HIGH_SPEED_DEV
+The device is running as a high speed device. This is a USB 2.x device.
+.It Sy USBA_SUPER_SPEED_DEV
+The device is running as a super speed device. This is a USB 3.0 device.
+.It Vt usb_cr_t
+This is a set of codes that may be returned as a part of the call to
+.Xr usb_hcdi_cb 9F .
+The best place for the full set of these is currently in the source
+control headers.
+.El
+.El
+.Ss Interrupts
+While some hardware supports more than one interrupt queue, a single
+interrupt is generally sufficient for most host controllers. If the
+controller supports interrupt coalescing, then the driver should
+generally enable it and set it to a moderate rate.
+.Ss driver.conf considerations
+Due to the way host controller drivers need to interact with hotplug,
+drivers should generally set the
+.Sy ddi-forceattach
+property to one in their
+.Xr driver.conf 4
+file.
+.Sh SEE ALSO
+.Xr driver.conf 4 ,
+.Xr hubd 7D ,
+.Xr usba 7D ,
+.Xr attach 9E ,
+.Xr close 9E ,
+.Xr detach 9E ,
+.Xr getinfo 9E ,
+.Xr ioctl 9E ,
+.Xr open 9E ,
+.Xr usba_hcdi_bulk_xfer 9E ,
+.Xr usba_hcdi_cb_close 9E ,
+.Xr usba_hcdi_cb_ioctl 9E ,
+.Xr usba_hcdi_cb_open 9E ,
+.Xr usba_hcdi_pipe_bulk_xfer 9E ,
+.Xr usba_hcdi_pipe_ctrl_xfer 9E ,
+.Xr usba_hcdi_pipe_intr_xfer 9E ,
+.Xr usba_hcdi_pipe_isoc_xfer 9E ,
+.Xr usba_hcdi_pipe_open 9E ,
+.Xr ddi_dma_addr_bind_handle 9F ,
+.Xr ddi_get_driver_private 9F ,
+.Xr ddi_prop_op 9F ,
+.Xr desballoc 9F ,
+.Xr nochpoll 9F ,
+.Xr nodev 9F ,
+.Xr timeout 9F ,
+.Xr usb_hcdi_bind_root_hub 9F ,
+.Xr usb_hubdi_bind_root_hub 9F ,
+.Xr usba_alloc_hcdi_ops 9F ,
+.Xr usba_hcdi_cb 9F ,
+.Xr usba_hcdi_dup_intr_req 9F ,
+.Xr usba_hcdi_dup_isoc_req 9F ,
+.Xr usba_hcdi_register 9F ,
+.Xr usba_hcdi_unregister 9F ,
+.Xr usba_hubdi_close 9F ,
+.Xr usba_hubdi_devops 9F ,
+.Xr usba_hubdi_Devops 9F ,
+.Xr usba_hubdi_ioctl 9F ,
+.Xr usba_hubdi_open 9F ,
+.Xr usba_hubdi_unbind_root_hub 9F ,
+.Xr usb_hcdi_bind_root_hub 9F. ,
+.Xr cb_ops 9S ,
+.Xr dev_ops 9S ,
+.Xr mblk 9S ,
+.Xr usb_bulk_req 9S ,
+.Xr usb_cfg_descr 9S ,
+.Xr usb_ctrl_req 9S ,
+.Xr usb_dev_descr 9S ,
+.Xr usb_ep_descr 9S ,
+.Xr usb_ep_ss_comp_descr 9S ,
+.Xr usb_if_descr 9S ,
+.Xr usb_intr_req 9S ,
+.Xr usb_isoc_req 9S ,
+.Xr usba_hcdi_ops 9S
diff --git a/usr/src/man/man9e/usba_hcdi_cb_ops.9e b/usr/src/man/man9e/usba_hcdi_cb_ops.9e
new file mode 100644
index 0000000000..a7ea0555aa
--- /dev/null
+++ b/usr/src/man/man9e/usba_hcdi_cb_ops.9e
@@ -0,0 +1,227 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 20, 2016
+.Dt USBA_HCDI_CB_OPS 9E
+.Os
+.Sh NAME
+.Nm usba_hcdi_cb_ops ,
+.Nm usba_hcdi_cb_open ,
+.Nm usba_hcdi_cb_ioctl ,
+.Nm usba_hcdi_cb_close
+.Nd USBA HCD Character Device character functions
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/file.h
+.In sys/errno.h
+.In sys/open.h
+.In sys/cred.h
+.In sys/ddi.h
+.In sys/sunddi.h
+.Ft int
+.Fo prefix_open
+.Fa "dev_t *devp"
+.Fa "int flag"
+.Fa "int otyp"
+.Fa "cred_t *credp"
+.Fc
+.Ft int
+.Fo prefix_ioctl
+.Fa "dev_t dev"
+.Fa "int cmd"
+.Fa "intptr_t arg"
+.Fa "int mode"
+.Fa "cred_t *cred_p"
+.Fa "int *rval_p"
+.Fc
+.Ft int
+.Fo prefix_close
+.Fa "dev_t dev"
+.Fa "int flag"
+.Fa "int otyp"
+.Fa "cred_t *cred_p"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This describes private interfaces that are not part of the stable DDI.
+This may be removed or changed at any time.
+.Sh PARAMETERS
+For parameter descriptions, see
+.Xr open 9E ,
+.Xr ioctl 9E ,
+and
+.Xr close 9E .
+.Sh DESCRIPTION
+The entry points listed here are the traditional character device
+.Xr open 9E ,
+.Xr ioctl 9E ,
+and
+.Xr close 9E
+entry points. As discussed in
+.Xr usba_hcdi 9E
+all HCD drivers are required to implement these functions and vector
+them to
+.Xr usba_hubdi_open 9F ,
+.Xr usba_hubdi_ioctl 9F ,
+and
+.Xr usba_hubdi_close 9F
+respectively. For background information on these functions and how they
+interact in the broader operating system, please see the general manual pages
+.Xr open 9E ,
+.Xr ioctl 9E ,
+and
+.Xr close 9E .
+.Pp
+The arguments between the two types of functions are slightly different.
+The
+.Sx EXAMPLES
+section provides a sketch for how most HCD drivers should perform those
+transformations.
+.Pp
+One important distinction from the traditional character routines is
+that the USBA controls a bit more of the minor space. Therefore, the
+driver needs to take extra care around the values encoded in the
+.Sy dev_t
+and it should not perform any cloning or renumbering in its
+.Xr open 9E
+entry point.
+.Sh EXAMPLES
+The following example is adapated from the
+.Xr xhci 7D
+driver which shows how an HCD driver might arrange things. This assumes
+that a driver is following the recommendations in
+.Xr usba_hcdi 9E
+and has initialized a soft state structure through the
+.Xr ddi_soft_state_init 9F
+function. This design also requires that the soft state structure
+contains a pointer to the
+.Sy dev_info_t
+structure during its
+.Xr attach 9E callback.
+.Pp
+This example does not stand alone, it will need to be adapted for a
+driver:
+.Bd -literal
+#include <sys/types.h>
+#include <sys/file.h>
+#include <sys/errno.h>
+#include <sys/open.h>
+#include <sys/cred.h>
+#include <sys/ddi.h>
+#include <sys/sunddi.h>
+
+static void *prefix_soft_state;
+
+/*
+ * Per-instance structure
+ */
+typedef struct prefix {
+	dev_info_t	*prefix_dev_info;
+	...
+} prefix_t;
+
+static dev_info_t *
+prefix_get_dip(dev_t dev)
+{
+	prefix_t *p;
+	int instance = getminor(dev) & ~HUBD_IS_ROOT_HUB;
+
+	p = ddi_get_soft_state(prefix_soft_state, instance);
+	if (p != NULL)
+		return (p->prefix_dip);
+	return (NULL);
+}
+
+static int
+prefix_open(dev_t *devp, int flags, int otyp, cred_t *credp)
+{
+	dev_info_t *dip = prefix_get_dip(*devp);
+
+	return (usba_hubdi_open(dip, devp, flags, otyp, credp));
+}
+
+static int
+prefix_ioctl(dev_t dev, int cmd, intptr_t arg, int mode, cred_t *credp,
+    int *rvalp)
+{
+	dev_info_t *dip = prefix_get_dip(dev);
+
+	/* Potentially handle private ioctls */
+
+	return (usba_hubdi_ioctl(dip, dev, cmd, arg, mode, credp, rvalp));
+}
+
+static int
+prefix_close(dev_t dev, int flag, int otyp, cred_t *credp)
+{
+	dev_info_t *dip = prefix_get_dip(dev);
+
+	return (usba_hubdi_close(dip, dev, flag, otyp, credp));
+}
+
+static int
+prefix_attach(dev_info_t *dip, ddi_attach_cmd_t cmd)
+{
+	int instance;
+	prefix_t *p;
+
+	/* Perform normal checking of cmd */
+
+	instance = ddi_get_instance(dip);
+	if (ddi_soft_state_zalloc(prefix_soft_state, inst) != 0)
+		return (DDI_FAILURE);
+	p = ddi_get_soft_state(prefix_soft_state, instance);
+	p->prefix_dev_info = dip;
+
+	/* Continue with normal attach(9E) initialization */
+}
+
+int
+_init(void)
+{
+	int ret;
+
+	if ((ret = ddi_soft_state_init(&prefx_soft_state, sizeof (prefx_t),
+	    0)) != 0) {
+		return (ret);
+	}
+
+	/* Perform normal module initialization here */
+
+	return (ret);
+}
+
+int
+_fini(void)
+{
+
+	/* Perform normal module teardown first */
+
+	ddi_soft_state_fini(&prefix_soft_state);
+
+	return (0);
+}
+.Ed
+.Sh SEE ALSO
+.Xr xhci 7D ,
+.Xr attach 9E ,
+.Xr close 9E ,
+.Xr ioctl 9E ,
+.Xr open 9E ,
+.Xr usba_hcdi 9E ,
+.Xr ddi_soft_state_init 9F ,
+.Xr usba_hubdi_close 9F ,
+.Xr usba_hubdi_ioctl 9F ,
+.Xr usba_hubdi_open 9F
diff --git a/usr/src/man/man9e/usba_hcdi_device_address.9e b/usr/src/man/man9e/usba_hcdi_device_address.9e
new file mode 100644
index 0000000000..8baf679752
--- /dev/null
+++ b/usr/src/man/man9e/usba_hcdi_device_address.9e
@@ -0,0 +1,83 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 20, 2016
+.Dt USBA_HCDI_HUB_UPDATE 9E
+.Os
+.Sh NAME
+.Nm usba_hcdi_device_address
+.Nd Assign USB address to device
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft int
+.Fo prefix_hcdi_device_address
+.Fa "usba_device_t *ud"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa ud
+Pointer to a USB device structure being updated. See
+.Xr usba_device 9S
+for more information.
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_device_address
+entry point is an optional entry point for USB host controller drivers.
+Some USB host controllers do not allow the USB SET_ADDRESS command to be
+issued to a device. Instead, they will be responsible for setting the
+address in a controller-specific way. If the host controller driver
+requires this behavior, then it must implement this function. Otherwise,
+if the host controller does not require this functionality, it should
+set the entry point in the
+.Xr usba_hcdi_ops 9S
+structure to
+.Dv NULL .
+.Pp
+The USBA will always set an address for the USBA device
+.Fa ud
+regardless of whether or not this function is implemented. If the HCD
+implements this entry point and it needs the addressing information for
+whatever reason, then it is the responsibility of the driver to keep
+track of it separately.
+.Pp
+This entry point will be called after the
+.Xr usba_hcdi_device_init 9E
+entry point has been called. Any private data stored on the device will
+be available through the
+.Xr usba_hcdi_get_device_private 9F
+function.
+.Pp
+Upon completion of the function, the device is expected to be addressed
+and thus able to have endpoints opened and transfers performed on them.
+If this function fails, the device's enumeration will halt.
+.Sh CONTEXT
+This function is called from kernel context ontly.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_device_address
+function should return
+.Sy USB_SUCCESS .
+Otherwise, it should return the appropriate USB error. If uncertain, use
+.Sy USB_FAILURE .
+.Sh SEE ALSO
+.Xr usba_hcdi_device_init 9E ,
+.Xr usba_hcdi_get_device_private 9F ,
+.Xr usba_device 9S ,
+.Xr usba_hcdi_ops 9S
diff --git a/usr/src/man/man9e/usba_hcdi_device_init.9e b/usr/src/man/man9e/usba_hcdi_device_init.9e
new file mode 100644
index 0000000000..932586b3c5
--- /dev/null
+++ b/usr/src/man/man9e/usba_hcdi_device_init.9e
@@ -0,0 +1,106 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd May 7, 2016
+.Dt USBA_HCDI_DEVICE_INIT 9E
+.Os
+.Sh NAME
+.Nm usba_hcdi_device_init ,
+.Nm usba_hcdi_device_fini
+.Nd USB device initialization and finalization
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft int
+.Fo prefix_hcdi_device_init
+.Fa "usba_device_t *usb_device"
+.Fa "usb_port_t port"
+.Fa "void **hcd_privatep"
+.Fc
+.Ft void
+.Fo prefix_hcdi_device_fini
+.Fa "usba_device_t *usb_device"
+.Fa "usb_port_t port"
+.Fa "void *hcd_private"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa usb_device
+Pointer to a USB device structure.
+.It Fa port
+The port number the device was detected on.
+.It Fa hcd_privatep
+Pointer to storage space for a HCD driver to store private data for the
+device.
+.It Fa hcd_private
+Pointer to the HCD driver's private data for the device.
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_device_init
+entry point is an optional entry point. It will be called when child
+devices of the root hub are being initialized. A call to this entry
+point will occur before any calls to open a pipe to the child device
+through the
+.Xr usba_hcdi_pipe_open 9E
+entry point.
+.Pp
+During this time, the HCD driver should do any required initialization
+required by the host controller. The HCD may also opt to store private
+data for this device as a result of whatever initialization it
+performed. The data should be stored in the
+.Fa hcd_privatep
+pointer. Data stored this will be accessible to the HCD driver through
+the
+.Xr usba_hcdi_get_device_private 9F
+function.
+.Pp
+The
+.Fn usba_hcdi_device_fini
+entry point is an optional entry point. It will be called when child
+devices of the root hub are being removed. The HCD should perform any
+necessary work with the root controller to finish tearing down the
+device. In addition, if the HCD stored private data it will a pointer to
+it in the
+.Fa hcd_private
+pointer. The HCD driver must release any resources associated with its
+private data. If it does not, the resources will be leaked.
+.Pp
+At the time
+.Fn usba_hcdi_device_fini
+is called, all associated pipes should have been closed through the
+.Xr usba_hcdi_pipe_close 9E
+function.
+.Pp
+The HCD driver is guaranteed that no other entry points will be invoked
+for the USB device
+.Fa usb_device
+while a call to either function is ongoing. However, the entry point may
+be called in parallel on behalf of separate devices.
+.Sh CONTEXT
+This function is called from kernel context only.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_device_init
+function should return
+.Sy USB_SUCCECSS .
+Otherwise, it should return the appropriate error.
+.Sh SEE ALSO
+.Xr usba_hcd 9E ,
+.Xr usba_hcdi_pipe_close 9E ,
+.Xr usba_hcdi_pipe_open 9E
diff --git a/usr/src/man/man9e/usba_hcdi_hub_update.9e b/usr/src/man/man9e/usba_hcdi_hub_update.9e
new file mode 100644
index 0000000000..141b296580
--- /dev/null
+++ b/usr/src/man/man9e/usba_hcdi_hub_update.9e
@@ -0,0 +1,88 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 20, 2016
+.Dt USBA_HCDI_HUB_UPDATE 9E
+.Os
+.Sh NAME
+.Nm usba_hcdi_hub_update
+.Nd USB HCD hub update entry point
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft int
+.Fo prefix_hcdi_hub_update
+.Fa "usba_device_t *ud"
+.Fa "uint8_t nports"
+.Fa "uint8_t tt"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa ud
+Pointer to a USB device structure being updated. See
+.Xr usba_device 9S
+for more information.
+.It Fa nports
+The number of ports present on the hub.
+.It Fa tt
+The value of the Think Time property as defined in the USB
+specification's hub descriptor.
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_hub_update
+entry point is an optional entry point for USB host controller drivers.
+It is used by some controllers to allow them to update information about
+a device in the controller after a device has been determined to be a
+hub during enumeration. If a host controller does not need to take any
+specific action after enumerating a hub, then it should simply set this
+entry point in the
+.Xr usba_hcdi_ops 9S
+structure to
+.Dv NULL .
+.Pp
+The
+.Fa nports
+and
+.Fa tt
+members provide relevant information from the device's hub class
+descriptor which can be used to help program the host controller. Any
+programming should be performed synchronously and be completed before
+this function returns.
+.Pp
+This function will be called after
+.Xr usba_hcdi_device_init 9E
+has been called. Any private data registered with that function will be
+available.
+.Pp
+If this function fails, the enumeration of this device will fail, the
+hub driver will not attach to this USB device, and all devices plugged
+into this hub will not be detected by the system.
+.Sh CONTEXT
+This functin is called from kernel context only.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_hub_update
+function should return
+.Sy USB_SUCCESS .
+Otherwise, it should return the appropriate USB error. If uncertain, use
+.Sy USB_FAILURE .
+.Sh SEE ALSO
+.Xr usba_hcdi_device_init 9E ,
+.Xr usba_device 9S ,
+.Xr usba_hcdi_ops 9S
diff --git a/usr/src/man/man9e/usba_hcdi_pipe_bulk_xfer.9e b/usr/src/man/man9e/usba_hcdi_pipe_bulk_xfer.9e
new file mode 100644
index 0000000000..67db98717a
--- /dev/null
+++ b/usr/src/man/man9e/usba_hcdi_pipe_bulk_xfer.9e
@@ -0,0 +1,177 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 22, 2016
+.Dt USBA_HCDI_PIPE_BULK_XFER 9E
+.Os
+.Sh NAME
+.Nm usba_hcdi_pipe_bulk_xfer
+.Nd perform a USB bulk transfer
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft int
+.Fo prefix_hcdi_pipe_bulk_xfer
+.Fa "usba_pipe_handle_data_t *ph"
+.Fa "usb_bulk_req_t *ubrp"
+.Fa "usb_flags_t usb_flags"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa ph
+A pointer to a USB pipe handle as defined in
+.Xr usba_pipe_handle_data 9S .
+.It Fa ubrp
+A pointer to a USB bulk transfer request. The structure's members are
+documented in
+.Xr usb_bulk_req 9S .
+.It Fa usb_flags
+Flags which describe how allocations should be performed. Valid flags
+are:
+.Bl -tag -width Sy
+.It Sy USB_FLAGS_NOSLEEP
+Do not block waiting for memory. If memory is not available the allocation
+will fail.
+.It Sy USB_FLAGS_SLEEP
+Perform a blocking allocation. If memory is not available, the function
+will wait until memory is made available.
+.Pp
+Note, the request may still fail even if
+.Sy USB_FLAGS_SLEEP
+is specified.
+.El
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_pipe_bulk_xfer
+entry point is used to initiate an
+.Em asynchronous
+USB bulk transfer on the pipe
+.Fa ph .
+The specific USB bulk transfer is provided in
+.Fa ubrp .
+For more background on transfer types, see
+.Xr usba_hcdi 9E .
+.Pp
+The host controller driver should first check the USB address of the
+pipe handle. It may correspond to the root hub. If it does, the driver
+should return
+.Sy USB_NOT_SUPPORTED .
+.Pp
+Bulk transfers may send data to the device or receive data from the
+device. A given bulk endpoint is uni-directional. The direction can be
+determined from the endpoint address based on the
+.Sy p_ep
+member of
+.Fa ubrp .
+See
+.Xr usb_ep_descr 9S
+for more information on how to determine the direction of the endpoint.
+.Pp
+The device driver should allocate memory, whether memory suitable for a
+DMA transfer or otherwise, to perform the transfer. For all memory
+allocated, it should honor the values in
+.Fa usb_flags
+to determine whether or not it should block for allocations.
+.Pp
+The length of the bulk transfer and its data can be found in the
+.Sy bulk_len
+and
+.Sy bulk_data
+members of
+.Fa ubrp
+respectively. The
+.Xr mblk 9S
+structure that should not be used directly and data should be copied to
+or from the data buffer that will go the controller.
+.Pp
+If the driver successfully schedules the I/O, then it should return
+.Sy USB_SUCCESS .
+When the I/O completes, it must call
+.Xr usba_hcdi_cb 9F
+with
+.Fa ubrp .
+If the transfer fails, but the driver returned
+.Sy USB_SUCCESS ,
+it still must call
+.Xr usba_hcdi_cb 9F
+and should specify an error there.
+.Pp
+It is the driver's responsibility to time out bulk transfer
+requests. If the timeout in the request as indicated in the
+.Sy bulk_timeout
+member of
+.Fa ubrp
+is set to zero, then the driver should use the USBA default timeout of
+.Sy HCDI_DEFAULT_TIMEOUT .
+All timeout values are in
+.Em seconds .
+.Ss Callback Handling
+When the bulk transfer completes the driver should consider the
+following items to determine what actions it should take on the
+callback:
+.Bl -bullet
+.It
+If the transfer timed out, it should remove the transfer from the
+outstanding list, queue the next transfer, and return the transfer back
+to the OS with the error code
+.Sy USB_CR_TIMEOUT
+with
+.Xr usba_hcdi_cb 9F .
+.It
+If the transfer failed, it should find the appropriate error and call
+.Xr usba_hcdi_cb 9F
+with that error.
+.It
+If the transfer succeeded, but less data was transferred than expected,
+consult the
+.Sy bulk_attributes
+member of the
+.Fa ubrp .
+If the
+.Sy USB_ATTRS_SHORT_XFER_OK
+flag is not present, then the driver should call
+.Xr usba_hcdi_cb 9F
+with the error
+.Sy USB_CR_DATA_UNDERRUN .
+.It
+If the transfer was going to the host, then the driver should copy the
+data into the transfer's message block and update the
+.Sy b_wptr
+member of the
+.Xr mblk 9S .
+.It
+If everything was successful, call
+.Xr usba_hcdi_cb 9F
+with the code
+.Sy USB_CR_OK .
+.El
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_pipe_bulk_xfer
+function should return
+.Sy USB_SUCCESS .
+Otherwise, it should return the appropriate USB error. If uncertain, use
+.Sy USB_FAILURE .
+.Sh SEE ALSO
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_cb 9F ,
+.Xr mblk 9S ,
+.Xr usb_bulk_req 9S ,
+.Xr usb_ep_descr 9S ,
+.Xr usba_pipe_handle_data 9S
diff --git a/usr/src/man/man9e/usba_hcdi_pipe_ctrl_xfer.9e b/usr/src/man/man9e/usba_hcdi_pipe_ctrl_xfer.9e
new file mode 100644
index 0000000000..8d4788bc51
--- /dev/null
+++ b/usr/src/man/man9e/usba_hcdi_pipe_ctrl_xfer.9e
@@ -0,0 +1,189 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 22, 2016
+.Dt USBA_HCDI_PIPE_CTRL_XFER 9E
+.Os
+.Sh NAME
+.Nm usba_hcdi_pipe_ctrl_xfer
+.Nd perform a USB control transfer
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft int
+.Fo prefix_hcdi_pipe_ctrl_xfer
+.Fa "usba_pipe_handle_data_t *ph"
+.Fa "usb_ctrl_req_t *ucrp"
+.Fa "usb_flags_t usb_flags"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa ph
+A pointer to a USB pipe handle as defined in
+.Xr usba_pipe_handle_data 9S .
+.It Fa ucrp
+A pointer to a USB control transfer request. The structure's members are
+documented in
+.Xr usb_ctrl_req 9S .
+.It Fa usb_flags
+Flags which describe how allocations should be performed. Valid flags
+are:
+.Bl -tag -width Sy
+.It Sy USB_FLAGS_NOSLEEP
+Do not block waiting for memory. If memory is not available the allocation
+will fail.
+.It Sy USB_FLAGS_SLEEP
+Perform a blocking allocation. If memory is not available, the function
+will wait until memory is made available.
+.Pp
+Note, the request may still fail even if
+.Sy USB_FLAGS_SLEEP
+is specified.
+.El
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_pipe_ctrl_xfer
+entry point is used to initiate an
+.Em asynchronous
+USB Control transfer on the pipe
+.Fa ph .
+The specific USB control transfer is provided in
+.Fa ucrp .
+For more background on transfer types, see
+.Xr usba_hcdi 9E .
+.Pp
+The host controller driver should first check the USB address of the
+pipe handle. It may correspond to the root hub. If it does, rather than
+initiating an I/O transfer, the driver may need to emulate it using
+available information.
+.Pp
+Control endpoints are always bi-directional. A given endpoint may
+perform transfer data from the OS to the device, or from the device to
+the OS. The driver will need to look at the control transfer request and
+transform that into the appropriate format for the controller.
+.Pp
+Control transfers are made up of three parts. A setup stage, an optional
+data stage, and a status stage. Depending on the controller, the driver
+may need to transform the transfer request into a format that matches
+this. Refer to the device's controller specification for more
+information on whether this is required or not.
+.Pp
+The device driver should a request based on the information present in
+the control request
+.Fa ucrp .
+If there is a non-zero length for the transfer, indicated by the
+.Sy ctrl_wLength
+member of
+.Fa ucrp
+being greater than zero, then the controller needs to allocate a
+separate memory buffer for the request. The corresponding data will be
+found in an
+.Xr mblk 9S
+structure as the
+.Sy ctrl_data
+member of
+.Fa ucrp .
+.Pp
+If this transfer needs to be sent to a device through the controller and
+is not being handled directly by the driver, then the driver should
+allocate a separate region of memory (generally memory suitable for a
+DMA transfer) for the transfer. If sending data to the device, the data
+in the message block should be copied prior to the transfer. Otherwise,
+once the transfer completes, data should be transferred into the message
+block and the write pointer incremented.
+.Pp
+If the driver needs to allocate memory for this transfer, it should
+honor the values set in
+.Fa usb_flags
+to indicate whether or not it should block for memory, whether DMA
+memory or normal kernel memory.
+.Pp
+If the driver successfully schedules the I/O or it can handle the I/O
+itself because it's a synthetic root hub request, then it should return
+.Sy USB_SUCCESS .
+If the driver returns successfully, it must call
+.Xr usba_hcdi_cb 9F
+with
+.Fa ucrp
+either before or after it returns. The only times that a driver would
+call the callback before the function returns are for requests to the
+root hub that it handles inline and does not need to send off
+asynchronous activity to the controller.
+.Pp
+For asynchronous requests, the controller is also responsible for
+timing out the request if it does not complete. If the timeout in the
+request as indicated in the
+.Sy ctrl_timeout
+member is set to zero, then the driver should use the USBA default
+timeout of
+.Sy HCDI_DEFAULT_TIMEOUT .
+All timeout values are in
+.Em seconds .
+.Ss Callback Handling
+When the control transfer completes the driver should consider the
+following items to determine what actions it should take on the callback:
+.Bl -bullet
+.It
+If the transfer timed out, it should remove the transfer from the
+outstanding list, queue the next transfer, and return the transfer back
+to the OS with the error code
+.Sy USB_CR_TIMEOUT
+with
+.Xr usba_hcdi_cb 9F .
+.It
+If the transfer failed, it should find the appropriate error and call
+.Xr usba_hcdi_cb 9F
+with that error.
+.It
+If the transfer succeeded, but less data was transferred than expected,
+consult the
+.Sy ctrl_attributes
+member of the
+.Fa ucrp .
+If the
+.Sy USB_ATTRS_SHORT_XFER_OK
+flag is not present, then the driver should call
+.Xr usba_hcdi_cb 9F
+with the error
+.Sy USB_CR_DATA_UNDERRUN .
+.It
+If the transfer was going to the host, then the driver should copy the
+data into the transfer's message block and update the
+.Sy b_wptr
+member of the
+.Xr mblk 9S .
+.It
+If everything was successful, call
+.Xr usba_hcdi_cb 9F
+with the code
+.Sy USB_CR_OK .
+.El
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_pipe_ctrl_xfer
+function should return
+.Sy USB_SUCCESS .
+Otherwise, it should return the appropriate USB error. If uncertain, use
+.Sy USB_FAILURE .
+.Sh SEE ALSO
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_cb 9F ,
+.Xr mblk 9S ,
+.Xr usb_ctrl_req 9S ,
+.Xr usba_pipe_handle_data 9S
diff --git a/usr/src/man/man9e/usba_hcdi_pipe_intr_xfer.9e b/usr/src/man/man9e/usba_hcdi_pipe_intr_xfer.9e
new file mode 100644
index 0000000000..c2031d15f7
--- /dev/null
+++ b/usr/src/man/man9e/usba_hcdi_pipe_intr_xfer.9e
@@ -0,0 +1,263 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 22, 2016
+.Dt USBA_HCDI_PIPE_INTR_XFER 9E
+.Os
+.Sh NAME
+.Nm usba_hcdi_pipe_intr_xfer
+.Nd perform a USB interrupt transfer
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft int
+.Fo prefix_hcdi_pipe_intr_xfer
+.Fa "usba_pipe_handle_data_t *ph"
+.Fa "usb_intr_req_t *uirp"
+.Fa "usb_flags_t usb_flags"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa ph
+A pointer to a USB pipe handle as defined in
+.Xr usba_pipe_handle_data 9S .
+.It Fa uirp
+A pointer to a USB interrupt transfer request. The structure's members
+are documented in
+.Xr usb_intr_req 9S .
+.It Fa usb_flags
+Flags which describe how allocations should be performed. Valid flags
+are:
+.Bl -tag -width Sy
+.It Sy USB_FLAGS_NOSLEEP
+Do not block waiting for memory. If memory is not available the allocation
+will fail.
+.It Sy USB_FLAGS_SLEEP
+Perform a blocking allocation. If memory is not available, the function
+will wait until memory is made available.
+.Pp
+Note, the request may still fail even if
+.Sy USB_FLAGS_SLEEP
+is specified.
+.El
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_pipe_intr_xfer
+entry point is used to initiate an
+.Em asynchronous
+USB interrupt transfer on the pipe
+.Fa ph .
+The specific USB interrupt transfer is provided in
+.Fa uirp .
+For more background on transfer types, see
+.Xr usba_hcdi 9E .
+.Pp
+The host controller driver should first check the USB address of the
+pipe handle. It may correspond to the root hub. If it does, rather than
+initiating an I/O transfer, the driver may need to emulate it.
+.Pp
+Unlike other transfers, interrupt transfers may be periodic. If the
+transfer is meant to be a one-shot, then the
+.Sy USB_ATTRS_ONE_XFER
+flag will be set in the
+.Sy intr_attributes
+member of the
+.Fa uirp
+structure. If the
+.Sy USB_ATTRS_ONE_XFER
+flag is not set, then the transfer begins a periodic transfer. Periodic
+transfers have different handling and behavior.
+.Pp
+Interrupt transfers may send data to the device or receive data from the
+device. A given interrupt endpoint is uni-directional. The direction can
+be determined from the endpoint address based on the
+.Sy p_ep
+member of
+.Fa ubrp .
+See
+.Xr usb_ep_descr 9S
+for more information on how to determine the direction of the endpoint.
+.Pp
+The device driver should allocate memory, whether memory suitable for a
+DMA transfer or otherwise, to perform the transfer. For all memory
+allocated, it should honor the values in
+.Fa usb_flags
+to determine whether or not it should block for allocations.
+.Pp
+The length of the interrupt transfer and its data can be found in the
+.Sy intr_len
+and
+.Sy intr_data
+members of
+.Fa uirp
+respectively.
+ The
+.Xr mblk 9S
+structure that should not be used directly and data should be copied to
+or from the data buffer that will go the controller.
+.Pp
+Unlike bulk and control transfers, the
+.Fa intr_data
+member may not be allocated for interrupt-IN transfers. In such cases,
+the device driver is required to allocate the message block through
+something like
+.Xr allocb 9F
+and assign it to the
+.Sy intr_data
+member.
+.Pp
+If the driver successfully schedules the I/O, then it should return
+.Sy USB_SUCCESS .
+When the I/O completes, it must call
+.Xr usba_hcdi_cb 9F
+with
+.Fa uirp .
+If the transfer fails, but the driver returned
+.Sy USB_SUCCESS ,
+it still must call
+.Xr usba_hcdi_cb 9F
+and should specify an error there.
+.Pp
+It is the driver's responsibility to time out one-shot interrupt transfer
+requests. If the timeout in the request as indicated in the
+.Sy intr_timeout
+member of
+.Fa uirp
+is set to zero, then the driver should use the USBA default timeout of
+.Sy HCDI_DEFAULT_TIMEOUT .
+All timeout values are in
+.Em seconds .
+.Ss Periodic Transfers
+When the
+.Sy USB_ATTRS_ONE_XFER
+flag is not present, it indicates that a periodic interrupt transfer is
+being initiated. Once a periodic interrupt transfer is initiated, every
+time data is received the driver should call
+.Xr usba_hcdi_cb 9F
+with the updated data.
+.Pp
+When a periodic transfer is initiated, many controller drivers will
+allocate multiple transfers up front and schedule them all. Many drivers
+do this to ensure that data isn't lost between servicing the first
+transfer and scheduling the next. The number of such transfers used
+depends on the polling frequency specified in the endpoint descriptor.
+.Pp
+Unless an error occurs, the driver must not use the original interrupt
+request,
+.Fa uirp .
+Instead, it should duplicate the request through the
+.Xr usba_hcdi_dup_intr_req 9F
+function before calling
+.Xr usba_hcdi_cb 9F .
+.Pp
+The driver should return the original transfer in one of the following
+conditions:
+.Bl -bullet
+.It
+A pipe reset request came in from the
+.Xr usba_hcdi_pipe_rest 9E
+entry point.
+.It
+A request to stop polling came in from the
+.Xr usba_hcdi_pipe_stop_intr_polling 9E
+entry point.
+.It
+A request to close the pipe came in from the
+.Xr usba_hcdi_pipe_close 9E
+entry point.
+.It
+An out of memory condition occurred. The caller should call
+.Xr usba_hcdi_cb 9F
+with the code
+.Sy USB_CR_NO_RESOURCES .
+.It
+Some other transfer error occurred.
+.El
+.Pp
+If the periodic interrupt transfer is for the root hub, the driver will
+need to emulate the behavior of a hub as specified in the USB
+specification. For more information, see the
+.Sx Root Hub Management
+section in
+.Xr usba_hcdi 9E .
+.Ss Callback Handling
+When the interrupt transfer completes, the driver should consider the
+following items to determine what actions it should take on the
+callback:
+.Sy USB_SUCCESS .
+Otherwise, it should return the appropriate USB error. If uncertain, use
+.Sy USB_FAILURE .
+.Bl -bullet
+.It
+If the transfer timed out, it should remove the transfer from the
+outstanding list, queue the next transfer, and return the transfer back
+to the OS with the error code
+.Sy USB_CR_TIMEOUT
+with
+.Xr usba_hcdi_cb 9F .
+.It
+If the transfer failed, it should find the appropriate error and call
+.Xr usba_hcdi_cb 9F
+with that error.
+.It
+If the transfer succeeded, but less data was transferred than expected,
+consult the
+.Sy intr_attributes
+member of the
+.Fa uirp .
+If the
+.Sy USB_ATTRS_SHORT_XFER_OK
+flag is not present, then the driver should call
+.Xr usba_hcdi_cb 9F
+with the error
+.Sy USB_CR_DATA_UNDERRUN .
+.It
+If the transfer was going to the host, then the driver should copy the
+data into the transfer's message block and update the
+.Sy b_wptr
+member of the
+.Xr mblk 9S .
+.It
+If everything was successful, call
+.Xr usba_hcdi_cb 9F
+with the code
+.Sy USB_CR_OK .
+.It
+If this was a periodic transfer, it should reschedule the transfer.
+.El
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_pipe_intr_xfer
+function should return
+function should return
+.Sy USB_SUCCESS .
+Otherwise, it should return the appropriate USB error. If uncertain, use
+.Sy USB_FAILURE .
+.Sh SEE ALSO
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_pipe_close 9E ,
+.Xr usba_hcdi_pipe_rest 9E ,
+.Xr usba_hcdi_pipe_stop_intr_polling 9E ,
+.Xr allocb 9F ,
+.Xr usba_hcdi_cb 9F ,
+.Xr usba_hcdi_dup_intr_req 9F ,
+.Xr mblk 9S ,
+.Xr usb_ep_descr 9S ,
+.Xr usb_intr_req 9S ,
+.Xr usba_pipe_handle_data 9S
diff --git a/usr/src/man/man9e/usba_hcdi_pipe_isoc_xfer.9e b/usr/src/man/man9e/usba_hcdi_pipe_isoc_xfer.9e
new file mode 100644
index 0000000000..7de6946a77
--- /dev/null
+++ b/usr/src/man/man9e/usba_hcdi_pipe_isoc_xfer.9e
@@ -0,0 +1,258 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 22, 2016
+.Dt USBA_HCDI_PIPE_ISOC_XFER 9E
+.Os
+.Sh NAME
+.Nm usba_hcdi_pipe_isoc_xfer
+.Nd perform a USB isochronous transfer
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft int
+.Fo prefix_hcdi_pipe_isoc_xfer
+.Fa "usba_pipe_handle_data_t *ph"
+.Fa "usb_isoc_req_t *usrp"
+.Fa "usb_flags_t usb_flags"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa ph
+A pointer to a USB pipe handle as defined in
+.Xr usba_pipe_handle_data 9S .
+.It Fa usrp
+A pointer to a USB isochronous transfer request. The structure's members
+are documented in
+.Xr usb_isoc_req 9S .
+.It Fa usb_flags
+Flags which describe how allocations should be performed. Valid flags
+are:
+.Bl -tag -width Sy
+.It Sy USB_FLAGS_NOSLEEP
+Do not block waiting for memory. If memory is not available the allocation
+will fail.
+.It Sy USB_FLAGS_SLEEP
+Perform a blocking allocation. If memory is not available, the function
+will wait until memory is made available.
+.Pp
+Note, the request may still fail even if
+.Sy USB_FLAGS_SLEEP
+is specified.
+.El
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_pipe_isoc_xfer
+entry point is used to initiate an
+.Em asynchronous
+USB isochronous transfer on the pipe
+.Fa ph .
+The specific USB interrupt transfer is provided in
+.Fa uirp .
+For more background on transfer types, see
+.Xr usba_hcdi 9E .
+.Pp
+The host controller driver should first check the USB address of the
+pipe handle. It may correspond to the root hub. If it does, the driver
+should return
+.Sy USB_NOT_SUPPORTED .
+.Pp
+Isochronous transfers happen once a period. Isochronous transfers may
+just be told to start as son as possible or to line up to a specific
+frame. At this time, nothing in the system uses the later behavior. It
+is reasonable for a new driver to require that the
+.Sy USB_ATTRS_ISOC_XFER_ASAP
+flag be set in the
+.Sy isoc_attributes
+member of the
+.Fa usrp
+argument. In the case where it's not set and the controller driver does
+not support setting the frame, it should return
+.Sy USB_NOT_SUPPORTED .
+.Pp
+Isochronous-IN transfers are
+.Em always periodic .
+Isochronous-OUT transfers are one shot transfers. Periodic transfers
+have slightly different handling and behavior.
+.Pp
+Isochronous transfers may send data to the device or receive data from
+the device. A given isochronous endpoint is uni-directional. The
+direction can be determined from the endpoint address based on the
+.Sy p_ep
+member of
+.Fa ubrp .
+See
+.Xr usb_ep_descr 9S
+for more information on how to determine the direction of the endpoint.
+.Pp
+Isochronous transfers are a little bit different from other transfers.
+While there is still a single
+.Xr mblk 9S
+structure that all the data goes to or from, the transfer may be broken
+up into multiple packets. All of these packets make up a single transfer
+request and each one represents the data that is transferred during a
+single portion of a frame. For the description of them, see
+.Xr usb_isoc_req 9S .
+Because of these data structures, the way that transfers are recorded is
+different and will be discussed later on.
+.Pp
+The device driver should allocate memory, whether memory suitable for a
+DMA transfer or otherwise, to perform the transfer. For all memory
+allocated, it should honor the values in
+.Fa usb_flags
+to determine whether or not it should block for allocations.
+.Pp
+For isochronous-out transfers which are one-shot transfers, the driver
+should verify that the sum of all of the individual packet counts
+matches the message block length of the data. If it does not, then the
+driver should return
+.Sy USB_INVALID_ARGS .
+.Pp
+If the driver successfully schedules the I/O, then it should return
+.Sy USB_SUCCESS .
+When the I/O completes, it must call
+.Xr usba_hcdi_cb 9F
+with
+.Fa usrp .
+If the transfer fails, but the driver returned
+.Sy USB_SUCCESS ,
+it still must call
+.Xr usba_hcdi_cb 9F
+and should specify an error there.
+.Pp
+The driver is responsible for timing out all one-shot outgoing requests.
+As there is no timeout member in the isochronous request structure, then
+the timeout should be set to
+.Sy HCDI_DEFAULT_TIMEOUT .
+.Ss Periodic Transfers
+All isochronous-in transfers are periodic transfers. Once a periodic
+transfer is initiated, every time data is received the driver should
+call the
+.Xr usba_hcdi_cb 9F
+function with updated data.
+.Pp
+When a periodic transfer is initiated, many controller drivers will
+allocate multiple transfers up front and schedule them all. Many drivers
+do this to ensure that data isn't lost between servicing the first
+transfer and scheduling the next. The number of such transfers used
+depends on the polling frequency specified in the endpoint descriptor.
+.Pp
+Unless an error occurs, the driver must not use the original isochronous
+request,
+.Fa usrp .
+Instead, it should duplicate the request through the
+.Xr usba_hcdi_dup_isoc_req 9F
+function before calling
+.Xr usba_hcdi_cb 9F .
+.Pp
+The driver should return the original transfer in one of the following
+conditions:
+.Bl -bullet
+.It
+A pipe reset request came in from the
+.Xr usba_hcdi_pipe_rest 9E
+entry point.
+.It
+A request to stop polling came in from the
+.Xr usba_hcdi_pipe_stop_isoc_polling 9E
+entry point.
+.It
+A request to close the pipe came in from the
+.Xr usba_hcdi_pipe_close 9E
+entry point.
+.It
+An out of memory condition occurred. The caller should call
+.Xr usba_hcdi_cb 9F
+with the code
+.Sy USB_CR_NO_RESOURCES .
+.It
+Some other transfer error occurred.
+.El
+.Ss Callback Handling
+When the isochronous transfer completes, the driver should consider the
+following items to determine what actions it should take on the
+callback:
+.Sy USB_SUCCESS .
+Otherwise, it should return the appropriate USB error. If uncertain, use
+.Sy USB_FAILURE .
+.Bl -bullet
+.It
+If the transfer timed out, it should remove the transfer from the
+outstanding list, queue the next transfer, and return the transfer back
+to the OS with the error code
+.Sy USB_CR_TIMEOUT
+with
+.Xr usba_hcdi_cb 9F .
+.It
+If the transfer failed, it should find the appropriate error and call
+.Xr usba_hcdi_cb 9F
+with that error.
+.It
+If the transfer succeeded, but less data was transferred than expected,
+consult the
+.Sy isoc_attributes
+member of the
+.Fa usrp .
+If the
+.Sy USB_ATTRS_SHORT_XFER_OK
+flag is not present, then the driver should call
+.Xr usba_hcdi_cb 9F
+with the error
+.Sy USB_CR_DATA_UNDERRUN .
+.It
+If the transfer was going to the host, then the driver should copy the
+data into the transfer's message block and update the
+.Sy b_wptr
+member of the
+.Xr mblk 9S .
+.It
+The driver should update the
+.Sy isoc_pkt_actual_length
+member of the
+.Sy isoc_pkt_descr
+array of the
+.Xr usb_isoc_req 9S
+structure with the actual transfer amounts.
+.It
+If everything was successful, call
+.Xr usba_hcdi_cb 9F
+with the code
+.Sy USB_CR_OK .
+.It
+If this was a periodic transfer, it should reschedule the transfer.
+.El
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_pipe_isoc_xfer
+function should return
+function should return
+.Sy USB_SUCCESS .
+Otherwise, it should return the appropriate USB error. If uncertain, use
+.Sy USB_FAILURE .
+.Sh SEE ALSO
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_pipe_close 9E ,
+.Xr usba_hcdi_pipe_rest 9E ,
+.Xr usba_hcdi_pipe_stop_isoc_polling 9E ,
+.Xr usba_hcdi_cb 9F ,
+.Xr usba_hcdi_dup_isoc_req 9F ,
+.Xr mblk 9S ,
+.Xr usb_ep_descr 9S ,
+.Xr usb_isoc_req 9S ,
+.Xr usba_pipe_handle_data 9S
diff --git a/usr/src/man/man9e/usba_hcdi_pipe_open.9e b/usr/src/man/man9e/usba_hcdi_pipe_open.9e
new file mode 100644
index 0000000000..78dc276209
--- /dev/null
+++ b/usr/src/man/man9e/usba_hcdi_pipe_open.9e
@@ -0,0 +1,155 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 20, 2016
+.Dt USBA_HCDI_PIPE_OPEN 9E
+.Os
+.Sh NAME
+.Nm usba_hcdi_pipe_open ,
+.Nm usba_hcdi_pipe_close
+.Nd open and close a USB pipe
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft int
+.Fo prefix_hcdi_pipe_open
+.Fa "usba_pipe_handle_data_t *ph"
+.Fa "usb_flags_t usb_flags"
+.Fc
+.Ft int
+.Fo prefix_hcdi_pipe_close
+.Fa "usba_pipe_handle_data_t *ph"
+.Fa "usb_flags_t usb_flags"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa ph
+A pointer to a USB pipe handle as defined in
+.Xr usba_pipe_handle_data 9S .
+.It Fa usb_flags
+Flags which describe how allocations should be performed. Valid flags
+are:
+.Bl -tag -width Sy
+.It Sy USB_FLAGS_NOSLEEP
+Do not block waiting for memory. If memory is not available the allocation
+will fail.
+.It Sy USB_FLAGS_SLEEP
+Perform a blocking allocation. If memory is not available, the function
+will wait until memory is made available.
+.Pp
+Note, the request may still fail even if
+.Sy USB_FLAGS_SLEEP
+is specified.
+.El
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_pipe_open
+and
+.Fn usba_hcdi_pipe_close
+entry points are called by the USB framework whenever a client, or the
+framework itself, need to open or close a specific pipe. For additional
+background see
+.Xr usba_hcdi 9E .
+.Pp
+When a pipe is opened, the host controller driver is responsible for
+preparing the specified endpoint for performing transfers. This may
+include allocating bandwidth, programming the controller, and more. When
+the pipe is closed, the host controller driver is responsible for
+cleaning up any resources that were allocated during the open call.
+.Pp
+The pipe handle,
+.Fa ph ,
+identifies the endpoint that it the USBA is trying to open or close
+through its endpoint descriptor in the
+.Sy p_ep
+member. The endpoint descriptor is described in
+.Xr usb_ep_descr 9S .
+From the endpoint descriptor the driver can determine the type of
+endpoint, what the address of the endpoint is, and what direction the
+endpoint is in. When combined, these uniquely describe the pipe.
+.Pp
+To open a pipe, the driver may need additional companion endpoint
+descriptors. If these are available, they will be in the
+.Sy p_xep
+member of the pipe handle. See
+.Xr usb_ep_xdescr 9S
+for more information on how to determine which descriptors are present
+and get the information encoded in them.
+.Pp
+Host controller drviers should check the USB address of the
+USB device that
+.Fa ph
+belongs to. The driver may be asked to open a pipe to the root hub. As
+the root hub is often sythetic, the driver man need to take a different
+path than normal.
+.Ss Pipe open specifics
+A given endpoint on a device can only be opened once. If there's a
+request to open an already open endpoint, then the request to open the
+pipe should be failed.
+.Pp
+By the time the call to open a pipe returns, the driver should expect
+that any of the pipe transfer or reset entry points will be called on
+the pipe.
+.Pp
+A driver can establish private data on an endpoint. During pipe open it
+may set the
+.Sy p_hcd_private
+member to any value. Generally this points to an allocated structure
+that contains data specific to the host controller. This value will
+remain on the pipe handle. It is the responsibility of the driver to
+clear the data when the pipe is closed.
+.Ss Pipe close specifics
+When a pipe is closed, the driver must clean up all of the resources
+that it allocated when opening the pipe. For non-periodic transfers, the
+host controller driver may assueme that there are no outstanding
+transfers that need to be cleaned up. However, the same is not true for
+periodic pipes.
+.Pp
+For pipes that have outstanding periodic transfers, the host controller
+driver needs to clean them up and quiesce them as though a call to
+either
+.Xr usba_hcdi_pipe_stop_intr_polling 9E
+or
+.Xr usba_hcdi_pipe_stop_isoc_polling 9E
+had been called.
+.Pp
+Just as with opening the pipe, the driver should pay attention to the
+address of the USB device, as it may be the root hub, which may be a
+synthetic pipe.
+.Pp
+When a call to
+.Fn usba_hcdi_pipe_close
+completes, the device should be in a state that the pipe can be opened
+again.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_pipe_open
+and
+.Fn uba_hcdi_pipe_close
+functions should return
+.Sy USB_SUCCESS .
+Otherwise, it should return the appropriate USB error. If uncertain, use
+.Sy USB_FAILURE .
+.Sh SEE ALSO
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_pipe_stop_intr_polling 9E ,
+.Xr usba_hcdi_pipe_stop_isoc_polling 9E ,
+.Xr usb_ep_descr 9S ,
+.Xr usb_ep_xdescr 9S ,
+.Xr usba_pipe_handle_data 9S
diff --git a/usr/src/man/man9e/usba_hcdi_pipe_reset.9e b/usr/src/man/man9e/usba_hcdi_pipe_reset.9e
new file mode 100644
index 0000000000..7c883c86d1
--- /dev/null
+++ b/usr/src/man/man9e/usba_hcdi_pipe_reset.9e
@@ -0,0 +1,97 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 22, 2016
+.Dt USBA_HCDI_PIPE_RESET 9E
+.Os
+.Sh NAME
+.Nm usba_hcdi_pipe_rest
+.Nd reset an open USB pipe
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft int
+.Fo prefix_hcdi_pipe_reset
+.Fa "usba_pipe_handle_data_t *ph"
+.Fa "usb_flags_t usb_flags"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa ph
+A pointer to a USB pipe handle as defined in
+.Xr usba_pipe_handle_data 9S .
+.It Fa usb_flags
+Flags which describe how allocations should be performed. Valid flags
+are:
+.Bl -tag -width Sy
+.It Sy USB_FLAGS_NOSLEEP
+Do not block waiting for memory. If memory is not available the allocation
+will fail.
+.It Sy USB_FLAGS_SLEEP
+Perform a blocking allocation. If memory is not available, the function
+will wait until memory is made available.
+.Pp
+Note, the request may still fail even if
+.Sy USB_FLAGS_SLEEP
+is specified.
+.El
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_pipe_reset
+entry point is designed to take a pipe in an arbitrary state and return
+it to the same state it was in after a call to
+.Xr usba_hcdi_pipe_open 9E .
+While this entry point does some similar things to the
+.Xr usba_hcdi_stop_intr_polling 9E
+and
+.Xr usba_hcdi_stop_isoc_polling 9E
+entry points, there are some notable differences.
+.Pp
+This entry point is synchronous. The host controller driver should take
+the following steps on the pipe before returning:
+.Bl -enum
+.It
+Quiesce and stop the endpoint.
+.It
+If the endpoint has any errors they should be cleared at this time.
+.It
+Remove any remaining, scheduled or queued transfers. For each one call
+.Xr usba_hcdi_cb 9F
+with the code
+.Sy USB_CR_PIPE_RESET .
+.It
+Perform any other necessary steps on the controller to have the endpoint
+be ready to perform I/O.
+.El
+.Pp
+This entry point is called by the broader USBA framework as part of
+closing a pipe or in response to a device stall.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_pipe_reset
+function should return
+.Sy USB_SUCCESS .
+Otherwise, it should return the appropriate USB error. If uncertain, use
+.Sy USB_FAILURE .
+.Sh SEE ALSO
+.Xr usba_hcdi_pipe_open 9E ,
+.Xr usba_hcdi_stop_intr_polling 9E ,
+.Xr usba_hcdi_stop_isoc_polling 9E ,
+.Xr usba_hcdi_cb 9F ,
+.Xr usba_pipe_handle_data 9S
diff --git a/usr/src/man/man9e/usba_hcdi_pipe_stop_intr_polling.9e b/usr/src/man/man9e/usba_hcdi_pipe_stop_intr_polling.9e
new file mode 100644
index 0000000000..62e1783510
--- /dev/null
+++ b/usr/src/man/man9e/usba_hcdi_pipe_stop_intr_polling.9e
@@ -0,0 +1,129 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 20, 2016
+.Dt USBA_HCDI_PIPE_STOP_INTR_POLLING 9E
+.Os
+.Sh NAME
+.Nm usba_hcdi_pipe_stop_intr_polling ,
+.Nm usba_hcdi_pipe_stop_isoc_polling
+.Nd stop polling on an interrupt or isochronous pipe
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft int
+.Fo prefix_hcdi_pipe_stop_intr_polling
+.Fa "usba_pipe_handle_data_t *ph"
+.Fa "usba_flags_t usb_flags"
+.Fc
+.Ft int
+.Fo prefix_hcdi_pipe_stop_isoc_polling
+.Fa "usba_pipe_handle_data_t *ph"
+.Fa "usba_flags_t usb_flags"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa ph
+A pointer to a USB pipe handle as defined in
+.Xr usba_pipe_handle_data 9S .
+.It Fa usb_flags
+Flags which describe how allocations should be performed. Valid flags
+are:
+.Bl -tag -width Sy
+.It Sy USB_FLAGS_NOSLEEP
+Do not block waiting for memory. If memory is not available the allocation
+will fail.
+.It Sy USB_FLAGS_SLEEP
+Perform a blocking allocation. If memory is not available, the function
+will wait until memory is made available.
+.Pp
+Note, the request may still fail even if
+.Sy USB_FLAGS_SLEEP
+is specified.
+.El
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_pipe_stop_intr_polling
+and
+.Fn usba_hcdi_pipe_stop_isoc_polling
+entry points are called when a client driver wishes to cease polling on
+an interrupt or isochronous pipe as describe by
+.Fa ph .
+While these functions should only be called on pipes that have
+outstanding periodic interrupt and isochronous requests started through
+calls to either
+.Xr usba_hcdi_pipe_intr_xfer 9E
+or
+.Xr usba_hcdi_pipe_isoc_xfer 9E ,
+as part of device driver hardening, device drivers should verify that
+there are outstanding transfers.
+.Pp
+For interrupt transfers,
+.Fa ph ,
+may refer to the root hub and so the driver may need to cease any
+synthetic polling it is performing. Isochronous transfers are forbidden
+on the root hub, so the
+.Fn usba_hcdi_pipe_stop_isoc_polling
+will only be called on a pipe that corresponds to an actual device.
+.Pp
+These functions are
+.Em synchronous
+requests. In all cases, the driver should take the following steps
+before returning from these entry points:
+.Bl -enum
+.It
+Quiesce and stop the endpoint.
+.It
+Remove any remaining scheduled transfers.
+.It
+Call
+.Xr usba_hcdi_cb 9F
+on the original interrupt or isochronous request with the code
+.Sy USB_CR_STOPPED_POLLING .
+.It
+Optionally, free all associated resources. If resources aren't freed
+at this time, they must be freed when
+.Xr usba_hcdi_pipe_close 9E
+is called.
+.It
+Any other steps needed such that a call to perform one-shot or periodic
+transfers on this endpoint again may be enabled.
+.El
+.Pp
+It is possible that this function may be called concurrently with a call
+to the
+.Xr usba_hcdi_pipe_reset 9E
+entry point. In such cases, the host controller driver is required to
+perform synchronization on its data structures.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_pipe_stop_intr_polling
+and
+.Fn uba_hcdi_pipe_stop_isoc_polling
+functions should return
+.Sy USB_SUCCESS .
+Otherwise, it should return the appropriate USB error. If uncertain, use
+.Sy USB_FAILURE .
+.Sh SEE ALSO
+.Xr usba_hcdi_pipe_close 9E ,
+.Xr usba_hcdi_pipe_intr_xfer 9E ,
+.Xr usba_hcdi_pipe_isoc_xfer 9E ,
+.Xr usba_hcdi_pipe_reset 9E ,
+.Xr usba_hcdi_cb 9F ,
+.Xr usba_pipe_handle_data 9S
diff --git a/usr/src/man/man9f/Makefile b/usr/src/man/man9f/Makefile
index 82ccf43a64..30c1d87148 100644
--- a/usr/src/man/man9f/Makefile
+++ b/usr/src/man/man9f/Makefile
@@ -12,7 +12,7 @@
 #
 # Copyright 2017, Richard Lowe
 # Copyright 2014 Garrett D'Amore <garrett@damore>
-# Copyright 2016 Joyent, Inc.
+# Copyright (c) 2017, Joyent, Inc.
 # Copyright 2016 Nexenta Systems, Inc.
 # Copyright 2016 Hans Rosenfeld <rosenfeld@grumpf.hope-2000.org>
 #
@@ -524,13 +524,22 @@ MANFILES=	ASSERT.9f				\
 		usb_pipe_xopen.9f			\
 		usb_register_hotplug_cbs.9f		\
 		usb_reset_device.9f			\
+		usba_alloc_hcdi_ops.9f			\
+		usba_hcdi_cb.9f				\
+		usba_hcdi_dup_intr_req.9f		\
+		usba_hcdi_dup_isoc_req.9f		\
+		usba_hcdi_get_device_private.9f		\
+		usba_hcdi_register.9f			\
+		usba_hubdi_bind_root_hub.9f		\
+		usba_hubdi_cb_ops.9f			\
+		usba_hubdi_dev_ops.9f			\
 		uwritec.9f				\
 		va_arg.9f				\
 		vmem_add.9f				\
 		vmem_alloc.9f				\
 		vmem_contains.9f			\
 		vmem_create.9f				\
-		vmem_walk.9f				
+		vmem_walk.9f
 
 MANLINKS=	AVL_NEXT.9f					\
 		AVL_PREV.9f					\
@@ -1225,6 +1234,13 @@ MANLINKS=	AVL_NEXT.9f					\
 		usb_set_alt_if.9f				\
 		usb_set_cfg.9f					\
 		usb_unregister_hotplug_cbs.9f			\
+		usba_free_hcdi_ops.9f				\
+		usba_hcdi_unregister.9f				\
+		usba_hubdi_close.9f				\
+		usba_hubdi_ioctl.9f				\
+		usba_hubdi_open.9f				\
+		usba_hubdi_root_hub_power.9f			\
+		usba_hubdi_unbind_root_hub.9f			\
 		va_copy.9f					\
 		va_end.9f					\
 		va_start.9f					\
@@ -2104,12 +2120,25 @@ usb_pipe_open.9f			:= LINKSRC = usb_pipe_xopen.9f
 
 usb_unregister_hotplug_cbs.9f		:= LINKSRC = usb_register_hotplug_cbs.9f
 
+usba_free_hcdi_ops.9f			:= LINKSRC = usba_alloc_hcdi_ops.9f
+
+usba_hcdi_unregister.9f			:= LINKSRC = usba_hcdi_register.9f
+
+usba_hubdi_close.9f			:= LINKSRC = usba_hubdi_cb_ops.9f
+usba_hubdi_ioctl.9f			:= LINKSRC = usba_hubdi_cb_ops.9f
+usba_hubdi_open.9f			:= LINKSRC = usba_hubdi_cb_ops.9f
+
+usba_hubdi_root_hub_power.9f		:= LINKSRC = usba_hubdi_dev_ops.9f
+
+usba_hubdi_unbind_root_hub.9f		:= LINKSRC = usba_hubdi_bind_root_hub.9f
+
+
 va_copy.9f				:= LINKSRC = va_arg.9f
 va_end.9f				:= LINKSRC = va_arg.9f
 va_start.9f				:= LINKSRC = va_arg.9f
 
 vmem_xalloc.9f				:= LINKSRC = vmem_alloc.9f
-vmem_free.9f				:= LINKSRC = vmem_alloc.9f    
+vmem_free.9f				:= LINKSRC = vmem_alloc.9f
 vmem_xfree.9f				:= LINKSRC = vmem_alloc.9f
 
 vmem_xcreate.9f				:= LINKSRC = vmem_create.9f
diff --git a/usr/src/man/man9f/usba_alloc_hcdi_ops.9f b/usr/src/man/man9f/usba_alloc_hcdi_ops.9f
new file mode 100644
index 0000000000..9f355ef031
--- /dev/null
+++ b/usr/src/man/man9f/usba_alloc_hcdi_ops.9f
@@ -0,0 +1,77 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd May 7, 2016
+.Dt USBA_ALLOC_HCDI_OPS 9F
+.Os
+.Sh NAME
+.Nm usba_alloc_hcdi_ops ,
+.Nm usba_free_hcdi_ops
+.Nd allocate and free USB HCD interface operations structure
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft "usba_hcdi_ops_t *"
+.Fo usba_alloc_hcdi_ops
+.Fa void
+.Fc
+.Ft void
+.Fo usba_free_hcdi_ops
+.Fa "usba_hcdi_ops_t *ops"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMATERS
+.Bl -tag -width Fa
+.It Fa ops
+Pointer to an allocated HCD interface operations structure.
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_alloc_hcdi_ops
+function allocates a
+.Xr usba_hcdi_ops_t 9S
+structure for use for a USB HCD driver. As part of initialization, a USB
+HCD driver will allocate this and fill it in. For more information on
+the full lifetime of the object and when a USB HCD driver should release
+the structure, see
+.Xr usba_hcdi 9E .
+.Pp
+The
+.Fn usba_free_hcdi_ops
+function release the memory associated with the
+.Xr usba_hcdi_ops_t 9S
+structure pointed to by
+.Fa ops .
+Only pointers received from a call to the
+.Fn usba_alloc_hcdi_ops
+function should be passed to this function.
+.Sh CONTEXT
+These functions are generally called from kernel context during a USB
+HCD driver's
+.Xr attach 9E
+and
+.Xr detach 9E
+entry points. While it is safe to call this function from user context,
+it would be quite unusal to do so.
+.Sh RETURN VALUES
+The
+.Fn usba_alloc_hcdi_ops
+function always succeeds and returns a pointer to an allocation
+operations structure.
+.Sh SEE ALSO
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_ops_t 9S
diff --git a/usr/src/man/man9f/usba_hcdi_cb.9f b/usr/src/man/man9f/usba_hcdi_cb.9f
new file mode 100644
index 0000000000..62cdc062ee
--- /dev/null
+++ b/usr/src/man/man9f/usba_hcdi_cb.9f
@@ -0,0 +1,145 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Sep 16, 2016
+.Dt USBA_HCDI_CB 9F
+.Os
+.Sh NAME
+.Nm usba_hcdi_cb
+.Nd USBA transfer callback
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft void
+.Fo usba_hcdi_cb
+.Fa "usba_pipe_handle_data_t *ph"
+.Fa "usb_opaque_t req"
+.Fa "ucb_cr_t cr"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa ph
+A pointer to the USBA pipe handle that was passed to the HCD driver
+during a call to the
+.Xr usba_hcdi_pipe_open
+entry point.
+.It Fa req
+A pointer to the request structure that is being completed.
+.It Fa cr
+The completion code for the request.
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_cb
+function is used when the HCD controller has completed processing a USB
+transfer request, whether
+successfully or not.
+.Pp
+The USB transfer will have been initiated by a call to
+.Xr usba_hcdi_pipe_bulk_xfer 9E ,
+.Xr usba_hcdi_pipe_ctrl_xfer 9E ,
+.Xr usba_hcdi_pipe_intr_xfer 9E ,
+or
+.Xr usba_hcdi_pipe_isoc_xfer 9E .
+If the transfer initiated was a periodic transfer (certain Interrupt-IN
+and Isochronous-IN transfers), then there may be more than one callback
+performed over the life of the transfer.
+.Pp
+This function must not be used if the HCD driver returned a value
+other than
+.Sy USB_SUCCESS
+to one of the transfer initialization functions listed above. For more
+information on transfer request handling, see
+.Xr usba_hcdi 9E .
+.Pp
+The
+.Fa ph
+argument corresponds to the USBA framework's pipe handle that was given
+to the HCDI when the pipe was opened. See
+.Xr usba_hcdi_pipe_open 9E
+and
+.Xr usba_hcdi 9E
+for more information.
+.Pp
+The
+.Fa req
+argument is one of the four request structures,
+.Xr usb_bulk_req 9S ,
+.Xr usb_ctrl_req 9S ,
+.Xr usb_intr_req 9S ,
+or
+.Xr usb_isoc_req 9S ,
+which have been cast to the type
+.Ft usb_oapque_t .
+The caller should ensure that all appropriate members of the request
+structure have been filled in. For example, if expecting data from the
+device and the request has completed successfully, then  that data
+should be copied into the request structure's
+.Xr mblk 9S
+prior to handing the request structure to the
+.Fn usb_hcdi_cb
+function.
+Similarly, the
+.Xr usb_isoc_req 9S
+structure's
+.Sy isoc_pkt_descr
+member should be filled in with the appropriate data.
+.Pp
+Once the request structure has been passed to the
+.Fn usba_hcdi_cb
+function, the HCD driver must not access the structure ever again. It
+should be treated as freed memory.
+.Pp
+The
+.Fa cr
+argument us used to indicate whether the transfer was successful or not.
+If
+.Fa cr
+is set to
+.Sy USB_CR_OK
+that indicates that the transfer completed successfully. This should
+also be used when a permitted short transfer has occurred. Otherwise, it
+should be set to one of the completion reasons.
+.Ss Locking
+The HCD driver should not hold its own internal locks across a call to
+the
+.Fn usba_hcdi_cb
+function. It is possible that the driver will have once of its
+.Xr usba_hcdi 9E
+entry points called based on the return value specified.
+.Sh CONTEXT
+The
+.Fn usba_hcdi_cb
+function may be called from
+.Sy user ,
+.Sy kernel ,
+or
+.Sy interrupt
+context.
+.Sh SEE ALSO
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_pipe_bulk_xfer 9E ,
+.Xr usba_hcdi_pipe_ctrl_xfer 9E ,
+.Xr usba_hcdi_pipe_intr_xfer 9E ,
+.Xr usba_hcdi_pipe_isoc_xfer 9E ,
+.Xr usba_hcdi_pipe_open 9E ,
+.Xr mblk 9S ,
+.Xr usb_bulk_req 9S ,
+.Xr usb_ctrl_req 9S ,
+.Xr usb_intr_req 9S ,
+.Xr usb_isoc_req 9S
diff --git a/usr/src/man/man9f/usba_hcdi_dup_intr_req.9f b/usr/src/man/man9f/usba_hcdi_dup_intr_req.9f
new file mode 100644
index 0000000000..976c8c8d37
--- /dev/null
+++ b/usr/src/man/man9f/usba_hcdi_dup_intr_req.9f
@@ -0,0 +1,115 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd May 10, 2016
+.Dt USBA_HCDI_DUP_INTER_REQ 9F
+.Os
+.Sh NAME
+.Nm usba_hcdi_dup_intr_req
+.Nd duplicate an interrupt request
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft usb_intr_req_t *
+.Fo usba_hcdi_dup_intr_req
+.Fa "dev_info_t *dip"
+.Fa "usb_intr_req_t *irqp"
+.Fa "size_t size"
+.Fa "usb_flags_t flags"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa dip
+A pointer to the HCD driver's
+.Sy dev_info
+structure.
+.It Fa irqp
+A pointer to the USB interrupt request which will be duplicated.
+.It Fa size
+The number of bytes in the allocated data block
+.Sy mblk_t .
+.It Fa flags
+Flags which describe how allocations should be performed. Valid flags
+are:
+.Bl -tag -width Sy
+.It Sy USB_FLAGS_NOSLEEP
+Do not block waiting for memory. If memory is not available the allocation
+will fail.
+.It Sy USB_FLAGS_SLEEP
+Perform a blocking allocation. If memory is not available, the function
+will wait until memory is made available.
+.Pp
+Note, the request may still fail even if
+.Sy USB_FLAGS_SLEEP
+is specified.
+.El
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_dup_intr_req
+function is used to duplicate an existing interrupt request,
+.Fa irqp .
+.Pp
+The USBA framework initiates interrupt operations through the
+.Xr usba_hcdi_pipe_intr_xfer 9E
+entry point. It provides an initial USB interrupt request as an argument.
+When the HCD driver has interrupt data to return, it needs to duplicate
+that initial interrupt request each time that it submits data through
+the
+.Xr usba_hcdi_cb 9F
+function. In addition to duplicating the request, callers may also need
+to increase the pipe handle's request count. For more information, see
+.Xr usba_hcdi_pipe_intr_xfer 9E .
+.Pp
+The
+.Fa dip
+argument should correspond to the HCD driver's
+.Sy dev_info_t
+structure. The
+.Fa irqp
+pointer should correspond to the initial interrupt request. The
+.Fa size
+argument should describe the maximum amount of data needed for this
+request. The amount of data will be dependent on the endpoint and
+device. The value of
+.Fa flags
+should depend on the caller's context. If
+.Dv USB_FLAGS_SLEEP
+is passed while in interrupt context, then this function will fail.
+.Sh CONTEXT
+The
+.Fn usba_hcdi_dup_intr_req
+function may be called from
+.Sy user ,
+.Sy kernel ,
+or
+.Sy interrupt
+context; however, when in interrupt context, the value of
+.Fa flags
+must be
+.Sy USB_FLAGS_NOSLEEP .
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_dup_intr_req
+function returns a pointer to a duplicated interrupt request. Otherwise,
+.Sy NULL
+is returned to indicate that the request could not be duplicated.
+.Sh SEE ALSO
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_pipe_intr_xfer 9E ,
+.Xr usba_hcdi_cb 9F
diff --git a/usr/src/man/man9f/usba_hcdi_dup_isoc_req.9f b/usr/src/man/man9f/usba_hcdi_dup_isoc_req.9f
new file mode 100644
index 0000000000..f8f881aa5b
--- /dev/null
+++ b/usr/src/man/man9f/usba_hcdi_dup_isoc_req.9f
@@ -0,0 +1,111 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Sep 16, 2016
+.Dt USBA_HCDI_DUP_ISOC_REQ 9F
+.Os
+.Sh NAME
+.Nm usba_hcdi_dup_isoc_req
+.Nd duplicate an isochronous request
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft "usb_isoc_req_t *"
+.Fo usba_hcdi_dup_isoc_req
+.Fa "dev_info_t *dip"
+.Fa "usb_isoc_req_t *usrp"
+.Fa "usb_flags_t flags"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa dip
+A pointer to the HCD driver's
+.Sy dev_info
+structure.
+.It Fa usrp
+A pointer to the USB isochronous request which will be duplicated.
+.It Fa flags
+.Bl -tag -width Sy
+.It Sy USB_FLAGS_NOSLEEP
+Do not block waiting for memory. If memory is not available the allocation
+will fail.
+.It Sy USB_FLAGS_SLEEP
+Perform a blocking allocation. If memory is not available, the function
+will wait until memory is made available.
+.Pp
+Note, the request may still fail even if
+.Sy USB_FLAGS_SLEEP
+is specified.
+.El
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_dup_isoc_req
+function is used to duplicate an existing isochronous request,
+.Fa usrp .
+.Pp
+When the USBA framework initiates an isochronous in transfer with the
+.Xr usba_hcdi_pipe_isoc_xfer 9E
+entry point, it is the HCD driver's responsibility to receive the
+periodic data from the pipe. When there is data available, the HCD must
+duplicate the original isochronous request and copy the available data
+into the request structure's
+.Fa isoc_data
+member, before handing over the request structure to the USBA framework
+by calling the
+.Xr usba_hcdi_cb 9F
+function.
+.Pp
+In addition to duplicating the request, it is the callers responsibility
+to increase the pipe handle's request count. For more information, see
+.Xr usba_hcdi_pipe_isoc_xfer 9E .
+.Pp
+The
+.Fa dip
+argument should correspond to the HCD driver's
+.Sy dev_info_t
+structure. The
+.Fa usrp
+pointer should correspond to the initial isochronous request. The
+.Fa flags
+member must be appropriate for the context. If
+.Dv USB_FLAGS_SLEEP
+is passed while in interrupt context, then this function may fail.
+.Sh CONTEXT
+The
+.Fn usba_hcdi_dup_isoc_req
+function may be called from
+.Sy user ,
+.Sy kernel ,
+or
+.Sy interrupt
+context; however, when in interrupt context, the value of
+.Fa flags
+must be
+.Sy USB_FLAGS_NOSLEEP .
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_dup_isoc_req
+function returns a pointer to a duplicate isochronous request.
+Otherwise,
+.Sy NULL
+is returned to indicate that the request could not be duplicated.
+.Sh SEE ALSO
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_pipe_isoc_xfer 9E ,
+.Xr usba_hcdi_cb 9F
diff --git a/usr/src/man/man9f/usba_hcdi_get_device_private.9f b/usr/src/man/man9f/usba_hcdi_get_device_private.9f
new file mode 100644
index 0000000000..05cf3b8ebe
--- /dev/null
+++ b/usr/src/man/man9f/usba_hcdi_get_device_private.9f
@@ -0,0 +1,66 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd May 7, 2016
+.Dt USBA_HCDI_GET_DEVICE_PRIVATE 9F
+.Os
+.Sh NAME
+.Nm usba_hcdi_get_device_private
+.Nd get HCD per-device private value
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft void *
+.Fo usba_hcdi_get_device_private
+.Fa "usba_device_t *usb_device"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa usb_device
+Pointer to a USB device.
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_get_device_private
+function obtains the private data set by a HCD driver. This private data
+is created by the HCD driver's optional entry point
+.Xr usba_hcdi_device_init 9E
+and is removed during the HCD driver's optional entry point
+.Xr usba_hcdi_device_fini 9E .
+If an HCD driver does not implement these entry points then the value
+obtained by a call will always be the null pointer,
+.Dv NULL .
+.Pp
+The framework provides no form of locking of this data and it is up to
+the HCD driver to use whatever synchronization primitives it requires if
+needed.
+.Sh CONTEXT
+The
+.Fn usba_hcdi_get_device_private
+function is generally called from the context of a
+.Xr usba_hcdi 9E
+entry point, but may be called from user, kernel, or interrupt context.
+.Sh RETURN VALUES
+The private data set by an HCD driver is always returned. If no such
+value has been set, then
+.Dv NULL
+is returned.
+.Sh SEE ALSO
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_device_fini 9E ,
+.Xr usba_hcdi_device_init 9E
diff --git a/usr/src/man/man9f/usba_hcdi_register.9f b/usr/src/man/man9f/usba_hcdi_register.9f
new file mode 100644
index 0000000000..a2bdbdb97f
--- /dev/null
+++ b/usr/src/man/man9f/usba_hcdi_register.9f
@@ -0,0 +1,112 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Sep 16, 2016
+.Dt USBA_HCDI_REGISTER 9F
+.Os
+.Sh NAME
+.Nm usba_hcdi_register ,
+.Nm usba_hcdi_unregister
+.Nd register and unregister HCD driver
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Ft int
+.Fo usba_hcdi_register
+.Fa "usba_hcdi_register_args_t *args"
+.Fa "uint_t flags"
+.Fc
+.Ft void
+.Fo usba_hcdi_unregister
+.Fa "dev_info_t *dip"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa args
+A pointer to a filled out registration structure. See
+.Xr usba_hcdi_register_args_t 9S
+for the members to fill in.
+.It Fa flags
+Should be set to
+.Sy 0 .
+.It Fa dip
+Pointer to the device's
+.Sy dev_info
+structure.
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hcdi_register
+and
+.Fn usba_hcdi_unregister
+functions are used to register and unregister a USB HCDI driver from the
+USBA framework.
+.Pp
+The
+.Fn usba_hcdi_register
+function is called during a device driver's
+.Xr attach 9E
+entry point after it has finished initializing the device. After this
+function successfuly returns, device drivers should assume that the
+.Xr usba_hcdi_ops 9S
+functions may be called at any time.
+.Pp
+The
+.Fn usba_hcdi_unregister
+function should be called during a driver's
+.Xr detach 9E
+entry point after it has unbound its root hub, but before the remainder
+of the device's state is torn down. After calling the
+.Fn usba_hcdi_unregister
+function, the driver will receive no more function calls to its
+.Xr usba_hcdi_ops 9S
+entry points.
+.Pp
+For more information on the initialization and finalization path of a
+USB HCD driver, see
+.Xr usba_hcdi 9E .
+.Sh CONTEXT
+The
+.Fn usba_hcdi_register
+function should only be called from a driver's
+.Xr attach 9E
+entry point.
+.Pp
+The
+.Fn usba_hcdi_unregister
+function should only be called frm a driver's
+.Xr detach 9E
+entry point.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hcdi_register
+function returns
+.Sy USB_SUCCESS .
+Otherwise
+.Sy USB_FAILURE
+is returned to indicate that the device was not registered.
+.Pp
+The
+.Fn usba_hcdi_unregister
+function does not define any return values and always succeeds.
+.Sh SEE ALSO
+.Xr attach 9E ,
+.Xr detach 9E ,
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_ops 9S ,
+.Xr usba_hcdi_register_args_t 9S
diff --git a/usr/src/man/man9f/usba_hubdi_bind_root_hub.9f b/usr/src/man/man9f/usba_hubdi_bind_root_hub.9f
new file mode 100644
index 0000000000..03b3b4a1a5
--- /dev/null
+++ b/usr/src/man/man9f/usba_hubdi_bind_root_hub.9f
@@ -0,0 +1,137 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Sep 16, 2016
+.Dt USBA_HCDI_BIND_ROOT_HUB 9F
+.Os
+.Sh NAME
+.Nm usba_hubdi_bind_root_hub ,
+.Nm usba_hubdi_unbind_root_hub
+.Nd bind and unbind the root USB hub
+.Sh SYNOPSIS
+.In sys/usb/usba/hubdi.h
+.Ft int
+.Fo usba_hubdi_bind_root_hub
+.Fa "dev_info_t *dip"
+.Fa "uchar_t *hub_descr"
+.Fa "size_t descr_len"
+.Fa "usb_dev_descr_t *dev_descr"
+.Fc
+.Ft int
+.Fo usba_hubdi_unbind_root_hub
+.Fa "dev_info_t *dip"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+.Bl -tag -width Fa
+.It Fa dip
+Pointer to the device's
+.Sy dev_info
+structure.
+.It Fa hub_descr
+Pointer to a byte array that contains the standard descriptors for a USB
+Hub device.
+.It Fa descr_len
+The length in bytes of the
+.Fa hub_descr
+byte array.
+.It Fa dev_descr
+A filled in standard USB device descriptor.
+.El
+.Sh DESCRIPTION
+The
+.Fn usba_hubdi_bind_root_hub
+and
+.Fn usba_hubdi_unbind_root_hub
+functions are used to bind and unbind the root USB hub that is a part of
+every HCD driver. See
+.Xr usba_hcdi 9E
+for more information on this relationship.
+.Pp
+The
+.Fn usba_hubdi_root_bind_driver
+is used after calling the
+.Xr usba_hcdi_register 9F
+function during a device's
+.Xr attach 9E
+entry point.
+.Pp
+Because the root hub is generally a virtual hub, the HCD driver is
+responsible for making it appear to the system as a normal USB hub.
+.Pp
+The contents of the
+.Fa hub_descr
+should be the standard USB Hub class-specific descriptor. This hub
+descriptor should match a hub of a similar class of speed. For example,
+with the xhci controller, a USB 3.x Hub class-specific descriptor is
+used, where as for the ehci controller, a USB 2.x Hub class-specific
+descriptor is used. For more information, see the USB 3.1
+specification, section 10.15.2
+.Em Class-specific Descriptors .
+.Pp
+Similarly, the contents of the
+.Fa dev_descr
+need to be a filled in USB device descriptor that indicates that the
+root hub corresponds to the appropriate USB generation. For more
+information on the contents, see
+.Xr usb_dev_descr 9S
+and the USB 3.1 specification, section 10.15.1
+.Em Standard Descriptors for Hub Class .
+.Pp
+The
+.Fn usba_hubdi_unbind_root_hub
+function is used to detach the root hub associated with the HCD driver.
+This should be called during a device's
+.Xr detach 9E
+routine before calling
+.Xr usba_hcdi_unregister .
+.Pp
+If a call to the
+.Fn usba_hubdi_unbind_root_hub
+function fails during a device's
+.Xr detach 9E
+function, then it should fail the call to
+.Xr detach 9E .
+.Sh CONTEXT
+The
+.Fn usba_hubdi_bind_root_hub
+function should only be called during a device's
+.Xr attach 9E
+entry point.
+.Pp
+The
+.Fn usba_hubdi_unbind_root_hub
+function should only be called during a device's
+.Xr detach 9E entry point.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn usba_hubdi_bind_root_hub
+and
+.Fn usba_hubdi_unbind_root_hub
+functions return
+.Sy USB_SUCCESS .
+Otherwise, they return
+.Sy USB_FAILURE
+to indicate that they could not proceed.
+.Sh SEE ALSO
+.Xr attach 9E ,
+.Xr detach 9E ,
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_register 9F ,
+.Xr usba_hcdi_unregister 9F ,
+.Xr usb_dev_Descr 9S
diff --git a/usr/src/man/man9f/usba_hubdi_cb_ops.9f b/usr/src/man/man9f/usba_hubdi_cb_ops.9f
new file mode 100644
index 0000000000..196874ad8f
--- /dev/null
+++ b/usr/src/man/man9f/usba_hubdi_cb_ops.9f
@@ -0,0 +1,109 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd May 7, 2016
+.Dt USBA_HCDI_CB_OPS 9F
+.Os
+.Sh NAME
+.Nm usba_hubdi_cb_ops ,
+.Nm usba_hubdi_open ,
+.Nm usba_hubdi_ioctl ,
+.Nm usba_hubdi_close
+.Nd character device utility functions for HCD drivers
+.Sh SYNOPSIS
+.In sys/usb/usba/hubdi.h
+.Ft int
+.Fo usba_hubdi_open
+.Fa "dev_info_t *dip"
+.Fa "dev_t *devp"
+.Fa "int flag"
+.Fa "int otyp"
+.Fa "cred_t *cred_p"
+.Fc
+.Ft int
+.Fo usba_hubdi_ioctl
+.Fa "dev_info_t *dip"
+.Fa "dev_t dev"
+.Fa "int flag"
+.Fa "intptr_t arg"
+.Fa "int mode"
+.Fa "cred_t *cred_pp"
+.Fa "int *rval_p"
+.Fc
+.Ft int
+.Fo usba_hubdi_close
+.Fa "dev_info_t *dip"
+.Fa "dev_t dev"
+.Fa "int flag"
+.Fa "int otyp"
+.Fa "cred_t *cred_p"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMATERS
+.Bl -tag -width Fa
+.It Fa dip
+Pointer to the device's
+.Sy dev_info
+structure.
+.El
+.Pp
+All other parameters are the same as the ones described and discussed in
+.Xr open 9E ,
+.Xr ioctl 9E ,
+and
+.Xr close 9E .
+.Sh DESCRIPTION
+The
+.Fn usba_hubdi_open ,
+.Fn usba_hubdi_ioctl ,
+and
+.Fn usba_hubdi_close
+functions are functions provided for the implementation of USB HCD
+drivers. USB HCD drivers are required to implemnt the
+.Xr open 9E ,
+.Xr ioctl 9E ,
+and
+.Xr close 9E
+.Xr cb_ops 9S
+functions. In each of those functions, they should use the device number
+to determine number in
+.Fa devp
+or
+.Fa dev
+to determine the device's corresponding
+.Sy dev_info_t .
+The USB HCD driver's entry points should then call the corresponding
+function described above, passing all the arguments they received
+unmodified.
+.Pp
+The USB HCD driver's entry points should return the value returned by
+the call to the corresponding USBA function.
+.Sh CONTEXT
+These functions should only be called from the context of a USB HCD
+driver's
+.Xr open 9E ,
+.Xr ioctl 9E ,
+and
+.Xr close 9E
+entry points.
+.Sh SEE ALSO
+.Xr close 9E ,
+.Xr ioctl 9E ,
+.Xr open 9E ,
+.Xr usb_hcdi 9E ,
+.Xr cb_ops 9S
diff --git a/usr/src/man/man9f/usba_hubdi_dev_ops.9f b/usr/src/man/man9f/usba_hubdi_dev_ops.9f
new file mode 100644
index 0000000000..a0a9530e8e
--- /dev/null
+++ b/usr/src/man/man9f/usba_hubdi_dev_ops.9f
@@ -0,0 +1,66 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Sep 16, 2016
+.Dt USBA_HCDI_DEV_OPS 9F
+.Os
+.Sh NAME
+.Nm usba_hubdi_bus_ops
+.Nm usba_hubdi_root_hub_power
+.Nd device operations utility functions for HCD drivers
+.Sh SYNOPSIS
+.Ft int
+.Fo usba_hubdi_root_hub_power
+.Fa "dev_info_t *dip"
+.Fa "int component"
+.Fa "int level"
+.Fc
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private function
+.Pp
+This is a private function that is not part of the stable DDI. It may be
+removed or changed at any time.
+.Sh PARAMETERS
+For the parameters of the
+.Fn usba_hubdi_root_hub_power
+function, see
+.Xr power 9E .
+.Sh DESCRIPTION
+The
+.Fn usba_hubdi_root_hub_power
+function is a utility function for the implementation of USB HCD
+drivers. USB HCD drivers that support power management, should use set
+the
+.Sy devo_power
+member of their
+.Xr dev_ops 9S
+structure to the
+.Fn usba_hubdi_root_hub_power
+function. They should not implement their own
+.Xr power 9E
+function.
+.Pp
+In addition, drivers should pass the symbol
+.Sy usba_hubdi_busops
+as the
+.Sy devo_bus_ops
+member. It contains a properly formatted bus operations structure.
+.Sh CONTEXT
+This function should not be called directly, it should only be used as a
+member of a device's
+.Xr dev_ops 9S
+structure.
+.Sh SEE ALSO
+.Xr power 9E ,
+.Xr dev_ops 9S
diff --git a/usr/src/man/man9s/Makefile b/usr/src/man/man9s/Makefile
index 36ff13a29b..6ef0e91166 100644
--- a/usr/src/man/man9s/Makefile
+++ b/usr/src/man/man9s/Makefile
@@ -13,92 +13,98 @@
 # Copyright 2011, Richard Lowe
 # Copyright 2013 Nexenta Systems, Inc.  All rights reserved.
 # Copyright 2014 Garrett D'Amore <garrett@damore.org>
+# Copyright (c) 2017, Joyent, Inc.
 #
 
 include		$(SRC)/Makefile.master
 
-MANSECT= 	9s
-
-MANFILES= 	Intro.9s			\
-	 	aio_req.9s			\
-	 	buf.9s				\
-	 	cb_ops.9s			\
-	 	copyreq.9s			\
-	 	copyresp.9s			\
-	 	datab.9s			\
-	 	ddi_device_acc_attr.9s		\
-	 	ddi_dma_attr.9s			\
-	 	ddi_dma_cookie.9s		\
-	 	ddi_dmae_req.9s			\
-	 	ddi_fm_error.9s			\
-	 	ddi_idevice_cookie.9s		\
-	 	dev_ops.9s			\
-	 	devmap_callback_ctl.9s		\
-	 	fmodsw.9s			\
-	 	free_rtn.9s			\
-	 	gld_mac_info.9s			\
-	 	gld_stats.9s			\
-	 	hook_nic_event.9s		\
-	 	hook_pkt_event.9s		\
-	 	hook_t.9s			\
-	 	iocblk.9s			\
-	 	iovec.9s			\
-	 	kstat.9s			\
-	 	kstat_intr.9s			\
-	 	kstat_io.9s			\
-	 	kstat_named.9s			\
-	 	linkblk.9s			\
+MANSECT=	9s
+
+MANFILES=	Intro.9s			\
+		aio_req.9s			\
+		buf.9s				\
+		cb_ops.9s			\
+		copyreq.9s			\
+		copyresp.9s			\
+		datab.9s			\
+		ddi_device_acc_attr.9s		\
+		ddi_dma_attr.9s			\
+		ddi_dma_cookie.9s		\
+		ddi_dmae_req.9s			\
+		ddi_fm_error.9s			\
+		ddi_idevice_cookie.9s		\
+		dev_ops.9s			\
+		devmap_callback_ctl.9s		\
+		fmodsw.9s			\
+		free_rtn.9s			\
+		gld_mac_info.9s			\
+		gld_stats.9s			\
+		hook_nic_event.9s		\
+		hook_pkt_event.9s		\
+		hook_t.9s			\
+		iocblk.9s			\
+		iovec.9s			\
+		kstat.9s			\
+		kstat_intr.9s			\
+		kstat_io.9s			\
+		kstat_named.9s			\
+		linkblk.9s			\
 		mac_callbacks.9s		\
 		mac_register.9s			\
-	 	modldrv.9s			\
-	 	modlinkage.9s			\
-	 	modlmisc.9s			\
-	 	modlstrmod.9s			\
-	 	module_info.9s			\
-	 	msgb.9s				\
-	 	net_inject_t.9s			\
-	 	net_instance_t.9s		\
-	 	qband.9s			\
-	 	qinit.9s			\
-	 	queclass.9s			\
-	 	queue.9s			\
-	 	scsi_address.9s			\
-	 	scsi_arq_status.9s		\
-	 	scsi_asc_key_strings.9s		\
-	 	scsi_device.9s			\
-	 	scsi_extended_sense.9s		\
-	 	scsi_hba_tran.9s		\
-	 	scsi_inquiry.9s			\
-	 	scsi_pkt.9s			\
-	 	scsi_status.9s			\
-	 	streamtab.9s			\
-	 	stroptions.9s			\
-	 	tuple.9s			\
-	 	uio.9s				\
+		modldrv.9s			\
+		modlinkage.9s			\
+		modlmisc.9s			\
+		modlstrmod.9s			\
+		module_info.9s			\
+		msgb.9s				\
+		net_inject_t.9s			\
+		net_instance_t.9s		\
+		qband.9s			\
+		qinit.9s			\
+		queclass.9s			\
+		queue.9s			\
+		scsi_address.9s			\
+		scsi_arq_status.9s		\
+		scsi_asc_key_strings.9s		\
+		scsi_device.9s			\
+		scsi_extended_sense.9s		\
+		scsi_hba_tran.9s		\
+		scsi_inquiry.9s			\
+		scsi_pkt.9s			\
+		scsi_status.9s			\
+		streamtab.9s			\
+		stroptions.9s			\
+		tuple.9s			\
+		uio.9s				\
 		usb_bulk_req.9s			\
-	 	usb_callback_flags.9s		\
-	 	usb_cfg_descr.9s		\
-	 	usb_client_dev_data.9s		\
-	 	usb_completion_reason.9s	\
+		usb_callback_flags.9s		\
+		usb_cfg_descr.9s		\
+		usb_client_dev_data.9s		\
+		usb_completion_reason.9s	\
 		usb_ctrl_req.9s			\
-	 	usb_dev_descr.9s		\
-	 	usb_dev_qlf_descr.9s		\
-	 	usb_ep_descr.9s			\
+		usb_dev_descr.9s		\
+		usb_dev_qlf_descr.9s		\
+		usb_ep_descr.9s			\
 		usb_ep_ss_comp_descr.9s		\
 		usb_ep_xdescr.9s		\
-	 	usb_if_descr.9s			\
+		usb_if_descr.9s			\
 		usb_intr_req.9s			\
 		usb_isoc_req.9s			\
-	 	usb_other_speed_cfg_descr.9s	\
-	 	usb_request_attributes.9s	\
-	 	usb_string_descr.9s
+		usb_other_speed_cfg_descr.9s	\
+		usb_request_attributes.9s	\
+		usb_string_descr.9s		\
+		usba_device.9s			\
+		usba_hcdi_ops.9s		\
+		usba_hcdi_register_args.9s	\
+		usba_pipe_handle_data.9s
+
 
 MANLINKS=	dblk.9s				\
 		intro.9s			\
 		mac_callbacks_t.9s		\
 		mac_register_t.9s		\
 		mblk.9s				\
-		usb_ep_ss_comp_descr_t.9s 	\
+		usb_ep_ss_comp_descr_t.9s	\
 		usb_bulk_req_t.9s		\
 		usb_bulk_request.9s		\
 		usb_ctrl_req_t.9s		\
@@ -106,7 +112,12 @@ MANLINKS=	dblk.9s				\
 		usb_intr_req_t.9s		\
 		usb_intr_request.9s		\
 		usb_isoc_req_t.9s		\
-		usb_isoc_request.9s
+		usb_isoc_request.9s		\
+		usba_device_t.9s		\
+		usba_hcdi_ops_t.9s		\
+		usba_hcdi_register_args_t.9s	\
+		usba_pipe_handle_data_t.9s
+
 
 intro.9s		:= LINKSRC = Intro.9s
 
@@ -135,6 +146,11 @@ usb_ep_ss_comp_descr_t.9s	:= LINKSRC =	usb_ep_ss_comp_descr.9s
 usb_ep_xdescr_t.9s		:= LINKSRC =	usb_ep_xdescr.9s
 usba_hcdi_register_args_t.9s	:= LINKSRC =	usba_hcdi_register_args.9s
 
+usba_device_t.9s		:= LINKSRC =	usba_device.9s
+usba_hcdi_ops_t.9s		:= LINKSRC =	usba_hcdi_ops.9s
+usba_hcdi_register_args_t.9s	:= LINKSRC =	usba_hcdi_register_args.9s
+usba_pipe_handle_data_t.9s	:= LINKSRC =	usba_pipe_handle_data.9s
+
 .KEEP_STATE:
 
 include		$(SRC)/man/Makefile.man
diff --git a/usr/src/man/man9s/usba_device.9s b/usr/src/man/man9s/usba_device.9s
new file mode 100644
index 0000000000..cb1fa5453f
--- /dev/null
+++ b/usr/src/man/man9s/usba_device.9s
@@ -0,0 +1,188 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 20, 2016
+.Dt USBA_DEVICE 9S
+.Os
+.Sh NAME
+.Nm usba_device ,
+.Nm usba_device_t
+.Nd USBA Device Data Structure
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private
+.Pp
+This is a private data structure that is not part of the stable DDI. It
+may be removed or changed at any time.
+.Sh DESCRIPTION
+The
+.Sy usba_device_t
+structure is used by the illumos USB Architecture (USBA) to represent a
+physical USB device. While a given USB device may be a composite device,
+a USB device that implements two or more classes, there will still only
+be a single device structure.  A USB device is always plugged into a
+port on some hub, excepting the root hub, and has an address on the USB
+fabric.
+.Pp
+Many of the USB HCD driver operations pass a
+.Sy usba_device_t
+to the HCD driver. The
+.Sy usba_device_t
+should be used by an HCD driver in a
+.Em read-only
+fashion. A subset of the structure's fields that are useful for HCD
+drivers to read are listed below.
+.Pp
+In addition, there are two optional HCD entry points that interact with
+this structure and give the change for a driver to store per-device
+state. If the driver implements the
+.Xr usba_hcdi_device_init 9E
+and
+.Xr usba_hcdi_device_fini 9E
+functions, then the private data stored from
+.Xr usba_hcdi_device_init 9E
+can be retrieved with
+.Xr usba_hcdi_get_device_private 9F .
+.Sh STRUCTURE MEMBERS
+The
+.Sy usba_device_t
+structure includes the following members:
+.Bd -literal -offset indent
+dev_info_t		*usb_dip
+usba_hubdi_t		*usb_hubdi;
+usb_addr_t		usb_addr;
+usb_dev_descr_t		*usb_dev_descr;
+char			*usb_mfg_str;
+char			*usb_product_str;
+char			*usb_serialno_str;
+usb_port_status_t	usb_port_status;
+usb_port_t		usb_port;
+usba_device_t		*usb_hs_hub_usba_dev;
+usba_device_t		*usb_parent_hub;
+.Ed
+.Pp
+The
+.Sy usb_dip
+member is a pointer to the device's
+.Sy dev_info_t
+structure. This generally is used if the HCD driver wants to get naming
+information for diagnostic purposes. When duplicating requests for
+isochronous and interrupt requests, HCD drivers should use the
+.Sy dev_info_t
+from the
+.Xr usba_pipe_handle_data_t 9S .
+.Pp
+The
+.Sy usb_hubdi
+member can be used to determine whether or not the
+.Sy usba_device_t
+in question is a hub or not. HCD drivers should compare this member to
+.Dv NULL .
+If the member is not
+.Dv NULL ,
+then this USB device corresponds to a hub.
+.Pp
+the
+.Sy usb_addr
+member indicates the address of the USB device on the broader USB bus.
+Note, that the actual address assigned to the device may be different,
+especially if the HCD driver implements the optional
+.Xr usba_hcdi_device_address 9E
+entry point. See the section
+.Sy USB addressing
+in
+.Xr usba_hcdi 9E
+for more information.
+.Pp
+The
+.Sy usb_dev_descr
+member points to the device descriptor for a given device. This
+structure is documented in
+.Xr usb_dev_descr 9S .
+This member may be
+.Dv NULL
+as it may not have been populated during device
+attachment. This member may be
+.Dv NULL .
+HCD drivers should always check for
+.Dv NULL
+before dereferencing it.
+.Pp
+The
+.Sy usb_mfg_str
+member may contain a pointer to a character string with the name of the
+manufacturer as retrieved from the device. This member may be
+.Dv NULL .
+HCD drivers should always check for
+.Dv NULL
+before dereferencing it.
+.Pp
+The
+.Sy usb_product_str
+member may contain a pointer to a character string with the name of the
+product as retrieved from the device. This member may be
+.Dv NULL .
+HCD drivers should always check for
+.Dv NULL
+before dereferencing it.
+.Pp
+The
+.Sy usb_serialno_str
+member may contain a pointer to a character string with the serial
+number of the device as retrieved from the device. This member may be
+.Dv NULL .
+HCD drivers should always check for
+.Dv NULL
+before dereferencing it.
+.Pp
+The
+.Sy usb_port_status_t
+contains a
+.Xr usb_port_status_t
+entry, which describes the current negotiated speed of the device. See
+.Xr usb_port_status_t 9T
+for more information on the values and types.
+.Pp
+The
+.Sy usb_port
+member contains the port on a hub that the device is plugged into. Ports
+are always numbered starting at 1.
+.Pp
+The
+.Sy usb_hs_hub_usba_dev
+member is set when there is a parent high-speed hub. This is most
+notable for low- and full- speed devices which require split
+transaction support. This points to the
+.Sy usb_device_t
+structure that is the closest high-speed parent hub. This member should
+always be set to
+.Dv NULL
+for super-speed devices. A device operating a super-speed can never be
+plugged into a high-speed hub.
+.Pp
+The
+.Sy usb_parent_hub
+member points to the
+.Sy usba_device_t
+structure that the device in question is plugged into. If the device
+represents the root hub, then this field will be
+.Dv NULL .
+.Sh SEE ALSO
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_device_address 9E ,
+.Xr usba_hcdi_device_fini 9E ,
+.Xr usba_hcdi_device_init 9E ,
+.Xr usba_pipe_handle_data_t 9S ,
+.Xr usb_port_status_t 9T
diff --git a/usr/src/man/man9s/usba_hcdi_ops.9s b/usr/src/man/man9s/usba_hcdi_ops.9s
new file mode 100644
index 0000000000..c1b8df0423
--- /dev/null
+++ b/usr/src/man/man9s/usba_hcdi_ops.9s
@@ -0,0 +1,310 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 20, 2016
+.Dt USBA_HCDI_OPS 9S
+.Os
+.Sh NAME
+.Nm usba_hcdi_ops ,
+.Nm usba_hcdi_ops_t
+.Nd USBA host controller driver operations vector
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private
+.Pp
+This is a private data structure that is not part of the stable DDI. It
+may be removed or changed at any time.
+.Sh DESCRIPTION
+The
+.Sy usba_hcdi_ops
+structure is usbed HCD drivers to register operations vectors and
+callbacks from the USBA HCD interface. See
+.Xr usba_hcdi 9E
+for more information on USB HCD device drivers.
+.Pp
+The structure is allocated through a call to the
+.Xr usba_alloc_hcdi_ops 9F
+function and is used with a call to
+.Xr usba_hcdi_register 9F .
+When the driver is done with the operations vector, either because
+registering has failed or it is unregistering, it should call
+.Xr usba_free_hcdi_ops 9F
+to free the associated memory.
+.Sh STRUCTURE MEMBERS
+The
+.Sy usba_hcdi_ops
+structure has the following members:
+.Bd -literal -offset indent
+int		usba_hcdi_ops_version;
+dev_info_t	*usba_hcdi_dip;
+
+int	(*usba_hcdi_pm_support)(dev_info_t *);
+int	(*usba_hcdi_pipe_open)(usba_pipe_handle_data_t *, usb_flags_t);
+int	(*usba_hcdi_pipe_close)(usba_pipe_handle_data_t *, usb_flags_t);
+int	(*usba_hcdi_pipe_reset)(usba_pipe_handle_data_t *, usb_flags_t);
+void	(*usba_hcdi_pipe_reset_data_toggle)(usba_pipe_handle_data_t *);
+
+int	(*usba_hcdi_pipe_ctrl_xfer)(usba_pipe_handle_data_t *,
+	    usb_ctrl_req_t *, usb_flags_t);
+
+int	(*usba_hcdi_bulk_transfer_size)(usba_device_t *, size_t *);
+int	(*usba_hcdi_pipe_bulk_xfer)(usba_pipe_handle_data_t *,
+	    usb_bulk_req_t *, usb_flags_t);
+
+int	(*usba_hcdi_pipe_intr_xfer)(usba_pipe_handle_data_t *,
+	    usb_intr_req_t *, usb_flags_t);
+int	(*usba_hcdi_pipe_stop_intr_polling)(usba_pipe_handle_data_t *,
+	    usb_flags_t);
+
+int	(*usba_hcdi_pipe_isoc_xfer)(usba_pipe_handle_data_t *,
+	    usb_isoc_req_t *, usb_flags_t);
+int	(*usba_hcdi_pipe_stop_isoc_polling)(usba_pipe_handle_data_t *,
+	    usb_flags_t);
+int	(*usba_hcdi_get_current_frame_number)(usba_device_t *,
+	    usb_frame_number_t *);
+int	(*usba_hcdi_get_max_isoc_pkts)(usba_device_t *, uint_t *);
+
+int	(*usba_hcdi_console_input_init)(usba_pipe_handle_data_t *,
+	    uchar_t **, usb_console_info_impl_t *);
+int	(*usba_hcdi_console_input_fini)(usb_console_info_impl_t *);
+int	(*usba_hcdi_console_input_enter)(usb_console_info_impl_t *);
+int	(*usba_hcdi_console_read)(usb_console_info_impl_t *, uint_t);
+int	(*usba_hcdi_console_input_exit)(usb_console_info_impl_t *);
+
+int	(*usba_hcdi_console_output_init)(usba_pipe_handle_data_t *,
+	    usb_console_info_impl_t *);
+int	(*usba_hcdi_console_output_fini)(usb_console_info_impl_t *);
+int	(*usba_hcdi_console_output_enter)(usb_console_info_impl_t *);
+int	(*usba_hcdi_console_write)(usb_console_info_impl_t *, uchar_t *,
+	    uint_t, uint_t *);
+int	(*usba_hcdi_console_output_exit)(usb_console_info_impl_t *);
+
+int	(*usba_hcdi_device_init)(usba_device_t *, usb_port_t, void **);
+void	(*usba_hcdi_device_fini)(usba_device_t *, void *);
+int	(*usba_hcdi_device_address)(usba_device_t *);
+
+int	(*usba_hcdi_hub_update)(usba_device_t *, uint8_t, uint8_t);
+.Ed
+.Pp
+The
+.Sy usba_hcdi_ops_version
+member is used to indicate the revision of the operations vector. HCD
+drivers should generally set this to
+.Dv HCDI_OPS_VERSION .
+.Pp
+The
+.Sy usba_hcdi_dip
+member should be set to the
+.Sy dev_info_t
+structure of the HCD driver that was received in
+.Xr attach 9E .
+.Pp
+The
+.Sy usba_hcdi_pm_support
+member is vestigial. If may be set to
+.Dv NULL
+or to a function which only returns
+.Sy USB_FAILURE .
+.Pp
+The
+.Sy usba_hcdi_pipe_open
+member should be set to a function which takes care of the all of the
+controller-specific actions of opening up an endpoint on a device and
+associating it with the pipe. See
+.Xr usba_hcdi_pipe_open 9E
+for more information.
+.Pp
+The
+.Sy usba_hcdi_pipe_close
+member should be set to a function which takes care of releasing all of
+the controller-specific resources and actions taken when the pipe was
+opened. This function also has the responsibility to clean up any
+outstanding polling on the endpoint. See
+.Xr usba_hcdi_pipe_close 9E
+for more information.
+.Pp
+The
+.Sy usba_hcdi_pipe_reset
+member should be set to a function that takes care of resetting a pipe.
+A pipe reset not only performs controller-specific functionality, but it
+also cleans up any outstanding requests and terminates polling. See
+.Xr usba_hcdi_pipe_reset 9E
+for more information.
+.Pp
+The
+.Sy usba_hcdi_pipe_reset_data_toggle
+member should be set to a function that takes care of the USB data
+toggle, if the controller exposes this functionality to the host.
+.Pp
+The
+.Sy usba_hcdi_pipe_ctrl_xfer
+member should be set to a function that handles control transfers for any
+device, including the root hub. See
+.Xr usba_hcdi_pipe_ctrl_xfer 9E
+for more information.
+.Pp
+The
+.Sy usba_hcdi_bulk_transfer_size
+member should be a set to a function which can return the maximum amount
+of data that can be performed in a given USB transfer for a bulk
+transfer.
+.Pp
+The
+.Sy usba_hcdi_pipe_bulk_xfer
+member should be set set to a function which performs a bulk transfer.
+See
+.Xr usba_hcdi_pipe_bulk_xfer 9E
+for more information.
+.Pp
+The
+.Sy usba_hcdi_pipe_intr_xfer
+member should be set to a function which performs interrupt transfers.
+These may be both periodic and one-shot transfers. In addition, this may
+need to handle requests for the root hub. See
+.Xr usba_hcdi_pipe_intr_xfer 9E
+for more information.
+.Pp
+The
+.Sy usba_hcdi_pipe_stop_intr_polling
+member should be set to a function which is used to terminate interrupt
+polling and return the original interrupt request. See
+.Xr usba_hcdi_pipe_stop_intr_polling 9E
+for more information.
+.Pp
+The
+.Sy usba_hcdi_pipe_isoc_xfer
+member should be set to a function which performs isochronous transfers.
+These may be both periodic and one-shot transfers. See
+.Xr usba_hcdi_pipe_isoc_xfer 9E
+for more information.
+.Pp
+The
+.Sy usba_hcdi_pipe_stop_isoc_polling
+member should be set to a function which is used to terminate isochronous
+polling and return the original isochronous request. See
+.Xr usba_hcdi_pipe_stop_isoc_polling 9E
+for more information.
+.Pp
+The
+.Sy usba_hcdi_get_current_frame_number
+member should be set to a function which returns the current virtual
+frame number. While this entry point is required, at this time, nothing
+uses this functionality in illumos, so having a dummy function which
+just returns
+.Sy USB_FAILURE
+is acceptable.
+.Pp
+The
+.Sy usba_hcdi_max_isoc_pkts
+member should be set to a function that returns the maximum number of
+isochronous fragments that can be queued in a given transfer.
+.Pp
+The
+.Sy usba_hcdi_console_input_init ,
+.Sy usba_hcdi_console_input_fini ,
+.Sy usba_hcdi_console_input_enter ,
+.Sy usba_hcdi_console_read ,
+and
+.Sy usba_hcdi_console_input_exit
+members are used to facilitate a USB device acting as the system console
+and reading input from it. Support for this is optional in an HCD
+driver. HCD drivers which do not support this functionality should have
+functions which return
+.Sy USB_FAILURE .
+.Pp
+The
+.Sy usba_hcdi_console_output_init ,
+.Sy usba_hcdi_console_output_fini ,
+.Sy usba_hcdi_console_output_enter ,
+.Sy usba_hcdi_console_writ ,
+and
+.Sy usba_hcdi_console_output_exit
+members are used to facilitate a USB device acting as the system console
+and outputting data to it. Support for this is optional in an HCD
+driver. HCD drivers which do not support this functionality should have
+functions which return
+.Sy USB_FAILURE .
+.Pp
+The
+.Sy usba_hcdi_device_init
+member is an
+.Em optional
+entry point that will be called every time a new device is initialized
+and detected by the system. If an HCD does not need this functionality,
+the member should be set to
+.Dv NULL .
+See
+.Xr usba_hcdi_device_init 9E
+for more information.
+.Pp
+The
+.Sy usba_hcdi_device_fini
+member is an
+.Em optional
+entry point that will be called every time a device is removed from the
+system, whether through it being unplugged or a
+.Xr cfgadm 1M
+action. If an HCD does not need this functionality,
+the member should be set to
+.Dv NULL .
+See
+.Xr usba_hcdi_device_fini 9E
+for more information.
+.Pp
+The
+.Sy usba_hcdi_device_address
+member is an
+.Em optional
+entry point that will be called every time a USB device needs to be
+addressed. If an HCD driver does not need this functionality, the member
+should be set to
+.Dv NULL .
+See
+.Xr usba_hcdi_device_address 9E
+for more information.
+.Pp
+The
+.Sy usba_hcdi_hub_update
+member is an
+.Em optional
+entry point that will be called every time a device descriptor is read
+that turns out to be a hub. This gives HCD drivers a chance to perform
+any needed controller-specific functionality before the device is
+used. If an HCD driver does not need this functionality, the member
+should be set to
+.Dv NULL .
+See
+.Xr usba_hcdi_hub_update 9E
+for more information.
+.Sh SEE ALSO
+.Xr cfgadm 1M ,
+.Xr attach 9E ,
+.Xr usba_hcdi 9E ,
+.Xr usba_hcdi_device_address 9E ,
+.Xr usba_hcdi_device_fini 9E ,
+.Xr usba_hcdi_device_init 9E ,
+.Xr usba_hcdi_hub_update 9E ,
+.Xr usba_hcdi_pipe_bulk_xfer 9E ,
+.Xr usba_hcdi_pipe_close 9E ,
+.Xr usba_hcdi_pipe_ctrl_xfer 9E ,
+.Xr usba_hcdi_pipe_intr_xfer 9E ,
+.Xr usba_hcdi_pipe_isoc_xfer 9E ,
+.Xr usba_hcdi_pipe_open 9E ,
+.Xr usba_hcdi_pipe_reset 9E ,
+.Xr usba_hcdi_pipe_stop_intr_polling 9E ,
+.Xr usba_hcdi_pipe_stop_isoc_polling 9E ,
+.Xr usba_alloc_hcdi_ops 9F ,
+.Xr usba_free_hcdi_ops 9F ,
+.Xr usba_hcdi_register 9F
diff --git a/usr/src/man/man9s/usba_hcdi_register_args.9s b/usr/src/man/man9s/usba_hcdi_register_args.9s
new file mode 100644
index 0000000000..bdb564d07d
--- /dev/null
+++ b/usr/src/man/man9s/usba_hcdi_register_args.9s
@@ -0,0 +1,112 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Sep 20, 2016
+.Dt USBA_HCDI_REGISTER_ARGS 9S
+.Os
+.Sh NAME
+.Nm usba_hcdi_register_args ,
+.Nm usba_hcdi_register_args_t
+.Nd USB HCD driver registeration
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private
+.Pp
+This is a private data structure that is not part of the stable DDI. It
+may be removed or changed at any time.
+.Sh DESCRIPTION
+The
+.Sy usba_hcdi_register_args_t
+structure is used by USB HCD device drivers to register with the USBA
+framework.
+.Pp
+The structure is used with the
+.Xr usba_hcdi_register 9F
+function. Device drivers may statically allocate this structure on the
+stack. It does not need to be allocated on the heap or used beyond the
+call to
+.Xr usba_hcdi_register 9F .
+.Pp
+For more information on the HCD device driver initialization process,
+see
+.Xr usba_hcdi 9E .
+.Sh STRUCTURE MEMBERS
+The
+.Sy usba_hcdi_register_args_t
+structure has the following members:
+.Bd -literal -offset indent
+uint_t			usba_hcdi_register_version;
+dev_info_t		*usba_hcdi_register_dip;
+usba_hcdi_ops_t		*usba_hcdi_register_ops;
+ddi_dma_attr_t		*usba_hcdi_register_dma_attr;
+ddi_iblock_cookie_t	usba_hcdi_register_iblock_cookie;
+.Ed
+.Pp
+The
+.Sy usba_hcdi_register_version
+function should be set to the value of the pre-processor macro
+.Sy HCDI_REGISTER_VERSION .
+This ensures that if future revisions to this structure are made,
+existing drivers should continue to function. Note, that this structure
+is
+.Sy Volatile .
+Support for older versions or drastic changes may occur at any time and
+this should not be relied on nor construed as a guarantee against such
+changes.
+.Pp
+The
+.Sy usba_hcdi_register_dip
+should be set to the
+.Sy dev_info_t
+of the device driver instance that is registering with the USBA.
+.Pp
+The
+.Sy usba_hcdi_register_ops
+member is a structure of entry points for the USBA framework to call
+into the USB framework. It should be allocated with a call to
+.Xr usba_alloc_hcdi_ops 9F
+and released with a call to
+.Xr usba_free_hcdi_ops 9F ,
+after the drive has called
+.Xr usba_hcdi_register 9F .
+.Pp
+Please see
+.Xr usba_hcdi_ops 9S
+for more information on the members of the structure and for more
+information on how they should be filled in.
+.Pp
+The
+.Sy usba_hcdi_register_dma_attr
+member should be a pointer to a set of DMA attributes. These DMA
+attributes will be used by a subset of client device drivers to perform
+allocations, in particular scsa2usb. In general, try to make sure that
+these DMA attributes are valid for more transforms, though these will
+generally be used for bulk transfers.
+.Pp
+The
+.Sy usba_hcdi_register_iblock_cookie
+members should be filed in with the general interrupt priority of the
+device driver after it has allocated interrupts. Device drivers may
+obtain the priority by calling
+.Xr ddi_intr_get_pri 9F
+and then casting the obtained interrupt priority to the
+.Sy ddi_iblock_cookie_t .
+.Sh SEE ALSO
+.Xr usba_hcdi 9E ,
+.Xr ddi_intr_get_pri 9F ,
+.Xr usba_alloc_hcdi_ops 9F ,
+.Xr usba_free_hcdi_ops 9F ,
+.Xr usba_hcdi_register 9F ,
+.Xr usba_hcdi_ops 9S
diff --git a/usr/src/man/man9s/usba_pipe_handle_data.9s b/usr/src/man/man9s/usba_pipe_handle_data.9s
new file mode 100644
index 0000000000..aed8e36fb6
--- /dev/null
+++ b/usr/src/man/man9s/usba_pipe_handle_data.9s
@@ -0,0 +1,145 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2016 Joyent, Inc.
+.\"
+.Dd Dec 20, 2016
+.Dt USBA_PIPE_HANDLE_DATA 9S
+.Os
+.Sh NAME
+.Nm usba_pipe_handle_data
+.Nm usba_pipe_handle_data_t
+.Nd USBA Pipe Handle Data Structure
+.Sh SYNOPSIS
+.In sys/usb/usba/hcdi.h
+.Sh INTERFACE LEVEL
+.Sy Volatile -
+illumos USB HCD private
+.Pp
+This is a private data structure that is not part of the stable DDI. It
+may be removed or changed at any time.
+.Sh DESCRIPTION
+The
+.Sy usba_pipe_handle_data
+structure is the USB architecture's (USBA) way of representing a pipe.
+Every pipe is a part of a USB device. Pipe's may be shared between
+client drivers or be exclusive to one.  For more background on pipe's
+see the
+.Sy USB Endpoint Background
+section of
+.Xr usba_hcdi 9E .
+.Pp
+This structure is provided to HCD driver's when performing requests of
+various kinds. The majority of the structures listed here are
+.Em read-only ;
+however, HCD drivers are allowed to update a single member, listed
+below. All of the writable members are protected by a lock, the member
+.Sy p_mutex .
+See the
+.Sy Locking
+section in
+.Xr usba_hcdi 9E
+for more information on lock ordering and when HCD drivers should enter
+this lock.
+.Pp
+A pipe handle has an explicit life cycle wih a device driver. The driver
+first sees the pipe handle when its
+.Xr usba_hcdi_pipe_open 9E
+entry point is called. At that time, the HCD driver has the change to
+store private data on the handle. This pipe handle will be used in
+subsequent requests until the handle is closed, through a call to the
+HCD driver's
+.Xr usba_hcdi_pipe_close 9E
+entry point.
+.Sh STRUCTURE MEMBERS
+The
+.Sy usba_pipe_handle_data_t
+structure includes the following members:
+.Bd -literal -offset -indent
+usba_device_t		*p_usba_device;
+usb_ep_descr_t		p_ep;
+usb_ep_xdescr_t		p_xep;
+dev_info_t		p_dip;
+usb_opaque_t		p_hcd_private;
+kmutex_t		p_mutex;
+int			p_req_count;
+.Ed
+.Pp
+The
+.Sy p_usba_device
+member points to the
+.Xr usba_device 9S
+structure that this pipe belongs to. This member should always be set
+for an endpoint handed to an HCD driver.
+.Pp
+The
+.Sy p_ep
+member is filled in with the endpoint descriptor that represents this
+device. The endpoint structure is documented in
+.Xr usb_ep_descr 9S .
+.Pp
+The
+.Sy p_xep
+member is filled in with the endpoint descriptor and any additional
+endpoint descriptors that may exist. The structure is documented in
+.Xr usb_ep_xdescr 9S .
+The endpoint descriptor is the same in both
+.Sy p_ep
+and
+.Sy p_xep .
+.Pp
+The
+.Sy p_hcd_private
+member is reserved for use with HCD drivers. An HCD driver may set
+this member during
+.Xr usba_hcdi_pipe_open 9E .
+If set, it can reference this member throughout the life time of the
+pipe. The driver should ensure to clean it up when its
+.Xr usba_hcdi_pipe_close 9E
+entry point is called.
+.Pp
+The
+.Sy p_mutex
+member protects the member
+.Sy p_req_count .
+The mutex should be entered whenever the value is being manipulated.
+.Pp
+The
+.Sy p_req_count
+member indicates the number of outstanding requests on the pipe. When
+performing
+.Em periodic
+interrupt or isochronous transfers, it is the responsibility of the HCD
+driver to increment the value of
+.Sy p_req_count
+if it duplicates a request with either
+.Xr usba_hcdi_dup_intr_req 9F
+or
+.Xr usba_hcdi_dup_isoc_req 9F .
+.Pp
+Similarly, if the device driver for some reasons removes a request it
+duplicated without submitting it to the USBA, it should decrement the
+member.
+.Pp
+The HCD driver should take special care to ensure that the value of
+.Sy p_req_count
+is always greater than one. There should always be an outstanding
+request that an HCD driver has for the pipe, especially if it is a
+periodic endpoint. It should only manipulate this member while it owns
+.Sy p_mutex .
+.Sh SEE ALSO
+.Xr usba_hcdi_pipe_close 9E ,
+.Xr usba_hcdi_pipe_open 9E ,
+.Xr usba_hcdi_dup_intr_req 9F ,
+.Xr usba_hcdi_dup_isoc_req 9F ,
+.Xr usb_ep_descr 9S ,
+.Xr usb_ep_xdescr 9S ,
+.Xr usba_device 9S
diff --git a/usr/src/pkg/manifests/driver-usb.mf b/usr/src/pkg/manifests/driver-usb.mf
index ce9dfe1321..e10e9a2d2a 100644
--- a/usr/src/pkg/manifests/driver-usb.mf
+++ b/usr/src/pkg/manifests/driver-usb.mf
@@ -23,6 +23,7 @@
 # Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
 # Copyright 2012 Nexenta Systems, Inc. All rights reserved.
 # Copyright 2014 Garrett D'Amore <garrett@damore.org>
+# Copyright 2017, Joyent, Inc.
 #
 
 #
@@ -64,6 +65,7 @@ $(i386_ONLY)dir path=usr/lib/xhci group=sys
 dir path=usr/share
 dir path=usr/share/man
 dir path=usr/share/man/man7m
+dir path=usr/share/man/man9e
 dir path=usr/share/man/man9f
 dir path=usr/share/man/man9s
 driver name=ehci alias=pciclass,0c0320 perms="* 0644 root sys"
@@ -144,9 +146,22 @@ file path=usr/share/man/man7d/usb_ia.7d
 file path=usr/share/man/man7d/usb_mid.7d
 file path=usr/share/man/man7d/usba.7d
 file path=usr/share/man/man7d/usbprn.7d
+$(i386_ONLY)file path=usr/share/man/man7d/xhci.7d
 file path=usr/share/man/man7m/usb_ah.7m
 file path=usr/share/man/man7m/usbkbm.7m
 file path=usr/share/man/man7m/usbms.7m
+file path=usr/share/man/man9e/usba_hcdi.9e
+file path=usr/share/man/man9e/usba_hcdi_cb_ops.9e
+file path=usr/share/man/man9e/usba_hcdi_device_address.9e
+file path=usr/share/man/man9e/usba_hcdi_device_init.9e
+file path=usr/share/man/man9e/usba_hcdi_hub_update.9e
+file path=usr/share/man/man9e/usba_hcdi_pipe_bulk_xfer.9e
+file path=usr/share/man/man9e/usba_hcdi_pipe_ctrl_xfer.9e
+file path=usr/share/man/man9e/usba_hcdi_pipe_intr_xfer.9e
+file path=usr/share/man/man9e/usba_hcdi_pipe_isoc_xfer.9e
+file path=usr/share/man/man9e/usba_hcdi_pipe_open.9e
+file path=usr/share/man/man9e/usba_hcdi_pipe_reset.9e
+file path=usr/share/man/man9e/usba_hcdi_pipe_stop_intr_polling.9e
 file path=usr/share/man/man9f/usb_alloc_request.9f
 file path=usr/share/man/man9f/usb_client_attach.9f
 file path=usr/share/man/man9f/usb_clr_feature.9f
@@ -176,6 +191,15 @@ file path=usr/share/man/man9f/usb_pipe_set_private.9f
 file path=usr/share/man/man9f/usb_pipe_xopen.9f
 file path=usr/share/man/man9f/usb_register_hotplug_cbs.9f
 file path=usr/share/man/man9f/usb_reset_device.9f
+file path=usr/share/man/man9f/usba_alloc_hcdi_ops.9f
+file path=usr/share/man/man9f/usba_hcdi_cb.9f
+file path=usr/share/man/man9f/usba_hcdi_dup_intr_req.9f
+file path=usr/share/man/man9f/usba_hcdi_dup_isoc_req.9f
+file path=usr/share/man/man9f/usba_hcdi_get_device_private.9f
+file path=usr/share/man/man9f/usba_hcdi_register.9f
+file path=usr/share/man/man9f/usba_hubdi_bind_root_hub.9f
+file path=usr/share/man/man9f/usba_hubdi_cb_ops.9f
+file path=usr/share/man/man9f/usba_hubdi_dev_ops.9f
 file path=usr/share/man/man9s/usb_bulk_req.9s
 file path=usr/share/man/man9s/usb_callback_flags.9s
 file path=usr/share/man/man9s/usb_cfg_descr.9s
@@ -193,6 +217,10 @@ file path=usr/share/man/man9s/usb_isoc_req.9s
 file path=usr/share/man/man9s/usb_other_speed_cfg_descr.9s
 file path=usr/share/man/man9s/usb_request_attributes.9s
 file path=usr/share/man/man9s/usb_string_descr.9s
+file path=usr/share/man/man9s/usba_device.9s
+file path=usr/share/man/man9s/usba_hcdi_ops.9s
+file path=usr/share/man/man9s/usba_hcdi_register_args.9s
+file path=usr/share/man/man9s/usba_pipe_handle_data.9s
 legacy pkg=SUNWusb desc="USBA (USB framework) and USB Device Drivers" \
     name="USB Device Drivers"
 license cr_Sun license=cr_Sun
@@ -201,6 +229,15 @@ license license_in_headers license=license_in_headers
 license usr/src/uts/common/sys/usb/hcd/xhci/THIRDPARTYLICENSE \
     license=usr/src/uts/common/sys/usb/hcd/xhci/THIRDPARTYLICENSE
 link path=usr/share/man/man7d/usb.7d target=usba.7d
+link path=usr/share/man/man9e/usba_hcdi_cb_close.9e target=usba_hcdi_cb_ops.9e
+link path=usr/share/man/man9e/usba_hcdi_cb_ioctl.9e target=usba_hcdi_cb_ops.9e
+link path=usr/share/man/man9e/usba_hcdi_cb_open.9e target=usba_hcdi_cb_ops.9e
+link path=usr/share/man/man9e/usba_hcdi_device_fini.9e \
+    target=usba_hcdi_device_init.9e
+link path=usr/share/man/man9e/usba_hcdi_pipe_close.9e \
+    target=usba_hcdi_pipe_open.9e
+link path=usr/share/man/man9e/usba_hcdi_pipe_stop_isoc_polling.9e \
+    target=usba_hcdi_pipe_stop_intr_polling.9e
 link path=usr/share/man/man9f/usb_alloc_bulk_req.9f \
     target=usb_alloc_request.9f
 link path=usr/share/man/man9f/usb_alloc_ctrl_req.9f \
@@ -234,6 +271,17 @@ link path=usr/share/man/man9f/usb_set_alt_if.9f target=usb_get_alt_if.9f
 link path=usr/share/man/man9f/usb_set_cfg.9f target=usb_get_cfg.9f
 link path=usr/share/man/man9f/usb_unregister_hotplug_cbs.9f \
     target=usb_register_hotplug_cbs.9f
+link path=usr/share/man/man9f/usba_free_hcdi_ops.9f \
+    target=usba_alloc_hcdi_ops.9f
+link path=usr/share/man/man9f/usba_hcdi_unregister.9f \
+    target=usba_hcdi_register.9f
+link path=usr/share/man/man9f/usba_hubdi_close.9f target=usba_hubdi_cb_ops.9f
+link path=usr/share/man/man9f/usba_hubdi_ioctl.9f target=usba_hubdi_cb_ops.9f
+link path=usr/share/man/man9f/usba_hubdi_open.9f target=usba_hubdi_cb_ops.9f
+link path=usr/share/man/man9f/usba_hubdi_root_hub_power.9f \
+    target=usba_hubdi_dev_ops.9f
+link path=usr/share/man/man9f/usba_hubdi_unbind_root_hub.9f \
+    target=usba_hubdi_bind_root_hub.9f
 link path=usr/share/man/man9s/usb_bulk_req_t.9s target=usb_bulk_req.9s
 link path=usr/share/man/man9s/usb_bulk_request.9s target=usb_bulk_req.9s
 link path=usr/share/man/man9s/usb_ctrl_req_t.9s target=usb_ctrl_req.9s
@@ -244,3 +292,9 @@ link path=usr/share/man/man9s/usb_intr_req_t.9s target=usb_intr_req.9s
 link path=usr/share/man/man9s/usb_intr_request.9s target=usb_intr_req.9s
 link path=usr/share/man/man9s/usb_isoc_req_t.9s target=usb_isoc_req.9s
 link path=usr/share/man/man9s/usb_isoc_request.9s target=usb_isoc_req.9s
+link path=usr/share/man/man9s/usba_device_t.9s target=usba_device.9s
+link path=usr/share/man/man9s/usba_hcdi_ops_t.9s target=usba_hcdi_ops.9s
+link path=usr/share/man/man9s/usba_hcdi_register_args_t.9s \
+    target=usba_hcdi_register_args.9s
+link path=usr/share/man/man9s/usba_pipe_handle_data_t.9s \
+    target=usba_pipe_handle_data.9s