[linux-block.git] / include / linux / tty_port.h

/* SPDX-License-Identifier: GPL-2.0 */
#ifndef _LINUX_TTY_PORT_H
#define _LINUX_TTY_PORT_H

#include <linux/kfifo.h>
#include <linux/kref.h>
#include <linux/mutex.h>
#include <linux/tty_buffer.h>
#include <linux/wait.h>

struct attribute_group;
struct tty_driver;
struct tty_port;
struct tty_struct;

/**
 * struct tty_port_operations -- operations on tty_port
 * @carrier_raised: return true if the carrier is raised on @port
 * @dtr_rts: raise the DTR line if @active is true, otherwise lower DTR
 * @shutdown: called when the last close completes or a hangup finishes IFF the
 *	port was initialized. Do not use to free resources. Turn off the device
 *	only. Called under the port mutex to serialize against @activate and
 *	@shutdown.
 * @activate: called under the port mutex from tty_port_open(), serialized using
 *	the port mutex. Supposed to turn on the device.
 *
 *	FIXME: long term getting the tty argument *out* of this would be good
 *	for consoles.
 *
 * @destruct: called on the final put of a port. Free resources, possibly incl.
 *	the port itself.
 */
struct tty_port_operations {
	bool (*carrier_raised)(struct tty_port *port);
	void (*dtr_rts)(struct tty_port *port, bool active);
	void (*shutdown)(struct tty_port *port);
	int (*activate)(struct tty_port *port, struct tty_struct *tty);
	void (*destruct)(struct tty_port *port);
};

struct tty_port_client_operations {
	int (*receive_buf)(struct tty_port *port, const unsigned char *, const unsigned char *, size_t);
	void (*lookahead_buf)(struct tty_port *port, const unsigned char *cp,
			      const unsigned char *fp, unsigned int count);
	void (*write_wakeup)(struct tty_port *port);
};

extern const struct tty_port_client_operations tty_port_default_client_ops;

/**
 * struct tty_port -- port level information
 *
 * @buf: buffer for this port, locked internally
 * @tty: back pointer to &struct tty_struct, valid only if the tty is open. Use
 *	 tty_port_tty_get() to obtain it (and tty_kref_put() to release).
 * @itty: internal back pointer to &struct tty_struct. Avoid this. It should be
 *	  eliminated in the long term.
 * @ops: tty port operations (like activate, shutdown), see &struct
 *	 tty_port_operations
 * @client_ops: tty port client operations (like receive_buf, write_wakeup).
 *		By default, tty_port_default_client_ops is used.
 * @lock: lock protecting @tty
 * @blocked_open: # of procs waiting for open in tty_port_block_til_ready()
 * @count: usage count
 * @open_wait: open waiters queue (waiting e.g. for a carrier)
 * @delta_msr_wait: modem status change queue (waiting for MSR changes)
 * @flags: user TTY flags (%ASYNC_)
 * @iflags: internal flags (%TTY_PORT_)
 * @console: when set, the port is a console
 * @mutex: locking, for open, shutdown and other port operations
 * @buf_mutex: @xmit_buf alloc lock
 * @xmit_buf: optional xmit buffer used by some drivers
 * @xmit_fifo: optional xmit buffer used by some drivers
 * @close_delay: delay in jiffies to wait when closing the port
 * @closing_wait: delay in jiffies for output to be sent before closing
 * @drain_delay: set to zero if no pure time based drain is needed else set to
 *		 size of fifo
 * @kref: references counter. Reaching zero calls @ops->destruct() if non-%NULL
 *	  or frees the port otherwise.
 * @client_data: pointer to private data, for @client_ops
 *
 * Each device keeps its own port level information. &struct tty_port was
 * introduced as a common structure for such information. As every TTY device
 * shall have a backing tty_port structure, every driver can use these members.
 *
 * The tty port has a different lifetime to the tty so must be kept apart.
 * In addition be careful as tty -> port mappings are valid for the life
 * of the tty object but in many cases port -> tty mappings are valid only
 * until a hangup so don't use the wrong path.
 *
 * Tty port shall be initialized by tty_port_init() and shut down either by
 * tty_port_destroy() (refcounting not used), or tty_port_put() (refcounting).
 *
 * There is a lot of helpers around &struct tty_port too. To name the most
 * significant ones: tty_port_open(), tty_port_close() (or
 * tty_port_close_start() and tty_port_close_end() separately if need be), and
 * tty_port_hangup(). These call @ops->activate() and @ops->shutdown() as
 * needed.
 */
struct tty_port {
	struct tty_bufhead	buf;
	struct tty_struct	*tty;
	struct tty_struct	*itty;
	const struct tty_port_operations *ops;
	const struct tty_port_client_operations *client_ops;
	spinlock_t		lock;
	int			blocked_open;
	int			count;
	wait_queue_head_t	open_wait;
	wait_queue_head_t	delta_msr_wait;
	unsigned long		flags;
	unsigned long		iflags;
	unsigned char		console:1;
	struct mutex		mutex;
	struct mutex		buf_mutex;
	unsigned char		*xmit_buf;
	DECLARE_KFIFO_PTR(xmit_fifo, unsigned char);
	unsigned int		close_delay;
	unsigned int		closing_wait;
	int			drain_delay;
	struct kref		kref;
	void			*client_data;
};

/* tty_port::iflags bits -- use atomic bit ops */
#define TTY_PORT_INITIALIZED	0	/* device is initialized */
#define TTY_PORT_SUSPENDED	1	/* device is suspended */
#define TTY_PORT_ACTIVE		2	/* device is open */

/*
 * uart drivers: use the uart_port::status field and the UPSTAT_* defines
 * for s/w-based flow control steering and carrier detection status
 */
#define TTY_PORT_CTS_FLOW	3	/* h/w flow control enabled */
#define TTY_PORT_CHECK_CD	4	/* carrier detect enabled */
#define TTY_PORT_KOPENED	5	/* device exclusively opened by
					   kernel */

void tty_port_init(struct tty_port *port);
void tty_port_link_device(struct tty_port *port, struct tty_driver *driver,
		unsigned index);
struct device *tty_port_register_device(struct tty_port *port,
		struct tty_driver *driver, unsigned index,
		struct device *device);
struct device *tty_port_register_device_attr(struct tty_port *port,
		struct tty_driver *driver, unsigned index,
		struct device *device, void *drvdata,
		const struct attribute_group **attr_grp);
struct device *tty_port_register_device_serdev(struct tty_port *port,
		struct tty_driver *driver, unsigned index,
		struct device *device);
struct device *tty_port_register_device_attr_serdev(struct tty_port *port,
		struct tty_driver *driver, unsigned index,
		struct device *device, void *drvdata,
		const struct attribute_group **attr_grp);
void tty_port_unregister_device(struct tty_port *port,
		struct tty_driver *driver, unsigned index);
int tty_port_alloc_xmit_buf(struct tty_port *port);
void tty_port_free_xmit_buf(struct tty_port *port);
void tty_port_destroy(struct tty_port *port);
void tty_port_put(struct tty_port *port);

static inline struct tty_port *tty_port_get(struct tty_port *port)
{
	if (port && kref_get_unless_zero(&port->kref))
		return port;
	return NULL;
}

/* If the cts flow control is enabled, return true. */
static inline bool tty_port_cts_enabled(const struct tty_port *port)
{
	return test_bit(TTY_PORT_CTS_FLOW, &port->iflags);
}

static inline void tty_port_set_cts_flow(struct tty_port *port, bool val)
{
	assign_bit(TTY_PORT_CTS_FLOW, &port->iflags, val);
}

static inline bool tty_port_active(const struct tty_port *port)
{
	return test_bit(TTY_PORT_ACTIVE, &port->iflags);
}

static inline void tty_port_set_active(struct tty_port *port, bool val)
{
	assign_bit(TTY_PORT_ACTIVE, &port->iflags, val);
}

static inline bool tty_port_check_carrier(const struct tty_port *port)
{
	return test_bit(TTY_PORT_CHECK_CD, &port->iflags);
}

static inline void tty_port_set_check_carrier(struct tty_port *port, bool val)
{
	assign_bit(TTY_PORT_CHECK_CD, &port->iflags, val);
}

static inline bool tty_port_suspended(const struct tty_port *port)
{
	return test_bit(TTY_PORT_SUSPENDED, &port->iflags);
}

static inline void tty_port_set_suspended(struct tty_port *port, bool val)
{
	assign_bit(TTY_PORT_SUSPENDED, &port->iflags, val);
}

static inline bool tty_port_initialized(const struct tty_port *port)
{
	return test_bit(TTY_PORT_INITIALIZED, &port->iflags);
}

static inline void tty_port_set_initialized(struct tty_port *port, bool val)
{
	assign_bit(TTY_PORT_INITIALIZED, &port->iflags, val);
}

static inline bool tty_port_kopened(const struct tty_port *port)
{
	return test_bit(TTY_PORT_KOPENED, &port->iflags);
}

static inline void tty_port_set_kopened(struct tty_port *port, bool val)
{
	assign_bit(TTY_PORT_KOPENED, &port->iflags, val);
}

struct tty_struct *tty_port_tty_get(struct tty_port *port);
void tty_port_tty_set(struct tty_port *port, struct tty_struct *tty);
bool tty_port_carrier_raised(struct tty_port *port);
void tty_port_raise_dtr_rts(struct tty_port *port);
void tty_port_lower_dtr_rts(struct tty_port *port);
void tty_port_hangup(struct tty_port *port);
void tty_port_tty_hangup(struct tty_port *port, bool check_clocal);
void tty_port_tty_wakeup(struct tty_port *port);
int tty_port_block_til_ready(struct tty_port *port, struct tty_struct *tty,
		struct file *filp);
int tty_port_close_start(struct tty_port *port, struct tty_struct *tty,
		struct file *filp);
void tty_port_close_end(struct tty_port *port, struct tty_struct *tty);
void tty_port_close(struct tty_port *port, struct tty_struct *tty,
		struct file *filp);
int tty_port_install(struct tty_port *port, struct tty_driver *driver,
		struct tty_struct *tty);
int tty_port_open(struct tty_port *port, struct tty_struct *tty,
		struct file *filp);

static inline int tty_port_users(struct tty_port *port)
{
	return port->count + port->blocked_open;
}

#endif
Commit	Line	Data
67b94be4 JS	1	/* SPDX-License-Identifier: GPL-2.0 */
	2	#ifndef _LINUX_TTY_PORT_H
	3	#define _LINUX_TTY_PORT_H
	4
4e2a44c1	5	#include <linux/kfifo.h>
67b94be4 JS	6	#include <linux/kref.h>
	7	#include <linux/mutex.h>
	8	#include <linux/tty_buffer.h>
	9	#include <linux/wait.h>
	10
67b94be4 JS	11	struct attribute_group;
	12	struct tty_driver;
	13	struct tty_port;
	14	struct tty_struct;
	15
630bf86d JS	16	/**
630bf86d JS	17	* struct tty_port_operations -- operations on tty_port
b300fb26	18	* @carrier_raised: return true if the carrier is raised on @port
5701cb8b	19	* @dtr_rts: raise the DTR line if @active is true, otherwise lower DTR
630bf86d JS	20	* @shutdown: called when the last close completes or a hangup finishes IFF the
	21	* port was initialized. Do not use to free resources. Turn off the device
	22	* only. Called under the port mutex to serialize against @activate and
	23	* @shutdown.
	24	* @activate: called under the port mutex from tty_port_open(), serialized using
	25	* the port mutex. Supposed to turn on the device.
	26	*
	27	* FIXME: long term getting the tty argument out of this would be good
	28	* for consoles.
	29	*
	30	* @destruct: called on the final put of a port. Free resources, possibly incl.
	31	* the port itself.
	32	*/
67b94be4	33	struct tty_port_operations {
b300fb26	34	bool (carrier_raised)(struct tty_port port);
5701cb8b	35	void (dtr_rts)(struct tty_port port, bool active);
67b94be4	36	void (shutdown)(struct tty_port port);
67b94be4	37	int (activate)(struct tty_port port, struct tty_struct *tty);
67b94be4 JS	38	void (destruct)(struct tty_port port);
	39	};
	40
	41	struct tty_port_client_operations {
	42	int (receive_buf)(struct tty_port port, const unsigned char , const unsigned char , size_t);
6bb6fa69 IJ	43	void (lookahead_buf)(struct tty_port port, const unsigned char *cp,
6bb6fa69 IJ	44	const unsigned char *fp, unsigned int count);
67b94be4 JS	45	void (write_wakeup)(struct tty_port port);
	46	};
	47
	48	extern const struct tty_port_client_operations tty_port_default_client_ops;
	49
61c83add JS	50	/**
	51	* struct tty_port -- port level information
	52	*
	53	* @buf: buffer for this port, locked internally
	54	* @tty: back pointer to &struct tty_struct, valid only if the tty is open. Use
	55	* tty_port_tty_get() to obtain it (and tty_kref_put() to release).
	56	* @itty: internal back pointer to &struct tty_struct. Avoid this. It should be
	57	* eliminated in the long term.
	58	* @ops: tty port operations (like activate, shutdown), see &struct
	59	* tty_port_operations
	60	* @client_ops: tty port client operations (like receive_buf, write_wakeup).
	61	* By default, tty_port_default_client_ops is used.
	62	* @lock: lock protecting @tty
	63	* @blocked_open: # of procs waiting for open in tty_port_block_til_ready()
	64	* @count: usage count
	65	* @open_wait: open waiters queue (waiting e.g. for a carrier)
	66	* @delta_msr_wait: modem status change queue (waiting for MSR changes)
	67	* @flags: user TTY flags (%ASYNC_)
	68	* @iflags: internal flags (%TTY_PORT_)
	69	* @console: when set, the port is a console
	70	* @mutex: locking, for open, shutdown and other port operations
	71	* @buf_mutex: @xmit_buf alloc lock
	72	* @xmit_buf: optional xmit buffer used by some drivers
4e2a44c1	73	* @xmit_fifo: optional xmit buffer used by some drivers
61c83add JS	74	* @close_delay: delay in jiffies to wait when closing the port
	75	* @closing_wait: delay in jiffies for output to be sent before closing
	76	* @drain_delay: set to zero if no pure time based drain is needed else set to
	77	* size of fifo
	78	* @kref: references counter. Reaching zero calls @ops->destruct() if non-%NULL
	79	* or frees the port otherwise.
	80	* @client_data: pointer to private data, for @client_ops
	81	*
	82	* Each device keeps its own port level information. &struct tty_port was
	83	* introduced as a common structure for such information. As every TTY device
	84	* shall have a backing tty_port structure, every driver can use these members.
	85	*
	86	* The tty port has a different lifetime to the tty so must be kept apart.
	87	* In addition be careful as tty -> port mappings are valid for the life
	88	* of the tty object but in many cases port -> tty mappings are valid only
	89	* until a hangup so don't use the wrong path.
	90	*
	91	* Tty port shall be initialized by tty_port_init() and shut down either by
	92	* tty_port_destroy() (refcounting not used), or tty_port_put() (refcounting).
	93	*
	94	* There is a lot of helpers around &struct tty_port too. To name the most
	95	* significant ones: tty_port_open(), tty_port_close() (or
	96	* tty_port_close_start() and tty_port_close_end() separately if need be), and
	97	* tty_port_hangup(). These call @ops->activate() and @ops->shutdown() as
	98	* needed.
	99	*/
67b94be4	100	struct tty_port {
61c83add JS	101	struct tty_bufhead buf;
	102	struct tty_struct *tty;
	103	struct tty_struct *itty;
	104	const struct tty_port_operations *ops;
	105	const struct tty_port_client_operations *client_ops;
	106	spinlock_t lock;
	107	int blocked_open;
	108	int count;
	109	wait_queue_head_t open_wait;
	110	wait_queue_head_t delta_msr_wait;
	111	unsigned long flags;
	112	unsigned long iflags;
	113	unsigned char console:1;
	114	struct mutex mutex;
	115	struct mutex buf_mutex;
	116	unsigned char *xmit_buf;
4e2a44c1	117	DECLARE_KFIFO_PTR(xmit_fifo, unsigned char);
61c83add JS	118	unsigned int close_delay;
	119	unsigned int closing_wait;
	120	int drain_delay;
	121	struct kref kref;
	122	void *client_data;
67b94be4 JS	123	};
	124
	125	/* tty_port::iflags bits -- use atomic bit ops */
	126	#define TTY_PORT_INITIALIZED 0 /* device is initialized */
	127	#define TTY_PORT_SUSPENDED 1 /* device is suspended */
	128	#define TTY_PORT_ACTIVE 2 /* device is open */
	129
	130	/*
	131	* uart drivers: use the uart_port::status field and the UPSTAT_* defines
	132	* for s/w-based flow control steering and carrier detection status
	133	*/
	134	#define TTY_PORT_CTS_FLOW 3 /* h/w flow control enabled */
	135	#define TTY_PORT_CHECK_CD 4 /* carrier detect enabled */
	136	#define TTY_PORT_KOPENED 5 /* device exclusively opened by
	137	kernel */
	138
	139	void tty_port_init(struct tty_port *port);
	140	void tty_port_link_device(struct tty_port port, struct tty_driver driver,
	141	unsigned index);
	142	struct device tty_port_register_device(struct tty_port port,
	143	struct tty_driver *driver, unsigned index,
	144	struct device *device);
	145	struct device tty_port_register_device_attr(struct tty_port port,
	146	struct tty_driver *driver, unsigned index,
	147	struct device device, void drvdata,
	148	const struct attribute_group **attr_grp);
	149	struct device tty_port_register_device_serdev(struct tty_port port,
	150	struct tty_driver *driver, unsigned index,
	151	struct device *device);
	152	struct device tty_port_register_device_attr_serdev(struct tty_port port,
	153	struct tty_driver *driver, unsigned index,
	154	struct device device, void drvdata,
	155	const struct attribute_group **attr_grp);
	156	void tty_port_unregister_device(struct tty_port *port,
	157	struct tty_driver *driver, unsigned index);
	158	int tty_port_alloc_xmit_buf(struct tty_port *port);
	159	void tty_port_free_xmit_buf(struct tty_port *port);
	160	void tty_port_destroy(struct tty_port *port);
	161	void tty_port_put(struct tty_port *port);
	162
	163	static inline struct tty_port tty_port_get(struct tty_port port)
	164	{
	165	if (port && kref_get_unless_zero(&port->kref))
	166	return port;
	167	return NULL;
	168	}
	169
	170	/* If the cts flow control is enabled, return true. */
	171	static inline bool tty_port_cts_enabled(const struct tty_port *port)
	172	{
	173	return test_bit(TTY_PORT_CTS_FLOW, &port->iflags);
	174	}
	175
	176	static inline void tty_port_set_cts_flow(struct tty_port *port, bool val)
	177	{
	178	assign_bit(TTY_PORT_CTS_FLOW, &port->iflags, val);
	179	}
	180
	181	static inline bool tty_port_active(const struct tty_port *port)
	182	{
	183	return test_bit(TTY_PORT_ACTIVE, &port->iflags);
	184	}
	185
	186	static inline void tty_port_set_active(struct tty_port *port, bool val)
187	{
188	assign_bit(TTY_PORT_ACTIVE, &port->iflags, val);
189	}
190
191	static inline bool tty_port_check_carrier(const struct tty_port *port)
192	{
193	return test_bit(TTY_PORT_CHECK_CD, &port->iflags);
194	}
195
196	static inline void tty_port_set_check_carrier(struct tty_port *port, bool val)
197	{
198	assign_bit(TTY_PORT_CHECK_CD, &port->iflags, val);
199	}
200
201	static inline bool tty_port_suspended(const struct tty_port *port)
202	{
203	return test_bit(TTY_PORT_SUSPENDED, &port->iflags);
204	}
205
206	static inline void tty_port_set_suspended(struct tty_port *port, bool val)
207	{
208	assign_bit(TTY_PORT_SUSPENDED, &port->iflags, val);
209	}
210
211	static inline bool tty_port_initialized(const struct tty_port *port)
212	{
213	return test_bit(TTY_PORT_INITIALIZED, &port->iflags);
214	}
215
216	static inline void tty_port_set_initialized(struct tty_port *port, bool val)
217	{
218	assign_bit(TTY_PORT_INITIALIZED, &port->iflags, val);
219	}
220
221	static inline bool tty_port_kopened(const struct tty_port *port)
222	{
223	return test_bit(TTY_PORT_KOPENED, &port->iflags);
224	}
225
226	static inline void tty_port_set_kopened(struct tty_port *port, bool val)
227	{
228	assign_bit(TTY_PORT_KOPENED, &port->iflags, val);
229	}
230
231	struct tty_struct tty_port_tty_get(struct tty_port port);
232	void tty_port_tty_set(struct tty_port port, struct tty_struct tty);
b300fb26	233	bool tty_port_carrier_raised(struct tty_port *port);
67b94be4 JS	234	void tty_port_raise_dtr_rts(struct tty_port *port);
	235	void tty_port_lower_dtr_rts(struct tty_port *port);
	236	void tty_port_hangup(struct tty_port *port);
	237	void tty_port_tty_hangup(struct tty_port *port, bool check_clocal);
	238	void tty_port_tty_wakeup(struct tty_port *port);
	239	int tty_port_block_til_ready(struct tty_port port, struct tty_struct tty,
	240	struct file *filp);
	241	int tty_port_close_start(struct tty_port port, struct tty_struct tty,
	242	struct file *filp);
	243	void tty_port_close_end(struct tty_port port, struct tty_struct tty);
	244	void tty_port_close(struct tty_port port, struct tty_struct tty,
	245	struct file *filp);
	246	int tty_port_install(struct tty_port port, struct tty_driver driver,
	247	struct tty_struct *tty);
	248	int tty_port_open(struct tty_port port, struct tty_struct tty,
	249	struct file *filp);
	250
	251	static inline int tty_port_users(struct tty_port *port)
	252	{
	253	return port->count + port->blocked_open;
	254	}
	255
	256	#endif