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_attr_serdev(struct tty_port *port, 151 struct tty_driver *driver, unsigned index, 152 struct device *host, struct device *parent, 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 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 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 assign_bit(TTY_PORT_INITIALIZED, &port->iflags, val); 217 } 218 219 static inline bool tty_port_kopened(const struct tty_port *port) 220 { 221 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 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 bool 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, bool async); 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 /** 255 * tty_port_tty_hangup - helper to hang up a tty asynchronously 256 * @port: tty port 257 * @check_clocal: hang only ttys with %CLOCAL unset? 258 */ 259 static inline void tty_port_tty_hangup(struct tty_port *port, bool check_clocal) 260 { 261 __tty_port_tty_hangup(port, check_clocal, true); 262 } 263 264 /** 265 * tty_port_tty_vhangup - helper to hang up a tty synchronously 266 * @port: tty port 267 */ 268 static inline void tty_port_tty_vhangup(struct tty_port *port) 269 { 270 __tty_port_tty_hangup(port, false, false); 271 } 272 273 #ifdef CONFIG_TTY 274 void tty_kref_put(struct tty_struct *tty); 275 __DEFINE_CLASS_IS_CONDITIONAL(tty_port_tty, true); 276 __DEFINE_UNLOCK_GUARD(tty_port_tty, struct tty_struct, tty_kref_put(_T->lock)); 277 static inline class_tty_port_tty_t class_tty_port_tty_constructor(struct tty_port *tport) 278 { 279 class_tty_port_tty_t _t = { 280 .lock = tty_port_tty_get(tport), 281 }; 282 return _t; 283 } 284 #define scoped_tty() ((struct tty_struct *)(__guard_ptr(tty_port_tty)(&scope))) 285 #endif 286 287 #endif 288