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