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