.\"
.\" 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 USB_EP_XDESCR 9S
.Os
.Sh NAME
.Nm usb_ep_xdescr ,
.Nm usb_ep_xdescr_t
.Nd extended endpoint descriptor
.Sh SYNOPSIS
.In sys/usb/usba.h
.Sh INTERFACE LEVEL
illumos DDI Specific
.Sh DESCRIPTION
The
.Sy usb_ep_xdescr_t
structure is used to describe an endpoint descriptor as well account for
the continuing evolutions in the USB specification.
.Pp
Starting with the
.Em USB 3.0
specification,
.Em USB 3.0
endpoints have an endpoint SuperSpeed companion descriptor.
See
.Xr usb_ep_ss_comp_descr 9S
for a description of the descriptor.
In the
.Em USB 3.1
specification, certain endpoints will have additional companion
descriptors.
.Pp
The
.Sy usb_ep_xdescr_t
structure, combined with the
.Xr usb_ep_xdescr_fill 9F
and
.Xr usb_pipe_xopen 9F
are designed to abstract away the need for USB client device drivers to
need to be updated in the face of these newer endpoints, whose
information is required for host controller devices to properly program
the device.
.Pp
After looking up endpoint data, through the
.Xr usb_lookup_ep_data 9F ,
device drivers should call the
.Xr usb_ep_xdescr_fill 9F
function.
After that, the
.Sy usb_ep_xdescr_t
structure will be filled in.
.Sh STRUCTURE MEMBERS
The
.Sy usb_ep_xdescr_t
structure has the following members:
.Bd -literal -offset indent
uint_t			uex_version;
usb_ep_xdescr_flags_t	uex_flags;
usb_ep_descr_t		uex_ep;
usb_ep_ss_comp_descr_t	uex_ep_ss;
.Ed
.Pp
The
.Sy uex_version
member is used to describe the current version of this structure.
This member will be set to the value passed in by the device driver to
.Xr usb_ep_xdescr_fill 9F .
Device drivers should ignore this field and should not modify the value
placed there or modify it.
.Pp
The
.Sy uex_flags
member is an enumeration that defines a number of flags.
Each flag indicates whether or not a given member is present or valid.
Before accessing any member other than
.Sy uex_ep ,
the device driver should check the flag here, otherwise its contents may
be undefined.
Currently the following flags are defined:
.Bl -tag -width Sy -offset indent
.It Sy USB_EP_XFLAGS_SS_COMP
Indicates that a SuperSpeed endpoint companion descriptor is present and
has been filled in.
The member
.Sy uex_ep_ss
is valid.
.El
.Pp
The
.Sy uex_ep
member contains a traditional USB endpoint descriptor.
Its contents are defined in
.Xr usb_ep_descr 9S .
There is no flag for this member in
.Sy uex_flags ,
it is always valid.
.Pp
The
.Sy uex_ep_ss
member contains a USB 3.0 SuperSpeed endpoint companion descriptor as
defined in
.Xr usb_ep_ss_comp_descr 9S .
This member is only valid if the
.Sy USB_EP_XFLAGS_SS_COMP
flag is specified in
.Sy uex_flags .
.Sh SEE ALSO
.Xr usb_ep_xdescr_fill 9F ,
.Xr usb_pipe_xopen 9F ,
.Xr usb_ep_descr 9S ,
.Xr usb_ep_ss_comp_descr 9S