usr/src/man/man9f/usb_ep_xdescr_fill.9f

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2016 Joyent, Inc.
  13 .\"
  14 .Dd Aug 7, 2016
  15 .Dt USB_EP_XDESCR_FILL 9F
  16 .Os
  17 .Sh NAME
  18 .Nm usb_ep_xdescr_fill
  19 .Nd fill extended endpoint description from endpoint data
  20 .Sh SYNOPSIS
  21 .In sys/usb/usba.h
  22 .Ft int
  23 .Fo usb_ep_xdescr_fill
  24 .Fa "uint_t version"
  25 .Fa "dev_info_t *dip"
  26 .Fa "usb_ep_data_t *ep_data"
  27 .Fa "usb_ep_xdescr_t *ep_xdescr"
  28 .Fc
  29 .Sh INTERFACE STABILITY
  30 illumos DDI specific
  31 .Sh PARAMETESR
  32 .Bl -tag -width Fa
  33 .It Fa version
  34 Indicates the current version of the
  35 .Ft usb_ep_xdescr_t
  36 structure the driver is using.
  37 Callers should always specify
  38 .Sy USB_EP_XDESCR_CURRENT_VERSION .
  39 .It Fa dip
  40 Pointer to the device's
  41 .Sy dev_info
  42 structure.
  43 .It Fa ep_data
  44 Pointer to endpoint data retrieved by calling
  45 .Xr usb_lookup_ep_data 9F .
  46 .It Fa ep_xdescr
  47 Pointer to the extended endpoint descriptor that will be filled out.
  48 .El
  49 .Sh DESCRIPTION
  50 The
  51 .Fn usb_ep_xdescr_fill
  52 function is used to fill in the members of the extended endpoint
  53 descriptor
  54 .Fa ep_xdescr
  55 based on the endpoint descriptor data in
  56 .Fa ep_data .
  57 Once filled in,
  58 .Fa ep_xdescr
  59 can be used to open a pipe by calling
  60 .Xr usb_pipe_xopen 9F .
  61 .Pp
  62 Prior to USB 3.0, only one descriptor, the
  63 .Xr usb_ep_descr 9S ,
  64 was needed to describe an endpoint.
  65 However, with USB 3.0, additional companion descriptors have been added and are
  66 required to successfully open an endpoint.
  67 After calling this, all descriptors needed to successfully open a pipe will be
  68 placed into
  69 .Fa ep_xdescr
  70 and the endpoint data,
  71 .Fa ep_data ,
  72 is no longer required.
  73 .Sh CONTEXT
  74 The
  75 .Fn usb_ep_xdescr_fill
  76 is generally only called from a drivers
  77 .Xr attach 9E
  78 entry point; however, it may be called from either
  79 .Sy user
  80 or
  81 .Sy kernel
  82 context.
  83 .Sh RETURN VALUES
  84 Upon successful completion, the
  85 .Fn usb_ep_xdescr_fill
  86 function returns
  87 .Sy USB_SUCCESS .
  88 Otherwise an error number is returned.
  89 .Sh ERRORS
  90 .Bl -tag -width Er
  91 .It Er USB_INVALID_ARGS
  92 The value of
  93 .Fa version
  94 is unknown, or one of
  95 .Fa dip ,
  96 .Fa ep_data ,
  97 and
  98 .Fa ep_xdescr
  99 was an invalid pointer.
 100 .It Er USB_FAILURE
 101 An unknown error occurred.
 102 .El
 103 .Sh SEE ALSO
 104 .Xr usb_lookup_ep_data 9F ,
 105 .Xr usb_pipe_xopen 9F ,
 106 .Xr usb_ep_descr 9S ,
 107 .Xr usb_ep_ss_comp_descr 9S ,
 108 .Xr usb_ep_xdescr 9S