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 - 56illumos USB HCD private function 57.Pp 58This describes private interfaces that are not part of the stable DDI. 59This may be removed or changed at any time. 60.Sh PARAMETERS 61For parameter descriptions, see 62.Xr open 9E , 63.Xr ioctl 9E , 64and 65.Xr close 9E . 66.Sh DESCRIPTION 67The entry points listed here are the traditional character device 68.Xr open 9E , 69.Xr ioctl 9E , 70and 71.Xr close 9E 72entry points. As discussed in 73.Xr usba_hcdi 9E 74all HCD drivers are required to implement these functions and vector 75them to 76.Xr usba_hubdi_open 9F , 77.Xr usba_hubdi_ioctl 9F , 78and 79.Xr usba_hubdi_close 9F 80respectively. For background information on these functions and how they 81interact in the broader operating system, please see the general manual pages 82.Xr open 9E , 83.Xr ioctl 9E , 84and 85.Xr close 9E . 86.Pp 87The arguments between the two types of functions are slightly different. 88The 89.Sx EXAMPLES 90section provides a sketch for how most HCD drivers should perform those 91transformations. 92.Pp 93One important distinction from the traditional character routines is 94that the USBA controls a bit more of the minor space. Therefore, the 95driver needs to take extra care around the values encoded in the 96.Sy dev_t 97and it should not perform any cloning or renumbering in its 98.Xr open 9E 99entry point. 100.Sh EXAMPLES 101The following example is adapated from the 102.Xr xhci 7D 103driver which shows how an HCD driver might arrange things. This assumes 104that a driver is following the recommendations in 105.Xr usba_hcdi 9E 106and has initialized a soft state structure through the 107.Xr ddi_soft_state_init 9F 108function. This design also requires that the soft state structure 109contains a pointer to the 110.Sy dev_info_t 111structure during its 112.Xr attach 9E callback. 113.Pp 114This example does not stand alone, it will need to be adapted for a 115driver: 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 125static void *prefix_soft_state; 126 127/* 128 * Per-instance structure 129 */ 130typedef struct prefix { 131 dev_info_t *prefix_dev_info; 132 ... 133} prefix_t; 134 135static dev_info_t * 136prefix_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 147static int 148prefix_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 155static int 156prefix_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 166static int 167prefix_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 174static int 175prefix_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 191int 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 206int 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 228