xref: /onnv-gate/usr/src/uts/common/sys/usb/clients/usbser/usbser_var.h (revision 10061:ddb28a51ae78)

/*
 * 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 */