usr/src/man/man9e/usba_hcdi_device_init.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 May 7, 2016
  15 .Dt USBA_HCDI_DEVICE_INIT 9E
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi_device_init ,
  19 .Nm usba_hcdi_device_fini
  20 .Nd USB device initialization and finalization
  21 .Sh SYNOPSIS
  22 .In sys/usb/usba/hcdi.h
  23 .Ft int
  24 .Fo prefix_hcdi_device_init
  25 .Fa "usba_device_t *usb_device"
  26 .Fa "usb_port_t port"
  27 .Fa "void **hcd_privatep"
  28 .Fc
  29 .Ft void
  30 .Fo prefix_hcdi_device_fini
  31 .Fa "usba_device_t *usb_device"
  32 .Fa "usb_port_t port"
  33 .Fa "void *hcd_private"
  34 .Fc
  35 .Sh INTERFACE LEVEL
  36 .Sy Volatile -
  37 illumos USB HCD private function
  38 .Pp
  39 This is a private function that is not part of the stable DDI. It may be
  40 removed or changed at any time.
  41 .Sh PARAMETERS
  42 .Bl -tag -width Fa
  43 .It Fa usb_device
  44 Pointer to a USB device structure.
  45 .It Fa port
  46 The port number the device was detected on.
  47 .It Fa hcd_privatep
  48 Pointer to storage space for a HCD driver to store private data for the
  49 device.
  50 .It Fa hcd_private
  51 Pointer to the HCD driver's private data for the device.
  52 .El
  53 .Sh DESCRIPTION
  54 The
  55 .Fn usba_hcdi_device_init
  56 entry point is an optional entry point. It will be called when child
  57 devices of the root hub are being initialized. A call to this entry
  58 point will occur before any calls to open a pipe to the child device
  59 through the
  60 .Xr usba_hcdi_pipe_open 9E
  61 entry point.
  62 .Pp
  63 During this time, the HCD driver should do any required initialization
  64 required by the host controller. The HCD may also opt to store private
  65 data for this device as a result of whatever initialization it
  66 performed. The data should be stored in the
  67 .Fa hcd_privatep
  68 pointer. Data stored this will be accessible to the HCD driver through
  69 the
  70 .Xr usba_hcdi_get_device_private 9F
  71 function.
  72 .Pp
  73 The
  74 .Fn usba_hcdi_device_fini
  75 entry point is an optional entry point. It will be called when child
  76 devices of the root hub are being removed. The HCD should perform any
  77 necessary work with the root controller to finish tearing down the
  78 device. In addition, if the HCD stored private data it will a pointer to
  79 it in the
  80 .Fa hcd_private
  81 pointer. The HCD driver must release any resources associated with its
  82 private data. If it does not, the resources will be leaked.
  83 .Pp
  84 At the time
  85 .Fn usba_hcdi_device_fini
  86 is called, all associated pipes should have been closed through the
  87 .Xr usba_hcdi_pipe_close 9E
  88 function.
  89 .Pp
  90 The HCD driver is guaranteed that no other entry points will be invoked
  91 for the USB device
  92 .Fa usb_device
  93 while a call to either function is ongoing. However, the entry point may
  94 be called in parallel on behalf of separate devices.
  95 .Sh CONTEXT
  96 This function is called from kernel context only.
  97 .Sh RETURN VALUES
  98 Upon successful completion, the
  99 .Fn usba_hcdi_device_init
 100 function should return
 101 .Sy USB_SUCCECSS .
 102 Otherwise, it should return the appropriate error.
 103 .Sh SEE ALSO
 104 .Xr usba_hcd 9E ,
 105 .Xr usba_hcdi_pipe_close 9E ,
 106 .Xr usba_hcdi_pipe_open 9E