clients/usbser/usbser_var.h

/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */
/*
 * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

#ifndef _SYS_USB_USBSER_VAR_H
#define _SYS_USB_USBSER_VAR_H


/*
 * USB-to-serial driver definitions
 */

#include <sys/tty.h>
#include <sys/mkdev.h>
#include <sys/sunddi.h>
#include <sys/note.h>

#include <sys/usb/clients/usbser/usbser_dsdi.h>

#ifdef  __cplusplus
extern "C" {
#endif

typedef struct usbser_state usbser_state_t;
typedef struct usbser_port  usbser_port_t;

/*
 * because put() and srv() routines are not allowed to block, usbser
 * provides each port with two threads: for read and write processing
 * this structure describes the data associated with a usbser thread
 */
typedef struct usbser_thread {
    kcondvar_t  thr_cv;     /* cv for request wait */
    uint_t      thr_flags;  /* state flags */
    usbser_port_t   *thr_port;  /* port owner of this thread */
    void        (*thr_func)(void *);    /* function to be run */
    void        *thr_arg;   /* function argument */
} usbser_thread_t;

/*
 * thr_flags
 */
enum {
    USBSER_THR_RUNNING  = 0x01, /* thread is running */
    USBSER_THR_WAKE     = 0x02, /* wake requested */
    USBSER_THR_EXITED   = 0x04  /* thread exited */
};

/*
 * additional device state
 */
#define USBSER_DEV_INIT     0x80    /* device is being initialized */

/*
 * per instance data
 */
struct usbser_state {
    struct usbser_state *us_next;       /* linked list */
    dev_info_t  *us_dip;        /* device information */
    kmutex_t    us_mutex;       /* structure lock */
    void        *us_statep;     /* soft state anchor */
    int     us_instance;        /* instance number */
    ds_ops_t    *us_ds_ops;     /* DSD operations */
    ds_hdl_t    us_ds_hdl;      /* DSD device handle */
    uint_t      us_port_cnt;        /* port count */
    usbser_port_t   *us_ports;      /* array of port structs */
    uint_t      us_dev_state;       /* USB device state */
    usb_log_handle_t us_lh;         /* USB log handle */
    ddi_taskq_t *us_taskq;      /* taskq for command handling */
};

_NOTE(MUTEX_PROTECTS_DATA(usbser_state::us_mutex, usbser_state::us_dev_state))

/*
 * per port data
 */
struct usbser_port {
    kmutex_t    port_mutex;     /* structure lock */
    usbser_state_t  *port_usp;      /* back pointer to state */
    char        port_lh_name[16];   /* log handle name */
    usb_log_handle_t port_lh;       /* log handle */
    ds_ops_t    *port_ds_ops;       /* copy from usbser_state */
    ds_hdl_t    port_ds_hdl;        /* copy from usbser_state */
    uint_t      port_num;       /* port number */
    uint_t      port_state;     /* port state */
    uint_t      port_act;       /* current activities on port */
    uint_t      port_flags;     /* port flags */
    kcondvar_t  port_state_cv;      /* port state cv */
    kcondvar_t  port_act_cv;        /* port activity cv */
    kcondvar_t  port_car_cv;        /* port carrier cv */
    uint_t      port_wq_data_cnt;   /* amount of unsent data */
    usbser_thread_t port_wq_thread;     /* wq thread */
    usbser_thread_t port_rq_thread;     /* rq thread */
    tty_common_t    port_ttycommon;     /* tty driver common data */
    uchar_t     port_flowc;     /* flow control char */
    timeout_id_t    port_delay_id;      /* delay/break timeout id */
};

_NOTE(MUTEX_PROTECTS_DATA(usbser_port::port_mutex, usbser_port))
_NOTE(DATA_READABLE_WITHOUT_LOCK(usbser_port::{
    port_usp
    port_lh
    port_ds_ops
    port_ds_hdl
    port_num
    port_ttycommon.t_{readq writeq}
}))

_NOTE(LOCK_ORDER(usbser_state::us_mutex usbser_port::port_mutex))

/*
 * port_state:
 *
 *   USBSER_PORT_NOT_INIT
 *          |   ^
 *          |   |
 *     attach   detach
 *          |   |
 *          |   |    +----open[1]----> USBSER_PORT_OPENING_TTY ------+
 *          |   |    |                      |    |                   |
 *          v   |    |                      |    |                   |
 *   USBSER_PORT_CLOSED <---device error---<    overtake[2]          |
 *            |      |                      |    |                   v
 *            |      |                      |    v                   |
 *            |      +----open[1]----> USBSER_PORT_OPENING_OUT       |
 *            |                             |                        |
 *            |                             |    +-------------------+
 *            |                             |    |
 *            |                             v    v
 * USBSER_PORT_CLOSING <-----close----- USBSER_PORT_OPEN <-----------+
 *            ^                             |    ^       --------+   |
 *            |                             |    |               |   |
 *            |                             |    |               |   |
 *            |                             v    |               v   |
 *            +------close----- USBSER_PORT_DISCONNECTED  USBSER_PORT_SUSPENDED
 *
 * Notes:
 *
 * [1] for each physical port N two device nodes are created:
 *
 *       /dev/term/N (tty mode)
 *       /dev/cua/N  (dial-out mode)
 *
 *     the port can only be opened in one of these modes at a time.
 *     difference between the two is that in tty mode the driver
 *     will block in open(9E) until the CD (Carrier Detect) pin comes up,
 *     while in dial-out mode CD is ignored. opening and closing states
 *     help to avoid race conditions between two threads trying to open/close
 *     one physical port in two different modes simultaneously.
 *
 * [2] tty mode open may be blocked waiting for carrier.
 *     if dial-out mode open happens at this time, it is allowed
 *     for it to overtake the port; from zs(7D) man page:
 *
 *   This allows a modem to be attached to  /dev/term/[n]
 *   and used for dial-in (by enabling the line for login in /etc/inittab)
 *   and also used for  dial-out  (by  tip(1) or uucp(1C)) as /dev/cua/[n]
 *   when no one is logged in on the line.
 */
enum {
    USBSER_PORT_NOT_INIT = 0,   /* port not initialized */
    USBSER_PORT_CLOSED,     /* port is closed */
    USBSER_PORT_OPENING_TTY,    /* tty open in progress */
    USBSER_PORT_OPENING_OUT,    /* dial-out open in progress */
    USBSER_PORT_OPEN,       /* port is open */
    USBSER_PORT_SUSPENDED,      /* port is suspended */
    USBSER_PORT_DISCONNECTED,   /* port is disconnected */
    USBSER_PORT_CLOSING     /* close() is in progress */
};

/* constants used by state machine implementation */
enum {
    USBSER_CONTINUE         = -1,
    USBSER_COMPLETE         = 0
};

/*
 * port_act: current activities on the port.
 * only one activity of each type is allowed at a time.
 */
enum {
    USBSER_ACT_TX       = 0x0001,   /* transmitting data */
    USBSER_ACT_RX       = 0x0002,   /* receiving data */
    USBSER_ACT_CTL      = 0x0004,   /* controlling the device */
    USBSER_ACT_BREAK    = 0x0010,   /* doing break */
    USBSER_ACT_DELAY    = 0x0020,   /* doing delay */
    USBSER_ACT_ALL      = 0xffff    /* all actions (must be >0) */
};

/*
 * port_flags
 */
enum {
    USBSER_FL_OUT       = 0x0001,   /* dial-out */
    USBSER_FL_WOPEN     = 0x0002,   /* waiting in open() */
    USBSER_FL_CARR_ON   = 0x0004,   /* carrier is on */
    USBSER_FL_TX_STOPPED    = 0x0008,   /* output stopped */
    USBSER_FL_RX_STOPPED    = 0x0010,   /* input stopped */
    USBSER_FL_HUNGUP    = 0x0020,   /* stream is hung up */
    USBSER_FL_DSD_OPEN  = 0x0040,   /* DSD is open */
    USBSER_FL_STATUS_CB = 0x0080,   /* status callback pending */
    USBSER_FL_IGNORE_CD = 0x0100,   /* ignore carrier detect */
    USBSER_FL_PRESERVE  = USBSER_FL_IGNORE_CD
                        /* flags that need to */
                        /* be preserved across opens */
};

/*
 * current sun compiler does not seem to inline static leaf routines at O3
 * so we have to use preprocessor macros to make up for compiler disability
 *
 * can we access the port?
 */
#define USBSER_PORT_ACCESS_OK(pp)   ((pp)->port_state == USBSER_PORT_OPEN)

/*
 * is port doing something?
 */
#define USBSER_PORT_IS_BUSY(pp)     ((pp)->port_act != 0)

/* port is busy on TX, delay, break, ctrl */
#define USBSER_PORT_IS_BUSY_NON_RX(pp)  \
    (((pp)->port_act & (USBSER_ACT_DELAY | USBSER_ACT_CTL | \
    USBSER_ACT_BREAK | USBSER_ACT_TX)) != 0)

/*
 * is the port opening?
 */
#define USBSER_IS_OPENING(pp)   \
    (((pp)->port_state == USBSER_PORT_OPENING_TTY) || \
    ((pp)->port_state == USBSER_PORT_OPENING_OUT))

/*
 * determine, while we are trying to open the port,
 * whether it is currently being open in the opposite mode
 */
#define USBSER_NO_OTHER_OPEN(pp, minor) \
    ((((minor) & OUTLINE) &&    \
    ((pp)->port_state == USBSER_PORT_OPENING_OUT)) ||   \
    (!((minor) & OUTLINE) && ((pp)->port_state == USBSER_PORT_OPENING_TTY)))

/*
 * determine, while we are trying to open the port,
 * whether it is already open in the opposite mode
 */
#define USBSER_OPEN_IN_OTHER_MODE(pp, minor)    \
    ((((minor) & OUTLINE) && !((pp)->port_flags & USBSER_FL_OUT)) || \
    (!((minor) & OUTLINE) && ((pp)->port_flags & USBSER_FL_OUT)))

/*
 * minor number manipulation
 */
enum {
    MAXPORTS_PER_DEVICE_SHIFT   = 4,
    MAXPORTS_PER_DEVICE     = (1 << MAXPORTS_PER_DEVICE_SHIFT),
    MAXPORTS_PER_DEVICE_MASK    = (MAXPORTS_PER_DEVICE - 1),
    OUTLINE             = (1 << (NBITSMINOR32 - 1))
};

#define USBSER_MAKEMINOR(instance, port, outline)   \
        ((port) | ((instance) << MAXPORTS_PER_DEVICE_SHIFT) | (outline))

#define USBSER_MINOR2INST(minor)    \
    (((minor) & ~(OUTLINE | MAXPORTS_PER_DEVICE_MASK)) \
    >> MAXPORTS_PER_DEVICE_SHIFT)

#define USBSER_MINOR2PORT(minor)    ((minor) & MAXPORTS_PER_DEVICE_MASK)

/*
 * various tunables
 *
 * timeouts are in seconds
 */
enum {
    USBSER_TX_FIFO_DRAIN_TIMEOUT    = 5, /* tx fifo drain timeout */
    USBSER_WQ_DRAIN_TIMEOUT     = 2, /* wq drain timeout */
    USBSER_SUSPEND_TIMEOUT      = 10 /* cpr suspend timeout */
};

/*
 * debug printing masks
 */
#define DPRINT_ATTACH       0x00000001
#define DPRINT_DETACH       0x00000002
#define DPRINT_OPEN     0x00000004
#define DPRINT_CLOSE        0x00000008
#define DPRINT_WQ       0x00000010
#define DPRINT_RQ       0x00000020
#define DPRINT_IOCTL        0x00000040
#define DPRINT_RX_CB        0x00000100
#define DPRINT_TX_CB        0x00000200
#define DPRINT_STATUS_CB    0x00000400
#define DPRINT_EVENTS       0x00001000
#define DPRINT_CPR      0x00002000
#define DPRINT_MASK_ALL     0xFFFFFFFF

/*
 * misc macros
 */
#define NELEM(a)    (sizeof (a) / sizeof (*(a)))

/*
 * shortcuts to DSD operations
 */
#define USBSER_DS_ATTACH(usp, aip)  usp->us_ds_ops->ds_attach(aip)

#define USBSER_DS_DETACH(usp)   usp->us_ds_ops->ds_detach(usp->us_ds_hdl)

#define USBSER_DS_OPEN_PORT(usp, port_num)  \
    usp->us_ds_ops->ds_open_port(usp->us_ds_hdl, port_num)

#define USBSER_DS_CLOSE_PORT(usp, port_num) \
    usp->us_ds_ops->ds_close_port(usp->us_ds_hdl, port_num)

#define USBSER_DS_REGISTER_CB(usp, port_num, cb)    \
    usp->us_ds_ops->ds_register_cb(usp->us_ds_hdl, port_num, cb)

#define USBSER_DS_UNREGISTER_CB(usp, port_num)  \
    usp->us_ds_ops->ds_unregister_cb(usp->us_ds_hdl, port_num)

/* power management */
#define USBSER_DS_USB_POWER(usp, comp, level, new_statep)   \
    usp->us_ds_ops->ds_usb_power(usp->us_ds_hdl, comp, level, new_statep)

#define USBSER_DS_SUSPEND(usp)  usp->us_ds_ops->ds_suspend(usp->us_ds_hdl)

#define USBSER_DS_RESUME(usp)   usp->us_ds_ops->ds_resume(usp->us_ds_hdl)

#define USBSER_DS_DISCONNECT(usp) usp->us_ds_ops->ds_disconnect(usp->us_ds_hdl)

#define USBSER_DS_RECONNECT(usp) usp->us_ds_ops->ds_reconnect(usp->us_ds_hdl)

/* standard UART operations */
#define USBSER_DS_SET_PORT_PARAMS(pp, params)   \
    pp->port_ds_ops->ds_set_port_params(pp->port_ds_hdl, pp->port_num, \
        params)

#define USBSER_DS_SET_MODEM_CTL(pp, mask, val)  \
    pp->port_ds_ops->ds_set_modem_ctl(pp->port_ds_hdl, pp->port_num, mask, \
        val)

#define USBSER_DS_GET_MODEM_CTL(pp, mask, valp) \
    pp->port_ds_ops->ds_get_modem_ctl(pp->port_ds_hdl, pp->port_num, \
        mask, valp)

#define USBSER_DS_BREAK_CTL(pp, val)        \
    pp->port_ds_ops->ds_break_ctl(pp->port_ds_hdl, pp->port_num, val)

#define USBSER_DS_LOOPBACK(pp, val)     \
    pp->port_ds_ops->ds_loopback(pp->port_ds_hdl, pp->port_num, val)

/* data xfer */
#define USBSER_DS_TX(pp, mp)        \
    pp->port_ds_ops->ds_tx(pp->port_ds_hdl, pp->port_num, mp)

#define USBSER_DS_RX(pp)        \
    pp->port_ds_ops->ds_rx(pp->port_ds_hdl, pp->port_num)

#define USBSER_DS_STOP(pp, dir)     \
    pp->port_ds_ops->ds_stop(pp->port_ds_hdl, pp->port_num, dir)

#define USBSER_DS_START(pp, dir)    \
    pp->port_ds_ops->ds_start(pp->port_ds_hdl, pp->port_num, dir)

/* fifos */
#define USBSER_DS_FIFO_FLUSH(pp, mask)      \
    pp->port_ds_ops->ds_fifo_flush(pp->port_ds_hdl, pp->port_num, mask)

#define USBSER_DS_FIFO_DRAIN(pp, tmout)     \
    pp->port_ds_ops->ds_fifo_drain(pp->port_ds_hdl, pp->port_num, tmout)


/* check for supported operations */
#define USBSER_DS_LOOPBACK_SUPPORTED(pp) (pp->port_ds_ops->ds_loopback != 0)

#ifdef  __cplusplus
}
#endif

#endif  /* _SYS_USB_USBSER_VAR_H */