share/man/man9e/usba_hcdi_cb_ops.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_CB_OPS 9E
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi_cb_ops ,
  19 .Nm usba_hcdi_cb_open ,
  20 .Nm usba_hcdi_cb_ioctl ,
  21 .Nm usba_hcdi_cb_close
  22 .Nd USBA HCD Character Device character functions
  23 .Sh SYNOPSIS
  24 .In sys/types.h
  25 .In sys/file.h
  26 .In sys/errno.h
  27 .In sys/open.h
  28 .In sys/cred.h
  29 .In sys/ddi.h
  30 .In sys/sunddi.h
  31 .Ft int
  32 .Fo prefix_open
  33 .Fa "dev_t *devp"
  34 .Fa "int flag"
  35 .Fa "int otyp"
  36 .Fa "cred_t *credp"
  37 .Fc
  38 .Ft int
  39 .Fo prefix_ioctl
  40 .Fa "dev_t dev"
  41 .Fa "int cmd"
  42 .Fa "intptr_t arg"
  43 .Fa "int mode"
  44 .Fa "cred_t *cred_p"
  45 .Fa "int *rval_p"
  46 .Fc
  47 .Ft int
  48 .Fo prefix_close
  49 .Fa "dev_t dev"
  50 .Fa "int flag"
  51 .Fa "int otyp"
  52 .Fa "cred_t *cred_p"
  53 .Fc
  54 .Sh INTERFACE LEVEL
  55 .Sy Volatile -
  56 illumos USB HCD private function
  57 .Pp
  58 This describes private interfaces that are not part of the stable DDI.
  59 This may be removed or changed at any time.
  60 .Sh PARAMETERS
  61 For parameter descriptions, see
  62 .Xr open 9E ,
  63 .Xr ioctl 9E ,
  64 and
  65 .Xr close 9E .
  66 .Sh DESCRIPTION
  67 The entry points listed here are the traditional character device
  68 .Xr open 9E ,
  69 .Xr ioctl 9E ,
  70 and
  71 .Xr close 9E
  72 entry points.
  73 As discussed in
  74 .Xr usba_hcdi 9E
  75 all HCD drivers are required to implement these functions and vector
  76 them to
  77 .Xr usba_hubdi_open 9F ,
  78 .Xr usba_hubdi_ioctl 9F ,
  79 and
  80 .Xr usba_hubdi_close 9F
  81 respectively.
  82 For background information on these functions and how they interact in the
  83 broader operating system, please see the general manual pages
  84 .Xr open 9E ,
  85 .Xr ioctl 9E ,
  86 and
  87 .Xr close 9E .
  88 .Pp
  89 The arguments between the two types of functions are slightly different.
  90 The
  91 .Sx EXAMPLES
  92 section provides a sketch for how most HCD drivers should perform those
  93 transformations.
  94 .Pp
  95 One important distinction from the traditional character routines is
  96 that the USBA controls a bit more of the minor space.
  97 Therefore, the driver needs to take extra care around the values encoded in the
  98 .Sy dev_t
  99 and it should not perform any cloning or renumbering in its
 100 .Xr open 9E
 101 entry point.
 102 .Sh EXAMPLES
 103 The following example is adapated from the
 104 .Xr xhci 7D
 105 driver which shows how an HCD driver might arrange things.
 106 This assumes that a driver is following the recommendations in
 107 .Xr usba_hcdi 9E
 108 and has initialized a soft state structure through the
 109 .Xr ddi_soft_state_init 9F
 110 function.
 111 This design also requires that the soft state structure contains a pointer to
 112 the
 113 .Sy dev_info_t
 114 structure during its
 115 .Xr attach 9E callback.
 116 .Pp
 117 This example does not stand alone, it will need to be adapted for a
 118 driver:
 119 .Bd -literal
 120 #include <sys/types.h>
 121 #include <sys/file.h>
 122 #include <sys/errno.h>
 123 #include <sys/open.h>
 124 #include <sys/cred.h>
 125 #include <sys/ddi.h>
 126 #include <sys/sunddi.h>
 127
 128 static void *prefix_soft_state;
 129
 130 /*
 131  * Per-instance structure
 132  */
 133 typedef struct prefix {
 134         dev_info_t      *prefix_dev_info;
 135         ...
 136 } prefix_t;
 137
 138 static dev_info_t *
 139 prefix_get_dip(dev_t dev)
 140 {
 141         prefix_t *p;
 142         int instance = getminor(dev) & ~HUBD_IS_ROOT_HUB;
 143
 144         p = ddi_get_soft_state(prefix_soft_state, instance);
 145         if (p != NULL)
 146                 return (p->prefix_dip);
 147         return (NULL);
 148 }
 149
 150 static int
 151 prefix_open(dev_t *devp, int flags, int otyp, cred_t *credp)
 152 {
 153         dev_info_t *dip = prefix_get_dip(*devp);
 154
 155         return (usba_hubdi_open(dip, devp, flags, otyp, credp));
 156 }
 157
 158 static int
 159 prefix_ioctl(dev_t dev, int cmd, intptr_t arg, int mode, cred_t *credp,
 160     int *rvalp)
 161 {
 162         dev_info_t *dip = prefix_get_dip(dev);
 163
 164         /* Potentially handle private ioctls */
 165
 166         return (usba_hubdi_ioctl(dip, dev, cmd, arg, mode, credp, rvalp));
 167 }
 168
 169 static int
 170 prefix_close(dev_t dev, int flag, int otyp, cred_t *credp)
 171 {
 172         dev_info_t *dip = prefix_get_dip(dev);
 173
 174         return (usba_hubdi_close(dip, dev, flag, otyp, credp));
 175 }
 176
 177 static int
 178 prefix_attach(dev_info_t *dip, ddi_attach_cmd_t cmd)
 179 {
 180         int instance;
 181         prefix_t *p;
 182
 183         /* Perform normal checking of cmd */
 184
 185         instance = ddi_get_instance(dip);
 186         if (ddi_soft_state_zalloc(prefix_soft_state, inst) != 0)
 187                 return (DDI_FAILURE);
 188         p = ddi_get_soft_state(prefix_soft_state, instance);
 189         p->prefix_dev_info = dip;
 190
 191         /* Continue with normal attach(9E) initialization */
 192 }
 193
 194 int
 195 _init(void)
 196 {
 197         int ret;
 198
 199         if ((ret = ddi_soft_state_init(&prefx_soft_state, sizeof (prefx_t),
 200             0)) != 0) {
 201                 return (ret);
 202         }
 203
 204         /* Perform normal module initialization here */
 205
 206         return (ret);
 207 }
 208
 209 int
 210 _fini(void)
 211 {
 212
 213         /* Perform normal module teardown first */
 214
 215         ddi_soft_state_fini(&prefix_soft_state);
 216
 217         return (0);
 218 }
 219 .Ed
 220 .Sh SEE ALSO
 221 .Xr xhci 7D ,
 222 .Xr attach 9E ,
 223 .Xr close 9E ,
 224 .Xr ioctl 9E ,
 225 .Xr open 9E ,
 226 .Xr usba_hcdi 9E ,
 227 .Xr ddi_soft_state_init 9F ,
 228 .Xr usba_hubdi_close 9F ,
 229 .Xr usba_hubdi_ioctl 9F ,
 230 .Xr usba_hubdi_open 9F