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 adapted 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 August 22, 2023 illumos