Commit 3b1a696b authored by Jiri Slaby (SUSE)'s avatar Jiri Slaby (SUSE) Committed by Greg Kroah-Hartman
Browse files

tty: fix up and plug in tty_ioctl kernel-doc 



The ioctl helpers are well documented, except they are not plugged in
the Documentation. So fix up the minor issues in the kernel-doc and plug
it in.

The minor issues include:
* bad \t on every line (sphinx misinterprets the description otherwise)
* missing colon after Return
* superfluous \n after the comment
* make some struct members and constants a hyperlink
* and so on

Perhaps better to use --word-diff if one wants to see the "real"
changes.

Signed-off-by: default avatar"Jiri Slaby (SUSE)" <jirislaby@kernel.org>
Link: https://lore.kernel.org/r/20230919085156.1578-9-jirislaby@kernel.org


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 5b4f9cf3

Documentation/driver-api/tty/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -36,6 +36,7 @@ In-detail description of the named TTY structures is in separate documents: 
   tty_struct

   tty_ldisc

   tty_buffer

   tty_ioctl

   tty_internals



Writing TTY Driver

Documentation/driver-api/tty/tty_ioctl.rst

0 → 100644
+7 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



=================

TTY IOCTL Helpers

=================



.. kernel-doc:: drivers/tty/tty_ioctl.c

drivers/tty/tty_ioctl.c

+107 −111
Original line number Diff line number Diff line
@@ -38,16 +38,13 @@ 
#define TERMIOS_TERMIO	BIT(2)

#define TERMIOS_OLD	BIT(3)





/**

 * 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)
@@ -60,13 +57,12 @@ EXPORT_SYMBOL(tty_chars_in_buffer); 
 * 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)
@@ -79,9 +75,9 @@ EXPORT_SYMBOL(tty_write_room); 
 * 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)

{
@@ -94,15 +90,14 @@ EXPORT_SYMBOL(tty_driver_flush_buffer); 
 * 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);
@@ -118,13 +113,12 @@ EXPORT_SYMBOL(tty_unthrottle); 
 * 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 true if tty is throttled (or was already throttled)

 * Returns: %true if @tty is throttled (or was already throttled)

 */

bool tty_throttle_safe(struct tty_struct *tty)

{
@@ -149,12 +143,12 @@ bool tty_throttle_safe(struct tty_struct *tty) 
 * 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 true if tty is unthrottled (or was already unthrottled)

 * Returns: %true if @tty is unthrottled (or was already unthrottled)

 */

bool tty_unthrottle_safe(struct tty_struct *tty)

{
@@ -180,8 +174,8 @@ bool tty_unthrottle_safe(struct tty_struct *tty) 
 * @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

 */
@@ -230,15 +224,14 @@ 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

 * @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
@@ -255,10 +248,11 @@ EXPORT_SYMBOL(tty_termios_copy_hw); 
 * @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)
@@ -273,8 +267,7 @@ EXPORT_SYMBOL(tty_termios_hw_change); 
 * 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)

{
@@ -296,10 +289,11 @@ EXPORT_SYMBOL_GPL(tty_get_char_size); 
 * 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)

{
@@ -321,12 +315,11 @@ EXPORT_SYMBOL_GPL(tty_get_frame_size); 
 * @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;
@@ -444,13 +437,14 @@ __weak int kernel_termios_to_user_termios(struct termios __user *u, 
 * @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 ldisc and termios_rwsem locks

 * Locking: called functions take &tty_struct->ldisc_sem and

 * &tty_struct->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;
@@ -626,12 +620,12 @@ static void set_sgflags(struct ktermios *termios, int flags) 
 * @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,12 +729,15 @@ static int set_ltchars(struct tty_struct *tty, struct ltchars __user *ltchars) 
/**

 * tty_change_softcar - carrier change ioctl helper

 * @tty: tty to update

 *	@enable: enable/disable CLOCAL

 * @enable: enable/disable %CLOCAL

 *

 * Perform a change to the %CLOCAL state and call into the driver layer to make

 * it visible.

 *

 *	Perform a change to the CLOCAL state and call into the driver

 *	layer to make it visible. All done with the termios rwsem

 * Locking: &tty_struct->termios_rwsem.

 *

 * Returns: 0 on success, an error otherwise

 */



static int tty_change_softcar(struct tty_struct *tty, bool enable)

{

	int ret = 0;
@@ -765,11 +762,10 @@ static int tty_change_softcar(struct tty_struct *tty, bool enable) 
 * @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;