1b2441318SGreg Kroah-Hartman /* SPDX-License-Identifier: GPL-2.0 */ 21da177e4SLinus Torvalds #ifndef _LINUX_TTY_LDISC_H 31da177e4SLinus Torvalds #define _LINUX_TTY_LDISC_H 41da177e4SLinus Torvalds 5a24bc667SJiri Slaby struct tty_struct; 6a24bc667SJiri Slaby 71da177e4SLinus Torvalds #include <linux/fs.h> 81da177e4SLinus Torvalds #include <linux/wait.h> 95fd691afSPeter Zijlstra #include <linux/atomic.h> 10abca9901SJiri Slaby #include <linux/list.h> 11abca9901SJiri Slaby #include <linux/lockdep.h> 12a24bc667SJiri Slaby #include <linux/seq_file.h> 134898e640SPeter Hurley 144898e640SPeter Hurley /* 154898e640SPeter Hurley * the semaphore definition 164898e640SPeter Hurley */ 174898e640SPeter Hurley struct ld_semaphore { 185fd691afSPeter Zijlstra atomic_long_t count; 194898e640SPeter Hurley raw_spinlock_t wait_lock; 204898e640SPeter Hurley unsigned int wait_readers; 214898e640SPeter Hurley struct list_head read_wait; 224898e640SPeter Hurley struct list_head write_wait; 234898e640SPeter Hurley #ifdef CONFIG_DEBUG_LOCK_ALLOC 244898e640SPeter Hurley struct lockdep_map dep_map; 254898e640SPeter Hurley #endif 264898e640SPeter Hurley }; 274898e640SPeter Hurley 2878941934SJiri Slaby void __init_ldsem(struct ld_semaphore *sem, const char *name, 294898e640SPeter Hurley struct lock_class_key *key); 304898e640SPeter Hurley 314898e640SPeter Hurley #define init_ldsem(sem) \ 324898e640SPeter Hurley do { \ 334898e640SPeter Hurley static struct lock_class_key __key; \ 344898e640SPeter Hurley \ 354898e640SPeter Hurley __init_ldsem((sem), #sem, &__key); \ 364898e640SPeter Hurley } while (0) 374898e640SPeter Hurley 384898e640SPeter Hurley 3978941934SJiri Slaby int ldsem_down_read(struct ld_semaphore *sem, long timeout); 4078941934SJiri Slaby int ldsem_down_read_trylock(struct ld_semaphore *sem); 4178941934SJiri Slaby int ldsem_down_write(struct ld_semaphore *sem, long timeout); 4278941934SJiri Slaby int ldsem_down_write_trylock(struct ld_semaphore *sem); 4378941934SJiri Slaby void ldsem_up_read(struct ld_semaphore *sem); 4478941934SJiri Slaby void ldsem_up_write(struct ld_semaphore *sem); 454898e640SPeter Hurley 464898e640SPeter Hurley #ifdef CONFIG_DEBUG_LOCK_ALLOC 4778941934SJiri Slaby int ldsem_down_read_nested(struct ld_semaphore *sem, int subclass, 484898e640SPeter Hurley long timeout); 4978941934SJiri Slaby int ldsem_down_write_nested(struct ld_semaphore *sem, int subclass, 504898e640SPeter Hurley long timeout); 514898e640SPeter Hurley #else 524898e640SPeter Hurley # define ldsem_down_read_nested(sem, subclass, timeout) \ 534898e640SPeter Hurley ldsem_down_read(sem, timeout) 544898e640SPeter Hurley # define ldsem_down_write_nested(sem, subclass, timeout) \ 554898e640SPeter Hurley ldsem_down_write(sem, timeout) 564898e640SPeter Hurley #endif 574898e640SPeter Hurley 580c6119f9SJiri Slaby /** 590c6119f9SJiri Slaby * struct tty_ldisc_ops - ldisc operations 600c6119f9SJiri Slaby * 610c6119f9SJiri Slaby * @name: name of this ldisc rendered in /proc/tty/ldiscs 620c6119f9SJiri Slaby * @num: ``N_*`` number (%N_TTY, %N_HDLC, ...) reserved to this ldisc 630c6119f9SJiri Slaby * 6440f4268cSJiri Slaby * @open: [TTY] ``int ()(struct tty_struct *tty)`` 650c6119f9SJiri Slaby * 660c6119f9SJiri Slaby * This function is called when the line discipline is associated with the 6740f4268cSJiri Slaby * @tty. No other call into the line discipline for this tty will occur 6840f4268cSJiri Slaby * until it completes successfully. It should initialize any state needed 6940f4268cSJiri Slaby * by the ldisc, and set @tty->receive_room to the maximum amount of data 7040f4268cSJiri Slaby * the line discipline is willing to accept from the driver with a single 7140f4268cSJiri Slaby * call to @receive_buf(). Returning an error will prevent the ldisc from 7240f4268cSJiri Slaby * being attached. 730c6119f9SJiri Slaby * 74abb05ac9SJiri Slaby (SUSE) * Optional. Can sleep. 7540f4268cSJiri Slaby * 7640f4268cSJiri Slaby * @close: [TTY] ``void ()(struct tty_struct *tty)`` 770c6119f9SJiri Slaby * 780c6119f9SJiri Slaby * This function is called when the line discipline is being shutdown, 790c6119f9SJiri Slaby * either because the @tty is being closed or because the @tty is being 8040f4268cSJiri Slaby * changed to use a new line discipline. At the point of execution no 8140f4268cSJiri Slaby * further users will enter the ldisc code for this tty. 820c6119f9SJiri Slaby * 83abb05ac9SJiri Slaby (SUSE) * Optional. Can sleep. 8440f4268cSJiri Slaby * 8540f4268cSJiri Slaby * @flush_buffer: [TTY] ``void ()(struct tty_struct *tty)`` 860c6119f9SJiri Slaby * 870c6119f9SJiri Slaby * This function instructs the line discipline to clear its buffers of any 880c6119f9SJiri Slaby * input characters it may have queued to be delivered to the user mode 8940f4268cSJiri Slaby * process. It may be called at any point between open and close. 900c6119f9SJiri Slaby * 91abb05ac9SJiri Slaby (SUSE) * Optional. 92abb05ac9SJiri Slaby (SUSE) * 93*49b8220cSJiri Slaby (SUSE) * @read: [TTY] ``ssize_t ()(struct tty_struct *tty, struct file *file, u8 *buf, 94*49b8220cSJiri Slaby (SUSE) * size_t nr)`` 950c6119f9SJiri Slaby * 960c6119f9SJiri Slaby * This function is called when the user requests to read from the @tty. 970c6119f9SJiri Slaby * The line discipline will return whatever characters it has buffered up 980c6119f9SJiri Slaby * for the user. If this function is not defined, the user will receive 9940f4268cSJiri Slaby * an %EIO error. Multiple read calls may occur in parallel and the ldisc 10040f4268cSJiri Slaby * must deal with serialization issues. 1010c6119f9SJiri Slaby * 102abb05ac9SJiri Slaby (SUSE) * Optional: %EIO unless provided. Can sleep. 10340f4268cSJiri Slaby * 10440f4268cSJiri Slaby * @write: [TTY] ``ssize_t ()(struct tty_struct *tty, struct file *file, 105*49b8220cSJiri Slaby (SUSE) * const u8 *buf, size_t nr)`` 1060c6119f9SJiri Slaby * 1070c6119f9SJiri Slaby * This function is called when the user requests to write to the @tty. 1080c6119f9SJiri Slaby * The line discipline will deliver the characters to the low-level tty 1090c6119f9SJiri Slaby * device for transmission, optionally performing some processing on the 1100c6119f9SJiri Slaby * characters first. If this function is not defined, the user will 1110c6119f9SJiri Slaby * receive an %EIO error. 1120c6119f9SJiri Slaby * 113abb05ac9SJiri Slaby (SUSE) * Optional: %EIO unless provided. Can sleep. 11440f4268cSJiri Slaby * 11540f4268cSJiri Slaby * @ioctl: [TTY] ``int ()(struct tty_struct *tty, unsigned int cmd, 1160c6119f9SJiri Slaby * unsigned long arg)`` 1170c6119f9SJiri Slaby * 1180c6119f9SJiri Slaby * This function is called when the user requests an ioctl which is not 1190c6119f9SJiri Slaby * handled by the tty layer or the low-level tty driver. It is intended 1200c6119f9SJiri Slaby * for ioctls which affect line discpline operation. Note that the search 1210c6119f9SJiri Slaby * order for ioctls is (1) tty layer, (2) tty low-level driver, (3) line 1220c6119f9SJiri Slaby * discpline. So a low-level driver can "grab" an ioctl request before 1230c6119f9SJiri Slaby * the line discpline has a chance to see it. 1240c6119f9SJiri Slaby * 125abb05ac9SJiri Slaby (SUSE) * Optional. 126abb05ac9SJiri Slaby (SUSE) * 12740f4268cSJiri Slaby * @compat_ioctl: [TTY] ``int ()(struct tty_struct *tty, unsigned int cmd, 1280c6119f9SJiri Slaby * unsigned long arg)`` 1290c6119f9SJiri Slaby * 1300c6119f9SJiri Slaby * Process ioctl calls from 32-bit process on 64-bit system. 1310c6119f9SJiri Slaby * 1320c6119f9SJiri Slaby * Note that only ioctls that are neither "pointer to compatible 1330c6119f9SJiri Slaby * structure" nor tty-generic. Something private that takes an integer or 1340c6119f9SJiri Slaby * a pointer to wordsize-sensitive structure belongs here, but most of 1350c6119f9SJiri Slaby * ldiscs will happily leave it %NULL. 1360c6119f9SJiri Slaby * 137abb05ac9SJiri Slaby (SUSE) * Optional. 138abb05ac9SJiri Slaby (SUSE) * 1398b7d2d95SIlpo Järvinen * @set_termios: [TTY] ``void ()(struct tty_struct *tty, const struct ktermios *old)`` 1400c6119f9SJiri Slaby * 1410c6119f9SJiri Slaby * This function notifies the line discpline that a change has been made 1420c6119f9SJiri Slaby * to the termios structure. 1430c6119f9SJiri Slaby * 144abb05ac9SJiri Slaby (SUSE) * Optional. 145abb05ac9SJiri Slaby (SUSE) * 14640f4268cSJiri Slaby * @poll: [TTY] ``int ()(struct tty_struct *tty, struct file *file, 1470c6119f9SJiri Slaby * struct poll_table_struct *wait)`` 1480c6119f9SJiri Slaby * 1490c6119f9SJiri Slaby * This function is called when a user attempts to select/poll on a @tty 1500c6119f9SJiri Slaby * device. It is solely the responsibility of the line discipline to 1510c6119f9SJiri Slaby * handle poll requests. 1520c6119f9SJiri Slaby * 153abb05ac9SJiri Slaby (SUSE) * Optional. 154abb05ac9SJiri Slaby (SUSE) * 15540f4268cSJiri Slaby * @hangup: [TTY] ``void ()(struct tty_struct *tty)`` 1560c6119f9SJiri Slaby * 1570c6119f9SJiri Slaby * Called on a hangup. Tells the discipline that it should cease I/O to 15840f4268cSJiri Slaby * the tty driver. The driver should seek to perform this action quickly 15940f4268cSJiri Slaby * but should wait until any pending driver I/O is completed. No further 16040f4268cSJiri Slaby * calls into the ldisc code will occur. 1610c6119f9SJiri Slaby * 162abb05ac9SJiri Slaby (SUSE) * Optional. Can sleep. 16340f4268cSJiri Slaby * 164a8d9cd23SJiri Slaby (SUSE) * @receive_buf: [DRV] ``void ()(struct tty_struct *tty, const u8 *cp, 165892bc209SJiri Slaby (SUSE) * const u8 *fp, size_t count)`` 1660c6119f9SJiri Slaby * 1670c6119f9SJiri Slaby * This function is called by the low-level tty driver to send characters 1680c6119f9SJiri Slaby * received by the hardware to the line discpline for processing. @cp is 1690c6119f9SJiri Slaby * a pointer to the buffer of input character received by the device. @fp 1700c6119f9SJiri Slaby * is a pointer to an array of flag bytes which indicate whether a 1710c6119f9SJiri Slaby * character was received with a parity error, etc. @fp may be %NULL to 1720c6119f9SJiri Slaby * indicate all data received is %TTY_NORMAL. 1730c6119f9SJiri Slaby * 174abb05ac9SJiri Slaby (SUSE) * Optional. 175abb05ac9SJiri Slaby (SUSE) * 17640f4268cSJiri Slaby * @write_wakeup: [DRV] ``void ()(struct tty_struct *tty)`` 1770c6119f9SJiri Slaby * 1780c6119f9SJiri Slaby * This function is called by the low-level tty driver to signal that line 1790c6119f9SJiri Slaby * discpline should try to send more characters to the low-level driver 1800c6119f9SJiri Slaby * for transmission. If the line discpline does not have any more data to 1810c6119f9SJiri Slaby * send, it can just return. If the line discipline does have some data to 1820c6119f9SJiri Slaby * send, please arise a tasklet or workqueue to do the real data transfer. 1830c6119f9SJiri Slaby * Do not send data in this hook, it may lead to a deadlock. 1840c6119f9SJiri Slaby * 185abb05ac9SJiri Slaby (SUSE) * Optional. 186abb05ac9SJiri Slaby (SUSE) * 1870388a152SIlpo Järvinen * @dcd_change: [DRV] ``void ()(struct tty_struct *tty, bool active)`` 1880c6119f9SJiri Slaby * 1890c6119f9SJiri Slaby * Tells the discipline that the DCD pin has changed its status. Used 1900c6119f9SJiri Slaby * exclusively by the %N_PPS (Pulse-Per-Second) line discipline. 1910c6119f9SJiri Slaby * 192abb05ac9SJiri Slaby (SUSE) * Optional. 193abb05ac9SJiri Slaby (SUSE) * 194a8d9cd23SJiri Slaby (SUSE) * @receive_buf2: [DRV] ``ssize_t ()(struct tty_struct *tty, const u8 *cp, 195892bc209SJiri Slaby (SUSE) * const u8 *fp, size_t count)`` 1960c6119f9SJiri Slaby * 1970c6119f9SJiri Slaby * This function is called by the low-level tty driver to send characters 1980c6119f9SJiri Slaby * received by the hardware to the line discpline for processing. @cp is a 1990c6119f9SJiri Slaby * pointer to the buffer of input character received by the device. @fp 2000c6119f9SJiri Slaby * is a pointer to an array of flag bytes which indicate whether a 2010c6119f9SJiri Slaby * character was received with a parity error, etc. @fp may be %NULL to 2020c6119f9SJiri Slaby * indicate all data received is %TTY_NORMAL. If assigned, prefer this 2030c6119f9SJiri Slaby * function for automatic flow control. 2040c6119f9SJiri Slaby * 205abb05ac9SJiri Slaby (SUSE) * Optional. 206abb05ac9SJiri Slaby (SUSE) * 207a8d9cd23SJiri Slaby (SUSE) * @lookahead_buf: [DRV] ``void ()(struct tty_struct *tty, const u8 *cp, 208892bc209SJiri Slaby (SUSE) * const u8 *fp, size_t count)`` 2096bb6fa69SIlpo Järvinen * 2106bb6fa69SIlpo Järvinen * This function is called by the low-level tty driver for characters 2116bb6fa69SIlpo Järvinen * not eaten by ->receive_buf() or ->receive_buf2(). It is useful for 2126bb6fa69SIlpo Järvinen * processing high-priority characters such as software flow-control 2136bb6fa69SIlpo Järvinen * characters that could otherwise get stuck into the intermediate 2146bb6fa69SIlpo Järvinen * buffer until tty has room to receive them. Ldisc must be able to 2156bb6fa69SIlpo Järvinen * handle later a ->receive_buf() or ->receive_buf2() call for the 2166bb6fa69SIlpo Järvinen * same characters (e.g. by skipping the actions for high-priority 2176bb6fa69SIlpo Järvinen * characters already handled by ->lookahead_buf()). 2186bb6fa69SIlpo Järvinen * 219abb05ac9SJiri Slaby (SUSE) * Optional. 220abb05ac9SJiri Slaby (SUSE) * 2210c6119f9SJiri Slaby * @owner: module containting this ldisc (for reference counting) 2220c6119f9SJiri Slaby * 2230c6119f9SJiri Slaby * This structure defines the interface between the tty line discipline 2240c6119f9SJiri Slaby * implementation and the tty routines. The above routines can be defined. 2250c6119f9SJiri Slaby * Unless noted otherwise, they are optional, and can be filled in with a %NULL 2260c6119f9SJiri Slaby * pointer. 22740f4268cSJiri Slaby * 22840f4268cSJiri Slaby * Hooks marked [TTY] are invoked from the TTY core, the [DRV] ones from the 22940f4268cSJiri Slaby * tty_driver side. 2300c6119f9SJiri Slaby */ 231a352def2SAlan Cox struct tty_ldisc_ops { 2321da177e4SLinus Torvalds char *name; 2331da177e4SLinus Torvalds int num; 2341da177e4SLinus Torvalds 2351da177e4SLinus Torvalds /* 2361da177e4SLinus Torvalds * The following routines are called from above. 2371da177e4SLinus Torvalds */ 2380c6119f9SJiri Slaby int (*open)(struct tty_struct *tty); 2390c6119f9SJiri Slaby void (*close)(struct tty_struct *tty); 2401da177e4SLinus Torvalds void (*flush_buffer)(struct tty_struct *tty); 241*49b8220cSJiri Slaby (SUSE) ssize_t (*read)(struct tty_struct *tty, struct file *file, u8 *buf, 242*49b8220cSJiri Slaby (SUSE) size_t nr, void **cookie, unsigned long offset); 2431da177e4SLinus Torvalds ssize_t (*write)(struct tty_struct *tty, struct file *file, 244*49b8220cSJiri Slaby (SUSE) const u8 *buf, size_t nr); 245d78328bcSJiri Slaby int (*ioctl)(struct tty_struct *tty, unsigned int cmd, 246d78328bcSJiri Slaby unsigned long arg); 247d78328bcSJiri Slaby int (*compat_ioctl)(struct tty_struct *tty, unsigned int cmd, 248d78328bcSJiri Slaby unsigned long arg); 2498b7d2d95SIlpo Järvinen void (*set_termios)(struct tty_struct *tty, const struct ktermios *old); 2500c6119f9SJiri Slaby __poll_t (*poll)(struct tty_struct *tty, struct file *file, 2510c6119f9SJiri Slaby struct poll_table_struct *wait); 25228f194daSJiri Slaby void (*hangup)(struct tty_struct *tty); 2531da177e4SLinus Torvalds 2541da177e4SLinus Torvalds /* 2551da177e4SLinus Torvalds * The following routines are called from below. 2561da177e4SLinus Torvalds */ 257a8d9cd23SJiri Slaby (SUSE) void (*receive_buf)(struct tty_struct *tty, const u8 *cp, 258892bc209SJiri Slaby (SUSE) const u8 *fp, size_t count); 2590c6119f9SJiri Slaby void (*write_wakeup)(struct tty_struct *tty); 2600388a152SIlpo Järvinen void (*dcd_change)(struct tty_struct *tty, bool active); 261a8d9cd23SJiri Slaby (SUSE) size_t (*receive_buf2)(struct tty_struct *tty, const u8 *cp, 262892bc209SJiri Slaby (SUSE) const u8 *fp, size_t count); 263a8d9cd23SJiri Slaby (SUSE) void (*lookahead_buf)(struct tty_struct *tty, const u8 *cp, 264892bc209SJiri Slaby (SUSE) const u8 *fp, size_t count); 2651da177e4SLinus Torvalds 2661da177e4SLinus Torvalds struct module *owner; 2671da177e4SLinus Torvalds }; 2681da177e4SLinus Torvalds 269a352def2SAlan Cox struct tty_ldisc { 270a352def2SAlan Cox struct tty_ldisc_ops *ops; 27136697529SPeter Hurley struct tty_struct *tty; 272a352def2SAlan Cox }; 273a352def2SAlan Cox 2741da177e4SLinus Torvalds #define MODULE_ALIAS_LDISC(ldisc) \ 2751da177e4SLinus Torvalds MODULE_ALIAS("tty-ldisc-" __stringify(ldisc)) 2761da177e4SLinus Torvalds 277a24bc667SJiri Slaby extern const struct seq_operations tty_ldiscs_seq_ops; 278a24bc667SJiri Slaby 279a24bc667SJiri Slaby struct tty_ldisc *tty_ldisc_ref(struct tty_struct *); 280a24bc667SJiri Slaby void tty_ldisc_deref(struct tty_ldisc *); 281a24bc667SJiri Slaby struct tty_ldisc *tty_ldisc_ref_wait(struct tty_struct *); 282a24bc667SJiri Slaby 283a24bc667SJiri Slaby void tty_ldisc_flush(struct tty_struct *tty); 284a24bc667SJiri Slaby 285a24bc667SJiri Slaby int tty_register_ldisc(struct tty_ldisc_ops *new_ldisc); 286a24bc667SJiri Slaby void tty_unregister_ldisc(struct tty_ldisc_ops *ldisc); 287a24bc667SJiri Slaby int tty_set_ldisc(struct tty_struct *tty, int disc); 288a24bc667SJiri Slaby 2891da177e4SLinus Torvalds #endif /* _LINUX_TTY_LDISC_H */ 290