include/linux/tty_port.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 #ifndef _LINUX_TTY_PORT_H
0003 #define _LINUX_TTY_PORT_H
0004
0005 #include <linux/kfifo.h>
0006 #include <linux/kref.h>
0007 #include <linux/mutex.h>
0008 #include <linux/tty_buffer.h>
0009 #include <linux/wait.h>
0010
0011 struct attribute_group;
0012 struct tty_driver;
0013 struct tty_port;
0014 struct tty_struct;
0015
0016 /**
0017  * struct tty_port_operations -- operations on tty_port
0018  * @carrier_raised: return 1 if the carrier is raised on @port
0019  * @dtr_rts: raise the DTR line if @raise is nonzero, otherwise lower DTR
0020  * @shutdown: called when the last close completes or a hangup finishes IFF the
0021  *  port was initialized. Do not use to free resources. Turn off the device
0022  *  only. Called under the port mutex to serialize against @activate and
0023  *  @shutdown.
0024  * @activate: called under the port mutex from tty_port_open(), serialized using
0025  *  the port mutex. Supposed to turn on the device.
0026  *
0027  *  FIXME: long term getting the tty argument *out* of this would be good
0028  *  for consoles.
0029  *
0030  * @destruct: called on the final put of a port. Free resources, possibly incl.
0031  *  the port itself.
0032  */
0033 struct tty_port_operations {
0034     int (*carrier_raised)(struct tty_port *port);
0035     void (*dtr_rts)(struct tty_port *port, int raise);
0036     void (*shutdown)(struct tty_port *port);
0037     int (*activate)(struct tty_port *port, struct tty_struct *tty);
0038     void (*destruct)(struct tty_port *port);
0039 };
0040
0041 struct tty_port_client_operations {
0042     int (*receive_buf)(struct tty_port *port, const unsigned char *, const unsigned char *, size_t);
0043     void (*lookahead_buf)(struct tty_port *port, const unsigned char *cp,
0044                   const unsigned char *fp, unsigned int count);
0045     void (*write_wakeup)(struct tty_port *port);
0046 };
0047
0048 extern const struct tty_port_client_operations tty_port_default_client_ops;
0049
0050 /**
0051  * struct tty_port -- port level information
0052  *
0053  * @buf: buffer for this port, locked internally
0054  * @tty: back pointer to &struct tty_struct, valid only if the tty is open. Use
0055  *   tty_port_tty_get() to obtain it (and tty_kref_put() to release).
0056  * @itty: internal back pointer to &struct tty_struct. Avoid this. It should be
0057  *    eliminated in the long term.
0058  * @ops: tty port operations (like activate, shutdown), see &struct
0059  *   tty_port_operations
0060  * @client_ops: tty port client operations (like receive_buf, write_wakeup).
0061  *      By default, tty_port_default_client_ops is used.
0062  * @lock: lock protecting @tty
0063  * @blocked_open: # of procs waiting for open in tty_port_block_til_ready()
0064  * @count: usage count
0065  * @open_wait: open waiters queue (waiting e.g. for a carrier)
0066  * @delta_msr_wait: modem status change queue (waiting for MSR changes)
0067  * @flags: user TTY flags (%ASYNC_)
0068  * @iflags: internal flags (%TTY_PORT_)
0069  * @console: when set, the port is a console
0070  * @mutex: locking, for open, shutdown and other port operations
0071  * @buf_mutex: @xmit_buf alloc lock
0072  * @xmit_buf: optional xmit buffer used by some drivers
0073  * @xmit_fifo: optional xmit buffer used by some drivers
0074  * @close_delay: delay in jiffies to wait when closing the port
0075  * @closing_wait: delay in jiffies for output to be sent before closing
0076  * @drain_delay: set to zero if no pure time based drain is needed else set to
0077  *       size of fifo
0078  * @kref: references counter. Reaching zero calls @ops->destruct() if non-%NULL
0079  *    or frees the port otherwise.
0080  * @client_data: pointer to private data, for @client_ops
0081  *
0082  * Each device keeps its own port level information. &struct tty_port was
0083  * introduced as a common structure for such information. As every TTY device
0084  * shall have a backing tty_port structure, every driver can use these members.
0085  *
0086  * The tty port has a different lifetime to the tty so must be kept apart.
0087  * In addition be careful as tty -> port mappings are valid for the life
0088  * of the tty object but in many cases port -> tty mappings are valid only
0089  * until a hangup so don't use the wrong path.
0090  *
0091  * Tty port shall be initialized by tty_port_init() and shut down either by
0092  * tty_port_destroy() (refcounting not used), or tty_port_put() (refcounting).
0093  *
0094  * There is a lot of helpers around &struct tty_port too. To name the most
0095  * significant ones: tty_port_open(), tty_port_close() (or
0096  * tty_port_close_start() and tty_port_close_end() separately if need be), and
0097  * tty_port_hangup(). These call @ops->activate() and @ops->shutdown() as
0098  * needed.
0099  */
0100 struct tty_port {
0101     struct tty_bufhead  buf;
0102     struct tty_struct   *tty;
0103     struct tty_struct   *itty;
0104     const struct tty_port_operations *ops;
0105     const struct tty_port_client_operations *client_ops;
0106     spinlock_t      lock;
0107     int         blocked_open;
0108     int         count;
0109     wait_queue_head_t   open_wait;
0110     wait_queue_head_t   delta_msr_wait;
0111     unsigned long       flags;
0112     unsigned long       iflags;
0113     unsigned char       console:1;
0114     struct mutex        mutex;
0115     struct mutex        buf_mutex;
0116     unsigned char       *xmit_buf;
0117     DECLARE_KFIFO_PTR(xmit_fifo, unsigned char);
0118     unsigned int        close_delay;
0119     unsigned int        closing_wait;
0120     int         drain_delay;
0121     struct kref     kref;
0122     void            *client_data;
0123 };
0124
0125 /* tty_port::iflags bits -- use atomic bit ops */
0126 #define TTY_PORT_INITIALIZED    0   /* device is initialized */
0127 #define TTY_PORT_SUSPENDED  1   /* device is suspended */
0128 #define TTY_PORT_ACTIVE     2   /* device is open */
0129
0130 /*
0131  * uart drivers: use the uart_port::status field and the UPSTAT_* defines
0132  * for s/w-based flow control steering and carrier detection status
0133  */
0134 #define TTY_PORT_CTS_FLOW   3   /* h/w flow control enabled */
0135 #define TTY_PORT_CHECK_CD   4   /* carrier detect enabled */
0136 #define TTY_PORT_KOPENED    5   /* device exclusively opened by
0137                        kernel */
0138
0139 void tty_port_init(struct tty_port *port);
0140 void tty_port_link_device(struct tty_port *port, struct tty_driver *driver,
0141         unsigned index);
0142 struct device *tty_port_register_device(struct tty_port *port,
0143         struct tty_driver *driver, unsigned index,
0144         struct device *device);
0145 struct device *tty_port_register_device_attr(struct tty_port *port,
0146         struct tty_driver *driver, unsigned index,
0147         struct device *device, void *drvdata,
0148         const struct attribute_group **attr_grp);
0149 struct device *tty_port_register_device_serdev(struct tty_port *port,
0150         struct tty_driver *driver, unsigned index,
0151         struct device *device);
0152 struct device *tty_port_register_device_attr_serdev(struct tty_port *port,
0153         struct tty_driver *driver, unsigned index,
0154         struct device *device, void *drvdata,
0155         const struct attribute_group **attr_grp);
0156 void tty_port_unregister_device(struct tty_port *port,
0157         struct tty_driver *driver, unsigned index);
0158 int tty_port_alloc_xmit_buf(struct tty_port *port);
0159 void tty_port_free_xmit_buf(struct tty_port *port);
0160 void tty_port_destroy(struct tty_port *port);
0161 void tty_port_put(struct tty_port *port);
0162
0163 static inline struct tty_port *tty_port_get(struct tty_port *port)
0164 {
0165     if (port && kref_get_unless_zero(&port->kref))
0166         return port;
0167     return NULL;
0168 }
0169
0170 /* If the cts flow control is enabled, return true. */
0171 static inline bool tty_port_cts_enabled(const struct tty_port *port)
0172 {
0173     return test_bit(TTY_PORT_CTS_FLOW, &port->iflags);
0174 }
0175
0176 static inline void tty_port_set_cts_flow(struct tty_port *port, bool val)
0177 {
0178     assign_bit(TTY_PORT_CTS_FLOW, &port->iflags, val);
0179 }
0180
0181 static inline bool tty_port_active(const struct tty_port *port)
0182 {
0183     return test_bit(TTY_PORT_ACTIVE, &port->iflags);
0184 }
0185
0186 static inline void tty_port_set_active(struct tty_port *port, bool val)
0187 {
0188     assign_bit(TTY_PORT_ACTIVE, &port->iflags, val);
0189 }
0190
0191 static inline bool tty_port_check_carrier(const struct tty_port *port)
0192 {
0193     return test_bit(TTY_PORT_CHECK_CD, &port->iflags);
0194 }
0195
0196 static inline void tty_port_set_check_carrier(struct tty_port *port, bool val)
0197 {
0198     assign_bit(TTY_PORT_CHECK_CD, &port->iflags, val);
0199 }
0200
0201 static inline bool tty_port_suspended(const struct tty_port *port)
0202 {
0203     return test_bit(TTY_PORT_SUSPENDED, &port->iflags);
0204 }
0205
0206 static inline void tty_port_set_suspended(struct tty_port *port, bool val)
0207 {
0208     assign_bit(TTY_PORT_SUSPENDED, &port->iflags, val);
0209 }
0210
0211 static inline bool tty_port_initialized(const struct tty_port *port)
0212 {
0213     return test_bit(TTY_PORT_INITIALIZED, &port->iflags);
0214 }
0215
0216 static inline void tty_port_set_initialized(struct tty_port *port, bool val)
0217 {
0218     assign_bit(TTY_PORT_INITIALIZED, &port->iflags, val);
0219 }
0220
0221 static inline bool tty_port_kopened(const struct tty_port *port)
0222 {
0223     return test_bit(TTY_PORT_KOPENED, &port->iflags);
0224 }
0225
0226 static inline void tty_port_set_kopened(struct tty_port *port, bool val)
0227 {
0228     assign_bit(TTY_PORT_KOPENED, &port->iflags, val);
0229 }
0230
0231 struct tty_struct *tty_port_tty_get(struct tty_port *port);
0232 void tty_port_tty_set(struct tty_port *port, struct tty_struct *tty);
0233 int tty_port_carrier_raised(struct tty_port *port);
0234 void tty_port_raise_dtr_rts(struct tty_port *port);
0235 void tty_port_lower_dtr_rts(struct tty_port *port);
0236 void tty_port_hangup(struct tty_port *port);
0237 void tty_port_tty_hangup(struct tty_port *port, bool check_clocal);
0238 void tty_port_tty_wakeup(struct tty_port *port);
0239 int tty_port_block_til_ready(struct tty_port *port, struct tty_struct *tty,
0240         struct file *filp);
0241 int tty_port_close_start(struct tty_port *port, struct tty_struct *tty,
0242         struct file *filp);
0243 void tty_port_close_end(struct tty_port *port, struct tty_struct *tty);
0244 void tty_port_close(struct tty_port *port, struct tty_struct *tty,
0245         struct file *filp);
0246 int tty_port_install(struct tty_port *port, struct tty_driver *driver,
0247         struct tty_struct *tty);
0248 int tty_port_open(struct tty_port *port, struct tty_struct *tty,
0249         struct file *filp);
0250
0251 static inline int tty_port_users(struct tty_port *port)
0252 {
0253     return port->count + port->blocked_open;
0254 }
0255
0256 #endif