include/linux/tty_port.h

   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_serdev(struct tty_port *port,
 151                 struct tty_driver *driver, unsigned index,
 152                 struct device *host, struct device *parent);
 153 struct device *tty_port_register_device_attr_serdev(struct tty_port *port,
 154                 struct tty_driver *driver, unsigned index,
 155                 struct device *host, struct device *parent, void *drvdata,
 156                 const struct attribute_group **attr_grp);
 157 void tty_port_unregister_device(struct tty_port *port,
 158                 struct tty_driver *driver, unsigned index);
 159 int tty_port_alloc_xmit_buf(struct tty_port *port);
 160 void tty_port_free_xmit_buf(struct tty_port *port);
 161 void tty_port_destroy(struct tty_port *port);
 162 void tty_port_put(struct tty_port *port);
 163
 164 static inline struct tty_port *tty_port_get(struct tty_port *port)
 165 {
 166         if (port && kref_get_unless_zero(&port->kref))
 167                 return port;
 168         return NULL;
 169 }
 170
 171 /* If the cts flow control is enabled, return true. */
 172 static inline bool tty_port_cts_enabled(const struct tty_port *port)
 173 {
 174         return test_bit(TTY_PORT_CTS_FLOW, &port->iflags);
 175 }
 176
 177 static inline void tty_port_set_cts_flow(struct tty_port *port, bool val)
 178 {
 179         assign_bit(TTY_PORT_CTS_FLOW, &port->iflags, val);
 180 }
 181
 182 static inline bool tty_port_active(const struct tty_port *port)
 183 {
 184         return test_bit(TTY_PORT_ACTIVE, &port->iflags);
 185 }
 186
 187 static inline void tty_port_set_active(struct tty_port *port, bool val)
 188 {
 189         assign_bit(TTY_PORT_ACTIVE, &port->iflags, val);
 190 }
 191
 192 static inline bool tty_port_check_carrier(const struct tty_port *port)
 193 {
 194         return test_bit(TTY_PORT_CHECK_CD, &port->iflags);
 195 }
 196
 197 static inline void tty_port_set_check_carrier(struct tty_port *port, bool val)
 198 {
 199         assign_bit(TTY_PORT_CHECK_CD, &port->iflags, val);
 200 }
 201
 202 static inline bool tty_port_suspended(const struct tty_port *port)
 203 {
 204         return test_bit(TTY_PORT_SUSPENDED, &port->iflags);
 205 }
 206
 207 static inline void tty_port_set_suspended(struct tty_port *port, bool val)
 208 {
 209         assign_bit(TTY_PORT_SUSPENDED, &port->iflags, val);
 210 }
 211
 212 static inline bool tty_port_initialized(const struct tty_port *port)
 213 {
 214         return test_bit(TTY_PORT_INITIALIZED, &port->iflags);
 215 }
 216
 217 static inline void tty_port_set_initialized(struct tty_port *port, bool val)
 218 {
 219         assign_bit(TTY_PORT_INITIALIZED, &port->iflags, val);
 220 }
 221
 222 static inline bool tty_port_kopened(const struct tty_port *port)
 223 {
 224         return test_bit(TTY_PORT_KOPENED, &port->iflags);
 225 }
 226
 227 static inline void tty_port_set_kopened(struct tty_port *port, bool val)
 228 {
 229         assign_bit(TTY_PORT_KOPENED, &port->iflags, val);
 230 }
 231
 232 struct tty_struct *tty_port_tty_get(struct tty_port *port);
 233 void tty_port_tty_set(struct tty_port *port, struct tty_struct *tty);
 234 bool tty_port_carrier_raised(struct tty_port *port);
 235 void tty_port_raise_dtr_rts(struct tty_port *port);
 236 void tty_port_lower_dtr_rts(struct tty_port *port);
 237 void tty_port_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);
 240 int tty_port_block_til_ready(struct tty_port *port, struct tty_struct *tty,
 241                 struct file *filp);
 242 int tty_port_close_start(struct tty_port *port, struct tty_struct *tty,
 243                 struct file *filp);
 244 void tty_port_close_end(struct tty_port *port, struct tty_struct *tty);
 245 void tty_port_close(struct tty_port *port, struct tty_struct *tty,
 246                 struct file *filp);
 247 int tty_port_install(struct tty_port *port, struct tty_driver *driver,
 248                 struct tty_struct *tty);
 249 int tty_port_open(struct tty_port *port, struct tty_struct *tty,
 250                 struct file *filp);
 251
 252 static inline int tty_port_users(struct tty_port *port)
 253 {
 254         return port->count + port->blocked_open;
 255 }
 256
 257 #endif