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. 73As discussed in 74.Xr usba_hcdi 9E 75all HCD drivers are required to implement these functions and vector 76them to 77.Xr usba_hubdi_open 9F , 78.Xr usba_hubdi_ioctl 9F , 79and 80.Xr usba_hubdi_close 9F 81respectively. 82For background information on these functions and how they interact in the 83broader operating system, please see the general manual pages 84.Xr open 9E , 85.Xr ioctl 9E , 86and 87.Xr close 9E . 88.Pp 89The arguments between the two types of functions are slightly different. 90The 91.Sx EXAMPLES 92section provides a sketch for how most HCD drivers should perform those 93transformations. 94.Pp 95One important distinction from the traditional character routines is 96that the USBA controls a bit more of the minor space. 97Therefore, the driver needs to take extra care around the values encoded in the 98.Sy dev_t 99and it should not perform any cloning or renumbering in its 100.Xr open 9E 101entry point. 102.Sh EXAMPLES 103The following example is adapated from the 104.Xr xhci 4D 105driver which shows how an HCD driver might arrange things. 106This assumes that a driver is following the recommendations in 107.Xr usba_hcdi 9E 108and has initialized a soft state structure through the 109.Xr ddi_soft_state_init 9F 110function. 111This design also requires that the soft state structure contains a pointer to 112the 113.Sy dev_info_t 114structure during its 115.Xr attach 9E callback. 116.Pp 117This example does not stand alone, it will need to be adapted for a 118driver: 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 128static void *prefix_soft_state; 129 130/* 131 * Per-instance structure 132 */ 133typedef struct prefix { 134 dev_info_t *prefix_dev_info; 135 ... 136} prefix_t; 137 138static dev_info_t * 139prefix_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 150static int 151prefix_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 158static int 159prefix_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 169static int 170prefix_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 177static int 178prefix_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 194int 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 209int 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 4D , 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 231