USBA_HCDI_CB_OPS(9E) Driver Entry Points USBA_HCDI_CB_OPS(9E)

NAME

usba_hcdi_cb_ops, usba_hcdi_cb_open, usba_hcdi_cb_ioctl,
usba_hcdi_cb_close - USBA HCD Character Device character functions

SYNOPSIS

#include <sys/types.h>
#include <sys/file.h>
#include <sys/errno.h>
#include <sys/open.h>
#include <sys/cred.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>

int
prefix_open(dev_t *devp, int flag, int otyp, cred_t *credp);

int
prefix_ioctl(dev_t dev, int cmd, intptr_t arg, int mode,
cred_t *cred_p, int *rval_p);

int
prefix_close(dev_t dev, int flag, int otyp, cred_t *cred_p);

INTERFACE LEVEL

Volatile - illumos USB HCD private function

This describes private interfaces that are not part of the stable DDI.
This may be removed or changed at any time.

PARAMETERS

For parameter descriptions, see open(9E), ioctl(9E), and close(9E).

DESCRIPTION

The entry points listed here are the traditional character device
open(9E), ioctl(9E), and close(9E) entry points. As discussed in
usba_hcdi(9E) all HCD drivers are required to implement these functions
and vector them to usba_hubdi_open(9F), usba_hubdi_ioctl(9F), and
usba_hubdi_close(9F) respectively. For background information on these
functions and how they interact in the broader operating system, please
see the general manual pages open(9E), ioctl(9E), and close(9E).

The arguments between the two types of functions are slightly
different. The EXAMPLES section provides a sketch for how most HCD
drivers should perform those transformations.

One important distinction from the traditional character routines is
that the USBA controls a bit more of the minor space. Therefore, the
driver needs to take extra care around the values encoded in the dev_t
and it should not perform any cloning or renumbering in its open(9E)
entry point.

EXAMPLES

The following example is adapated from the xhci(4D) driver which shows
how an HCD driver might arrange things. This assumes that a driver is
following the recommendations in usba_hcdi(9E) and has initialized a
soft state structure through the ddi_soft_state_init(9F) function.
This design also requires that the soft state structure contains a
pointer to the dev_info_t structure during its attach(9E) callback.

This example does not stand alone, it will need to be adapted for a
driver:

#include <sys/types.h>
#include <sys/file.h>
#include <sys/errno.h>
#include <sys/open.h>
#include <sys/cred.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>

static void *prefix_soft_state;

/*
* Per-instance structure
*/
typedef struct prefix {
dev_info_t *prefix_dev_info;
...
} prefix_t;

static dev_info_t *
prefix_get_dip(dev_t dev)
{
prefix_t *p;
int instance = getminor(dev) & ~HUBD_IS_ROOT_HUB;

p = ddi_get_soft_state(prefix_soft_state, instance);
if (p != NULL)
return (p->prefix_dip);
return (NULL);
}

static int
prefix_open(dev_t *devp, int flags, int otyp, cred_t *credp)
{
dev_info_t *dip = prefix_get_dip(*devp);

return (usba_hubdi_open(dip, devp, flags, otyp, credp));
}

static int
prefix_ioctl(dev_t dev, int cmd, intptr_t arg, int mode, cred_t *credp,
int *rvalp)
{
dev_info_t *dip = prefix_get_dip(dev);

/* Potentially handle private ioctls */

return (usba_hubdi_ioctl(dip, dev, cmd, arg, mode, credp, rvalp));
}

static int
prefix_close(dev_t dev, int flag, int otyp, cred_t *credp)
{
dev_info_t *dip = prefix_get_dip(dev);

return (usba_hubdi_close(dip, dev, flag, otyp, credp));
}

static int
prefix_attach(dev_info_t *dip, ddi_attach_cmd_t cmd)
{
int instance;
prefix_t *p;

/* Perform normal checking of cmd */

instance = ddi_get_instance(dip);
if (ddi_soft_state_zalloc(prefix_soft_state, inst) != 0)
return (DDI_FAILURE);
p = ddi_get_soft_state(prefix_soft_state, instance);
p->prefix_dev_info = dip;

/* Continue with normal attach(9E) initialization */
}

int
_init(void)
{
int ret;

if ((ret = ddi_soft_state_init(&prefx_soft_state, sizeof (prefx_t),
0)) != 0) {
return (ret);
}

/* Perform normal module initialization here */

return (ret);
}

int
_fini(void)
{

/* Perform normal module teardown first */

ddi_soft_state_fini(&prefix_soft_state);

return (0);
}

SEE ALSO

xhci(4D), attach(9E), close(9E), ioctl(9E), open(9E), usba_hcdi(9E),
ddi_soft_state_init(9F), usba_hubdi_close(9F), usba_hubdi_ioctl(9F),
usba_hubdi_open(9F)

illumos December 20, 2016 illumos