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.
  40 It may be 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.
  57 It will be called when child devices of the root hub are being initialized.
  58 A call to this entry point will occur before any calls to open a pipe to the
  59 child device 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.
  65 The HCD may also opt to store private data for this device as a result of
  66 whatever initialization it performed.
  67 The data should be stored in the
  68 .Fa hcd_privatep
  69 pointer.
  70 Data stored this will be accessible to the HCD driver through the
  71 .Xr usba_hcdi_get_device_private 9F
  72 function.
  73 .Pp
  74 The
  75 .Fn usba_hcdi_device_fini
  76 entry point is an optional entry point.
  77 It will be called when child devices of the root hub are being removed.
  78 The HCD should perform any necessary work with the root controller to finish
  79 tearing down the device.
  80 In addition, if the HCD stored private data it will a pointer to it in the
  81 .Fa hcd_private
  82 pointer.
  83 The HCD driver must release any resources associated with its private data.
  84 If it does not, the resources will be leaked.
  85 .Pp
  86 At the time
  87 .Fn usba_hcdi_device_fini
  88 is called, all associated pipes should have been closed through the
  89 .Xr usba_hcdi_pipe_close 9E
  90 function.
  91 .Pp
  92 The HCD driver is guaranteed that no other entry points will be invoked
  93 for the USB device
  94 .Fa usb_device
  95 while a call to either function is ongoing.
  96 However, the entry point may be called in parallel on behalf of separate
  97 devices.
  98 .Sh CONTEXT
  99 This function is called from kernel context only.
 100 .Sh RETURN VALUES
 101 Upon successful completion, the
 102 .Fn usba_hcdi_device_init
 103 function should return
 104 .Sy USB_SUCCESS .
 105 Otherwise, it should return the appropriate error.
 106 .Sh SEE ALSO
 107 .Xr usba_hcd 9E ,
 108 .Xr usba_hcdi_pipe_close 9E ,
 109 .Xr usba_hcdi_pipe_open 9E