Difference between revisions of "TTY Driver"

From Embedded Xinu
Jump to navigation Jump to search
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Image:TtyUartInteraction.png|frame|Diagram of the interaction between hardware, UART driver, TTY driver, and user application.]]The TTY driver is built on top of the UART driver (or other TTY appropriate hardware).  The driver is responsible for sending and receiving character input between a user level application, such as the XINU [[Shell]], and a char-oriented hardware driver.  Line buffering and cooking are the two primary responsibilities for the new TTY driver.
+
[[Image:TtyDriver.png|right|450px]]The TTY driver serves as an intermediary device between hardware device drivers and user applications to provide line buffering of input and cooking of input and output. The driver is purely software oriented and makes no direct communication with physical hardware.  Instead, the TTY driver relies on an underlying device driver to communicate directly with the hardware.  The [[Shell|XINU Shell]] utilizes a TTY device to line buffer and cook user input read from the [[UART_Driver|UART]].
  
== Conceptual structure ==
+
== Open & Close ==
[[Image:TtyDriver.png]]
+
Open associates a TTY with an underlying char-oriented hardware device. The underlying device driver must provide both getc and putc functions for the TTY to obtain input and send output character by character.  The device should already be opened and initialized before the TTY is opened.  When a TTY is opened, its device control block, input buffer, and flags are initialized.  No input flags are set when a TTY device is opened.  The TTY_ONLCR output flag is set when a TTY device is opened. 
  
== Functionality ==
+
Close disassociates a TTY from its underlying device and resets the TTY's device control block.
=== Initialize ===
 
''This section needs updating''
 
  
=== Open ===
+
== Read ==
  struct tty *ttyAlloc(void)
+
The TTY driver reads characters from an underlying device driver using the devices getc function.  Input is first buffered in the TTY driver's circular  buffer before being copied to the user buffer supplied as a parameter in the <code>ttyRead</code> function call.
  DEVCALL ttyOpen(struct dentry *pdev, va_list ap)
 
  
Open associates a TTY with an underlying char-oriented hardware driver.  The underlying device should already be initialized.  A TTY is allocated from the available TTY devices and its circular buffers are initialized.
+
The <code>ttyRead</code> function begins by checking the <code>ieof</code> flag to determine if the EOF character (Control+D) was read during the last call to <code>ttyRead</code>  If the <code>ieof</code> flag is set, the function returns the <code>EOF</code> constant, defined in <code>stddef.h</code>.  <code>EOF</code> is only returned once for each EOF character read by the TTY driver.  A call made to <code>ttyRead</code> after <code>EOF</code> was returned, will result in an attempt to read more characters from the underlying device driver.
  
=== Close ===
+
If the <code>TTY_IRAW</code> flag is set, the TTY driver performs no line buffering or line editing (input cooking).  The user buffer is first filled from any data remaining in the TTY driver's input buffer from the last <code>ttyRead</code> call.  The remaining portion of the user supplied buffer is filled by reading characters from the underlying device driver.
  DEVCALL ttyClose(struct dentry *pdev)
 
  
Close disasociates a TTY from its underlying device.  It also makes the TTY available to be allocated to other processes.
+
The TTY driver performs line buffering and line editing (input cooking) when the <code>TTY_IRAW</code> flag is not set.  Characters are read from the underlying device driver until a line delimiter is read or the TTY driver's input buffer is fullLines may be terminated with the newline (LF or <code>'\n'</code>) or end of file (EOF or ASCII character 0x04) characters.  If the <code>TTY_ECHO</code> flag is set, each character is output as it is read.
  
=== Read ===
+
Special handling is required for some characters to perform line editing (input cooking).  If the TTY driver's input buffer contains characters, backspace (BS or <code>'\b'</code>) and delete (DEL or ASCII character 0x7F) remove the last character from the TTY's input buffer.  The newline and carriage return (CR or <code>'\r'</code>) characters are cooked if certain input flags are set. The end of file character causes the <code>ieof</code> flag to be set.  Any other unprintable characters are ignored.
The TTY driver reads input in lines. Input is buffered in a secondary buffer and cooked (if not in RAW mode) until the secondary buffer is full or a carriage return (CR or '\r') or line feed (LF or '\n') is encountered. When pressing the 'Enter' key on the keyboard, xinu-console is configured to send '\n' to the backend.
 
  
When not in RAW input mode, the TTY driver cooks backspace (BS or '\b') and delete (DEL or ASCII character 0x7F). BS and DEL remove the last character from the secondary buffer, and decrease the secondary buffer count by one. When in RAW mode, set using "control(device id, TTC_IRAW, TRUE, NULL)," and BS and DEL are ignored.
+
After a line of input is buffered in the TTY's device driver, the user supplied buffer is filled from the TTY's input buffer. If the end of file character was the only character read, the <code>EOF</code> constant is returned. Otherwise, the number of characters read into the user buffer is returned.
  
The TTY driver sets a flag if EOF (EOT or Control-D) or CBREAK (ETX or Control-C) are seen in the input ready from the secondary buffer. The flags can be checked using "control(device id, TTC_EOF, NULL NULL)" or "control(device id, TTC_CBREAK, NULL NULL)" for EOF and CBREAK, respectively. When not in RAW mode the EOT character is converted to the EOF constant (-2) defined in XINU.
+
The TTY driver has the following input flags:
 +
* <code>TTY_IRAW</code> - reads input unbuffered and uncooked
 +
* <code>TTY_INLCR</code> - converts '\n' to '\r'
 +
* <code>TTY_IGNCR</code> - ignores '\r'
 +
* <code>TTY_ICRNL</code> - converts '\r' to '\n'
 +
* <code>TTY_ECHO</code> - echoes input
  
''This section needs updating''
+
== Write ==
 +
The TTY driver does not buffer output; it writes characters directly to an underlying device driver.  The TTY driver cooks newlines (LF or <code>'\n'</code>) and carriage returns (CR or <code>'\r'</code>) if certain output flags are set.
  
=== Write ===
+
The TTY driver has the following output flags:
When not in RAW output mode, the TTY driver cooks line feeds (also known as LF, \n, or ASCII character 0x0A) and carriage returns (also known as CR, \r, or ASCII character 0x0D). The ttyWrite function always ensures CRLF is written to the output buffer when any of the following escape sequences are to be written: \r, \n, or \r\n. When in RAW mode, set using "control(device id, TTC_ORAW, TRUE, NULL)", CR and LF are not cooked.
+
* <code>TTY_ONLCR</code> - converts '\n' to '\r\n'
 +
* <code>TTY_OCRNL</code> - converts '\r' to '\n'
  
''This section needs updating''
+
== Control ==
 
+
The TTY driver has four control functions: two to set and clear input flags and two to set and clear output flags. Each of control functions returns the previous state of the flags being changed.
=== Control ===
 
  DEVCALL ttyControl(struct dentry *pdev, int func, unsigned char arg1, unsigned char arg2)
 
 
 
  /* ttyControl() functions */
 
  #define TTY_IOC_SETIFLAG 0x0020  /* set input flags         */
 
  #define TTY_IOC_CLRIFLAG 0x0021  /* clear input flags         */
 
  #define TTY_IOC_GETIFLAG 0x0022  /* get input flags              */
 
  #define TTY_IOC_SETOFLAG 0x0023  /* set output flags            */
 
  #define TTY_IOC_CLROFLAG 0x0024  /* clear output flags           */
 
  #define TTY_IOC_GETOFLAG 0x0025 /* get output flags            */
 
  #define TTY_IOC_EOF            0x0026  /* check if EOF in input        */
 
  #define TTY_IOC_CBREAK          0x0027  /* check if CBREAK in input    */
 
 
 
  /* TTY input flags */
 
  #define TTY_IFLAG_RAW 0x0001  /* do raw input                */
 
  #define TTY_IFLAG_ECHO         0x0002  /* echo input         */
 
  #define TTY_IFLAG_CBREAK 0x0004  /* have seen Break (Control-C)  */
 
  #define TTY_IFLAG_EOF 0x0008 /* have seen EOF (Control-D)    */
 
  /* TTY output flags */
 
  #define TTY_OFLAG_RAW 0x0001 /* do raw output */
 
 
 
''This section needs updating''
 
  
 
== See also ==
 
== See also ==
* [[Input Cooking]]
 
 
* [[UART Driver]]
 
* [[UART Driver]]

Latest revision as of 19:58, 23 May 2008

TtyDriver.png

The TTY driver serves as an intermediary device between hardware device drivers and user applications to provide line buffering of input and cooking of input and output. The driver is purely software oriented and makes no direct communication with physical hardware. Instead, the TTY driver relies on an underlying device driver to communicate directly with the hardware. The XINU Shell utilizes a TTY device to line buffer and cook user input read from the UART.

Open & Close

Open associates a TTY with an underlying char-oriented hardware device. The underlying device driver must provide both getc and putc functions for the TTY to obtain input and send output character by character. The device should already be opened and initialized before the TTY is opened. When a TTY is opened, its device control block, input buffer, and flags are initialized. No input flags are set when a TTY device is opened. The TTY_ONLCR output flag is set when a TTY device is opened.

Close disassociates a TTY from its underlying device and resets the TTY's device control block.

Read

The TTY driver reads characters from an underlying device driver using the devices getc function. Input is first buffered in the TTY driver's circular buffer before being copied to the user buffer supplied as a parameter in the ttyRead function call.

The ttyRead function begins by checking the ieof flag to determine if the EOF character (Control+D) was read during the last call to ttyRead If the ieof flag is set, the function returns the EOF constant, defined in stddef.h. EOF is only returned once for each EOF character read by the TTY driver. A call made to ttyRead after EOF was returned, will result in an attempt to read more characters from the underlying device driver.

If the TTY_IRAW flag is set, the TTY driver performs no line buffering or line editing (input cooking). The user buffer is first filled from any data remaining in the TTY driver's input buffer from the last ttyRead call. The remaining portion of the user supplied buffer is filled by reading characters from the underlying device driver.

The TTY driver performs line buffering and line editing (input cooking) when the TTY_IRAW flag is not set. Characters are read from the underlying device driver until a line delimiter is read or the TTY driver's input buffer is full. Lines may be terminated with the newline (LF or '\n') or end of file (EOF or ASCII character 0x04) characters. If the TTY_ECHO flag is set, each character is output as it is read.

Special handling is required for some characters to perform line editing (input cooking). If the TTY driver's input buffer contains characters, backspace (BS or '\b') and delete (DEL or ASCII character 0x7F) remove the last character from the TTY's input buffer. The newline and carriage return (CR or '\r') characters are cooked if certain input flags are set. The end of file character causes the ieof flag to be set. Any other unprintable characters are ignored.

After a line of input is buffered in the TTY's device driver, the user supplied buffer is filled from the TTY's input buffer. If the end of file character was the only character read, the EOF constant is returned. Otherwise, the number of characters read into the user buffer is returned.

The TTY driver has the following input flags:

  • TTY_IRAW - reads input unbuffered and uncooked
  • TTY_INLCR - converts '\n' to '\r'
  • TTY_IGNCR - ignores '\r'
  • TTY_ICRNL - converts '\r' to '\n'
  • TTY_ECHO - echoes input

Write

The TTY driver does not buffer output; it writes characters directly to an underlying device driver. The TTY driver cooks newlines (LF or '\n') and carriage returns (CR or '\r') if certain output flags are set.

The TTY driver has the following output flags:

  • TTY_ONLCR - converts '\n' to '\r\n'
  • TTY_OCRNL - converts '\r' to '\n'

Control

The TTY driver has four control functions: two to set and clear input flags and two to set and clear output flags. Each of control functions returns the previous state of the flags being changed.

See also