tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

[PATCH] tty layer comment the locking assumptions and functions somewhat

Doesn't fix them but does show up some interesting areas that need review
and fixing.

Signed-off-by: Alan Cox <alan@redhat.com>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>

authored by

Alan Cox and committed by
Linus Torvalds af9b897e 9c275a83

+715 -62
+658 -60
drivers/char/tty_io.c
··· 153 153 static int tty_fasync(int fd, struct file * filp, int on); 154 154 static void release_mem(struct tty_struct *tty, int idx); 155 155 156 + /** 157 + * alloc_tty_struct - allocate a tty object 158 + * 159 + * Return a new empty tty structure. The data fields have not 160 + * been initialized in any way but has been zeroed 161 + * 162 + * Locking: none 163 + * FIXME: use kzalloc 164 + */ 156 165 157 166 static struct tty_struct *alloc_tty_struct(void) 158 167 { ··· 175 166 176 167 static void tty_buffer_free_all(struct tty_struct *); 177 168 169 + /** 170 + * free_tty_struct - free a disused tty 171 + * @tty: tty struct to free 172 + * 173 + * Free the write buffers, tty queue and tty memory itself. 174 + * 175 + * Locking: none. Must be called after tty is definitely unused 176 + */ 177 + 178 178 static inline void free_tty_struct(struct tty_struct *tty) 179 179 { 180 180 kfree(tty->write_buf); ··· 192 174 } 193 175 194 176 #define TTY_NUMBER(tty) ((tty)->index + (tty)->driver->name_base) 177 + 178 + /** 179 + * tty_name - return tty naming 180 + * @tty: tty structure 181 + * @buf: buffer for output 182 + * 183 + * Convert a tty structure into a name. The name reflects the kernel 184 + * naming policy and if udev is in use may not reflect user space 185 + * 186 + * Locking: none 187 + */ 195 188 196 189 char *tty_name(struct tty_struct *tty, char *buf) 197 190 { ··· 262 233 263 234 /* 264 235 * Tty buffer allocation management 236 + */ 237 + 238 + 239 + /** 240 + * tty_buffer_free_all - free buffers used by a tty 241 + * @tty: tty to free from 242 + * 243 + * Remove all the buffers pending on a tty whether queued with data 244 + * or in the free ring. Must be called when the tty is no longer in use 245 + * 246 + * Locking: none 265 247 */ 266 248 267 249 static void tty_buffer_free_all(struct tty_struct *tty) ··· 387 347 } 388 348 EXPORT_SYMBOL_GPL(tty_buffer_request_room); 389 349 350 + /** 351 + * tty_insert_flip_string - Add characters to the tty buffer 352 + * @tty: tty structure 353 + * @chars: characters 354 + * @size: size 355 + * 356 + * Queue a series of bytes to the tty buffering. All the characters 357 + * passed are marked as without error. Returns the number added. 358 + * 359 + * Locking: Called functions may take tty->buf.lock 360 + */ 361 + 390 362 int tty_insert_flip_string(struct tty_struct *tty, const unsigned char *chars, 391 363 size_t size) 392 364 { ··· 421 369 return copied; 422 370 } 423 371 EXPORT_SYMBOL(tty_insert_flip_string); 372 + 373 + /** 374 + * tty_insert_flip_string_flags - Add characters to the tty buffer 375 + * @tty: tty structure 376 + * @chars: characters 377 + * @flags: flag bytes 378 + * @size: size 379 + * 380 + * Queue a series of bytes to the tty buffering. For each character 381 + * the flags array indicates the status of the character. Returns the 382 + * number added. 383 + * 384 + * Locking: Called functions may take tty->buf.lock 385 + */ 424 386 425 387 int tty_insert_flip_string_flags(struct tty_struct *tty, 426 388 const unsigned char *chars, const char *flags, size_t size) ··· 460 394 } 461 395 EXPORT_SYMBOL(tty_insert_flip_string_flags); 462 396 397 + /** 398 + * tty_schedule_flip - push characters to ldisc 399 + * @tty: tty to push from 400 + * 401 + * Takes any pending buffers and transfers their ownership to the 402 + * ldisc side of the queue. It then schedules those characters for 403 + * processing by the line discipline. 404 + * 405 + * Locking: Takes tty->buf.lock 406 + */ 407 + 463 408 void tty_schedule_flip(struct tty_struct *tty) 464 409 { 465 410 unsigned long flags; ··· 482 405 } 483 406 EXPORT_SYMBOL(tty_schedule_flip); 484 407 485 - /* 408 + /** 409 + * tty_prepare_flip_string - make room for characters 410 + * @tty: tty 411 + * @chars: return pointer for character write area 412 + * @size: desired size 413 + * 486 414 * Prepare a block of space in the buffer for data. Returns the length 487 415 * available and buffer pointer to the space which is now allocated and 488 416 * accounted for as ready for normal characters. This is used for drivers 489 417 * that need their own block copy routines into the buffer. There is no 490 418 * guarantee the buffer is a DMA target! 419 + * 420 + * Locking: May call functions taking tty->buf.lock 491 421 */ 492 422 493 423 int tty_prepare_flip_string(struct tty_struct *tty, unsigned char **chars, size_t size) ··· 511 427 512 428 EXPORT_SYMBOL_GPL(tty_prepare_flip_string); 513 429 514 - /* 430 + /** 431 + * tty_prepare_flip_string_flags - make room for characters 432 + * @tty: tty 433 + * @chars: return pointer for character write area 434 + * @flags: return pointer for status flag write area 435 + * @size: desired size 436 + * 515 437 * Prepare a block of space in the buffer for data. Returns the length 516 438 * available and buffer pointer to the space which is now allocated and 517 439 * accounted for as ready for characters. This is used for drivers 518 440 * that need their own block copy routines into the buffer. There is no 519 441 * guarantee the buffer is a DMA target! 442 + * 443 + * Locking: May call functions taking tty->buf.lock 520 444 */ 521 445 522 446 int tty_prepare_flip_string_flags(struct tty_struct *tty, unsigned char **chars, char **flags, size_t size) ··· 543 451 544 452 545 453 546 - /* 454 + /** 455 + * tty_set_termios_ldisc - set ldisc field 456 + * @tty: tty structure 457 + * @num: line discipline number 458 + * 547 459 * This is probably overkill for real world processors but 548 460 * they are not on hot paths so a little discipline won't do 549 461 * any harm. 462 + * 463 + * Locking: takes termios_sem 550 464 */ 551 465 552 466 static void tty_set_termios_ldisc(struct tty_struct *tty, int num) ··· 571 473 static DEFINE_SPINLOCK(tty_ldisc_lock); 572 474 static DECLARE_WAIT_QUEUE_HEAD(tty_ldisc_wait); 573 475 static struct tty_ldisc tty_ldiscs[NR_LDISCS]; /* line disc dispatch table */ 476 + 477 + /** 478 + * tty_register_ldisc - install a line discipline 479 + * @disc: ldisc number 480 + * @new_ldisc: pointer to the ldisc object 481 + * 482 + * Installs a new line discipline into the kernel. The discipline 483 + * is set up as unreferenced and then made available to the kernel 484 + * from this point onwards. 485 + * 486 + * Locking: 487 + * takes tty_ldisc_lock to guard against ldisc races 488 + */ 574 489 575 490 int tty_register_ldisc(int disc, struct tty_ldisc *new_ldisc) 576 491 { ··· 604 493 } 605 494 EXPORT_SYMBOL(tty_register_ldisc); 606 495 496 + /** 497 + * tty_unregister_ldisc - unload a line discipline 498 + * @disc: ldisc number 499 + * @new_ldisc: pointer to the ldisc object 500 + * 501 + * Remove a line discipline from the kernel providing it is not 502 + * currently in use. 503 + * 504 + * Locking: 505 + * takes tty_ldisc_lock to guard against ldisc races 506 + */ 507 + 607 508 int tty_unregister_ldisc(int disc) 608 509 { 609 510 unsigned long flags; ··· 634 511 return ret; 635 512 } 636 513 EXPORT_SYMBOL(tty_unregister_ldisc); 514 + 515 + /** 516 + * tty_ldisc_get - take a reference to an ldisc 517 + * @disc: ldisc number 518 + * 519 + * Takes a reference to a line discipline. Deals with refcounts and 520 + * module locking counts. Returns NULL if the discipline is not available. 521 + * Returns a pointer to the discipline and bumps the ref count if it is 522 + * available 523 + * 524 + * Locking: 525 + * takes tty_ldisc_lock to guard against ldisc races 526 + */ 637 527 638 528 struct tty_ldisc *tty_ldisc_get(int disc) 639 529 { ··· 676 540 677 541 EXPORT_SYMBOL_GPL(tty_ldisc_get); 678 542 543 + /** 544 + * tty_ldisc_put - drop ldisc reference 545 + * @disc: ldisc number 546 + * 547 + * Drop a reference to a line discipline. Manage refcounts and 548 + * module usage counts 549 + * 550 + * Locking: 551 + * takes tty_ldisc_lock to guard against ldisc races 552 + */ 553 + 679 554 void tty_ldisc_put(int disc) 680 555 { 681 556 struct tty_ldisc *ld; ··· 704 557 705 558 EXPORT_SYMBOL_GPL(tty_ldisc_put); 706 559 560 + /** 561 + * tty_ldisc_assign - set ldisc on a tty 562 + * @tty: tty to assign 563 + * @ld: line discipline 564 + * 565 + * Install an instance of a line discipline into a tty structure. The 566 + * ldisc must have a reference count above zero to ensure it remains/ 567 + * The tty instance refcount starts at zero. 568 + * 569 + * Locking: 570 + * Caller must hold references 571 + */ 572 + 707 573 static void tty_ldisc_assign(struct tty_struct *tty, struct tty_ldisc *ld) 708 574 { 709 575 tty->ldisc = *ld; ··· 731 571 * the tty ldisc. Return 0 on failure or 1 on success. This is 732 572 * used to implement both the waiting and non waiting versions 733 573 * of tty_ldisc_ref 574 + * 575 + * Locking: takes tty_ldisc_lock 734 576 */ 735 577 736 578 static int tty_ldisc_try(struct tty_struct *tty) ··· 764 602 * must also be careful not to hold other locks that will deadlock 765 603 * against a discipline change, such as an existing ldisc reference 766 604 * (which we check for) 605 + * 606 + * Locking: call functions take tty_ldisc_lock 767 607 */ 768 608 769 609 struct tty_ldisc *tty_ldisc_ref_wait(struct tty_struct *tty) ··· 786 622 * Dereference the line discipline for the terminal and take a 787 623 * reference to it. If the line discipline is in flux then 788 624 * return NULL. Can be called from IRQ and timer functions. 625 + * 626 + * Locking: called functions take tty_ldisc_lock 789 627 */ 790 628 791 629 struct tty_ldisc *tty_ldisc_ref(struct tty_struct *tty) ··· 805 639 * 806 640 * Undoes the effect of tty_ldisc_ref or tty_ldisc_ref_wait. May 807 641 * be called in IRQ context. 642 + * 643 + * Locking: takes tty_ldisc_lock 808 644 */ 809 645 810 646 void tty_ldisc_deref(struct tty_ldisc *ld) ··· 851 683 * 852 684 * Set the discipline of a tty line. Must be called from a process 853 685 * context. 686 + * 687 + * Locking: takes tty_ldisc_lock. 688 + * called functions take termios_sem 854 689 */ 855 690 856 691 static int tty_set_ldisc(struct tty_struct *tty, int ldisc) ··· 1017 846 return retval; 1018 847 } 1019 848 1020 - /* 1021 - * This routine returns a tty driver structure, given a device number 849 + /** 850 + * get_tty_driver - find device of a tty 851 + * @dev_t: device identifier 852 + * @index: returns the index of the tty 853 + * 854 + * This routine returns a tty driver structure, given a device number 855 + * and also passes back the index number. 856 + * 857 + * Locking: caller must hold tty_mutex 1022 858 */ 859 + 1023 860 static struct tty_driver *get_tty_driver(dev_t device, int *index) 1024 861 { 1025 862 struct tty_driver *p; ··· 1042 863 return NULL; 1043 864 } 1044 865 1045 - /* 1046 - * If we try to write to, or set the state of, a terminal and we're 1047 - * not in the foreground, send a SIGTTOU. If the signal is blocked or 1048 - * ignored, go ahead and perform the operation. (POSIX 7.2) 866 + /** 867 + * tty_check_change - check for POSIX terminal changes 868 + * @tty: tty to check 869 + * 870 + * If we try to write to, or set the state of, a terminal and we're 871 + * not in the foreground, send a SIGTTOU. If the signal is blocked or 872 + * ignored, go ahead and perform the operation. (POSIX 7.2) 873 + * 874 + * Locking: none 1049 875 */ 876 + 1050 877 int tty_check_change(struct tty_struct * tty) 1051 878 { 1052 879 if (current->signal->tty != tty) ··· 1190 1005 1191 1006 EXPORT_SYMBOL_GPL(tty_ldisc_flush); 1192 1007 1193 - /* 1194 - * This can be called by the "eventd" kernel thread. That is process synchronous, 1195 - * but doesn't hold any locks, so we need to make sure we have the appropriate 1196 - * locks for what we're doing.. 1008 + /** 1009 + * do_tty_hangup - actual handler for hangup events 1010 + * @data: tty device 1011 + * 1012 + * This can be called by the "eventd" kernel thread. That is process 1013 + * synchronous but doesn't hold any locks, so we need to make sure we 1014 + * have the appropriate locks for what we're doing. 1015 + * 1016 + * The hangup event clears any pending redirections onto the hung up 1017 + * device. It ensures future writes will error and it does the needed 1018 + * line discipline hangup and signal delivery. The tty object itself 1019 + * remains intact. 1020 + * 1021 + * Locking: 1022 + * BKL 1023 + * redirect lock for undoing redirection 1024 + * file list lock for manipulating list of ttys 1025 + * tty_ldisc_lock from called functions 1026 + * termios_sem resetting termios data 1027 + * tasklist_lock to walk task list for hangup event 1028 + * 1197 1029 */ 1198 1030 static void do_tty_hangup(void *data) 1199 1031 { ··· 1335 1133 fput(f); 1336 1134 } 1337 1135 1136 + /** 1137 + * tty_hangup - trigger a hangup event 1138 + * @tty: tty to hangup 1139 + * 1140 + * A carrier loss (virtual or otherwise) has occurred on this like 1141 + * schedule a hangup sequence to run after this event. 1142 + */ 1143 + 1338 1144 void tty_hangup(struct tty_struct * tty) 1339 1145 { 1340 1146 #ifdef TTY_DEBUG_HANGUP ··· 1355 1145 1356 1146 EXPORT_SYMBOL(tty_hangup); 1357 1147 1148 + /** 1149 + * tty_vhangup - process vhangup 1150 + * @tty: tty to hangup 1151 + * 1152 + * The user has asked via system call for the terminal to be hung up. 1153 + * We do this synchronously so that when the syscall returns the process 1154 + * is complete. That guarantee is neccessary for security reasons. 1155 + */ 1156 + 1358 1157 void tty_vhangup(struct tty_struct * tty) 1359 1158 { 1360 1159 #ifdef TTY_DEBUG_HANGUP ··· 1375 1156 } 1376 1157 EXPORT_SYMBOL(tty_vhangup); 1377 1158 1159 + /** 1160 + * tty_hung_up_p - was tty hung up 1161 + * @filp: file pointer of tty 1162 + * 1163 + * Return true if the tty has been subject to a vhangup or a carrier 1164 + * loss 1165 + */ 1166 + 1378 1167 int tty_hung_up_p(struct file * filp) 1379 1168 { 1380 1169 return (filp->f_op == &hung_up_tty_fops); ··· 1390 1163 1391 1164 EXPORT_SYMBOL(tty_hung_up_p); 1392 1165 1393 - /* 1394 - * This function is typically called only by the session leader, when 1395 - * it wants to disassociate itself from its controlling tty. 1166 + /** 1167 + * disassociate_ctty - disconnect controlling tty 1168 + * @on_exit: true if exiting so need to "hang up" the session 1396 1169 * 1397 - * It performs the following functions: 1170 + * This function is typically called only by the session leader, when 1171 + * it wants to disassociate itself from its controlling tty. 1172 + * 1173 + * It performs the following functions: 1398 1174 * (1) Sends a SIGHUP and SIGCONT to the foreground process group 1399 1175 * (2) Clears the tty from being controlling the session 1400 1176 * (3) Clears the controlling tty for all processes in the 1401 1177 * session group. 1402 1178 * 1403 - * The argument on_exit is set to 1 if called when a process is 1404 - * exiting; it is 0 if called by the ioctl TIOCNOTTY. 1179 + * The argument on_exit is set to 1 if called when a process is 1180 + * exiting; it is 0 if called by the ioctl TIOCNOTTY. 1181 + * 1182 + * Locking: tty_mutex is taken to protect current->signal->tty 1183 + * BKL is taken for hysterical raisins 1184 + * Tasklist lock is taken (under tty_mutex) to walk process 1185 + * lists for the session. 1405 1186 */ 1187 + 1406 1188 void disassociate_ctty(int on_exit) 1407 1189 { 1408 1190 struct tty_struct *tty; ··· 1458 1222 unlock_kernel(); 1459 1223 } 1460 1224 1225 + 1226 + /** 1227 + * stop_tty - propogate flow control 1228 + * @tty: tty to stop 1229 + * 1230 + * Perform flow control to the driver. For PTY/TTY pairs we 1231 + * must also propogate the TIOCKPKT status. May be called 1232 + * on an already stopped device and will not re-call the driver 1233 + * method. 1234 + * 1235 + * This functionality is used by both the line disciplines for 1236 + * halting incoming flow and by the driver. It may therefore be 1237 + * called from any context, may be under the tty atomic_write_lock 1238 + * but not always. 1239 + * 1240 + * Locking: 1241 + * Broken. Relies on BKL which is unsafe here. 1242 + */ 1243 + 1461 1244 void stop_tty(struct tty_struct *tty) 1462 1245 { 1463 1246 if (tty->stopped) ··· 1492 1237 } 1493 1238 1494 1239 EXPORT_SYMBOL(stop_tty); 1240 + 1241 + /** 1242 + * start_tty - propogate flow control 1243 + * @tty: tty to start 1244 + * 1245 + * Start a tty that has been stopped if at all possible. Perform 1246 + * any neccessary wakeups and propogate the TIOCPKT status. If this 1247 + * is the tty was previous stopped and is being started then the 1248 + * driver start method is invoked and the line discipline woken. 1249 + * 1250 + * Locking: 1251 + * Broken. Relies on BKL which is unsafe here. 1252 + */ 1495 1253 1496 1254 void start_tty(struct tty_struct *tty) 1497 1255 { ··· 1525 1257 } 1526 1258 1527 1259 EXPORT_SYMBOL(start_tty); 1260 + 1261 + /** 1262 + * tty_read - read method for tty device files 1263 + * @file: pointer to tty file 1264 + * @buf: user buffer 1265 + * @count: size of user buffer 1266 + * @ppos: unused 1267 + * 1268 + * Perform the read system call function on this terminal device. Checks 1269 + * for hung up devices before calling the line discipline method. 1270 + * 1271 + * Locking: 1272 + * Locks the line discipline internally while needed 1273 + * For historical reasons the line discipline read method is 1274 + * invoked under the BKL. This will go away in time so do not rely on it 1275 + * in new code. Multiple read calls may be outstanding in parallel. 1276 + */ 1528 1277 1529 1278 static ssize_t tty_read(struct file * file, char __user * buf, size_t count, 1530 1279 loff_t *ppos) ··· 1587 1302 ssize_t ret = 0, written = 0; 1588 1303 unsigned int chunk; 1589 1304 1305 + /* FIXME: O_NDELAY ... */ 1590 1306 if (mutex_lock_interruptible(&tty->atomic_write_lock)) { 1591 1307 return -ERESTARTSYS; 1592 1308 } ··· 1604 1318 * layer has problems with bigger chunks. It will 1605 1319 * claim to be able to handle more characters than 1606 1320 * it actually does. 1321 + * 1322 + * FIXME: This can probably go away now except that 64K chunks 1323 + * are too likely to fail unless switched to vmalloc... 1607 1324 */ 1608 1325 chunk = 2048; 1609 1326 if (test_bit(TTY_NO_WRITE_SPLIT, &tty->flags)) ··· 1664 1375 } 1665 1376 1666 1377 1378 + /** 1379 + * tty_write - write method for tty device file 1380 + * @file: tty file pointer 1381 + * @buf: user data to write 1382 + * @count: bytes to write 1383 + * @ppos: unused 1384 + * 1385 + * Write data to a tty device via the line discipline. 1386 + * 1387 + * Locking: 1388 + * Locks the line discipline as required 1389 + * Writes to the tty driver are serialized by the atomic_write_lock 1390 + * and are then processed in chunks to the device. The line discipline 1391 + * write method will not be involked in parallel for each device 1392 + * The line discipline write method is called under the big 1393 + * kernel lock for historical reasons. New code should not rely on this. 1394 + */ 1395 + 1667 1396 static ssize_t tty_write(struct file * file, const char __user * buf, size_t count, 1668 1397 loff_t *ppos) 1669 1398 { ··· 1729 1422 1730 1423 static char ptychar[] = "pqrstuvwxyzabcde"; 1731 1424 1732 - static inline void pty_line_name(struct tty_driver *driver, int index, char *p) 1425 + /** 1426 + * pty_line_name - generate name for a pty 1427 + * @driver: the tty driver in use 1428 + * @index: the minor number 1429 + * @p: output buffer of at least 6 bytes 1430 + * 1431 + * Generate a name from a driver reference and write it to the output 1432 + * buffer. 1433 + * 1434 + * Locking: None 1435 + */ 1436 + static void pty_line_name(struct tty_driver *driver, int index, char *p) 1733 1437 { 1734 1438 int i = index + driver->name_base; 1735 1439 /* ->name is initialized to "ttyp", but "tty" is expected */ ··· 1749 1431 ptychar[i >> 4 & 0xf], i & 0xf); 1750 1432 } 1751 1433 1752 - static inline void tty_line_name(struct tty_driver *driver, int index, char *p) 1434 + /** 1435 + * pty_line_name - generate name for a tty 1436 + * @driver: the tty driver in use 1437 + * @index: the minor number 1438 + * @p: output buffer of at least 7 bytes 1439 + * 1440 + * Generate a name from a driver reference and write it to the output 1441 + * buffer. 1442 + * 1443 + * Locking: None 1444 + */ 1445 + static void tty_line_name(struct tty_driver *driver, int index, char *p) 1753 1446 { 1754 1447 sprintf(p, "%s%d", driver->name, index + driver->name_base); 1755 1448 } 1756 1449 1757 - /* 1450 + /** 1451 + * init_dev - initialise a tty device 1452 + * @driver: tty driver we are opening a device on 1453 + * @idx: device index 1454 + * @tty: returned tty structure 1455 + * 1456 + * Prepare a tty device. This may not be a "new" clean device but 1457 + * could also be an active device. The pty drivers require special 1458 + * handling because of this. 1459 + * 1460 + * Locking: 1461 + * The function is called under the tty_mutex, which 1462 + * protects us from the tty struct or driver itself going away. 1463 + * 1464 + * On exit the tty device has the line discipline attached and 1465 + * a reference count of 1. If a pair was created for pty/tty use 1466 + * and the other was a pty master then it too has a reference count of 1. 1467 + * 1758 1468 * WSH 06/09/97: Rewritten to remove races and properly clean up after a 1759 1469 * failed open. The new code protects the open with a mutex, so it's 1760 1470 * really quite straightforward. The mutex locking can probably be 1761 1471 * relaxed for the (most common) case of reopening a tty. 1762 1472 */ 1473 + 1763 1474 static int init_dev(struct tty_driver *driver, int idx, 1764 1475 struct tty_struct **ret_tty) 1765 1476 { 1766 1477 struct tty_struct *tty, *o_tty; 1767 1478 struct termios *tp, **tp_loc, *o_tp, **o_tp_loc; 1768 1479 struct termios *ltp, **ltp_loc, *o_ltp, **o_ltp_loc; 1769 - int retval=0; 1480 + int retval = 0; 1770 1481 1771 1482 /* check whether we're reopening an existing tty */ 1772 1483 if (driver->flags & TTY_DRIVER_DEVPTS_MEM) { ··· 2009 1662 goto end_init; 2010 1663 } 2011 1664 2012 - /* 2013 - * Releases memory associated with a tty structure, and clears out the 2014 - * driver table slots. 1665 + /** 1666 + * release_mem - release tty structure memory 1667 + * 1668 + * Releases memory associated with a tty structure, and clears out the 1669 + * driver table slots. This function is called when a device is no longer 1670 + * in use. It also gets called when setup of a device fails. 1671 + * 1672 + * Locking: 1673 + * tty_mutex - sometimes only 1674 + * takes the file list lock internally when working on the list 1675 + * of ttys that the driver keeps. 1676 + * FIXME: should we require tty_mutex is held here ?? 2015 1677 */ 1678 + 2016 1679 static void release_mem(struct tty_struct *tty, int idx) 2017 1680 { 2018 1681 struct tty_struct *o_tty; ··· 2363 2006 2364 2007 } 2365 2008 2366 - /* 2367 - * tty_open and tty_release keep up the tty count that contains the 2368 - * number of opens done on a tty. We cannot use the inode-count, as 2369 - * different inodes might point to the same tty. 2009 + /** 2010 + * tty_open - open a tty device 2011 + * @inode: inode of device file 2012 + * @filp: file pointer to tty 2370 2013 * 2371 - * Open-counting is needed for pty masters, as well as for keeping 2372 - * track of serial lines: DTR is dropped when the last close happens. 2373 - * (This is not done solely through tty->count, now. - Ted 1/27/92) 2014 + * tty_open and tty_release keep up the tty count that contains the 2015 + * number of opens done on a tty. We cannot use the inode-count, as 2016 + * different inodes might point to the same tty. 2374 2017 * 2375 - * The termios state of a pty is reset on first open so that 2376 - * settings don't persist across reuse. 2018 + * Open-counting is needed for pty masters, as well as for keeping 2019 + * track of serial lines: DTR is dropped when the last close happens. 2020 + * (This is not done solely through tty->count, now. - Ted 1/27/92) 2021 + * 2022 + * The termios state of a pty is reset on first open so that 2023 + * settings don't persist across reuse. 2024 + * 2025 + * Locking: tty_mutex protects current->signal->tty, get_tty_driver and 2026 + * init_dev work. tty->count should protect the rest. 2027 + * task_lock is held to update task details for sessions 2377 2028 */ 2029 + 2378 2030 static int tty_open(struct inode * inode, struct file * filp) 2379 2031 { 2380 2032 struct tty_struct *tty; ··· 2498 2132 } 2499 2133 2500 2134 #ifdef CONFIG_UNIX98_PTYS 2135 + /** 2136 + * ptmx_open - open a unix 98 pty master 2137 + * @inode: inode of device file 2138 + * @filp: file pointer to tty 2139 + * 2140 + * Allocate a unix98 pty master device from the ptmx driver. 2141 + * 2142 + * Locking: tty_mutex protects theinit_dev work. tty->count should 2143 + protect the rest. 2144 + * allocated_ptys_lock handles the list of free pty numbers 2145 + */ 2146 + 2501 2147 static int ptmx_open(struct inode * inode, struct file * filp) 2502 2148 { 2503 2149 struct tty_struct *tty; ··· 2569 2191 } 2570 2192 #endif 2571 2193 2194 + /** 2195 + * tty_release - vfs callback for close 2196 + * @inode: inode of tty 2197 + * @filp: file pointer for handle to tty 2198 + * 2199 + * Called the last time each file handle is closed that references 2200 + * this tty. There may however be several such references. 2201 + * 2202 + * Locking: 2203 + * Takes bkl. See release_dev 2204 + */ 2205 + 2572 2206 static int tty_release(struct inode * inode, struct file * filp) 2573 2207 { 2574 2208 lock_kernel(); ··· 2589 2199 return 0; 2590 2200 } 2591 2201 2592 - /* No kernel lock held - fine */ 2202 + /** 2203 + * tty_poll - check tty status 2204 + * @filp: file being polled 2205 + * @wait: poll wait structures to update 2206 + * 2207 + * Call the line discipline polling method to obtain the poll 2208 + * status of the device. 2209 + * 2210 + * Locking: locks called line discipline but ldisc poll method 2211 + * may be re-entered freely by other callers. 2212 + */ 2213 + 2593 2214 static unsigned int tty_poll(struct file * filp, poll_table * wait) 2594 2215 { 2595 2216 struct tty_struct * tty; ··· 2644 2243 return 0; 2645 2244 } 2646 2245 2246 + /** 2247 + * tiocsti - fake input character 2248 + * @tty: tty to fake input into 2249 + * @p: pointer to character 2250 + * 2251 + * Fake input to a tty device. Does the neccessary locking and 2252 + * input management. 2253 + * 2254 + * FIXME: does not honour flow control ?? 2255 + * 2256 + * Locking: 2257 + * Called functions take tty_ldisc_lock 2258 + * current->signal->tty check is safe without locks 2259 + */ 2260 + 2647 2261 static int tiocsti(struct tty_struct *tty, char __user *p) 2648 2262 { 2649 2263 char ch, mbz = 0; ··· 2674 2258 return 0; 2675 2259 } 2676 2260 2261 + /** 2262 + * tiocgwinsz - implement window query ioctl 2263 + * @tty; tty 2264 + * @arg: user buffer for result 2265 + * 2266 + * Copies the kernel idea of the window size into the user buffer. No 2267 + * locking is done. 2268 + * 2269 + * FIXME: Returning random values racing a window size set is wrong 2270 + * should lock here against that 2271 + */ 2272 + 2677 2273 static int tiocgwinsz(struct tty_struct *tty, struct winsize __user * arg) 2678 2274 { 2679 2275 if (copy_to_user(arg, &tty->winsize, sizeof(*arg))) 2680 2276 return -EFAULT; 2681 2277 return 0; 2682 2278 } 2279 + 2280 + /** 2281 + * tiocswinsz - implement window size set ioctl 2282 + * @tty; tty 2283 + * @arg: user buffer for result 2284 + * 2285 + * Copies the user idea of the window size to the kernel. Traditionally 2286 + * this is just advisory information but for the Linux console it 2287 + * actually has driver level meaning and triggers a VC resize. 2288 + * 2289 + * Locking: 2290 + * The console_sem is used to ensure we do not try and resize 2291 + * the console twice at once. 2292 + * FIXME: Two racing size sets may leave the console and kernel 2293 + * parameters disagreeing. Is this exploitable ? 2294 + * FIXME: Random values racing a window size get is wrong 2295 + * should lock here against that 2296 + */ 2683 2297 2684 2298 static int tiocswinsz(struct tty_struct *tty, struct tty_struct *real_tty, 2685 2299 struct winsize __user * arg) ··· 2740 2294 return 0; 2741 2295 } 2742 2296 2297 + /** 2298 + * tioccons - allow admin to move logical console 2299 + * @file: the file to become console 2300 + * 2301 + * Allow the adminstrator to move the redirected console device 2302 + * 2303 + * Locking: uses redirect_lock to guard the redirect information 2304 + */ 2305 + 2743 2306 static int tioccons(struct file *file) 2744 2307 { 2745 2308 if (!capable(CAP_SYS_ADMIN)) ··· 2774 2319 return 0; 2775 2320 } 2776 2321 2322 + /** 2323 + * fionbio - non blocking ioctl 2324 + * @file: file to set blocking value 2325 + * @p: user parameter 2326 + * 2327 + * Historical tty interfaces had a blocking control ioctl before 2328 + * the generic functionality existed. This piece of history is preserved 2329 + * in the expected tty API of posix OS's. 2330 + * 2331 + * Locking: none, the open fle handle ensures it won't go away. 2332 + */ 2777 2333 2778 2334 static int fionbio(struct file *file, int __user *p) 2779 2335 { ··· 2799 2333 file->f_flags &= ~O_NONBLOCK; 2800 2334 return 0; 2801 2335 } 2336 + 2337 + /** 2338 + * tiocsctty - set controlling tty 2339 + * @tty: tty structure 2340 + * @arg: user argument 2341 + * 2342 + * This ioctl is used to manage job control. It permits a session 2343 + * leader to set this tty as the controlling tty for the session. 2344 + * 2345 + * Locking: 2346 + * Takes tasklist lock internally to walk sessions 2347 + * Takes task_lock() when updating signal->tty 2348 + * 2349 + * FIXME: tty_mutex is needed to protect signal->tty references. 2350 + * FIXME: why task_lock on the signal->tty reference ?? 2351 + * 2352 + */ 2802 2353 2803 2354 static int tiocsctty(struct tty_struct *tty, int arg) 2804 2355 { ··· 2857 2374 return 0; 2858 2375 } 2859 2376 2377 + /** 2378 + * tiocgpgrp - get process group 2379 + * @tty: tty passed by user 2380 + * @real_tty: tty side of the tty pased by the user if a pty else the tty 2381 + * @p: returned pid 2382 + * 2383 + * Obtain the process group of the tty. If there is no process group 2384 + * return an error. 2385 + * 2386 + * Locking: none. Reference to ->signal->tty is safe. 2387 + */ 2388 + 2860 2389 static int tiocgpgrp(struct tty_struct *tty, struct tty_struct *real_tty, pid_t __user *p) 2861 2390 { 2862 2391 /* ··· 2879 2384 return -ENOTTY; 2880 2385 return put_user(real_tty->pgrp, p); 2881 2386 } 2387 + 2388 + /** 2389 + * tiocspgrp - attempt to set process group 2390 + * @tty: tty passed by user 2391 + * @real_tty: tty side device matching tty passed by user 2392 + * @p: pid pointer 2393 + * 2394 + * Set the process group of the tty to the session passed. Only 2395 + * permitted where the tty session is our session. 2396 + * 2397 + * Locking: None 2398 + * 2399 + * FIXME: current->signal->tty referencing is unsafe. 2400 + */ 2882 2401 2883 2402 static int tiocspgrp(struct tty_struct *tty, struct tty_struct *real_tty, pid_t __user *p) 2884 2403 { ··· 2917 2408 return 0; 2918 2409 } 2919 2410 2411 + /** 2412 + * tiocgsid - get session id 2413 + * @tty: tty passed by user 2414 + * @real_tty: tty side of the tty pased by the user if a pty else the tty 2415 + * @p: pointer to returned session id 2416 + * 2417 + * Obtain the session id of the tty. If there is no session 2418 + * return an error. 2419 + * 2420 + * Locking: none. Reference to ->signal->tty is safe. 2421 + */ 2422 + 2920 2423 static int tiocgsid(struct tty_struct *tty, struct tty_struct *real_tty, pid_t __user *p) 2921 2424 { 2922 2425 /* ··· 2942 2421 return put_user(real_tty->session, p); 2943 2422 } 2944 2423 2424 + /** 2425 + * tiocsetd - set line discipline 2426 + * @tty: tty device 2427 + * @p: pointer to user data 2428 + * 2429 + * Set the line discipline according to user request. 2430 + * 2431 + * Locking: see tty_set_ldisc, this function is just a helper 2432 + */ 2433 + 2945 2434 static int tiocsetd(struct tty_struct *tty, int __user *p) 2946 2435 { 2947 2436 int ldisc; ··· 2960 2429 return -EFAULT; 2961 2430 return tty_set_ldisc(tty, ldisc); 2962 2431 } 2432 + 2433 + /** 2434 + * send_break - performed time break 2435 + * @tty: device to break on 2436 + * @duration: timeout in mS 2437 + * 2438 + * Perform a timed break on hardware that lacks its own driver level 2439 + * timed break functionality. 2440 + * 2441 + * Locking: 2442 + * None 2443 + * 2444 + * FIXME: 2445 + * What if two overlap 2446 + */ 2963 2447 2964 2448 static int send_break(struct tty_struct *tty, unsigned int duration) 2965 2449 { ··· 2988 2442 return 0; 2989 2443 } 2990 2444 2991 - static int 2992 - tty_tiocmget(struct tty_struct *tty, struct file *file, int __user *p) 2445 + /** 2446 + * tiocmget - get modem status 2447 + * @tty: tty device 2448 + * @file: user file pointer 2449 + * @p: pointer to result 2450 + * 2451 + * Obtain the modem status bits from the tty driver if the feature 2452 + * is supported. Return -EINVAL if it is not available. 2453 + * 2454 + * Locking: none (up to the driver) 2455 + */ 2456 + 2457 + static int tty_tiocmget(struct tty_struct *tty, struct file *file, int __user *p) 2993 2458 { 2994 2459 int retval = -EINVAL; 2995 2460 ··· 3013 2456 return retval; 3014 2457 } 3015 2458 3016 - static int 3017 - tty_tiocmset(struct tty_struct *tty, struct file *file, unsigned int cmd, 2459 + /** 2460 + * tiocmset - set modem status 2461 + * @tty: tty device 2462 + * @file: user file pointer 2463 + * @cmd: command - clear bits, set bits or set all 2464 + * @p: pointer to desired bits 2465 + * 2466 + * Set the modem status bits from the tty driver if the feature 2467 + * is supported. Return -EINVAL if it is not available. 2468 + * 2469 + * Locking: none (up to the driver) 2470 + */ 2471 + 2472 + static int tty_tiocmset(struct tty_struct *tty, struct file *file, unsigned int cmd, 3018 2473 unsigned __user *p) 3019 2474 { 3020 2475 int retval = -EINVAL; ··· 3142 2573 clear_bit(TTY_EXCLUSIVE, &tty->flags); 3143 2574 return 0; 3144 2575 case TIOCNOTTY: 2576 + /* FIXME: taks lock or tty_mutex ? */ 3145 2577 if (current->signal->tty != tty) 3146 2578 return -ENOTTY; 3147 2579 if (current->signal->leader) ··· 3323 2753 3324 2754 EXPORT_SYMBOL(do_SAK); 3325 2755 3326 - /* 3327 - * This routine is called out of the software interrupt to flush data 3328 - * from the buffer chain to the line discipline. 2756 + /** 2757 + * flush_to_ldisc 2758 + * @private_: tty structure passed from work queue. 2759 + * 2760 + * This routine is called out of the software interrupt to flush data 2761 + * from the buffer chain to the line discipline. 2762 + * 2763 + * Locking: holds tty->buf.lock to guard buffer list. Drops the lock 2764 + * while invoking the line discipline receive_buf method. The 2765 + * receive_buf method is single threaded for each tty instance. 3329 2766 */ 3330 2767 3331 2768 static void flush_to_ldisc(void *private_) ··· 3408 2831 * Convert termios baud rate data into a speed. This should be called 3409 2832 * with the termios lock held if this termios is a terminal termios 3410 2833 * structure. May change the termios data. 2834 + * 2835 + * Locking: none 3411 2836 */ 3412 2837 3413 2838 int tty_termios_baud_rate(struct termios *termios) ··· 3438 2859 * Returns the baud rate as an integer for this terminal. The 3439 2860 * termios lock must be held by the caller and the terminal bit 3440 2861 * flags may be updated. 2862 + * 2863 + * Locking: none 3441 2864 */ 3442 2865 3443 2866 int tty_get_baud_rate(struct tty_struct *tty) ··· 3469 2888 * 3470 2889 * In the event of the queue being busy for flipping the work will be 3471 2890 * held off and retried later. 2891 + * 2892 + * Locking: tty buffer lock. Driver locks in low latency mode. 3472 2893 */ 3473 2894 3474 2895 void tty_flip_buffer_push(struct tty_struct *tty) ··· 3490 2907 EXPORT_SYMBOL(tty_flip_buffer_push); 3491 2908 3492 2909 3493 - /* 3494 - * This subroutine initializes a tty structure. 2910 + /** 2911 + * initialize_tty_struct 2912 + * @tty: tty to initialize 2913 + * 2914 + * This subroutine initializes a tty structure that has been newly 2915 + * allocated. 2916 + * 2917 + * Locking: none - tty in question must not be exposed at this point 3495 2918 */ 2919 + 3496 2920 static void initialize_tty_struct(struct tty_struct *tty) 3497 2921 { 3498 2922 memset(tty, 0, sizeof(struct tty_struct)); ··· 3525 2935 /* 3526 2936 * The default put_char routine if the driver did not define one. 3527 2937 */ 2938 + 3528 2939 static void tty_default_put_char(struct tty_struct *tty, unsigned char ch) 3529 2940 { 3530 2941 tty->driver->write(tty, &ch, 1); ··· 3534 2943 static struct class *tty_class; 3535 2944 3536 2945 /** 3537 - * tty_register_device - register a tty device 3538 - * @driver: the tty driver that describes the tty device 3539 - * @index: the index in the tty driver for this tty device 3540 - * @device: a struct device that is associated with this tty device. 3541 - * This field is optional, if there is no known struct device for this 3542 - * tty device it can be set to NULL safely. 2946 + * tty_register_device - register a tty device 2947 + * @driver: the tty driver that describes the tty device 2948 + * @index: the index in the tty driver for this tty device 2949 + * @device: a struct device that is associated with this tty device. 2950 + * This field is optional, if there is no known struct device 2951 + * for this tty device it can be set to NULL safely. 3543 2952 * 3544 - * Returns a pointer to the class device (or ERR_PTR(-EFOO) on error). 2953 + * Returns a pointer to the class device (or ERR_PTR(-EFOO) on error). 3545 2954 * 3546 - * This call is required to be made to register an individual tty device if 3547 - * the tty driver's flags have the TTY_DRIVER_DYNAMIC_DEV bit set. If that 3548 - * bit is not set, this function should not be called by a tty driver. 2955 + * This call is required to be made to register an individual tty device 2956 + * if the tty driver's flags have the TTY_DRIVER_DYNAMIC_DEV bit set. If 2957 + * that bit is not set, this function should not be called by a tty 2958 + * driver. 2959 + * 2960 + * Locking: ?? 3549 2961 */ 2962 + 3550 2963 struct class_device *tty_register_device(struct tty_driver *driver, 3551 2964 unsigned index, struct device *device) 3552 2965 { ··· 3572 2977 } 3573 2978 3574 2979 /** 3575 - * tty_unregister_device - unregister a tty device 3576 - * @driver: the tty driver that describes the tty device 3577 - * @index: the index in the tty driver for this tty device 2980 + * tty_unregister_device - unregister a tty device 2981 + * @driver: the tty driver that describes the tty device 2982 + * @index: the index in the tty driver for this tty device 3578 2983 * 3579 - * If a tty device is registered with a call to tty_register_device() then 3580 - * this function must be made when the tty device is gone. 2984 + * If a tty device is registered with a call to tty_register_device() then 2985 + * this function must be called when the tty device is gone. 2986 + * 2987 + * Locking: ?? 3581 2988 */ 2989 + 3582 2990 void tty_unregister_device(struct tty_driver *driver, unsigned index) 3583 2991 { 3584 2992 class_device_destroy(tty_class, MKDEV(driver->major, driver->minor_start) + index);
+57 -2
drivers/char/tty_ioctl.c
··· 36 36 #define TERMIOS_WAIT 2 37 37 #define TERMIOS_TERMIO 4 38 38 39 + 40 + /** 41 + * tty_wait_until_sent - wait for I/O to finish 42 + * @tty: tty we are waiting for 43 + * @timeout: how long we will wait 44 + * 45 + * Wait for characters pending in a tty driver to hit the wire, or 46 + * for a timeout to occur (eg due to flow control) 47 + * 48 + * Locking: none 49 + */ 50 + 39 51 void tty_wait_until_sent(struct tty_struct * tty, long timeout) 40 52 { 41 53 DECLARE_WAITQUEUE(wait, current); ··· 105 93 termios->c_cc[i] = locked->c_cc[i] ? 106 94 old->c_cc[i] : termios->c_cc[i]; 107 95 } 96 + 97 + /** 98 + * change_termios - update termios values 99 + * @tty: tty to update 100 + * @new_termios: desired new value 101 + * 102 + * Perform updates to the termios values set on this terminal. There 103 + * is a bit of layering violation here with n_tty in terms of the 104 + * internal knowledge of this function. 105 + * 106 + * Locking: termios_sem 107 + */ 108 108 109 109 static void change_termios(struct tty_struct * tty, struct termios * new_termios) 110 110 { ··· 178 154 } 179 155 up(&tty->termios_sem); 180 156 } 157 + 158 + /** 159 + * set_termios - set termios values for a tty 160 + * @tty: terminal device 161 + * @arg: user data 162 + * @opt: option information 163 + * 164 + * Helper function to prepare termios data and run neccessary other 165 + * functions before using change_termios to do the actual changes. 166 + * 167 + * Locking: 168 + * Called functions take ldisc and termios_sem locks 169 + */ 181 170 182 171 static int set_termios(struct tty_struct * tty, void __user *arg, int opt) 183 172 { ··· 321 284 } 322 285 } 323 286 287 + /** 288 + * set_sgttyb - set legacy terminal values 289 + * @tty: tty structure 290 + * @sgttyb: pointer to old style terminal structure 291 + * 292 + * Updates a terminal from the legacy BSD style terminal information 293 + * structure. 294 + * 295 + * Locking: termios_sem 296 + */ 297 + 324 298 static int set_sgttyb(struct tty_struct * tty, struct sgttyb __user * sgttyb) 325 299 { 326 300 int retval; ··· 417 369 } 418 370 #endif 419 371 420 - /* 421 - * Send a high priority character to the tty. 372 + /** 373 + * send_prio_char - send priority character 374 + * 375 + * Send a high priority character to the tty even if stopped 376 + * 377 + * Locking: none 378 + * 379 + * FIXME: overlapping calls with start/stop tty lose state of tty 422 380 */ 381 + 423 382 static void send_prio_char(struct tty_struct *tty, char ch) 424 383 { 425 384 int was_stopped = tty->stopped;