diff options
Diffstat (limited to 'drivers/tty/tty_ioctl.c')
| -rw-r--r-- | drivers/tty/tty_ioctl.c | 234 |
1 files changed, 114 insertions, 120 deletions
diff --git a/drivers/tty/tty_ioctl.c b/drivers/tty/tty_ioctl.c index 7958bf6d27c4..4b499301a3db 100644 --- a/drivers/tty/tty_ioctl.c +++ b/drivers/tty/tty_ioctl.c @@ -38,16 +38,13 @@ #define TERMIOS_TERMIO BIT(2) #define TERMIOS_OLD BIT(3) - /** - * tty_chars_in_buffer - characters pending - * @tty: terminal + * tty_chars_in_buffer - characters pending + * @tty: terminal * - * Return the number of bytes of data in the device private - * output queue. If no private method is supplied there is assumed - * to be no queue on the device. + * Returns: the number of bytes of data in the device private output queue. If + * no private method is supplied there is assumed to be no queue on the device. */ - unsigned int tty_chars_in_buffer(struct tty_struct *tty) { if (tty->ops->chars_in_buffer) @@ -57,16 +54,15 @@ unsigned int tty_chars_in_buffer(struct tty_struct *tty) EXPORT_SYMBOL(tty_chars_in_buffer); /** - * tty_write_room - write queue space - * @tty: terminal + * tty_write_room - write queue space + * @tty: terminal * - * Return the number of bytes that can be queued to this device - * at the present time. The result should be treated as a guarantee - * and the driver cannot offer a value it later shrinks by more than - * the number of bytes written. If no method is provided 2K is always - * returned and data may be lost as there will be no flow control. + * Returns: the number of bytes that can be queued to this device at the present + * time. The result should be treated as a guarantee and the driver cannot + * offer a value it later shrinks by more than the number of bytes written. If + * no method is provided, 2K is always returned and data may be lost as there + * will be no flow control. */ - unsigned int tty_write_room(struct tty_struct *tty) { if (tty->ops->write_room) @@ -76,12 +72,12 @@ unsigned int tty_write_room(struct tty_struct *tty) EXPORT_SYMBOL(tty_write_room); /** - * tty_driver_flush_buffer - discard internal buffer - * @tty: terminal + * tty_driver_flush_buffer - discard internal buffer + * @tty: terminal * - * Discard the internal output buffer for this device. If no method - * is provided then either the buffer cannot be hardware flushed or - * there is no buffer driver side. + * Discard the internal output buffer for this device. If no method is provided, + * then either the buffer cannot be hardware flushed or there is no buffer + * driver side. */ void tty_driver_flush_buffer(struct tty_struct *tty) { @@ -91,50 +87,47 @@ void tty_driver_flush_buffer(struct tty_struct *tty) EXPORT_SYMBOL(tty_driver_flush_buffer); /** - * tty_unthrottle - flow control - * @tty: terminal + * tty_unthrottle - flow control + * @tty: terminal * - * Indicate that a tty may continue transmitting data down the stack. - * Takes the termios rwsem to protect against parallel throttle/unthrottle - * and also to ensure the driver can consistently reference its own - * termios data at this point when implementing software flow control. + * Indicate that a @tty may continue transmitting data down the stack. Takes + * the &tty_struct->termios_rwsem to protect against parallel + * throttle/unthrottle and also to ensure the driver can consistently reference + * its own termios data at this point when implementing software flow control. * - * Drivers should however remember that the stack can issue a throttle, - * then change flow control method, then unthrottle. + * Drivers should however remember that the stack can issue a throttle, then + * change flow control method, then unthrottle. */ - void tty_unthrottle(struct tty_struct *tty) { down_write(&tty->termios_rwsem); if (test_and_clear_bit(TTY_THROTTLED, &tty->flags) && tty->ops->unthrottle) tty->ops->unthrottle(tty); - tty->flow_change = 0; + tty->flow_change = TTY_FLOW_NO_CHANGE; up_write(&tty->termios_rwsem); } EXPORT_SYMBOL(tty_unthrottle); /** - * tty_throttle_safe - flow control - * @tty: terminal + * tty_throttle_safe - flow control + * @tty: terminal * - * Indicate that a tty should stop transmitting data down the stack. - * tty_throttle_safe will only attempt throttle if tty->flow_change is - * TTY_THROTTLE_SAFE. Prevents an accidental throttle due to race - * conditions when throttling is conditional on factors evaluated prior to - * throttling. + * Indicate that a @tty should stop transmitting data down the stack. + * tty_throttle_safe() will only attempt throttle if @tty->flow_change is + * %TTY_THROTTLE_SAFE. Prevents an accidental throttle due to race conditions + * when throttling is conditional on factors evaluated prior to throttling. * - * Returns 0 if tty is throttled (or was already throttled) + * Returns: %true if @tty is throttled (or was already throttled) */ - -int tty_throttle_safe(struct tty_struct *tty) +bool tty_throttle_safe(struct tty_struct *tty) { - int ret = 0; + bool ret = true; mutex_lock(&tty->throttle_mutex); if (!tty_throttled(tty)) { if (tty->flow_change != TTY_THROTTLE_SAFE) - ret = 1; + ret = false; else { set_bit(TTY_THROTTLED, &tty->flags); if (tty->ops->throttle) @@ -147,25 +140,24 @@ int tty_throttle_safe(struct tty_struct *tty) } /** - * tty_unthrottle_safe - flow control - * @tty: terminal + * tty_unthrottle_safe - flow control + * @tty: terminal * - * Similar to tty_unthrottle() but will only attempt unthrottle - * if tty->flow_change is TTY_UNTHROTTLE_SAFE. Prevents an accidental - * unthrottle due to race conditions when unthrottling is conditional - * on factors evaluated prior to unthrottling. + * Similar to tty_unthrottle() but will only attempt unthrottle if + * @tty->flow_change is %TTY_UNTHROTTLE_SAFE. Prevents an accidental unthrottle + * due to race conditions when unthrottling is conditional on factors evaluated + * prior to unthrottling. * - * Returns 0 if tty is unthrottled (or was already unthrottled) + * Returns: %true if @tty is unthrottled (or was already unthrottled) */ - -int tty_unthrottle_safe(struct tty_struct *tty) +bool tty_unthrottle_safe(struct tty_struct *tty) { - int ret = 0; + bool ret = true; mutex_lock(&tty->throttle_mutex); if (tty_throttled(tty)) { if (tty->flow_change != TTY_UNTHROTTLE_SAFE) - ret = 1; + ret = false; else { clear_bit(TTY_THROTTLED, &tty->flags); if (tty->ops->unthrottle) @@ -178,14 +170,14 @@ int tty_unthrottle_safe(struct tty_struct *tty) } /** - * tty_wait_until_sent - wait for I/O to finish - * @tty: tty we are waiting for - * @timeout: how long we will wait + * tty_wait_until_sent - wait for I/O to finish + * @tty: tty we are waiting for + * @timeout: how long we will wait * - * Wait for characters pending in a tty driver to hit the wire, or - * for a timeout to occur (eg due to flow control) + * Wait for characters pending in a tty driver to hit the wire, or for a + * timeout to occur (eg due to flow control). * - * Locking: none + * Locking: none */ void tty_wait_until_sent(struct tty_struct *tty, long timeout) @@ -231,16 +223,15 @@ static void unset_locked_termios(struct tty_struct *tty, const struct ktermios * } /** - * tty_termios_copy_hw - copy hardware settings - * @new: New termios - * @old: Old termios + * tty_termios_copy_hw - copy hardware settings + * @new: new termios + * @old: old termios * - * Propagate the hardware specific terminal setting bits from - * the old termios structure to the new one. This is used in cases - * where the hardware does not support reconfiguration or as a helper - * in some cases where only minimal reconfiguration is supported + * Propagate the hardware specific terminal setting bits from the @old termios + * structure to the @new one. This is used in cases where the hardware does not + * support reconfiguration or as a helper in some cases where only minimal + * reconfiguration is supported. */ - void tty_termios_copy_hw(struct ktermios *new, const struct ktermios *old) { /* The bits a dumb device handles in software. Smart devices need @@ -253,14 +244,15 @@ void tty_termios_copy_hw(struct ktermios *new, const struct ktermios *old) EXPORT_SYMBOL(tty_termios_copy_hw); /** - * tty_termios_hw_change - check for setting change - * @a: termios - * @b: termios to compare + * tty_termios_hw_change - check for setting change + * @a: termios + * @b: termios to compare * - * Check if any of the bits that affect a dumb device have changed - * between the two termios structures, or a speed change is needed. + * Check if any of the bits that affect a dumb device have changed between the + * two termios structures, or a speed change is needed. + * + * Returns: %true if change is needed */ - bool tty_termios_hw_change(const struct ktermios *a, const struct ktermios *b) { if (a->c_ispeed != b->c_ispeed || a->c_ospeed != b->c_ospeed) @@ -272,11 +264,10 @@ bool tty_termios_hw_change(const struct ktermios *a, const struct ktermios *b) EXPORT_SYMBOL(tty_termios_hw_change); /** - * tty_get_char_size - get size of a character - * @cflag: termios cflag value + * tty_get_char_size - get size of a character + * @cflag: termios cflag value * - * Get the size (in bits) of a character depending on @cflag's %CSIZE - * setting. + * Returns: size (in bits) of a character depending on @cflag's %CSIZE setting */ unsigned char tty_get_char_size(unsigned int cflag) { @@ -295,13 +286,14 @@ unsigned char tty_get_char_size(unsigned int cflag) EXPORT_SYMBOL_GPL(tty_get_char_size); /** - * tty_get_frame_size - get size of a frame - * @cflag: termios cflag value + * tty_get_frame_size - get size of a frame + * @cflag: termios cflag value * - * Get the size (in bits) of a frame depending on @cflag's %CSIZE, %CSTOPB, - * and %PARENB setting. The result is a sum of character size, start and - * stop bits -- one bit each -- second stop bit (if set), and parity bit - * (if set). + * Get the size (in bits) of a frame depending on @cflag's %CSIZE, %CSTOPB, and + * %PARENB setting. The result is a sum of character size, start and stop bits + * -- one bit each -- second stop bit (if set), and parity bit (if set). + * + * Returns: size (in bits) of a frame depending on @cflag's setting. */ unsigned char tty_get_frame_size(unsigned int cflag) { @@ -319,16 +311,15 @@ unsigned char tty_get_frame_size(unsigned int cflag) EXPORT_SYMBOL_GPL(tty_get_frame_size); /** - * tty_set_termios - update termios values - * @tty: tty to update - * @new_termios: desired new value + * tty_set_termios - update termios values + * @tty: tty to update + * @new_termios: desired new value * - * Perform updates to the termios values set on this terminal. - * A master pty's termios should never be set. + * Perform updates to the termios values set on this @tty. A master pty's + * termios should never be set. * - * Locking: termios_rwsem + * Locking: &tty_struct->termios_rwsem */ - int tty_set_termios(struct tty_struct *tty, struct ktermios *new_termios) { struct ktermios old_termios; @@ -441,18 +432,19 @@ __weak int kernel_termios_to_user_termios(struct termios __user *u, #endif /* TCGETS2 */ /** - * set_termios - set termios values for a tty - * @tty: terminal device - * @arg: user data - * @opt: option information + * set_termios - set termios values for a tty + * @tty: terminal device + * @arg: user data + * @opt: option information + * + * Helper function to prepare termios data and run necessary other functions + * before using tty_set_termios() to do the actual changes. * - * Helper function to prepare termios data and run necessary other - * functions before using tty_set_termios to do the actual changes. + * Locking: called functions take &tty_struct->ldisc_sem and + * &tty_struct->termios_rwsem locks * - * Locking: - * Called functions take ldisc and termios_rwsem locks + * Returns: 0 on success, an error otherwise */ - static int set_termios(struct tty_struct *tty, void __user *arg, int opt) { struct ktermios tmp_termios; @@ -624,16 +616,16 @@ static void set_sgflags(struct ktermios *termios, int flags) } /** - * set_sgttyb - set legacy terminal values - * @tty: tty structure - * @sgttyb: pointer to old style terminal structure + * set_sgttyb - set legacy terminal values + * @tty: tty structure + * @sgttyb: pointer to old style terminal structure + * + * Updates a terminal from the legacy BSD style terminal information structure. * - * Updates a terminal from the legacy BSD style terminal information - * structure. + * Locking: &tty_struct->termios_rwsem * - * Locking: termios_rwsem + * Returns: 0 on success, an error otherwise */ - static int set_sgttyb(struct tty_struct *tty, struct sgttyb __user *sgttyb) { int retval; @@ -735,14 +727,17 @@ static int set_ltchars(struct tty_struct *tty, struct ltchars __user *ltchars) #endif /** - * tty_change_softcar - carrier change ioctl helper - * @tty: tty to update - * @enable: enable/disable CLOCAL + * tty_change_softcar - carrier change ioctl helper + * @tty: tty to update + * @enable: enable/disable %CLOCAL + * + * Perform a change to the %CLOCAL state and call into the driver layer to make + * it visible. + * + * Locking: &tty_struct->termios_rwsem. * - * Perform a change to the CLOCAL state and call into the driver - * layer to make it visible. All done with the termios rwsem + * Returns: 0 on success, an error otherwise */ - static int tty_change_softcar(struct tty_struct *tty, bool enable) { int ret = 0; @@ -762,16 +757,15 @@ static int tty_change_softcar(struct tty_struct *tty, bool enable) } /** - * tty_mode_ioctl - mode related ioctls - * @tty: tty for the ioctl - * @cmd: command - * @arg: ioctl argument + * tty_mode_ioctl - mode related ioctls + * @tty: tty for the ioctl + * @cmd: command + * @arg: ioctl argument * - * Perform non line discipline specific mode control ioctls. This - * is designed to be called by line disciplines to ensure they provide - * consistent mode setting. + * Perform non-line discipline specific mode control ioctls. This is designed + * to be called by line disciplines to ensure they provide consistent mode + * setting. */ - int tty_mode_ioctl(struct tty_struct *tty, unsigned int cmd, unsigned long arg) { struct tty_struct *real_tty; |