Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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_wq(struct tty_port *port, struct workqueue_struct *flip_wq);
142void tty_port_link_device(struct tty_port *port, struct tty_driver *driver,
143 unsigned index);
144struct device *tty_port_register_device(struct tty_port *port,
145 struct tty_driver *driver, unsigned index,
146 struct device *device);
147struct device *tty_port_register_device_attr(struct tty_port *port,
148 struct tty_driver *driver, unsigned index,
149 struct device *device, void *drvdata,
150 const struct attribute_group **attr_grp);
151struct device *tty_port_register_device_attr_serdev(struct tty_port *port,
152 struct tty_driver *driver, unsigned index,
153 struct device *host, struct device *parent, void *drvdata,
154 const struct attribute_group **attr_grp);
155void tty_port_unregister_device(struct tty_port *port,
156 struct tty_driver *driver, unsigned index);
157int tty_port_alloc_xmit_buf(struct tty_port *port);
158void tty_port_free_xmit_buf(struct tty_port *port);
159void tty_port_destroy(struct tty_port *port);
160void tty_port_put(struct tty_port *port);
161
162static inline struct tty_port *tty_port_get(struct tty_port *port)
163{
164 if (port && kref_get_unless_zero(&port->kref))
165 return port;
166 return NULL;
167}
168
169/*
170 * Never overwrite the workqueue set by tty_port_link_wq().
171 * No effect when %TTY_DRIVER_NO_WORKQUEUE is set, as driver->flip_wq is
172 * %NULL.
173 */
174static inline void tty_port_link_driver_wq(struct tty_port *port,
175 struct tty_driver *driver)
176{
177 if (!port->buf.flip_wq)
178 tty_port_link_wq(port, driver->flip_wq);
179}
180
181/* If the cts flow control is enabled, return true. */
182static inline bool tty_port_cts_enabled(const struct tty_port *port)
183{
184 return test_bit(TTY_PORT_CTS_FLOW, &port->iflags);
185}
186
187static inline void tty_port_set_cts_flow(struct tty_port *port, bool val)
188{
189 assign_bit(TTY_PORT_CTS_FLOW, &port->iflags, val);
190}
191
192static inline bool tty_port_active(const struct tty_port *port)
193{
194 return test_bit(TTY_PORT_ACTIVE, &port->iflags);
195}
196
197static inline void tty_port_set_active(struct tty_port *port, bool val)
198{
199 assign_bit(TTY_PORT_ACTIVE, &port->iflags, val);
200}
201
202static inline bool tty_port_check_carrier(const struct tty_port *port)
203{
204 return test_bit(TTY_PORT_CHECK_CD, &port->iflags);
205}
206
207static inline void tty_port_set_check_carrier(struct tty_port *port, bool val)
208{
209 assign_bit(TTY_PORT_CHECK_CD, &port->iflags, val);
210}
211
212static inline bool tty_port_suspended(const struct tty_port *port)
213{
214 return test_bit(TTY_PORT_SUSPENDED, &port->iflags);
215}
216
217static inline void tty_port_set_suspended(struct tty_port *port, bool val)
218{
219 assign_bit(TTY_PORT_SUSPENDED, &port->iflags, val);
220}
221
222static inline bool tty_port_initialized(const struct tty_port *port)
223{
224 return test_bit(TTY_PORT_INITIALIZED, &port->iflags);
225}
226
227static inline void tty_port_set_initialized(struct tty_port *port, bool val)
228{
229 assign_bit(TTY_PORT_INITIALIZED, &port->iflags, val);
230}
231
232static inline bool tty_port_kopened(const struct tty_port *port)
233{
234 return test_bit(TTY_PORT_KOPENED, &port->iflags);
235}
236
237static inline void tty_port_set_kopened(struct tty_port *port, bool val)
238{
239 assign_bit(TTY_PORT_KOPENED, &port->iflags, val);
240}
241
242struct tty_struct *tty_port_tty_get(struct tty_port *port);
243void tty_port_tty_set(struct tty_port *port, struct tty_struct *tty);
244bool tty_port_carrier_raised(struct tty_port *port);
245void tty_port_raise_dtr_rts(struct tty_port *port);
246void tty_port_lower_dtr_rts(struct tty_port *port);
247void tty_port_hangup(struct tty_port *port);
248void __tty_port_tty_hangup(struct tty_port *port, bool check_clocal, bool async);
249void tty_port_tty_wakeup(struct tty_port *port);
250int tty_port_block_til_ready(struct tty_port *port, struct tty_struct *tty,
251 struct file *filp);
252int tty_port_close_start(struct tty_port *port, struct tty_struct *tty,
253 struct file *filp);
254void tty_port_close_end(struct tty_port *port, struct tty_struct *tty);
255void tty_port_close(struct tty_port *port, struct tty_struct *tty,
256 struct file *filp);
257int tty_port_install(struct tty_port *port, struct tty_driver *driver,
258 struct tty_struct *tty);
259int tty_port_open(struct tty_port *port, struct tty_struct *tty,
260 struct file *filp);
261
262static inline int tty_port_users(struct tty_port *port)
263{
264 return port->count + port->blocked_open;
265}
266
267/**
268 * tty_port_tty_hangup - helper to hang up a tty asynchronously
269 * @port: tty port
270 * @check_clocal: hang only ttys with %CLOCAL unset?
271 */
272static inline void tty_port_tty_hangup(struct tty_port *port, bool check_clocal)
273{
274 __tty_port_tty_hangup(port, check_clocal, true);
275}
276
277/**
278 * tty_port_tty_vhangup - helper to hang up a tty synchronously
279 * @port: tty port
280 */
281static inline void tty_port_tty_vhangup(struct tty_port *port)
282{
283 __tty_port_tty_hangup(port, false, false);
284}
285
286#ifdef CONFIG_TTY
287void tty_kref_put(struct tty_struct *tty);
288__DEFINE_CLASS_IS_CONDITIONAL(tty_port_tty, true);
289__DEFINE_UNLOCK_GUARD(tty_port_tty, struct tty_struct, tty_kref_put(_T->lock));
290static inline class_tty_port_tty_t class_tty_port_tty_constructor(struct tty_port *tport)
291{
292 class_tty_port_tty_t _t = {
293 .lock = tty_port_tty_get(tport),
294 };
295 return _t;
296}
297#define scoped_tty() ((struct tty_struct *)(__guard_ptr(tty_port_tty)(&scope)))
298#endif
299
300#endif