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