1 /* SPDX-License-Identifier: GPL-2.0 */ 2 #ifndef _LINUX_TTY_DRIVER_H 3 #define _LINUX_TTY_DRIVER_H 4 5 #include <linux/export.h> 6 #include <linux/fs.h> 7 #include <linux/kref.h> 8 #include <linux/list.h> 9 #include <linux/cdev.h> 10 #include <linux/termios.h> 11 #include <linux/seq_file.h> 12 13 struct tty_struct; 14 struct tty_driver; 15 struct serial_icounter_struct; 16 struct serial_struct; 17 18 /** 19 * struct tty_operations -- interface between driver and tty 20 * 21 * @lookup: ``struct tty_struct *()(struct tty_driver *self, struct file *, 22 * int idx)`` 23 * 24 * Return the tty device corresponding to @idx, %NULL if there is not 25 * one currently in use and an %ERR_PTR value on error. Called under 26 * %tty_mutex (for now!) 27 * 28 * Optional method. Default behaviour is to use the @self->ttys array. 29 * 30 * @install: ``int ()(struct tty_driver *self, struct tty_struct *tty)`` 31 * 32 * Install a new @tty into the @self's internal tables. Used in 33 * conjunction with @lookup and @remove methods. 34 * 35 * Optional method. Default behaviour is to use the @self->ttys array. 36 * 37 * @remove: ``void ()(struct tty_driver *self, struct tty_struct *tty)`` 38 * 39 * Remove a closed @tty from the @self's internal tables. Used in 40 * conjunction with @lookup and @remove methods. 41 * 42 * Optional method. Default behaviour is to use the @self->ttys array. 43 * 44 * @open: ``int ()(struct tty_struct *tty, struct file *)`` 45 * 46 * This routine is called when a particular @tty device is opened. This 47 * routine is mandatory; if this routine is not filled in, the attempted 48 * open will fail with %ENODEV. 49 * 50 * Required method. Called with tty lock held. 51 * 52 * @close: ``void ()(struct tty_struct *tty, struct file *)`` 53 * 54 * This routine is called when a particular @tty device is closed. 55 * 56 * Remark: called even if the corresponding @open() failed. 57 * 58 * Required method. Called with tty lock held. 59 * 60 * @shutdown: ``void ()(struct tty_struct *tty)`` 61 * 62 * This routine is called under the tty lock when a particular @tty device 63 * is closed for the last time. It executes before the @tty resources 64 * are freed so may execute while another function holds a @tty kref. 65 * 66 * @cleanup: ``void ()(struct tty_struct *tty)`` 67 * 68 * This routine is called asynchronously when a particular @tty device 69 * is closed for the last time freeing up the resources. This is 70 * actually the second part of shutdown for routines that might sleep. 71 * 72 * @write: ``int ()(struct tty_struct *tty, const unsigned char *buf, 73 * int count)`` 74 * 75 * This routine is called by the kernel to write a series (@count) of 76 * characters (@buf) to the @tty device. The characters may come from 77 * user space or kernel space. This routine will return the 78 * number of characters actually accepted for writing. 79 * 80 * Optional: Required for writable devices. 81 * 82 * @put_char: ``int ()(struct tty_struct *tty, unsigned char ch)`` 83 * 84 * This routine is called by the kernel to write a single character @ch to 85 * the @tty device. If the kernel uses this routine, it must call the 86 * @flush_chars() routine (if defined) when it is done stuffing characters 87 * into the driver. If there is no room in the queue, the character is 88 * ignored. 89 * 90 * Optional: Kernel will use the @write method if not provided. Do not 91 * call this function directly, call tty_put_char(). 92 * 93 * @flush_chars: ``void ()(struct tty_struct *tty)`` 94 * 95 * This routine is called by the kernel after it has written a 96 * series of characters to the tty device using @put_char(). 97 * 98 * Optional. Do not call this function directly, call 99 * tty_driver_flush_chars(). 100 * 101 * @write_room: ``unsigned int ()(struct tty_struct *tty)`` 102 * 103 * This routine returns the numbers of characters the @tty driver 104 * will accept for queuing to be written. This number is subject 105 * to change as output buffers get emptied, or if the output flow 106 * control is acted. 107 * 108 * Required if @write method is provided else not needed. Do not call this 109 * function directly, call tty_write_room() 110 * 111 * @chars_in_buffer: ``unsigned int ()(struct tty_struct *tty)`` 112 * 113 * This routine returns the number of characters in the device private 114 * output queue. Used in tty_wait_until_sent() and for poll() 115 * implementation. 116 * 117 * Optional: if not provided, it is assumed there is no queue on the 118 * device. Do not call this function directly, call tty_chars_in_buffer(). 119 * 120 * @ioctl: ``int ()(struct tty_struct *tty, unsigned int cmd, 121 * unsigned long arg)`` 122 * 123 * This routine allows the @tty driver to implement device-specific 124 * ioctls. If the ioctl number passed in @cmd is not recognized by the 125 * driver, it should return %ENOIOCTLCMD. 126 * 127 * Optional. 128 * 129 * @compat_ioctl: ``long ()(struct tty_struct *tty, unsigned int cmd, 130 * unsigned long arg)`` 131 * 132 * Implement ioctl processing for 32 bit process on 64 bit system. 133 * 134 * Optional. 135 * 136 * @set_termios: ``void ()(struct tty_struct *tty, struct ktermios *old)`` 137 * 138 * This routine allows the @tty driver to be notified when device's 139 * termios settings have changed. 140 * 141 * Optional: Called under the @tty->termios_rwsem. 142 * 143 * @set_ldisc: ``void ()(struct tty_struct *tty)`` 144 * 145 * This routine allows the @tty driver to be notified when the device's 146 * line discipline is being changed. 147 * 148 * Optional. Called under the @tty->ldisc_sem and @tty->termios_rwsem. 149 * 150 * @throttle: ``void ()(struct tty_struct *tty)`` 151 * 152 * This routine notifies the @tty driver that input buffers for the line 153 * discipline are close to full, and it should somehow signal that no more 154 * characters should be sent to the @tty. 155 * 156 * Optional: Always invoke via tty_throttle_safe(). Called under the 157 * @tty->termios_rwsem. 158 * 159 * @unthrottle: ``void ()(struct tty_struct *tty)`` 160 * 161 * This routine notifies the @tty driver that it should signal that 162 * characters can now be sent to the @tty without fear of overrunning the 163 * input buffers of the line disciplines. 164 * 165 * Optional. Always invoke via tty_unthrottle(). Called under the 166 * @tty->termios_rwsem. 167 * 168 * @stop: ``void ()(struct tty_struct *tty)`` 169 * 170 * This routine notifies the @tty driver that it should stop outputting 171 * characters to the tty device. 172 * 173 * Called with @tty->flow.lock held. Serialized with @start() method. 174 * 175 * Optional. Always invoke via stop_tty(). 176 * 177 * @start: ``void ()(struct tty_struct *tty)`` 178 * 179 * This routine notifies the @tty driver that it resumed sending 180 * characters to the @tty device. 181 * 182 * Called with @tty->flow.lock held. Serialized with stop() method. 183 * 184 * Optional. Always invoke via start_tty(). 185 * 186 * @hangup: ``void ()(struct tty_struct *tty)`` 187 * 188 * This routine notifies the @tty driver that it should hang up the @tty 189 * device. 190 * 191 * Optional. Called with tty lock held. 192 * 193 * @break_ctl: ``int ()(struct tty_struct *tty, int state)`` 194 * 195 * This optional routine requests the @tty driver to turn on or off BREAK 196 * status on the RS-232 port. If @state is -1, then the BREAK status 197 * should be turned on; if @state is 0, then BREAK should be turned off. 198 * 199 * If this routine is implemented, the high-level tty driver will handle 200 * the following ioctls: %TCSBRK, %TCSBRKP, %TIOCSBRK, %TIOCCBRK. 201 * 202 * If the driver sets %TTY_DRIVER_HARDWARE_BREAK in tty_alloc_driver(), 203 * then the interface will also be called with actual times and the 204 * hardware is expected to do the delay work itself. 0 and -1 are still 205 * used for on/off. 206 * 207 * Optional: Required for %TCSBRK/%BRKP/etc. handling. 208 * 209 * @flush_buffer: ``void ()(struct tty_struct *tty)`` 210 * 211 * This routine discards device private output buffer. Invoked on close, 212 * hangup, to implement %TCOFLUSH ioctl and similar. 213 * 214 * Optional: if not provided, it is assumed there is no queue on the 215 * device. Do not call this function directly, call 216 * tty_driver_flush_buffer(). 217 * 218 * @wait_until_sent: ``void ()(struct tty_struct *tty, int timeout)`` 219 * 220 * This routine waits until the device has written out all of the 221 * characters in its transmitter FIFO. Or until @timeout (in jiffies) is 222 * reached. 223 * 224 * Optional: If not provided, the device is assumed to have no FIFO. 225 * Usually correct to invoke via tty_wait_until_sent(). 226 * 227 * @send_xchar: ``void ()(struct tty_struct *tty, char ch)`` 228 * 229 * This routine is used to send a high-priority XON/XOFF character (@ch) 230 * to the @tty device. 231 * 232 * Optional: If not provided, then the @write method is called under 233 * the @tty->atomic_write_lock to keep it serialized with the ldisc. 234 * 235 * @tiocmget: ``int ()(struct tty_struct *tty)`` 236 * 237 * This routine is used to obtain the modem status bits from the @tty 238 * driver. 239 * 240 * Optional: If not provided, then %ENOTTY is returned from the %TIOCMGET 241 * ioctl. Do not call this function directly, call tty_tiocmget(). 242 * 243 * @tiocmset: ``int ()(struct tty_struct *tty, 244 * unsigned int set, unsigned int clear)`` 245 * 246 * This routine is used to set the modem status bits to the @tty driver. 247 * First, @clear bits should be cleared, then @set bits set. 248 * 249 * Optional: If not provided, then %ENOTTY is returned from the %TIOCMSET 250 * ioctl. Do not call this function directly, call tty_tiocmset(). 251 * 252 * @resize: ``int ()(struct tty_struct *tty, struct winsize *ws)`` 253 * 254 * Called when a termios request is issued which changes the requested 255 * terminal geometry to @ws. 256 * 257 * Optional: the default action is to update the termios structure 258 * without error. This is usually the correct behaviour. Drivers should 259 * not force errors here if they are not resizable objects (e.g. a serial 260 * line). See tty_do_resize() if you need to wrap the standard method 261 * in your own logic -- the usual case. 262 * 263 * @get_icount: ``int ()(struct tty_struct *tty, 264 * struct serial_icounter *icount)`` 265 * 266 * Called when the @tty device receives a %TIOCGICOUNT ioctl. Passed a 267 * kernel structure @icount to complete. 268 * 269 * Optional: called only if provided, otherwise %ENOTTY will be returned. 270 * 271 * @get_serial: ``int ()(struct tty_struct *tty, struct serial_struct *p)`` 272 * 273 * Called when the @tty device receives a %TIOCGSERIAL ioctl. Passed a 274 * kernel structure @p (&struct serial_struct) to complete. 275 * 276 * Optional: called only if provided, otherwise %ENOTTY will be returned. 277 * Do not call this function directly, call tty_tiocgserial(). 278 * 279 * @set_serial: ``int ()(struct tty_struct *tty, struct serial_struct *p)`` 280 * 281 * Called when the @tty device receives a %TIOCSSERIAL ioctl. Passed a 282 * kernel structure @p (&struct serial_struct) to set the values from. 283 * 284 * Optional: called only if provided, otherwise %ENOTTY will be returned. 285 * Do not call this function directly, call tty_tiocsserial(). 286 * 287 * @show_fdinfo: ``void ()(struct tty_struct *tty, struct seq_file *m)`` 288 * 289 * Called when the @tty device file descriptor receives a fdinfo request 290 * from VFS (to show in /proc/<pid>/fdinfo/). @m should be filled with 291 * information. 292 * 293 * Optional: called only if provided, otherwise nothing is written to @m. 294 * Do not call this function directly, call tty_show_fdinfo(). 295 * 296 * @poll_init: ``int ()(struct tty_driver *driver, int line, char *options)`` 297 * 298 * kgdboc support (Documentation/dev-tools/kgdb.rst). This routine is 299 * called to initialize the HW for later use by calling @poll_get_char or 300 * @poll_put_char. 301 * 302 * Optional: called only if provided, otherwise skipped as a non-polling 303 * driver. 304 * 305 * @poll_get_char: ``int ()(struct tty_driver *driver, int line)`` 306 * 307 * kgdboc support (see @poll_init). @driver should read a character from a 308 * tty identified by @line and return it. 309 * 310 * Optional: called only if @poll_init provided. 311 * 312 * @poll_put_char: ``void ()(struct tty_driver *driver, int line, char ch)`` 313 * 314 * kgdboc support (see @poll_init). @driver should write character @ch to 315 * a tty identified by @line. 316 * 317 * Optional: called only if @poll_init provided. 318 * 319 * @proc_show: ``int ()(struct seq_file *m, void *driver)`` 320 * 321 * Driver @driver (cast to &struct tty_driver) can show additional info in 322 * /proc/tty/driver/<driver_name>. It is enough to fill in the information 323 * into @m. 324 * 325 * Optional: called only if provided, otherwise no /proc entry created. 326 * 327 * This structure defines the interface between the low-level tty driver and 328 * the tty routines. These routines can be defined. Unless noted otherwise, 329 * they are optional, and can be filled in with a %NULL pointer. 330 */ 331 struct tty_operations { 332 struct tty_struct * (*lookup)(struct tty_driver *driver, 333 struct file *filp, int idx); 334 int (*install)(struct tty_driver *driver, struct tty_struct *tty); 335 void (*remove)(struct tty_driver *driver, struct tty_struct *tty); 336 int (*open)(struct tty_struct * tty, struct file * filp); 337 void (*close)(struct tty_struct * tty, struct file * filp); 338 void (*shutdown)(struct tty_struct *tty); 339 void (*cleanup)(struct tty_struct *tty); 340 int (*write)(struct tty_struct * tty, 341 const unsigned char *buf, int count); 342 int (*put_char)(struct tty_struct *tty, unsigned char ch); 343 void (*flush_chars)(struct tty_struct *tty); 344 unsigned int (*write_room)(struct tty_struct *tty); 345 unsigned int (*chars_in_buffer)(struct tty_struct *tty); 346 int (*ioctl)(struct tty_struct *tty, 347 unsigned int cmd, unsigned long arg); 348 long (*compat_ioctl)(struct tty_struct *tty, 349 unsigned int cmd, unsigned long arg); 350 void (*set_termios)(struct tty_struct *tty, struct ktermios * old); 351 void (*throttle)(struct tty_struct * tty); 352 void (*unthrottle)(struct tty_struct * tty); 353 void (*stop)(struct tty_struct *tty); 354 void (*start)(struct tty_struct *tty); 355 void (*hangup)(struct tty_struct *tty); 356 int (*break_ctl)(struct tty_struct *tty, int state); 357 void (*flush_buffer)(struct tty_struct *tty); 358 void (*set_ldisc)(struct tty_struct *tty); 359 void (*wait_until_sent)(struct tty_struct *tty, int timeout); 360 void (*send_xchar)(struct tty_struct *tty, char ch); 361 int (*tiocmget)(struct tty_struct *tty); 362 int (*tiocmset)(struct tty_struct *tty, 363 unsigned int set, unsigned int clear); 364 int (*resize)(struct tty_struct *tty, struct winsize *ws); 365 int (*get_icount)(struct tty_struct *tty, 366 struct serial_icounter_struct *icount); 367 int (*get_serial)(struct tty_struct *tty, struct serial_struct *p); 368 int (*set_serial)(struct tty_struct *tty, struct serial_struct *p); 369 void (*show_fdinfo)(struct tty_struct *tty, struct seq_file *m); 370 #ifdef CONFIG_CONSOLE_POLL 371 int (*poll_init)(struct tty_driver *driver, int line, char *options); 372 int (*poll_get_char)(struct tty_driver *driver, int line); 373 void (*poll_put_char)(struct tty_driver *driver, int line, char ch); 374 #endif 375 int (*proc_show)(struct seq_file *m, void *driver); 376 } __randomize_layout; 377 378 /** 379 * struct tty_driver -- driver for TTY devices 380 * 381 * @magic: set to %TTY_DRIVER_MAGIC in __tty_alloc_driver() 382 * @kref: reference counting. Reaching zero frees all the internals and the 383 * driver. 384 * @cdevs: allocated/registered character /dev devices 385 * @owner: modules owning this driver. Used drivers cannot be rmmod'ed. 386 * Automatically set by tty_alloc_driver(). 387 * @driver_name: name of the driver used in /proc/tty 388 * @name: used for constructing /dev node name 389 * @name_base: used as a number base for constructing /dev node name 390 * @major: major /dev device number (zero for autoassignment) 391 * @minor_start: the first minor /dev device number 392 * @num: number of devices allocated 393 * @type: type of tty driver (%TTY_DRIVER_TYPE_) 394 * @subtype: subtype of tty driver (%SYSTEM_TYPE_, %PTY_TYPE_, %SERIAL_TYPE_) 395 * @init_termios: termios to set to each tty initially (e.g. %tty_std_termios) 396 * @flags: tty driver flags (%TTY_DRIVER_) 397 * @proc_entry: proc fs entry, used internally 398 * @other: driver of the linked tty; only used for the PTY driver 399 * @ttys: array of active &struct tty_struct, set by tty_standard_install() 400 * @ports: array of &struct tty_port; can be set during initialization by 401 * tty_port_link_device() and similar 402 * @termios: storage for termios at each TTY close for the next open 403 * @driver_state: pointer to driver's arbitrary data 404 * @ops: driver hooks for TTYs. Set them using tty_set_operations(). Use &struct 405 * tty_port helpers in them as much as possible. 406 * @tty_drivers: used internally to link tty_drivers together 407 * 408 * The usual handling of &struct tty_driver is to allocate it by 409 * tty_alloc_driver(), set up all the necessary members, and register it by 410 * tty_register_driver(). At last, the driver is torn down by calling 411 * tty_unregister_driver() followed by tty_driver_kref_put(). 412 * 413 * The fields required to be set before calling tty_register_driver() include 414 * @driver_name, @name, @type, @subtype, @init_termios, and @ops. 415 */ 416 struct tty_driver { 417 int magic; 418 struct kref kref; 419 struct cdev **cdevs; 420 struct module *owner; 421 const char *driver_name; 422 const char *name; 423 int name_base; 424 int major; 425 int minor_start; 426 unsigned int num; 427 short type; 428 short subtype; 429 struct ktermios init_termios; 430 unsigned long flags; 431 struct proc_dir_entry *proc_entry; 432 struct tty_driver *other; 433 434 /* 435 * Pointer to the tty data structures 436 */ 437 struct tty_struct **ttys; 438 struct tty_port **ports; 439 struct ktermios **termios; 440 void *driver_state; 441 442 /* 443 * Driver methods 444 */ 445 446 const struct tty_operations *ops; 447 struct list_head tty_drivers; 448 } __randomize_layout; 449 450 extern struct list_head tty_drivers; 451 452 struct tty_driver *__tty_alloc_driver(unsigned int lines, struct module *owner, 453 unsigned long flags); 454 struct tty_driver *tty_find_polling_driver(char *name, int *line); 455 456 void tty_driver_kref_put(struct tty_driver *driver); 457 458 /* Use TTY_DRIVER_* flags below */ 459 #define tty_alloc_driver(lines, flags) \ 460 __tty_alloc_driver(lines, THIS_MODULE, flags) 461 462 static inline struct tty_driver *tty_driver_kref_get(struct tty_driver *d) 463 { 464 kref_get(&d->kref); 465 return d; 466 } 467 468 static inline void tty_set_operations(struct tty_driver *driver, 469 const struct tty_operations *op) 470 { 471 driver->ops = op; 472 } 473 474 /* tty driver magic number */ 475 #define TTY_DRIVER_MAGIC 0x5402 476 477 /* 478 * tty driver flags 479 * 480 * TTY_DRIVER_RESET_TERMIOS --- requests the tty layer to reset the 481 * termios setting when the last process has closed the device. 482 * Used for PTY's, in particular. 483 * 484 * TTY_DRIVER_REAL_RAW --- if set, indicates that the driver will 485 * guarantee never to set any special character handling 486 * flags if ((IGNBRK || (!BRKINT && !PARMRK)) && (IGNPAR || 487 * !INPCK)). That is, if there is no reason for the driver to 488 * send notifications of parity and break characters up to the 489 * line driver, it won't do so. This allows the line driver to 490 * optimize for this case if this flag is set. (Note that there 491 * is also a promise, if the above case is true, not to signal 492 * overruns, either.) 493 * 494 * TTY_DRIVER_DYNAMIC_DEV --- if set, the individual tty devices need 495 * to be registered with a call to tty_register_device() when the 496 * device is found in the system and unregistered with a call to 497 * tty_unregister_device() so the devices will be show up 498 * properly in sysfs. If not set, driver->num entries will be 499 * created by the tty core in sysfs when tty_register_driver() is 500 * called. This is to be used by drivers that have tty devices 501 * that can appear and disappear while the main tty driver is 502 * registered with the tty core. 503 * 504 * TTY_DRIVER_DEVPTS_MEM -- don't use the standard arrays, instead 505 * use dynamic memory keyed through the devpts filesystem. This 506 * is only applicable to the pty driver. 507 * 508 * TTY_DRIVER_HARDWARE_BREAK -- hardware handles break signals. Pass 509 * the requested timeout to the caller instead of using a simple 510 * on/off interface. 511 * 512 * TTY_DRIVER_DYNAMIC_ALLOC -- do not allocate structures which are 513 * needed per line for this driver as it would waste memory. 514 * The driver will take care. 515 * 516 * TTY_DRIVER_UNNUMBERED_NODE -- do not create numbered /dev nodes. In 517 * other words create /dev/ttyprintk and not /dev/ttyprintk0. 518 * Applicable only when a driver for a single tty device is 519 * being allocated. 520 */ 521 #define TTY_DRIVER_INSTALLED 0x0001 522 #define TTY_DRIVER_RESET_TERMIOS 0x0002 523 #define TTY_DRIVER_REAL_RAW 0x0004 524 #define TTY_DRIVER_DYNAMIC_DEV 0x0008 525 #define TTY_DRIVER_DEVPTS_MEM 0x0010 526 #define TTY_DRIVER_HARDWARE_BREAK 0x0020 527 #define TTY_DRIVER_DYNAMIC_ALLOC 0x0040 528 #define TTY_DRIVER_UNNUMBERED_NODE 0x0080 529 530 /* tty driver types */ 531 #define TTY_DRIVER_TYPE_SYSTEM 0x0001 532 #define TTY_DRIVER_TYPE_CONSOLE 0x0002 533 #define TTY_DRIVER_TYPE_SERIAL 0x0003 534 #define TTY_DRIVER_TYPE_PTY 0x0004 535 #define TTY_DRIVER_TYPE_SCC 0x0005 /* scc driver */ 536 #define TTY_DRIVER_TYPE_SYSCONS 0x0006 537 538 /* system subtypes (magic, used by tty_io.c) */ 539 #define SYSTEM_TYPE_TTY 0x0001 540 #define SYSTEM_TYPE_CONSOLE 0x0002 541 #define SYSTEM_TYPE_SYSCONS 0x0003 542 #define SYSTEM_TYPE_SYSPTMX 0x0004 543 544 /* pty subtypes (magic, used by tty_io.c) */ 545 #define PTY_TYPE_MASTER 0x0001 546 #define PTY_TYPE_SLAVE 0x0002 547 548 /* serial subtype definitions */ 549 #define SERIAL_TYPE_NORMAL 1 550 551 int tty_register_driver(struct tty_driver *driver); 552 void tty_unregister_driver(struct tty_driver *driver); 553 struct device *tty_register_device(struct tty_driver *driver, unsigned index, 554 struct device *dev); 555 struct device *tty_register_device_attr(struct tty_driver *driver, 556 unsigned index, struct device *device, void *drvdata, 557 const struct attribute_group **attr_grp); 558 void tty_unregister_device(struct tty_driver *driver, unsigned index); 559 560 #ifdef CONFIG_PROC_FS 561 void proc_tty_register_driver(struct tty_driver *); 562 void proc_tty_unregister_driver(struct tty_driver *); 563 #else 564 static inline void proc_tty_register_driver(struct tty_driver *d) {} 565 static inline void proc_tty_unregister_driver(struct tty_driver *d) {} 566 #endif 567 568 #endif /* #ifdef _LINUX_TTY_DRIVER_H */ 569