tty_driver.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448
  1. /* SPDX-License-Identifier: GPL-2.0 */
  2. #ifndef _LINUX_TTY_DRIVER_H
  3. #define _LINUX_TTY_DRIVER_H
  4. /*
  5. * This structure defines the interface between the low-level tty
  6. * driver and the tty routines. The following routines can be
  7. * defined; unless noted otherwise, they are optional, and can be
  8. * filled in with a null pointer.
  9. *
  10. * struct tty_struct * (*lookup)(struct tty_driver *self, struct file *, int idx)
  11. *
  12. * Return the tty device corresponding to idx, NULL if there is not
  13. * one currently in use and an ERR_PTR value on error. Called under
  14. * tty_mutex (for now!)
  15. *
  16. * Optional method. Default behaviour is to use the ttys array
  17. *
  18. * int (*install)(struct tty_driver *self, struct tty_struct *tty)
  19. *
  20. * Install a new tty into the tty driver internal tables. Used in
  21. * conjunction with lookup and remove methods.
  22. *
  23. * Optional method. Default behaviour is to use the ttys array
  24. *
  25. * void (*remove)(struct tty_driver *self, struct tty_struct *tty)
  26. *
  27. * Remove a closed tty from the tty driver internal tables. Used in
  28. * conjunction with lookup and remove methods.
  29. *
  30. * Optional method. Default behaviour is to use the ttys array
  31. *
  32. * int (*open)(struct tty_struct * tty, struct file * filp);
  33. *
  34. * This routine is called when a particular tty device is opened.
  35. * This routine is mandatory; if this routine is not filled in,
  36. * the attempted open will fail with ENODEV.
  37. *
  38. * Required method. Called with tty lock held.
  39. *
  40. * void (*close)(struct tty_struct * tty, struct file * filp);
  41. *
  42. * This routine is called when a particular tty device is closed.
  43. * Note: called even if the corresponding open() failed.
  44. *
  45. * Required method. Called with tty lock held.
  46. *
  47. * void (*shutdown)(struct tty_struct * tty);
  48. *
  49. * This routine is called under the tty lock when a particular tty device
  50. * is closed for the last time. It executes before the tty resources
  51. * are freed so may execute while another function holds a tty kref.
  52. *
  53. * void (*cleanup)(struct tty_struct * tty);
  54. *
  55. * This routine is called asynchronously when a particular tty device
  56. * is closed for the last time freeing up the resources. This is
  57. * actually the second part of shutdown for routines that might sleep.
  58. *
  59. *
  60. * int (*write)(struct tty_struct * tty,
  61. * const unsigned char *buf, int count);
  62. *
  63. * This routine is called by the kernel to write a series of
  64. * characters to the tty device. The characters may come from
  65. * user space or kernel space. This routine will return the
  66. * number of characters actually accepted for writing.
  67. *
  68. * Optional: Required for writable devices.
  69. *
  70. * int (*put_char)(struct tty_struct *tty, unsigned char ch);
  71. *
  72. * This routine is called by the kernel to write a single
  73. * character to the tty device. If the kernel uses this routine,
  74. * it must call the flush_chars() routine (if defined) when it is
  75. * done stuffing characters into the driver. If there is no room
  76. * in the queue, the character is ignored.
  77. *
  78. * Optional: Kernel will use the write method if not provided.
  79. *
  80. * Note: Do not call this function directly, call tty_put_char
  81. *
  82. * void (*flush_chars)(struct tty_struct *tty);
  83. *
  84. * This routine is called by the kernel after it has written a
  85. * series of characters to the tty device using put_char().
  86. *
  87. * Optional:
  88. *
  89. * Note: Do not call this function directly, call tty_driver_flush_chars
  90. *
  91. * int (*write_room)(struct tty_struct *tty);
  92. *
  93. * This routine returns the numbers of characters the tty driver
  94. * will accept for queuing to be written. This number is subject
  95. * to change as output buffers get emptied, or if the output flow
  96. * control is acted.
  97. *
  98. * Required if write method is provided else not needed.
  99. *
  100. * Note: Do not call this function directly, call tty_write_room
  101. *
  102. * int (*ioctl)(struct tty_struct *tty, unsigned int cmd, unsigned long arg);
  103. *
  104. * This routine allows the tty driver to implement
  105. * device-specific ioctls. If the ioctl number passed in cmd
  106. * is not recognized by the driver, it should return ENOIOCTLCMD.
  107. *
  108. * Optional
  109. *
  110. * long (*compat_ioctl)(struct tty_struct *tty,,
  111. * unsigned int cmd, unsigned long arg);
  112. *
  113. * implement ioctl processing for 32 bit process on 64 bit system
  114. *
  115. * Optional
  116. *
  117. * void (*set_termios)(struct tty_struct *tty, struct ktermios * old);
  118. *
  119. * This routine allows the tty driver to be notified when
  120. * device's termios settings have changed.
  121. *
  122. * Optional: Called under the termios lock
  123. *
  124. *
  125. * void (*set_ldisc)(struct tty_struct *tty);
  126. *
  127. * This routine allows the tty driver to be notified when the
  128. * device's termios settings have changed.
  129. *
  130. * Optional: Called under BKL (currently)
  131. *
  132. * void (*throttle)(struct tty_struct * tty);
  133. *
  134. * This routine notifies the tty driver that input buffers for
  135. * the line discipline are close to full, and it should somehow
  136. * signal that no more characters should be sent to the tty.
  137. *
  138. * Optional: Always invoke via tty_throttle(), called under the
  139. * termios lock.
  140. *
  141. * void (*unthrottle)(struct tty_struct * tty);
  142. *
  143. * This routine notifies the tty drivers that it should signals
  144. * that characters can now be sent to the tty without fear of
  145. * overrunning the input buffers of the line disciplines.
  146. *
  147. * Optional: Always invoke via tty_unthrottle(), called under the
  148. * termios lock.
  149. *
  150. * void (*stop)(struct tty_struct *tty);
  151. *
  152. * This routine notifies the tty driver that it should stop
  153. * outputting characters to the tty device.
  154. *
  155. * Called with ->flow_lock held. Serialized with start() method.
  156. *
  157. * Optional:
  158. *
  159. * Note: Call stop_tty not this method.
  160. *
  161. * void (*start)(struct tty_struct *tty);
  162. *
  163. * This routine notifies the tty driver that it resume sending
  164. * characters to the tty device.
  165. *
  166. * Called with ->flow_lock held. Serialized with stop() method.
  167. *
  168. * Optional:
  169. *
  170. * Note: Call start_tty not this method.
  171. *
  172. * void (*hangup)(struct tty_struct *tty);
  173. *
  174. * This routine notifies the tty driver that it should hang up the
  175. * tty device.
  176. *
  177. * Optional:
  178. *
  179. * Called with tty lock held.
  180. *
  181. * int (*break_ctl)(struct tty_struct *tty, int state);
  182. *
  183. * This optional routine requests the tty driver to turn on or
  184. * off BREAK status on the RS-232 port. If state is -1,
  185. * then the BREAK status should be turned on; if state is 0, then
  186. * BREAK should be turned off.
  187. *
  188. * If this routine is implemented, the high-level tty driver will
  189. * handle the following ioctls: TCSBRK, TCSBRKP, TIOCSBRK,
  190. * TIOCCBRK.
  191. *
  192. * If the driver sets TTY_DRIVER_HARDWARE_BREAK then the interface
  193. * will also be called with actual times and the hardware is expected
  194. * to do the delay work itself. 0 and -1 are still used for on/off.
  195. *
  196. * Optional: Required for TCSBRK/BRKP/etc handling.
  197. *
  198. * void (*wait_until_sent)(struct tty_struct *tty, int timeout);
  199. *
  200. * This routine waits until the device has written out all of the
  201. * characters in its transmitter FIFO.
  202. *
  203. * Optional: If not provided the device is assumed to have no FIFO
  204. *
  205. * Note: Usually correct to call tty_wait_until_sent
  206. *
  207. * void (*send_xchar)(struct tty_struct *tty, char ch);
  208. *
  209. * This routine is used to send a high-priority XON/XOFF
  210. * character to the device.
  211. *
  212. * Optional: If not provided then the write method is called under
  213. * the atomic write lock to keep it serialized with the ldisc.
  214. *
  215. * int (*resize)(struct tty_struct *tty, struct winsize *ws)
  216. *
  217. * Called when a termios request is issued which changes the
  218. * requested terminal geometry.
  219. *
  220. * Optional: the default action is to update the termios structure
  221. * without error. This is usually the correct behaviour. Drivers should
  222. * not force errors here if they are not resizable objects (eg a serial
  223. * line). See tty_do_resize() if you need to wrap the standard method
  224. * in your own logic - the usual case.
  225. *
  226. * int (*get_icount)(struct tty_struct *tty, struct serial_icounter *icount);
  227. *
  228. * Called when the device receives a TIOCGICOUNT ioctl. Passed a kernel
  229. * structure to complete. This method is optional and will only be called
  230. * if provided (otherwise ENOTTY will be returned).
  231. */
  232. #include <linux/export.h>
  233. #include <linux/fs.h>
  234. #include <linux/list.h>
  235. #include <linux/cdev.h>
  236. #include <linux/termios.h>
  237. #include <linux/seq_file.h>
  238. #include <linux/android_kabi.h>
  239. struct tty_struct;
  240. struct tty_driver;
  241. struct serial_icounter_struct;
  242. struct serial_struct;
  243. struct tty_operations {
  244. struct tty_struct * (*lookup)(struct tty_driver *driver,
  245. struct file *filp, int idx);
  246. int (*install)(struct tty_driver *driver, struct tty_struct *tty);
  247. void (*remove)(struct tty_driver *driver, struct tty_struct *tty);
  248. int (*open)(struct tty_struct * tty, struct file * filp);
  249. void (*close)(struct tty_struct * tty, struct file * filp);
  250. void (*shutdown)(struct tty_struct *tty);
  251. void (*cleanup)(struct tty_struct *tty);
  252. int (*write)(struct tty_struct * tty,
  253. const unsigned char *buf, int count);
  254. int (*put_char)(struct tty_struct *tty, unsigned char ch);
  255. void (*flush_chars)(struct tty_struct *tty);
  256. int (*write_room)(struct tty_struct *tty);
  257. int (*chars_in_buffer)(struct tty_struct *tty);
  258. int (*ioctl)(struct tty_struct *tty,
  259. unsigned int cmd, unsigned long arg);
  260. long (*compat_ioctl)(struct tty_struct *tty,
  261. unsigned int cmd, unsigned long arg);
  262. void (*set_termios)(struct tty_struct *tty, struct ktermios * old);
  263. void (*throttle)(struct tty_struct * tty);
  264. void (*unthrottle)(struct tty_struct * tty);
  265. void (*stop)(struct tty_struct *tty);
  266. void (*start)(struct tty_struct *tty);
  267. void (*hangup)(struct tty_struct *tty);
  268. int (*break_ctl)(struct tty_struct *tty, int state);
  269. void (*flush_buffer)(struct tty_struct *tty);
  270. void (*set_ldisc)(struct tty_struct *tty);
  271. void (*wait_until_sent)(struct tty_struct *tty, int timeout);
  272. void (*send_xchar)(struct tty_struct *tty, char ch);
  273. int (*tiocmget)(struct tty_struct *tty);
  274. int (*tiocmset)(struct tty_struct *tty,
  275. unsigned int set, unsigned int clear);
  276. int (*resize)(struct tty_struct *tty, struct winsize *ws);
  277. /* only for abi preservation */
  278. int (*set_termiox)(struct tty_struct *tty, struct termiox *tnew);
  279. int (*get_icount)(struct tty_struct *tty,
  280. struct serial_icounter_struct *icount);
  281. int (*get_serial)(struct tty_struct *tty, struct serial_struct *p);
  282. int (*set_serial)(struct tty_struct *tty, struct serial_struct *p);
  283. void (*show_fdinfo)(struct tty_struct *tty, struct seq_file *m);
  284. #ifdef CONFIG_CONSOLE_POLL
  285. int (*poll_init)(struct tty_driver *driver, int line, char *options);
  286. int (*poll_get_char)(struct tty_driver *driver, int line);
  287. void (*poll_put_char)(struct tty_driver *driver, int line, char ch);
  288. #endif
  289. int (*proc_show)(struct seq_file *, void *);
  290. ANDROID_KABI_RESERVE(1);
  291. ANDROID_KABI_RESERVE(2);
  292. } __randomize_layout;
  293. struct tty_driver {
  294. int magic; /* magic number for this structure */
  295. struct kref kref; /* Reference management */
  296. struct cdev **cdevs;
  297. struct module *owner;
  298. const char *driver_name;
  299. const char *name;
  300. int name_base; /* offset of printed name */
  301. int major; /* major device number */
  302. int minor_start; /* start of minor device number */
  303. unsigned int num; /* number of devices allocated */
  304. short type; /* type of tty driver */
  305. short subtype; /* subtype of tty driver */
  306. struct ktermios init_termios; /* Initial termios */
  307. unsigned long flags; /* tty driver flags */
  308. struct proc_dir_entry *proc_entry; /* /proc fs entry */
  309. struct tty_driver *other; /* only used for the PTY driver */
  310. /*
  311. * Pointer to the tty data structures
  312. */
  313. struct tty_struct **ttys;
  314. struct tty_port **ports;
  315. struct ktermios **termios;
  316. void *driver_state;
  317. /*
  318. * Driver methods
  319. */
  320. const struct tty_operations *ops;
  321. struct list_head tty_drivers;
  322. ANDROID_KABI_RESERVE(1);
  323. ANDROID_KABI_RESERVE(2);
  324. } __randomize_layout;
  325. extern struct list_head tty_drivers;
  326. extern struct tty_driver *__tty_alloc_driver(unsigned int lines,
  327. struct module *owner, unsigned long flags);
  328. extern void put_tty_driver(struct tty_driver *driver);
  329. extern void tty_set_operations(struct tty_driver *driver,
  330. const struct tty_operations *op);
  331. extern struct tty_driver *tty_find_polling_driver(char *name, int *line);
  332. extern void tty_driver_kref_put(struct tty_driver *driver);
  333. /* Use TTY_DRIVER_* flags below */
  334. #define tty_alloc_driver(lines, flags) \
  335. __tty_alloc_driver(lines, THIS_MODULE, flags)
  336. /*
  337. * DEPRECATED Do not use this in new code, use tty_alloc_driver instead.
  338. * (And change the return value checks.)
  339. */
  340. static inline struct tty_driver *alloc_tty_driver(unsigned int lines)
  341. {
  342. struct tty_driver *ret = tty_alloc_driver(lines, 0);
  343. if (IS_ERR(ret))
  344. return NULL;
  345. return ret;
  346. }
  347. static inline struct tty_driver *tty_driver_kref_get(struct tty_driver *d)
  348. {
  349. kref_get(&d->kref);
  350. return d;
  351. }
  352. /* tty driver magic number */
  353. #define TTY_DRIVER_MAGIC 0x5402
  354. /*
  355. * tty driver flags
  356. *
  357. * TTY_DRIVER_RESET_TERMIOS --- requests the tty layer to reset the
  358. * termios setting when the last process has closed the device.
  359. * Used for PTY's, in particular.
  360. *
  361. * TTY_DRIVER_REAL_RAW --- if set, indicates that the driver will
  362. * guarantee never not to set any special character handling
  363. * flags if ((IGNBRK || (!BRKINT && !PARMRK)) && (IGNPAR ||
  364. * !INPCK)). That is, if there is no reason for the driver to
  365. * send notifications of parity and break characters up to the
  366. * line driver, it won't do so. This allows the line driver to
  367. * optimize for this case if this flag is set. (Note that there
  368. * is also a promise, if the above case is true, not to signal
  369. * overruns, either.)
  370. *
  371. * TTY_DRIVER_DYNAMIC_DEV --- if set, the individual tty devices need
  372. * to be registered with a call to tty_register_device() when the
  373. * device is found in the system and unregistered with a call to
  374. * tty_unregister_device() so the devices will be show up
  375. * properly in sysfs. If not set, driver->num entries will be
  376. * created by the tty core in sysfs when tty_register_driver() is
  377. * called. This is to be used by drivers that have tty devices
  378. * that can appear and disappear while the main tty driver is
  379. * registered with the tty core.
  380. *
  381. * TTY_DRIVER_DEVPTS_MEM -- don't use the standard arrays, instead
  382. * use dynamic memory keyed through the devpts filesystem. This
  383. * is only applicable to the pty driver.
  384. *
  385. * TTY_DRIVER_HARDWARE_BREAK -- hardware handles break signals. Pass
  386. * the requested timeout to the caller instead of using a simple
  387. * on/off interface.
  388. *
  389. * TTY_DRIVER_DYNAMIC_ALLOC -- do not allocate structures which are
  390. * needed per line for this driver as it would waste memory.
  391. * The driver will take care.
  392. *
  393. * TTY_DRIVER_UNNUMBERED_NODE -- do not create numbered /dev nodes. In
  394. * other words create /dev/ttyprintk and not /dev/ttyprintk0.
  395. * Applicable only when a driver for a single tty device is
  396. * being allocated.
  397. */
  398. #define TTY_DRIVER_INSTALLED 0x0001
  399. #define TTY_DRIVER_RESET_TERMIOS 0x0002
  400. #define TTY_DRIVER_REAL_RAW 0x0004
  401. #define TTY_DRIVER_DYNAMIC_DEV 0x0008
  402. #define TTY_DRIVER_DEVPTS_MEM 0x0010
  403. #define TTY_DRIVER_HARDWARE_BREAK 0x0020
  404. #define TTY_DRIVER_DYNAMIC_ALLOC 0x0040
  405. #define TTY_DRIVER_UNNUMBERED_NODE 0x0080
  406. /* tty driver types */
  407. #define TTY_DRIVER_TYPE_SYSTEM 0x0001
  408. #define TTY_DRIVER_TYPE_CONSOLE 0x0002
  409. #define TTY_DRIVER_TYPE_SERIAL 0x0003
  410. #define TTY_DRIVER_TYPE_PTY 0x0004
  411. #define TTY_DRIVER_TYPE_SCC 0x0005 /* scc driver */
  412. #define TTY_DRIVER_TYPE_SYSCONS 0x0006
  413. /* system subtypes (magic, used by tty_io.c) */
  414. #define SYSTEM_TYPE_TTY 0x0001
  415. #define SYSTEM_TYPE_CONSOLE 0x0002
  416. #define SYSTEM_TYPE_SYSCONS 0x0003
  417. #define SYSTEM_TYPE_SYSPTMX 0x0004
  418. /* pty subtypes (magic, used by tty_io.c) */
  419. #define PTY_TYPE_MASTER 0x0001
  420. #define PTY_TYPE_SLAVE 0x0002
  421. /* serial subtype definitions */
  422. #define SERIAL_TYPE_NORMAL 1
  423. #endif /* #ifdef _LINUX_TTY_DRIVER_H */