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