usr/src/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. As discussed in
  73 .Xr usba_hcdi 9E
  74 all HCD drivers are required to implement these functions and vector
  75 them to
  76 .Xr usba_hubdi_open 9F ,
  77 .Xr usba_hubdi_ioctl 9F ,
  78 and
  79 .Xr usba_hubdi_close 9F
  80 respectively. For background information on these functions and how they
  81 interact in the broader operating system, please see the general manual pages
  82 .Xr open 9E ,
  83 .Xr ioctl 9E ,
  84 and
  85 .Xr close 9E .
  86 .Pp
  87 The arguments between the two types of functions are slightly different.
  88 The
  89 .Sx EXAMPLES
  90 section provides a sketch for how most HCD drivers should perform those
  91 transformations.
  92 .Pp
  93 One important distinction from the traditional character routines is
  94 that the USBA controls a bit more of the minor space. Therefore, the
  95 driver needs to take extra care around the values encoded in the
  96 .Sy dev_t
  97 and it should not perform any cloning or renumbering in its
  98 .Xr open 9E
  99 entry point.
 100 .Sh EXAMPLES
 101 The following example is adapated from the
 102 .Xr xhci 7D
 103 driver which shows how an HCD driver might arrange things. This assumes
 104 that a driver is following the recommendations in
 105 .Xr usba_hcdi 9E
 106 and has initialized a soft state structure through the
 107 .Xr ddi_soft_state_init 9F
 108 function. This design also requires that the soft state structure
 109 contains a pointer to the
 110 .Sy dev_info_t
 111 structure during its
 112 .Xr attach 9E callback.
 113 .Pp
 114 This example does not stand alone, it will need to be adapted for a
 115 driver:
 116 .Bd -literal
 117 #include <sys/types.h>
 118 #include <sys/file.h>
 119 #include <sys/errno.h>
 120 #include <sys/open.h>
 121 #include <sys/cred.h>
 122 #include <sys/ddi.h>
 123 #include <sys/sunddi.h>
 124
 125 static void *prefix_soft_state;
 126
 127 /*
 128  * Per-instance structure
 129  */
 130 typedef struct prefix {
 131         dev_info_t      *prefix_dev_info;
 132         ...
 133 } prefix_t;
 134
 135 static dev_info_t *
 136 prefix_get_dip(dev_t dev)
 137 {
 138         prefix_t *p;
 139         int instance = getminor(dev) & ~HUBD_IS_ROOT_HUB;
 140
 141         p = ddi_get_soft_state(prefix_soft_state, instance);
 142         if (p != NULL)
 143                 return (p->prefix_dip);
 144         return (NULL);
 145 }
 146
 147 static int
 148 prefix_open(dev_t *devp, int flags, int otyp, cred_t *credp)
 149 {
 150         dev_info_t *dip = prefix_get_dip(*devp);
 151
 152         return (usba_hubdi_open(dip, devp, flags, otyp, credp));
 153 }
 154
 155 static int
 156 prefix_ioctl(dev_t dev, int cmd, intptr_t arg, int mode, cred_t *credp,
 157     int *rvalp)
 158 {
 159         dev_info_t *dip = prefix_get_dip(dev);
 160
 161         /* Potentially handle private ioctls */
 162
 163         return (usba_hubdi_ioctl(dip, dev, cmd, arg, mode, credp, rvalp));
 164 }
 165
 166 static int
 167 prefix_close(dev_t dev, int flag, int otyp, cred_t *credp)
 168 {
 169         dev_info_t *dip = prefix_get_dip(dev);
 170
 171         return (usba_hubdi_close(dip, dev, flag, otyp, credp));
 172 }
 173
 174 static int
 175 prefix_attach(dev_info_t *dip, ddi_attach_cmd_t cmd)
 176 {
 177         int instance;
 178         prefix_t *p;
 179
 180         /* Perform normal checking of cmd */
 181
 182         instance = ddi_get_instance(dip);
 183         if (ddi_soft_state_zalloc(prefix_soft_state, inst) != 0)
 184                 return (DDI_FAILURE);
 185         p = ddi_get_soft_state(prefix_soft_state, instance);
 186         p->prefix_dev_info = dip;
 187
 188         /* Continue with normal attach(9E) initialization */
 189 }
 190
 191 int
 192 _init(void)
 193 {
 194         int ret;
 195
 196         if ((ret = ddi_soft_state_init(&prefx_soft_state, sizeof (prefx_t),
 197             0)) != 0) {
 198                 return (ret);
 199         }
 200
 201         /* Perform normal module initialization here */
 202
 203         return (ret);
 204 }
 205
 206 int
 207 _fini(void)
 208 {
 209
 210         /* Perform normal module teardown first */
 211
 212         ddi_soft_state_fini(&prefix_soft_state);
 213
 214         return (0);
 215 }
 216 .Ed
 217 .Sh SEE ALSO
 218 .Xr xhci 7D ,
 219 .Xr attach 9E ,
 220 .Xr close 9E ,
 221 .Xr ioctl 9E ,
 222 .Xr open 9E ,
 223 .Xr usba_hcdi 9E ,
 224 .Xr ddi_soft_state_init 9F ,
 225 .Xr usba_hubdi_close 9F ,
 226 .Xr usba_hubdi_ioctl 9F ,
 227 .Xr usba_hubdi_open 9F