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 February 15, 2020
  15 .Dt USBA_HCDI_HUB_UPDATE 9E
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi_hub_update
  19 .Nd USB HCD hub update entry point
  20 .Sh SYNOPSIS
  21 .In sys/usb/usba/hcdi.h
  22 .Ft int
  23 .Fo prefix_hcdi_hub_update
  24 .Fa "usba_device_t *ud"
  25 .Fa "uint8_t nports"
  26 .Fa "uint8_t tt"
  27 .Fc
  28 .Sh INTERFACE LEVEL
  29 .Sy Volatile -
  30 illumos USB HCD private function
  31 .Pp
  32 This is a private function that is not part of the stable DDI.
  33 It may be removed or changed at any time.
  34 .Sh PARAMETERS
  35 .Bl -tag -width Fa
  36 .It Fa ud
  37 Pointer to a USB device structure being updated.
  38 See
  39 .Xr usba_device 9S
  40 for more information.
  41 .It Fa nports
  42 The number of ports present on the hub.
  43 .It Fa tt
  44 The value of the Think Time property as defined in the USB
  45 specification's hub descriptor.
  46 .El
  47 .Sh DESCRIPTION
  48 The
  49 .Fn usba_hcdi_hub_update
  50 entry point is an optional entry point for USB host controller drivers.
  51 It is used by some controllers to allow them to update information about
  52 a device in the controller after a device has been determined to be a
  53 hub during enumeration.
  54 If a host controller does not need to take any specific action after enumerating
  55 a hub, then it should simply set this entry point in the
  56 .Xr usba_hcdi_ops 9S
  57 structure to
  58 .Dv NULL .
  59 .Pp
  60 The
  61 .Fa nports
  62 and
  63 .Fa tt
  64 members provide relevant information from the device's hub class
  65 descriptor which can be used to help program the host controller.
  66 Any programming should be performed synchronously and be completed before
  67 this function returns.
  68 .Pp
  69 This function will be called after
  70 .Xr usba_hcdi_device_init 9E
  71 has been called.
  72 Any private data registered with that function will be available.
  73 .Pp
  74 If this function fails, the enumeration of this device will fail, the
  75 hub driver will not attach to this USB device, and all devices plugged
  76 into this hub will not be detected by the system.
  77 .Sh CONTEXT
  78 This function is called from kernel context only.
  79 .Sh RETURN VALUES
  80 Upon successful completion, the
  81 .Fn usba_hcdi_hub_update
  82 function should return
  83 .Sy USB_SUCCESS .
  84 Otherwise, it should return the appropriate USB error.
  85 If uncertain, use
  86 .Sy USB_FAILURE .
  87 .Sh SEE ALSO
  88 .Xr usba_hcdi_device_init 9E ,
  89 .Xr usba_device 9S ,
  90 .Xr usba_hcdi_ops 9S