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 andthen flip the buffer, so that the data are passed toline discipline for further processing.
Flip Buffer Management¶
Parameters
structtty_port*porttty port
u8**charsreturn pointer for character write area
size_tsizedesired 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 thebuffer. There is no guarantee the buffer is a DMA target!
Return
the length available and buffer pointer (chars) to the space whichis now allocated and accounted for as ready for normal characters.
- size_ttty_ldisc_receive_buf(structtty_ldisc*ld,constu8*p,constu8*f,size_tcount)¶
forward data to line discipline
Parameters
structtty_ldisc*ldline discipline to process input
constu8*pchar buffer
constu8*fTTY_NORMAL,TTY_BREAK, etc. flags buffersize_tcountnumber of bytes to process
Description
Callers other thanflush_to_ldisc() need to exclude the kworker fromconcurrent use of the line discipline, seepaste_selection().
Return
the number of bytes processed.
Parameters
structtty_port*porttty port to push
Description
Queue a push of the terminal flip buffers to the line discipline. Can becalled from IRQ/atomic context.
In the event of the queue being busy for flipping the work will be held offand retried later.
- size_ttty_insert_flip_string_fixed_flag(structtty_port*port,constu8*chars,u8flag,size_tsize)¶
add characters to the tty buffer
Parameters
structtty_port*porttty port
constu8*charscharacters
u8flagflag value for each character
size_tsizesize
Description
Queue a series of bytes to the tty buffering. All the characters passed aremarked with the supplied flag.
Return
the number added.
- size_ttty_insert_flip_string_flags(structtty_port*port,constu8*chars,constu8*flags,size_tsize)¶
add characters to the tty buffer
Parameters
structtty_port*porttty port
constu8*charscharacters
constu8*flagsflag bytes
size_tsizesize
Description
Queue a series of bytes to the tty buffering. For each character the flagsarray indicates the status of the character.
Return
the number added.
Parameters
structtty_port*porttty port
u8chcharacter
u8flagflag byte
Description
Queue a single bytech to the tty buffering, with an optional flag.
Other Functions¶
Parameters
structtty_port*porttty port owning the flip buffer
Return
the # of bytes which can be written by the driver without reachingthe buffer limit.
Note
this does not guarantee that memory is available to write the returned# of bytes (usetty_prepare_flip_string() to pre-allocate if memoryguarantee is required).
Parameters
structtty_port*porttty port to change
intlimitmemory 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
structtty_port*porttty port owning the flip buffer
Description
Guarantees safe use of thetty_ldisc_ops.receive_buf() method by excludingthe buffer work and any pending flush from using the flip buffer. Data cancontinue to be added concurrently to the flip buffer from the driver side.
See alsotty_buffer_unlock_exclusive().
Parameters
structtty_port*porttty port owning the flip buffer
Description
The buffer work is restarted if there is data in the flip buffer.
See alsotty_buffer_lock_exclusive().
Internal Functions¶
Parameters
structtty_port*porttty port to free from
Description
Remove all the buffers pending on a tty whether queued with data or in thefree ring. Must be called when the tty is no longer in use.
Parameters
structtty_port*porttty port
size_tsizedesired size (characters)
Description
Allocate a new tty buffer to hold the desired number of characters. Weround our buffers off in 256 character chunks to get better allocationbehaviour.
Return
NULL if out of memory or the allocation would exceed the perdevice queue.
Parameters
structtty_port*porttty port owning the buffer
structtty_buffer*bthe buffer to free
Description
Free a tty buffer, or add it to the free list according to our internalstrategy.
- voidtty_buffer_flush(structtty_struct*tty,structtty_ldisc*ld)¶
flush full tty buffers
Parameters
structtty_struct*ttytty to flush
structtty_ldisc*ldoptional ldisc ptr (must be referenced)
Description
Flush all the buffers containing receive data. Ifld !=NULL, flush theldisc input buffer.
Locking: takes buffer lock to ensure single-threaded flip buffer ‘consumer’.
Parameters
structtty_port*porttty port
size_tsizesize desired
boolflagsbuffer has to store flags along character data
Description
Make at leastsize bytes of linear space available for the tty buffer.
Will change over to a new buffer if the current buffer is encoded asTTY_NORMAL (so has no flags buffer) and the new buffer requires a flagsbuffer.
Return
the size we managed to find.
- voidflush_to_ldisc(structwork_struct*work)¶
flush data from buffer to ldisc
Parameters
structwork_struct*worktty structure passed from work queue.
Description
This routine is called out of the software interrupt to flush data from thebuffer chain to the line discipline.
Thereceive_buf() method is single threaded for each tty instance.
Locking: takes buffer lock to ensure single-threaded flip buffer ‘consumer’.
- inttty_insert_flip_string_and_push_buffer(structtty_port*port,constu8*chars,size_tsize)¶
add characters to the tty buffer and push
Parameters
structtty_port*porttty port
constu8*charscharacters
size_tsizesize
Description
The function combinestty_insert_flip_string() andtty_flip_buffer_push()with the exception of properly holding theport->lock.
To be used only internally (by pty currently).
Return
the number added.
Parameters
structtty_port*porttty port to initialise
Description
Set up the initial state of the buffer management for a tty device. Must becalled before the other tty buffer functions are used.