TTY Buffer¶
Here, we document functions for taking care of tty buffer and their flipping. Drivers are supposed to fill the buffer by one of those functions below and then flip the buffer, so that the data are passed to line discipline for further processing.
Flip Buffer Management¶
-
int
tty_insert_flip_string_fixed_flag(struct tty_port *port, const unsigned char *chars, char flag, size_t size)¶ add characters to the tty buffer
Parameters
struct tty_port *port- tty port
const unsigned char *chars- characters
char flag- flag value for each character
size_t size- size
Description
Queue a series of bytes to the tty buffering. All the characters passed are marked with the supplied flag.
Return
the number added.
-
int
tty_insert_flip_string_flags(struct tty_port *port, const unsigned char *chars, const char *flags, size_t size)¶ add characters to the tty buffer
Parameters
struct tty_port *port- tty port
const unsigned char *chars- characters
const char *flags- flag bytes
size_t size- size
Description
Queue a series of bytes to the tty buffering. For each character the flags array indicates the status of the character.
Return
the number added.
-
int
__tty_insert_flip_char(struct tty_port *port, unsigned char ch, char flag)¶ add one character to the tty buffer
Parameters
struct tty_port *port- tty port
unsigned char ch- character
char flag- flag byte
Description
Queue a single byte ch to the tty buffering, with an optional flag. This is the slow path of tty_insert_flip_char().
-
int
tty_prepare_flip_string(struct tty_port *port, unsigned char **chars, size_t size)¶ make room for characters
Parameters
struct tty_port *port- tty port
unsigned char **chars- return pointer for character write area
size_t size- desired size
Description
Prepare a block of space in the buffer for data.
This is used for drivers that need their own block copy routines into the buffer. There is no guarantee the buffer is a DMA target!
Return
the length available and buffer pointer (chars) to the space which is now allocated and accounted for as ready for normal characters.
-
int
tty_ldisc_receive_buf(struct tty_ldisc *ld, const unsigned char *p, const char *f, int count)¶ forward data to line discipline
Parameters
struct tty_ldisc *ld- line discipline to process input
const unsigned char *p- char buffer
const char *fTTY_NORMAL,TTY_BREAK, etc. flags bufferint count- number of bytes to process
Description
Callers other than flush_to_ldisc() need to exclude the kworker from
concurrent use of the line discipline, see paste_selection().
Return
the number of bytes processed.
Parameters
struct tty_port *port- tty port to push
Description
Queue a push of the terminal flip buffers to the line discipline. Can be called from IRQ/atomic context.
In the event of the queue being busy for flipping the work will be held off and retried later.
Other Functions¶
Parameters
struct tty_port *port- tty port owning the flip buffer
Return
the # of bytes which can be written by the driver without reaching the buffer limit.
Note
this does not guarantee that memory is available to write the returned
# of bytes (use tty_prepare_flip_string() to pre-allocate if memory
guarantee is required).
Parameters
struct tty_port *port- tty port to change
int limit- memory limit to set
Description
Change the tty buffer memory limit.
Must be called before the other tty buffer functions are used.
Buffer Locking¶
These are used only in special circumstances. Avoid them.
Parameters
struct tty_port *port- tty port owning the flip buffer
Description
Guarantees safe use of the tty_ldisc_ops.receive_buf() method by excluding
the buffer work and any pending flush from using the flip buffer. Data can
continue to be added concurrently to the flip buffer from the driver side.
See also tty_buffer_unlock_exclusive().
Parameters
struct tty_port *port- tty port owning the flip buffer
Description
The buffer work is restarted if there is data in the flip buffer.
See also tty_buffer_lock_exclusive().
Internal Functions¶
Parameters
struct tty_port *port- tty port to free from
Description
Remove all the buffers pending on a tty whether queued with data or in the free ring. Must be called when the tty is no longer in use.
Parameters
struct tty_port *port- tty port
size_t size- desired size (characters)
Description
Allocate a new tty buffer to hold the desired number of characters. We round our buffers off in 256 character chunks to get better allocation behaviour.
Return
NULL if out of memory or the allocation would exceed the per
device queue.
Parameters
struct tty_port *port- tty port owning the buffer
struct tty_buffer *b- the buffer to free
Description
Free a tty buffer, or add it to the free list according to our internal strategy.
-
void
tty_buffer_flush(struct tty_struct *tty, struct tty_ldisc *ld)¶ flush full tty buffers
Parameters
struct tty_struct *tty- tty to flush
struct tty_ldisc *ld- optional ldisc ptr (must be referenced)
Description
Flush all the buffers containing receive data. If ld != NULL, flush the
ldisc input buffer.
Locking: takes buffer lock to ensure single-threaded flip buffer ‘consumer’.
-
int
__tty_buffer_request_room(struct tty_port *port, size_t size, int flags)¶ grow tty buffer if needed
Parameters
struct tty_port *port- tty port
size_t size- size desired
int flags- buffer flags if new buffer allocated (default = 0)
Description
Make at least size bytes of linear space available for the tty buffer.
Will change over to a new buffer if the current buffer is encoded as
TTY_NORMAL (so has no flags buffer) and the new buffer requires a flags
buffer.
Return
the size we managed to find.
-
void
flush_to_ldisc(struct work_struct *work)¶ flush data from buffer to ldisc
Parameters
struct work_struct *work- tty structure passed from work queue.
Description
This routine is called out of the software interrupt to flush data from the buffer chain to the line discipline.
The receive_buf() method is single threaded for each tty instance.
Locking: takes buffer lock to ensure single-threaded flip buffer ‘consumer’.
Parameters
struct tty_port *port- tty port to initialise
Description
Set up the initial state of the buffer management for a tty device. Must be called before the other tty buffer functions are used.