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