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: Jiri Slaby <jslaby@suse.cz> Link: https://lore.kernel.org/r/20211126081611.11001-7-jslaby@suse.cz Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Jiri Slaby
Greg Kroah-Hartman
Родитель
630bf86d15
Коммит
0c6119f9f7
|
|
@ -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;
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче