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 | |
11 | struct attribute_group; |
12 | struct tty_driver; |
13 | struct tty_port; |
14 | struct 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 | */ |
33 | struct 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 | |
41 | struct 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 | |
49 | extern 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 | */ |
101 | struct 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 | |
140 | void tty_port_init(struct tty_port *port); |
141 | void tty_port_link_device(struct tty_port *port, struct tty_driver *driver, |
142 | unsigned index); |
143 | struct device *tty_port_register_device(struct tty_port *port, |
144 | struct tty_driver *driver, unsigned index, |
145 | struct device *device); |
146 | struct 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); |
150 | struct device *tty_port_register_device_serdev(struct tty_port *port, |
151 | struct tty_driver *driver, unsigned index, |
152 | struct device *host, struct device *parent); |
153 | struct device *tty_port_register_device_attr_serdev(struct tty_port *port, |
154 | struct tty_driver *driver, unsigned index, |
155 | struct device *host, struct device *parent, void *drvdata, |
156 | const struct attribute_group **attr_grp); |
157 | void tty_port_unregister_device(struct tty_port *port, |
158 | struct tty_driver *driver, unsigned index); |
159 | int tty_port_alloc_xmit_buf(struct tty_port *port); |
160 | void tty_port_free_xmit_buf(struct tty_port *port); |
161 | void tty_port_destroy(struct tty_port *port); |
162 | void tty_port_put(struct tty_port *port); |
163 | |
164 | static inline struct tty_port *tty_port_get(struct tty_port *port) |
165 | { |
166 | if (port && kref_get_unless_zero(kref: &port->kref)) |
167 | return port; |
168 | return NULL; |
169 | } |
170 | |
171 | /* If the cts flow control is enabled, return true. */ |
172 | static inline bool tty_port_cts_enabled(const struct tty_port *port) |
173 | { |
174 | return test_bit(TTY_PORT_CTS_FLOW, &port->iflags); |
175 | } |
176 | |
177 | static inline void tty_port_set_cts_flow(struct tty_port *port, bool val) |
178 | { |
179 | assign_bit(TTY_PORT_CTS_FLOW, addr: &port->iflags, value: val); |
180 | } |
181 | |
182 | static inline bool tty_port_active(const struct tty_port *port) |
183 | { |
184 | return test_bit(TTY_PORT_ACTIVE, &port->iflags); |
185 | } |
186 | |
187 | static inline void tty_port_set_active(struct tty_port *port, bool val) |
188 | { |
189 | assign_bit(TTY_PORT_ACTIVE, addr: &port->iflags, value: val); |
190 | } |
191 | |
192 | static inline bool tty_port_check_carrier(const struct tty_port *port) |
193 | { |
194 | return test_bit(TTY_PORT_CHECK_CD, &port->iflags); |
195 | } |
196 | |
197 | static inline void tty_port_set_check_carrier(struct tty_port *port, bool val) |
198 | { |
199 | assign_bit(TTY_PORT_CHECK_CD, addr: &port->iflags, value: val); |
200 | } |
201 | |
202 | static inline bool tty_port_suspended(const struct tty_port *port) |
203 | { |
204 | return test_bit(TTY_PORT_SUSPENDED, &port->iflags); |
205 | } |
206 | |
207 | static inline void tty_port_set_suspended(struct tty_port *port, bool val) |
208 | { |
209 | assign_bit(TTY_PORT_SUSPENDED, addr: &port->iflags, value: val); |
210 | } |
211 | |
212 | static inline bool tty_port_initialized(const struct tty_port *port) |
213 | { |
214 | return test_bit(TTY_PORT_INITIALIZED, &port->iflags); |
215 | } |
216 | |
217 | static inline void tty_port_set_initialized(struct tty_port *port, bool val) |
218 | { |
219 | assign_bit(TTY_PORT_INITIALIZED, addr: &port->iflags, value: val); |
220 | } |
221 | |
222 | static inline bool tty_port_kopened(const struct tty_port *port) |
223 | { |
224 | return test_bit(TTY_PORT_KOPENED, &port->iflags); |
225 | } |
226 | |
227 | static inline void tty_port_set_kopened(struct tty_port *port, bool val) |
228 | { |
229 | assign_bit(TTY_PORT_KOPENED, addr: &port->iflags, value: val); |
230 | } |
231 | |
232 | struct tty_struct *tty_port_tty_get(struct tty_port *port); |
233 | void tty_port_tty_set(struct tty_port *port, struct tty_struct *tty); |
234 | bool tty_port_carrier_raised(struct tty_port *port); |
235 | void tty_port_raise_dtr_rts(struct tty_port *port); |
236 | void tty_port_lower_dtr_rts(struct tty_port *port); |
237 | void tty_port_hangup(struct tty_port *port); |
238 | void tty_port_tty_hangup(struct tty_port *port, bool check_clocal); |
239 | void tty_port_tty_wakeup(struct tty_port *port); |
240 | int tty_port_block_til_ready(struct tty_port *port, struct tty_struct *tty, |
241 | struct file *filp); |
242 | int tty_port_close_start(struct tty_port *port, struct tty_struct *tty, |
243 | struct file *filp); |
244 | void tty_port_close_end(struct tty_port *port, struct tty_struct *tty); |
245 | void tty_port_close(struct tty_port *port, struct tty_struct *tty, |
246 | struct file *filp); |
247 | int tty_port_install(struct tty_port *port, struct tty_driver *driver, |
248 | struct tty_struct *tty); |
249 | int tty_port_open(struct tty_port *port, struct tty_struct *tty, |
250 | struct file *filp); |
251 | |
252 | static inline int tty_port_users(struct tty_port *port) |
253 | { |
254 | return port->count + port->blocked_open; |
255 | } |
256 | |
257 | #endif |
258 | |