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