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 */
289

source code of linux/include/linux/tty_ldisc.h

Morty Proxy This is a proxified and sanitized view of the page, visit original site.