usr/src/man/man9e/usba_hcdi_device_address.9e

   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 Dec 20, 2016
  15 .Dt USBA_HCDI_HUB_UPDATE 9E
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi_device_address
  19 .Nd Assign USB address to device
  20 .Sh SYNOPSIS
  21 .In sys/usb/usba/hcdi.h
  22 .Ft int
  23 .Fo prefix_hcdi_device_address
  24 .Fa "usba_device_t *ud"
  25 .Fc
  26 .Sh INTERFACE LEVEL
  27 .Sy Volatile -
  28 illumos USB HCD private function
  29 .Pp
  30 This is a private function that is not part of the stable DDI. It may be
  31 removed or changed at any time.
  32 .Sh PARAMETERS
  33 .Bl -tag -width Fa
  34 .It Fa ud
  35 Pointer to a USB device structure being updated. See
  36 .Xr usba_device 9S
  37 for more information.
  38 .El
  39 .Sh DESCRIPTION
  40 The
  41 .Fn usba_hcdi_device_address
  42 entry point is an optional entry point for USB host controller drivers.
  43 Some USB host controllers do not allow the USB SET_ADDRESS command to be
  44 issued to a device. Instead, they will be responsible for setting the
  45 address in a controller-specific way. If the host controller driver
  46 requires this behavior, then it must implement this function. Otherwise,
  47 if the host controller does not require this functionality, it should
  48 set the entry point in the
  49 .Xr usba_hcdi_ops 9S
  50 structure to
  51 .Dv NULL .
  52 .Pp
  53 The USBA will always set an address for the USBA device
  54 .Fa ud
  55 regardless of whether or not this function is implemented. If the HCD
  56 implements this entry point and it needs the addressing information for
  57 whatever reason, then it is the responsibility of the driver to keep
  58 track of it separately.
  59 .Pp
  60 This entry point will be called after the
  61 .Xr usba_hcdi_device_init 9E
  62 entry point has been called. Any private data stored on the device will
  63 be available through the
  64 .Xr usba_hcdi_get_device_private 9F
  65 function.
  66 .Pp
  67 Upon completion of the function, the device is expected to be addressed
  68 and thus able to have endpoints opened and transfers performed on them.
  69 If this function fails, the device's enumeration will halt.
  70 .Sh CONTEXT
  71 This function is called from kernel context ontly.
  72 .Sh RETURN VALUES
  73 Upon successful completion, the
  74 .Fn usba_hcdi_device_address
  75 function should return
  76 .Sy USB_SUCCESS .
  77 Otherwise, it should return the appropriate USB error. If uncertain, use
  78 .Sy USB_FAILURE .
  79 .Sh SEE ALSO
  80 .Xr usba_hcdi_device_init 9E ,
  81 .Xr usba_hcdi_get_device_private 9F ,
  82 .Xr usba_device 9S ,
  83 .Xr usba_hcdi_ops 9S