tty_ldisc.h

  1/* SPDX-License-Identifier: GPL-2.0 */
  2#ifndef _LINUX_TTY_LDISC_H
  3#define _LINUX_TTY_LDISC_H
  4
  5struct tty_struct;
  6
  7#include <linux/fs.h>
  8#include <linux/wait.h>
  9#include <linux/atomic.h>
 10#include <linux/list.h>
 11#include <linux/lockdep.h>
 12#include <linux/seq_file.h>
 13
 14/*
 15 * the semaphore definition
 16 */
 17struct ld_semaphore {
 18	atomic_long_t		count;
 19	raw_spinlock_t		wait_lock;
 20	unsigned int		wait_readers;
 21	struct list_head	read_wait;
 22	struct list_head	write_wait;
 23#ifdef CONFIG_DEBUG_LOCK_ALLOC
 24	struct lockdep_map	dep_map;
 25#endif
 26};
 27
 28void __init_ldsem(struct ld_semaphore *sem, const char *name,
 29			 struct lock_class_key *key);
 30
 31#define init_ldsem(sem)						\
 32do {								\
 33	static struct lock_class_key __key;			\
 34								\
 35	__init_ldsem((sem), #sem, &__key);			\
 36} while (0)
 37
 38
 39int ldsem_down_read(struct ld_semaphore *sem, long timeout);
 40int ldsem_down_read_trylock(struct ld_semaphore *sem);
 41int ldsem_down_write(struct ld_semaphore *sem, long timeout);
 42void ldsem_up_read(struct ld_semaphore *sem);
 43void ldsem_up_write(struct ld_semaphore *sem);
 44
 45#ifdef CONFIG_DEBUG_LOCK_ALLOC
 46int ldsem_down_read_nested(struct ld_semaphore *sem, int subclass,
 47		long timeout);
 48int ldsem_down_write_nested(struct ld_semaphore *sem, int subclass,
 49		long timeout);
 50#else
 51# define ldsem_down_read_nested(sem, subclass, timeout)		\
 52		ldsem_down_read(sem, timeout)
 53# define ldsem_down_write_nested(sem, subclass, timeout)	\
 54		ldsem_down_write(sem, timeout)
 55#endif
 56
 57/**
 58 * struct tty_ldisc_ops - ldisc operations
 59 *
 60 * @name: name of this ldisc rendered in /proc/tty/ldiscs
 61 * @num: ``N_*`` number (%N_TTY, %N_HDLC, ...) reserved to this ldisc
 62 *
 63 * @open: [TTY] ``int ()(struct tty_struct *tty)``
 64 *
 65 *	This function is called when the line discipline is associated with the
 66 *	@tty. No other call into the line discipline for this tty will occur
 67 *	until it completes successfully. It should initialize any state needed
 68 *	by the ldisc, and set @tty->receive_room to the maximum amount of data
 69 *	the line discipline is willing to accept from the driver with a single
 70 *	call to @receive_buf(). Returning an error will prevent the ldisc from
 71 *	being attached.
 72 *
 73 *	Optional. Can sleep.
 74 *
 75 * @close: [TTY] ``void ()(struct tty_struct *tty)``
 76 *
 77 *	This function is called when the line discipline is being shutdown,
 78 *	either because the @tty is being closed or because the @tty is being
 79 *	changed to use a new line discipline. At the point of execution no
 80 *	further users will enter the ldisc code for this tty.
 81 *
 82 *	Optional. Can sleep.
 83 *
 84 * @flush_buffer: [TTY] ``void ()(struct tty_struct *tty)``
 85 *
 86 *	This function instructs the line discipline to clear its buffers of any
 87 *	input characters it may have queued to be delivered to the user mode
 88 *	process. It may be called at any point between open and close.
 89 *
 90 *	Optional.
 91 *
 92 * @read: [TTY] ``ssize_t ()(struct tty_struct *tty, struct file *file, u8 *buf,
 93 *		size_t nr)``
 94 *
 95 *	This function is called when the user requests to read from the @tty.
 96 *	The line discipline will return whatever characters it has buffered up
 97 *	for the user. If this function is not defined, the user will receive
 98 *	an %EIO error. Multiple read calls may occur in parallel and the ldisc
 99 *	must deal with serialization issues.
100 *
101 *	Optional: %EIO unless provided. Can sleep.
102 *
103 * @write: [TTY] ``ssize_t ()(struct tty_struct *tty, struct file *file,
104 *		 const u8 *buf, size_t nr)``
105 *
106 *	This function is called when the user requests to write to the @tty.
107 *	The line discipline will deliver the characters to the low-level tty
108 *	device for transmission, optionally performing some processing on the
109 *	characters first. If this function is not defined, the user will
110 *	receive an %EIO error.
111 *
112 *	Optional: %EIO unless provided. Can sleep.
113 *
114 * @ioctl: [TTY] ``int ()(struct tty_struct *tty, unsigned int cmd,
115 *		unsigned long arg)``
116 *
117 *	This function is called when the user requests an ioctl which is not
118 *	handled by the tty layer or the low-level tty driver. It is intended
119 *	for ioctls which affect line discpline operation.  Note that the search
120 *	order for ioctls is (1) tty layer, (2) tty low-level driver, (3) line
121 *	discpline. So a low-level driver can "grab" an ioctl request before
122 *	the line discpline has a chance to see it.
123 *
124 *	Optional.
125 *
126 * @compat_ioctl: [TTY] ``int ()(struct tty_struct *tty, unsigned int cmd,
127 *		unsigned long arg)``
128 *
129 *	Process ioctl calls from 32-bit process on 64-bit system.
130 *
131 *	Note that only ioctls that are neither "pointer to compatible
132 *	structure" nor tty-generic.  Something private that takes an integer or
133 *	a pointer to wordsize-sensitive structure belongs here, but most of
134 *	ldiscs will happily leave it %NULL.
135 *
136 *	Optional.
137 *
138 * @set_termios: [TTY] ``void ()(struct tty_struct *tty, const struct ktermios *old)``
139 *
140 *	This function notifies the line discpline that a change has been made
141 *	to the termios structure.
142 *
143 *	Optional.
144 *
145 * @poll: [TTY] ``int ()(struct tty_struct *tty, struct file *file,
146 *		  struct poll_table_struct *wait)``
147 *
148 *	This function is called when a user attempts to select/poll on a @tty
149 *	device. It is solely the responsibility of the line discipline to
150 *	handle poll requests.
151 *
152 *	Optional.
153 *
154 * @hangup: [TTY] ``void ()(struct tty_struct *tty)``
155 *
156 *	Called on a hangup. Tells the discipline that it should cease I/O to
157 *	the tty driver. The driver should seek to perform this action quickly
158 *	but should wait until any pending driver I/O is completed. No further
159 *	calls into the ldisc code will occur.
160 *
161 *	Optional. Can sleep.
162 *
163 * @receive_buf: [DRV] ``void ()(struct tty_struct *tty, const u8 *cp,
164 *		       const u8 *fp, size_t count)``
165 *
166 *	This function is called by the low-level tty driver to send characters
167 *	received by the hardware to the line discpline for processing. @cp is
168 *	a pointer to the buffer of input character received by the device. @fp
169 *	is a pointer to an array of flag bytes which indicate whether a
170 *	character was received with a parity error, etc. @fp may be %NULL to
171 *	indicate all data received is %TTY_NORMAL.
172 *
173 *	Optional.
174 *
175 * @write_wakeup: [DRV] ``void ()(struct tty_struct *tty)``
176 *
177 *	This function is called by the low-level tty driver to signal that line
178 *	discpline should try to send more characters to the low-level driver
179 *	for transmission. If the line discpline does not have any more data to
180 *	send, it can just return. If the line discipline does have some data to
181 *	send, please arise a tasklet or workqueue to do the real data transfer.
182 *	Do not send data in this hook, it may lead to a deadlock.
183 *
184 *	Optional.
185 *
186 * @dcd_change: [DRV] ``void ()(struct tty_struct *tty, bool active)``
187 *
188 *	Tells the discipline that the DCD pin has changed its status. Used
189 *	exclusively by the %N_PPS (Pulse-Per-Second) line discipline.
190 *
191 *	Optional.
192 *
193 * @receive_buf2: [DRV] ``ssize_t ()(struct tty_struct *tty, const u8 *cp,
194 *			const u8 *fp, size_t count)``
195 *
196 *	This function is called by the low-level tty driver to send characters
197 *	received by the hardware to the line discpline for processing. @cp is a
198 *	pointer to the buffer of input character received by the device.  @fp
199 *	is a pointer to an array of flag bytes which indicate whether a
200 *	character was received with a parity error, etc. @fp may be %NULL to
201 *	indicate all data received is %TTY_NORMAL. If assigned, prefer this
202 *	function for automatic flow control.
203 *
204 *	Optional.
205 *
206 * @lookahead_buf: [DRV] ``void ()(struct tty_struct *tty, const u8 *cp,
207 *			 const u8 *fp, size_t count)``
208 *
209 *	This function is called by the low-level tty driver for characters
210 *	not eaten by ->receive_buf() or ->receive_buf2(). It is useful for
211 *	processing high-priority characters such as software flow-control
212 *	characters that could otherwise get stuck into the intermediate
213 *	buffer until tty has room to receive them. Ldisc must be able to
214 *	handle later a ->receive_buf() or ->receive_buf2() call for the
215 *	same characters (e.g. by skipping the actions for high-priority
216 *	characters already handled by ->lookahead_buf()).
217 *
218 *	Optional.
219 *
220 * @owner: module containting this ldisc (for reference counting)
221 *
222 * This structure defines the interface between the tty line discipline
223 * implementation and the tty routines. The above routines can be defined.
224 * Unless noted otherwise, they are optional, and can be filled in with a %NULL
225 * pointer.
226 *
227 * Hooks marked [TTY] are invoked from the TTY core, the [DRV] ones from the
228 * tty_driver side.
229 */
230struct tty_ldisc_ops {
231	char	*name;
232	int	num;
233
234	/*
235	 * The following routines are called from above.
236	 */
237	int	(*open)(struct tty_struct *tty);
238	void	(*close)(struct tty_struct *tty);
239	void	(*flush_buffer)(struct tty_struct *tty);
240	ssize_t	(*read)(struct tty_struct *tty, struct file *file, u8 *buf,
241			size_t nr, void **cookie, unsigned long offset);
242	ssize_t	(*write)(struct tty_struct *tty, struct file *file,
243			 const u8 *buf, size_t nr);
244	int	(*ioctl)(struct tty_struct *tty, unsigned int cmd,
245			unsigned long arg);
246	int	(*compat_ioctl)(struct tty_struct *tty, unsigned int cmd,
247			unsigned long arg);
248	void	(*set_termios)(struct tty_struct *tty, const struct ktermios *old);
249	__poll_t (*poll)(struct tty_struct *tty, struct file *file,
250			     struct poll_table_struct *wait);
251	void	(*hangup)(struct tty_struct *tty);
252
253	/*
254	 * The following routines are called from below.
255	 */
256	void	(*receive_buf)(struct tty_struct *tty, const u8 *cp,
257			       const u8 *fp, size_t count);
258	void	(*write_wakeup)(struct tty_struct *tty);
259	void	(*dcd_change)(struct tty_struct *tty, bool active);
260	size_t	(*receive_buf2)(struct tty_struct *tty, const u8 *cp,
261				const u8 *fp, size_t count);
262	void	(*lookahead_buf)(struct tty_struct *tty, const u8 *cp,
263				 const u8 *fp, size_t count);
264
265	struct  module *owner;
266};
267
268struct tty_ldisc {
269	struct tty_ldisc_ops *ops;
270	struct tty_struct *tty;
271};
272
273#define MODULE_ALIAS_LDISC(ldisc) \
274	MODULE_ALIAS("tty-ldisc-" __stringify(ldisc))
275
276extern const struct seq_operations tty_ldiscs_seq_ops;
277
278struct tty_ldisc *tty_ldisc_ref(struct tty_struct *);
279void tty_ldisc_deref(struct tty_ldisc *);
280struct tty_ldisc *tty_ldisc_ref_wait(struct tty_struct *);
281
282void tty_ldisc_flush(struct tty_struct *tty);
283
284int tty_register_ldisc(struct tty_ldisc_ops *new_ldisc);
285void tty_unregister_ldisc(struct tty_ldisc_ops *ldisc);
286int tty_set_ldisc(struct tty_struct *tty, int disc);
287
288#endif /* _LINUX_TTY_LDISC_H */