mirrors/linux-stable
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git synced 2024-10-05 00:20:32 +00:00
Code Issues Releases Wiki Activity

tty: add kernel-doc for tty_port

Browse source 
tty_port used to have only short comments along its members. Convert
them into proper kernel-doc comments in front of the structure. And add
some more explanation to them where needed.

The whole structure purpose and handling is documented at the end too --
some pieces of preexisting text moved to this place.

Signed-off-by: Jiri Slaby <jslaby@suse.cz>
Link: https://lore.kernel.org/r/20211126081611.11001-3-jslaby@suse.cz
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Jiri Slaby 2021-11-26 09:15:50 +01:00 committed by Greg Kroah-Hartman
parent 18e6c0751c
commit 61c83addb7
1 changed files with 70 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

104
include/linux/tty_port.h
View file

@ -7,17 +7,6 @@
#include <linux/tty_buffer.h>
#include <linux/wait.h>
/*
* Port level information. Each device keeps its own port level information
* so provide a common structure for those ports wanting to use common support
* routines.
*
* The tty port has a different lifetime to the tty so must be kept apart.
* In addition be careful as tty -> port mappings are valid for the life
* of the tty object but in many cases port -> tty mappings are valid only
* until a hangup so don't use the wrong path.
*/
struct attribute_group;
struct tty_driver;
struct tty_port;
@ -48,30 +37,77 @@ struct tty_port_client_operations {
extern const struct tty_port_client_operations tty_port_default_client_ops;
/**
* struct tty_port -- port level information
*
* @buf: buffer for this port, locked internally
* @tty: back pointer to &struct tty_struct, valid only if the tty is open. Use
* tty_port_tty_get() to obtain it (and tty_kref_put() to release).
* @itty: internal back pointer to &struct tty_struct. Avoid this. It should be
* eliminated in the long term.
* @ops: tty port operations (like activate, shutdown), see &struct
* tty_port_operations
* @client_ops: tty port client operations (like receive_buf, write_wakeup).
* By default, tty_port_default_client_ops is used.
* @lock: lock protecting @tty
* @blocked_open: # of procs waiting for open in tty_port_block_til_ready()
* @count: usage count
* @open_wait: open waiters queue (waiting e.g. for a carrier)
* @delta_msr_wait: modem status change queue (waiting for MSR changes)
* @flags: user TTY flags (%ASYNC_)
* @iflags: internal flags (%TTY_PORT_)
* @console: when set, the port is a console
* @mutex: locking, for open, shutdown and other port operations
* @buf_mutex: @xmit_buf alloc lock
* @xmit_buf: optional xmit buffer used by some drivers
* @close_delay: delay in jiffies to wait when closing the port
* @closing_wait: delay in jiffies for output to be sent before closing
* @drain_delay: set to zero if no pure time based drain is needed else set to
* size of fifo
* @kref: references counter. Reaching zero calls @ops->destruct() if non-%NULL
* or frees the port otherwise.
* @client_data: pointer to private data, for @client_ops
*
* Each device keeps its own port level information. &struct tty_port was
* introduced as a common structure for such information. As every TTY device
* shall have a backing tty_port structure, every driver can use these members.
*
* The tty port has a different lifetime to the tty so must be kept apart.
* In addition be careful as tty -> port mappings are valid for the life
* of the tty object but in many cases port -> tty mappings are valid only
* until a hangup so don't use the wrong path.
*
* Tty port shall be initialized by tty_port_init() and shut down either by
* tty_port_destroy() (refcounting not used), or tty_port_put() (refcounting).
*
* There is a lot of helpers around &struct tty_port too. To name the most
* significant ones: tty_port_open(), tty_port_close() (or
* tty_port_close_start() and tty_port_close_end() separately if need be), and
* tty_port_hangup(). These call @ops->activate() and @ops->shutdown() as
* needed.
*/
struct tty_port {
struct tty_bufhead buf; /* Locked internally */
struct tty_struct *tty; /* Back pointer */
struct tty_struct *itty; /* internal back ptr */
const struct tty_port_operations *ops; /* Port operations */
const struct tty_port_client_operations *client_ops; /* Port client operations */
spinlock_t lock; /* Lock protecting tty field */
int blocked_open; /* Waiting to open */
int count; /* Usage count */
wait_queue_head_t open_wait; /* Open waiters */
wait_queue_head_t delta_msr_wait; /* Modem status change */
unsigned long flags; /* User TTY flags ASYNC_ */
unsigned long iflags; /* Internal flags TTY_PORT_ */
unsigned char console:1; /* port is a console */
struct mutex mutex; /* Locking */
struct mutex buf_mutex; /* Buffer alloc lock */
unsigned char *xmit_buf; /* Optional buffer */
unsigned int close_delay; /* Close port delay */
unsigned int closing_wait; /* Delay for output */
int drain_delay; /* Set to zero if no pure time
based drain is needed else
set to size of fifo */
struct kref kref; /* Ref counter */
void *client_data;
struct tty_bufhead buf;
struct tty_struct *tty;
struct tty_struct *itty;
const struct tty_port_operations *ops;
const struct tty_port_client_operations *client_ops;
spinlock_t lock;
int blocked_open;
int count;
wait_queue_head_t open_wait;
wait_queue_head_t delta_msr_wait;
unsigned long flags;
unsigned long iflags;
unsigned char console:1;
struct mutex mutex;
struct mutex buf_mutex;
unsigned char *xmit_buf;
unsigned int close_delay;
unsigned int closing_wait;
int drain_delay;
struct kref kref;
void *client_data;
};
/* tty_port::iflags bits -- use atomic bit ops */