share/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.
  31 It may be 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.
  36 See
  37 .Xr usba_device 9S
  38 for more information.
  39 .El
  40 .Sh DESCRIPTION
  41 The
  42 .Fn usba_hcdi_device_address
  43 entry point is an optional entry point for USB host controller drivers.
  44 Some USB host controllers do not allow the USB SET_ADDRESS command to be
  45 issued to a device.
  46 Instead, they will be responsible for setting the address in a
  47 controller-specific way.
  48 If the host controller driver requires this behavior, then it must implement
  49 this function.
  50 Otherwise, if the host controller does not require this functionality, it should
  51 set the entry point in the
  52 .Xr usba_hcdi_ops 9S
  53 structure to
  54 .Dv NULL .
  55 .Pp
  56 The USBA will always set an address for the USBA device
  57 .Fa ud
  58 regardless of whether or not this function is implemented.
  59 If the HCD implements this entry point and it needs the addressing information
  60 for whatever reason, then it is the responsibility of the driver to keep
  61 track of it separately.
  62 .Pp
  63 This entry point will be called after the
  64 .Xr usba_hcdi_device_init 9E
  65 entry point has been called.
  66 Any private data stored on the device will be available through the
  67 .Xr usba_hcdi_get_device_private 9F
  68 function.
  69 .Pp
  70 Upon completion of the function, the device is expected to be addressed
  71 and thus able to have endpoints opened and transfers performed on them.
  72 If this function fails, the device's enumeration will halt.
  73 .Sh CONTEXT
  74 This function is called from kernel context ontly.
  75 .Sh RETURN VALUES
  76 Upon successful completion, the
  77 .Fn usba_hcdi_device_address
  78 function should return
  79 .Sy USB_SUCCESS .
  80 Otherwise, it should return the appropriate USB error.
  81 If uncertain, use
  82 .Sy USB_FAILURE .
  83 .Sh SEE ALSO
  84 .Xr usba_hcdi_device_init 9E ,
  85 .Xr usba_hcdi_get_device_private 9F ,
  86 .Xr usba_device 9S ,
  87 .Xr usba_hcdi_ops 9S