xref: /linux/include/linux/tty_port.h (revision 06d07429858317ded2db7986113a9e0129cd599b)
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 
tty_port_get(struct tty_port * port)164 static inline struct tty_port *tty_port_get(struct tty_port *port)
165 {
166 	if (port && kref_get_unless_zero(&port->kref))
167 		return port;
168 	return NULL;
169 }
170 
171 /* If the cts flow control is enabled, return true. */
tty_port_cts_enabled(const struct tty_port * port)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 
tty_port_set_cts_flow(struct tty_port * port,bool val)177 static inline void tty_port_set_cts_flow(struct tty_port *port, bool val)
178 {
179 	assign_bit(TTY_PORT_CTS_FLOW, &port->iflags, val);
180 }
181 
tty_port_active(const struct tty_port * port)182 static inline bool tty_port_active(const struct tty_port *port)
183 {
184 	return test_bit(TTY_PORT_ACTIVE, &port->iflags);
185 }
186 
tty_port_set_active(struct tty_port * port,bool val)187 static inline void tty_port_set_active(struct tty_port *port, bool val)
188 {
189 	assign_bit(TTY_PORT_ACTIVE, &port->iflags, val);
190 }
191 
tty_port_check_carrier(const struct tty_port * port)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 
tty_port_set_check_carrier(struct tty_port * port,bool val)197 static inline void tty_port_set_check_carrier(struct tty_port *port, bool val)
198 {
199 	assign_bit(TTY_PORT_CHECK_CD, &port->iflags, val);
200 }
201 
tty_port_suspended(const struct tty_port * port)202 static inline bool tty_port_suspended(const struct tty_port *port)
203 {
204 	return test_bit(TTY_PORT_SUSPENDED, &port->iflags);
205 }
206 
tty_port_set_suspended(struct tty_port * port,bool val)207 static inline void tty_port_set_suspended(struct tty_port *port, bool val)
208 {
209 	assign_bit(TTY_PORT_SUSPENDED, &port->iflags, val);
210 }
211 
tty_port_initialized(const struct tty_port * port)212 static inline bool tty_port_initialized(const struct tty_port *port)
213 {
214 	return test_bit(TTY_PORT_INITIALIZED, &port->iflags);
215 }
216 
tty_port_set_initialized(struct tty_port * port,bool val)217 static inline void tty_port_set_initialized(struct tty_port *port, bool val)
218 {
219 	assign_bit(TTY_PORT_INITIALIZED, &port->iflags, val);
220 }
221 
tty_port_kopened(const struct tty_port * port)222 static inline bool tty_port_kopened(const struct tty_port *port)
223 {
224 	return test_bit(TTY_PORT_KOPENED, &port->iflags);
225 }
226 
tty_port_set_kopened(struct tty_port * port,bool val)227 static inline void tty_port_set_kopened(struct tty_port *port, bool val)
228 {
229 	assign_bit(TTY_PORT_KOPENED, &port->iflags, 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 
tty_port_users(struct tty_port * port)252 static inline int tty_port_users(struct tty_port *port)
253 {
254 	return port->count + port->blocked_open;
255 }
256 
257 #endif
258