tty_port.h

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