usr/src/man/man9e/usba_hcdi_hub_update.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_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. It may be
  33 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. See
  38 .Xr usba_device 9S
  39 for more information.
  40 .It Fa nports
  41 The number of ports present on the hub.
  42 .It Fa tt
  43 The value of the Think Time property as defined in the USB
  44 specification's hub descriptor.
  45 .El
  46 .Sh DESCRIPTION
  47 The
  48 .Fn usba_hcdi_hub_update
  49 entry point is an optional entry point for USB host controller drivers.
  50 It is used by some controllers to allow them to update information about
  51 a device in the controller after a device has been determined to be a
  52 hub during enumeration. If a host controller does not need to take any
  53 specific action after enumerating a hub, then it should simply set this
  54 entry point in the
  55 .Xr usba_hcdi_ops 9S
  56 structure to
  57 .Dv NULL .
  58 .Pp
  59 The
  60 .Fa nports
  61 and
  62 .Fa tt
  63 members provide relevant information from the device's hub class
  64 descriptor which can be used to help program the host controller. Any
  65 programming should be performed synchronously and be completed before
  66 this function returns.
  67 .Pp
  68 This function will be called after
  69 .Xr usba_hcdi_device_init 9E
  70 has been called. Any private data registered with that function will be
  71 available.
  72 .Pp
  73 If this function fails, the enumeration of this device will fail, the
  74 hub driver will not attach to this USB device, and all devices plugged
  75 into this hub will not be detected by the system.
  76 .Sh CONTEXT
  77 This functin is called from kernel context only.
  78 .Sh RETURN VALUES
  79 Upon successful completion, the
  80 .Fn usba_hcdi_hub_update
  81 function should return
  82 .Sy USB_SUCCESS .
  83 Otherwise, it should return the appropriate USB error. If uncertain, use
  84 .Sy USB_FAILURE .
  85 .Sh SEE ALSO
  86 .Xr usba_hcdi_device_init 9E ,
  87 .Xr usba_device 9S ,
  88 .Xr usba_hcdi_ops 9S