Commit 0c6119f9 authored by Jiri Slaby's avatar Jiri Slaby Committed by Greg Kroah-Hartman
Browse files

tty: add kernel-doc for tty_ldisc_ops 



tty_ldisc_ops structure was already partially documented in a standalone
comment in the header beginning.

Move it right before the structure and reformat it so it complies to
kernel-doc. That way, we can include it in Documentation/ later in this
series.

And add the documentation for the members where missing too.

Signed-off-by: default avatarJiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-7-jslaby@suse.cz


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

include/linux/tty_ldisc.h

+130 −129
Original line number Diff line number Diff line
@@ -4,126 +4,6 @@ 


struct tty_struct;



/*

 * This structure defines the interface between the tty line discipline

 * implementation and the tty routines.  The following routines can be

 * defined; unless noted otherwise, they are optional, and can be

 * filled in with a null pointer.

 *

 * int	(*open)(struct tty_struct *);

 *

 *	This function is called when the line discipline is associated

 *	with the tty.  The line discipline can use this as an

 *	opportunity to initialize any state needed by the ldisc routines.

 *

 * void	(*close)(struct tty_struct *);

 *

 *	This function is called when the line discipline is being

 *	shutdown, either because the tty is being closed or because

 *	the tty is being changed to use a new line discipline

 *

 * void	(*flush_buffer)(struct tty_struct *tty);

 *

 *	This function instructs the line discipline to clear its

 *	buffers of any input characters it may have queued to be

 *	delivered to the user mode process.

 *

 * ssize_t (*read)(struct tty_struct * tty, struct file * file,

 *		   unsigned char * buf, size_t nr);

 *

 *	This function is called when the user requests to read from

 *	the tty.  The line discipline will return whatever characters

 *	it has buffered up for the user.  If this function is not

 *	defined, the user will receive an EIO error.

 *

 * ssize_t (*write)(struct tty_struct * tty, struct file * file,

 *		    const unsigned char * buf, size_t nr);

 *

 *	This function is called when the user requests to write to the

 *	tty.  The line discipline will deliver the characters to the

 *	low-level tty device for transmission, optionally performing

 *	some processing on the characters first.  If this function is

 *	not defined, the user will receive an EIO error.

 *

 * int	(*ioctl)(struct tty_struct *tty, unsigned int cmd, unsigned long arg);

 *

 *	This function is called when the user requests an ioctl which

 *	is not handled by the tty layer or the low-level tty driver.

 *	It is intended for ioctls which affect line discpline

 *	operation.  Note that the search order for ioctls is (1) tty

 *	layer, (2) tty low-level driver, (3) line discpline.  So a

 *	low-level driver can "grab" an ioctl request before the line

 *	discpline has a chance to see it.

 *

 * int	(*compat_ioctl)(struct tty_struct *tty, unsigned int cmd,

 *			unsigned long arg);

 *

 *	Process ioctl calls from 32-bit process on 64-bit system

 *

 *	NOTE: only ioctls that are neither "pointer to compatible

 *	structure" nor tty-generic.  Something private that takes

 *	an integer or a pointer to wordsize-sensitive structure

 *	belongs here, but most of ldiscs will happily leave

 *	it NULL.

 *

 * void	(*set_termios)(struct tty_struct *tty, struct ktermios * old);

 *

 *	This function notifies the line discpline that a change has

 *	been made to the termios structure.

 *

 * int	(*poll)(struct tty_struct * tty, struct file * file,

 *		  poll_table *wait);

 *

 *	This function is called when a user attempts to select/poll on a

 *	tty device.  It is solely the responsibility of the line

 *	discipline to handle poll requests.

 *

 * void	(*receive_buf)(struct tty_struct *, const unsigned char *cp,

 *		       char *fp, int count);

 *

 *	This function is called by the low-level tty driver to send

 *	characters received by the hardware to the line discpline for

 *	processing.  <cp> is a pointer to the buffer of input

 *	character received by the device.  <fp> is a pointer to a

 *	pointer of flag bytes which indicate whether a character was

 *	received with a parity error, etc. <fp> may be NULL to indicate

 *	all data received is TTY_NORMAL.

 *

 * void	(*write_wakeup)(struct tty_struct *);

 *

 *	This function is called by the low-level tty driver to signal

 *	that line discpline should try to send more characters to the

 *	low-level driver for transmission.  If the line discpline does

 *	not have any more data to send, it can just return. If the line

 *	discipline does have some data to send, please arise a tasklet

 *	or workqueue to do the real data transfer. Do not send data in

 *	this hook, it may leads to a deadlock.

 *

 * int (*hangup)(struct tty_struct *)

 *

 *	Called on a hangup. Tells the discipline that it should

 *	cease I/O to the tty driver. Can sleep. The driver should

 *	seek to perform this action quickly but should wait until

 *	any pending driver I/O is completed.

 *

 * void (*dcd_change)(struct tty_struct *tty, unsigned int status)

 *

 *	Tells the discipline that the DCD pin has changed its status.

 *	Used exclusively by the N_PPS (Pulse-Per-Second) line discipline.

 *

 * int	(*receive_buf2)(struct tty_struct *, const unsigned char *cp,

 *			char *fp, int count);

 *

 *	This function is called by the low-level tty driver to send

 *	characters received by the hardware to the line discpline for

 *	processing.  <cp> is a pointer to the buffer of input

 *	character received by the device.  <fp> is a pointer to a

 *	pointer of flag bytes which indicate whether a character was

 *	received with a parity error, etc. <fp> may be NULL to indicate

 *	all data received is TTY_NORMAL.

 *	If assigned, prefer this function for automatic flow control.

 */



#include <linux/fs.h>

#include <linux/wait.h>

#include <linux/atomic.h>
@@ -175,7 +55,128 @@ int ldsem_down_write_nested(struct ld_semaphore *sem, int subclass, 
		ldsem_down_write(sem, timeout)

#endif





/**

 * struct tty_ldisc_ops - ldisc operations

 *

 * @name: name of this ldisc rendered in /proc/tty/ldiscs

 * @num: ``N_*`` number (%N_TTY, %N_HDLC, ...) reserved to this ldisc

 *

 * @open: ``int ()(struct tty_struct *tty)``

 *

 *	This function is called when the line discipline is associated with the

 *	@tty. The line discipline can use this as an opportunity to initialize

 *	any state needed by the ldisc routines.

 *

 * @close: ``void ()(struct tty_struct *tty)``

 *

 *	This function is called when the line discipline is being shutdown,

 *	either because the @tty is being closed or because the @tty is being

 *	changed to use a new line discipline

 *

 * @flush_buffer: ``void ()(struct tty_struct *tty)``

 *

 *	This function instructs the line discipline to clear its buffers of any

 *	input characters it may have queued to be delivered to the user mode

 *	process.

 *

 * @read: ``ssize_t ()(struct tty_struct *tty, struct file *file,

 *		unsigned char *buf, size_t nr)``

 *

 *	This function is called when the user requests to read from the @tty.

 *	The line discipline will return whatever characters it has buffered up

 *	for the user. If this function is not defined, the user will receive

 *	an %EIO error.

 *

 * @write: ``ssize_t ()(struct tty_struct *tty, struct file *file,

 *		const unsigned char *buf, size_t nr)``

 *

 *	This function is called when the user requests to write to the @tty.

 *	The line discipline will deliver the characters to the low-level tty

 *	device for transmission, optionally performing some processing on the

 *	characters first. If this function is not defined, the user will

 *	receive an %EIO error.

 *

 * @ioctl: ``int ()(struct tty_struct *tty, unsigned int cmd,

 *		unsigned long arg)``

 *

 *	This function is called when the user requests an ioctl which is not

 *	handled by the tty layer or the low-level tty driver. It is intended

 *	for ioctls which affect line discpline operation.  Note that the search

 *	order for ioctls is (1) tty layer, (2) tty low-level driver, (3) line

 *	discpline. So a low-level driver can "grab" an ioctl request before

 *	the line discpline has a chance to see it.

 *

 * @compat_ioctl: ``int ()(struct tty_struct *tty, unsigned int cmd,

 *		unsigned long arg)``

 *

 *	Process ioctl calls from 32-bit process on 64-bit system.

 *

 *	Note that only ioctls that are neither "pointer to compatible

 *	structure" nor tty-generic.  Something private that takes an integer or

 *	a pointer to wordsize-sensitive structure belongs here, but most of

 *	ldiscs will happily leave it %NULL.

 *

 * @set_termios: ``void ()(struct tty_struct *tty, struct ktermios *old)``

 *

 *	This function notifies the line discpline that a change has been made

 *	to the termios structure.

 *

 * @poll: ``int ()(struct tty_struct *tty, struct file *file,

 *		  struct poll_table_struct *wait)``

 *

 *	This function is called when a user attempts to select/poll on a @tty

 *	device. It is solely the responsibility of the line discipline to

 *	handle poll requests.

 *

 * @hangup: ``void ()(struct tty_struct *tty)``

 *

 *	Called on a hangup. Tells the discipline that it should cease I/O to

 *	the tty driver. Can sleep. The driver should seek to perform this

 *	action quickly but should wait until any pending driver I/O is

 *	completed.

 *

 * @receive_buf: ``void ()(struct tty_struct *tty, const unsigned char *cp,

 *		       const char *fp, int count)``

 *

 *	This function is called by the low-level tty driver to send characters

 *	received by the hardware to the line discpline for processing. @cp is

 *	a pointer to the buffer of input character received by the device. @fp

 *	is a pointer to an array of flag bytes which indicate whether a

 *	character was received with a parity error, etc. @fp may be %NULL to

 *	indicate all data received is %TTY_NORMAL.

 *

 * @write_wakeup: ``void ()(struct tty_struct *tty)``

 *

 *	This function is called by the low-level tty driver to signal that line

 *	discpline should try to send more characters to the low-level driver

 *	for transmission. If the line discpline does not have any more data to

 *	send, it can just return. If the line discipline does have some data to

 *	send, please arise a tasklet or workqueue to do the real data transfer.

 *	Do not send data in this hook, it may lead to a deadlock.

 *

 * @dcd_change: ``void ()(struct tty_struct *tty, unsigned int status)``

 *

 *	Tells the discipline that the DCD pin has changed its status. Used

 *	exclusively by the %N_PPS (Pulse-Per-Second) line discipline.

 *

 * @receive_buf2: ``int ()(struct tty_struct *tty, const unsigned char *cp,

 *			const char *fp, int count)``

 *

 *	This function is called by the low-level tty driver to send characters

 *	received by the hardware to the line discpline for processing. @cp is a

 *	pointer to the buffer of input character received by the device.  @fp

 *	is a pointer to an array of flag bytes which indicate whether a

 *	character was received with a parity error, etc. @fp may be %NULL to

 *	indicate all data received is %TTY_NORMAL. If assigned, prefer this

 *	function for automatic flow control.

 *

 * @owner: module containting this ldisc (for reference counting)

 *

 * This structure defines the interface between the tty line discipline

 * implementation and the tty routines. The above routines can be defined.

 * Unless noted otherwise, they are optional, and can be filled in with a %NULL

 * pointer.

 */

struct tty_ldisc_ops {

	char	*name;

	int	num;
@@ -183,8 +184,8 @@ struct tty_ldisc_ops { 
	/*

	 * The following routines are called from above.

	 */

	int	(*open)(struct tty_struct *);

	void	(*close)(struct tty_struct *);

	int	(*open)(struct tty_struct *tty);

	void	(*close)(struct tty_struct *tty);

	void	(*flush_buffer)(struct tty_struct *tty);

	ssize_t	(*read)(struct tty_struct *tty, struct file *file,

			unsigned char *buf, size_t nr,
@@ -196,18 +197,18 @@ struct tty_ldisc_ops { 
	int	(*compat_ioctl)(struct tty_struct *tty, unsigned int cmd,

			unsigned long arg);

	void	(*set_termios)(struct tty_struct *tty, struct ktermios *old);

	__poll_t (*poll)(struct tty_struct *, struct file *,

			     struct poll_table_struct *);

	__poll_t (*poll)(struct tty_struct *tty, struct file *file,

			     struct poll_table_struct *wait);

	void	(*hangup)(struct tty_struct *tty);



	/*

	 * The following routines are called from below.

	 */

	void	(*receive_buf)(struct tty_struct *, const unsigned char *cp,

	void	(*receive_buf)(struct tty_struct *tty, const unsigned char *cp,

			       const char *fp, int count);

	void	(*write_wakeup)(struct tty_struct *);

	void	(*dcd_change)(struct tty_struct *, unsigned int);

	int	(*receive_buf2)(struct tty_struct *, const unsigned char *cp,

	void	(*write_wakeup)(struct tty_struct *tty);

	void	(*dcd_change)(struct tty_struct *tty, unsigned int status);

	int	(*receive_buf2)(struct tty_struct *tty, const unsigned char *cp,

				const char *fp, int count);



	struct  module *owner;