tty(D3oddi)

Syntax

   #include <sys/tty.h>

Routines referenced by line discipline zero members

   int ttclose(struct tty tp);			                / l_close /
   

   int ttin(struct tty tp, int code);		                / l_input /
   

   int ttioctl(strcut tty tp, int cmd, int arg, int mode);	/ l_ioctl /
   

   int ttopen(struct tty tp);			                / l_open /
   

   int ttout(struct tty tp);			                / l_output /
   

   int ttread(struct tty tp);			                / l_read /
   

   int ttwrite(struct tty tp);			                / l_write /

tty utility routines

   void ttinit(struct tty tp);
   

   int ttrdchk(struct tty tp);
   

   int ttselect(struct tty tp, int rw);
   

   int ttyflush(struct tty tp, int rdwrt);
   

   int ttywait(struct tty tp);

Description

Arguments

tp

Pointer to the tty data structure associated with the device being accessed. This structure is defined in the <sys/tty.h> header file. xxproc is registered as the t_proc member, and the line discipline as the t_line member of the tty structure. The device driver declares an array of tty structures as large as the possible number of minor devices for the device.

code

Used by ttin. It is set to L_BREAK to handle a break interrupt on the line.

cmd, arg, and mode

Used by ttioctl to control I/O.

rw

Used with ttselect; it is set to SELREAD for non-blocking reads, or to SELWRITE for non-blocking writes.

rdwrt

Used by ttyflush to indicate which queues to release to the free list. Set to FREAD to release the input queues, t_canq and t_rawq; set FWRITE to release the output queue, t_outq.

Return values

ttrdchk returns 1 if there are characters present in the read queues, t_rawq or t_canq. It returns 0 (zero) if no characters are present.

Usage

The following TTY routines are referenced by line discipline zero members. Multithreaded drivers should call these routines through the run_ld(D3oddi) function.

ttclose

Referenced by line discipline zero member l_close. It is called by the driver's xxclose routine to remove access to a TTY device for a user process calling close(S) . The following actions occur:

• ttclose waits for t_outq to empty to the output device.

• The character blocks associated with input queues t_canq and t_rawq are released.

• ISOPEN is cleared from the t_state member of the tty structure pointed to by tp.

• XCLUDE is cleared from the t_lflag member of the tty structure pointed to by tp.

• The terminal's process group is cleared.

ttin

Referenced by line discipline zero member l_input. It is called from a driver's xxintr routine to process and move characters placed in t_rbuf to the raw character queue, t_rawq. ttin handles signals issued from the keyboard such as SIGINT or SIGQUIT, echoing of input characters to the display, and mapping of input characters to character sequences including international character mapping.

If the value of code is passed as L_BREAK to indicate a break interrupt on the line, ttin takes the following actions:

• SIGINT is sent to the process group.

• The character blocks associated with input and output queues t_rawq, t_canq and t_outq are released.

The raw buffer is then tested to see if any characters require processing. ttin then does the following:

• Scan codes are mapped to characters on input.

• Channel mapping is performed.

• The mapping implied by any of the following flags set in t_iflag; ICRNL, IGNCR, INLCR, or IUCLC is performed.

• xxproc is called, with command argument T_BLOCK, to stop input from the input device if t_rawq exceeds its high water mark. TBLOCK is also set in t_state. ttin will flush the input buffers altogether if t_rawq exceeds the absolute high water mark. This prevents all the ccblocks being taken by the device if its output cannot be stopped.

• Mapping for the international character set is performed.

• If ISIG is set in t_lflag, the characters in t_rbuf are checked against the Interrupt, Quit, Suspend and Switch control characters in the array t_cc (a member of the tty structure pointed to by tp).

  If the character is Interrupt or Quit, SIGINT or SIGQUIT is sent to the process group and the input and output queues are conditionally flushed. (Flushing is not performed if NOFLSH is set in t_lflag.)

  If the character is Suspend, SIGTSTP is sent to the process group and only the input queues are conditionally flushed.

  If the character is Switch, both input and output queues are conditionally flushed and xxproc is called, with command argument T_SWTCH, to inform the driver.

• If ICANON is set in t_lflag (for canonical input processing), each character in the input buffer, t_rbuf, is processed in turn.

  The character is checked against the Erase, Line Kill, End of File, and End of Line characters in t_cc.

  Backspace and Space are echoed to the output queue, t_outq, for the Erase character if ECHOE is set in t_lflag.

  Line Kill is echoed to the output queue for the Line Kill character if ECHOK is set in t_lflag

  If ECHO is set in t_lflag, the character is echoed to the output queue. (Erase is echoed as Back Space and Line Kill as Newline.)

  t_delct is set to the number of End of Line or End of File characters in t_rbuf.

• If ICANON is not set in t_lflag, ttin checks whether raw input is possible. If so, its sets t_delct to the number of characters in t_rbuf.

  If ECHO is set in t_lflag, the characters in t_rbuf are echoed to the output queue, t_outq.

• xxproc is called, with the command argument set to T_OUTPUT, to ask the driver to start output.

• Any processes waiting for input are woken if t_delct is non-zero.

• Finally, the character is put onto t_rawq.

ttioctl

Referenced by line discipline zero member l_ioctl. The driver's xxioctl routine calls ttiocom(D3oddi) which in turn calls ttioctl to allocate, deallocate, or move the contents of terminal buffers. The cmd argument to ttioctl can take the following values:

• LDOPEN

• LDCLOSE

• LDCHG

• LDSMAP

• LDGMAP

• LDNMAP

• TCGETSC

• TCSETSC

• GIO_STRMAP

• PIO_STRMAP

• GIO_KEYMAP

• PIO_KEYMAP

• GETKEY

• SETKEY

• KBIO_GETMODE

• KBIO_SETMODE

• KDGKBMODE

• KDSKBMODE

• KDGKBSTATE

• KDGKBMAP

• KDGKBLOCK

ttopen

Referenced by line discipline zero member l_open. It is called from a driver's xxopen routine in response to a call to open(S) to open a serial line. The following actions are performed:

• The controlling terminal is set for the process group.

• If XCLUDE bit is set in t_lflag and the user is not root, EBUSY is set in u.u_error and errno; ttopen then returns.

• Input is initiated by calling ttioctl with command argument LDOPEN.

• The TTY state is set to ISOPEN.

ttout

Referenced by line discipline zero member l_output. A driver's xxproc routine calls ttout to move data to the output buffer. ttout performs the following actions:

• Data is moved from the output queue, t_outq, to the output buffer, t_tbuf.

• Any output post-processing is performed, such as adding a time delay if OPOST is set in t_oflag. A time delay on output is indicated by the two character sequence; QESC followed by QESC ORed with the delay in clock ticks.

• Any processes waiting for output are woken.

ttread

Referenced by line discipline zero member l_read. It is called from a driver's xxread routine in response to a call to read(S) to read data from a device. ttread performs the following actions:

• Perform POSIX SIGTTIN handling.

• If ICANON is set in t_lflag, data in t_rawq is processed for Backslash (escaped characters), Backspace, Line Kill, and End of File. The data is transferred to the canonical input queue, t_canq.

• If ICANON is not set, the VMIN and VTIME elements of t_cc are managed for handling raw input.

• At most u.u_count characters from the canonical input queue (ICANON set), or from the raw inut queue (ICANON not set), are moved to the user address space.

• If necessary, xxproc is called with command argument T_UNBLOCK to request more input from the device, and TBLOCK is unset in t_state.

ttwrite

is referenced by line discipline zero member l_write. It is called by a driver's xxwrite routine in response to a call to write(S) to write data to a device. ttwrite performs the following actions:

• u.u_error is set to EIO if there is no carrier or the process group has been orphaned; ttwrite then returns immediately.

• SIGTTOU is sent to all processes in the current process group if the write occurs in the background.

• ttwrite checks if the number of characters in the output queue, t_outq, exceeds the high water mark for output. If so, call the driver's xxproc routine with command argument set to T_OUTPUT. The process is then put to sleep on the address of t_outq at a priority of TTOPRI.

  If a signal is sent to the sleeping process, control returns to the calling user process and sets the EINTR error in u.u_error and errno.

• The data is copied from user address space to the output queue, t_outq.

  u.u_error is set to EFAULT if a paging fault occurs while attempting to copy the data from user space.

  u.u_base and u.u_count are updated to reflect the amount of data transferred.

• The driver's xxproc routine is called with command argument T_OUTPUT to output the data to the device.

The following are tty utility routines which may be called from a driver:

ttinit

Initializes the tty structure for line discipline zero. The following members of the tty structure are initialized:

• The line discipline index (t_line), terminal input control (t_iflag), terminal output control (t_oflag), and line discipline terminal control (t_lflag) are set to 0 (zero).

• Channel mapping data is initialized.

• Scan code data is initialized, if in use.

• The terminal hardware control (t_cflag) is set to 9600 baud (SSPEED), 8 bits (CS8), enable receiver (CREAD), and hang up on last close (HUPCL).

ttrdchk

Returns a non-zero value (1) if there are characters to be read from the input queue, t_rawq or t_canq (depending on whether ICANON is set in t_lflag) , and the device carrier is present (CARR_ON is set in t_state).

Otherwise, ttrdchk returns 0 (zero).

ttselect

Ensures that one-byte read or write can be performed without blocking. (Blocking puts the process to sleep until I/O can be satisfied.)

Set the argument rw to SELREAD to disable blocking for reading; to SELWRITE to disable blocking for writing.

Do not call sleep(D3oddi) before calling ttselect.

Do not call ttselect from an interrupt routine.

ttyflush

Releases character blocks to the free list from the write queue, t_outq, or from the two read queues, t_canq and t_rawq.

Set FREAD in the argument rdwrt to release the read queues; FWRITE to release the write queue. These two values may be ORed together to free all three queues.

Releasing the write queue causes the driver's xxproc routine to be called with the command argument T_WFLUSH set. If OASLP is set in t_state, any processes sleeping on the address of t_outq are woken and OASLP unset. If TTIOW is set in t_state, any processes sleeping on the address of t_oflag are woken and TTIOW unset.

Releasing the read buffers causes the driver's xxproc routine to be called with the command argument T_RFLUSH set. If IASLP is set in t_state, any processes sleeping on the address of t_rawq are woken and IASLP unset.

ttywait

waits for the UART to empty of all data. On entry, if characters are present in t_outq, or t_state is set to BUSY or TIMEOUT, then t_state is ORed with TTIOW and the process is put to sleep on the address of t_oflag at TTOPRI. On receiving a wakeup signal, control returns to the user process and EINTR is set in u.u_error and errno in the user program.

Usage

Context and synchronization

ttin and ttout

Non-blockable, interrupt, user, or blockable context.

ttclose, ttioctl (called via ttiocom), ttopen, ttread and ttwrite

User context.

ttinit, ttrdchk, ttselect, ttyflush and ttywait

User context.

ttioctl, ttwrite, ttselect and ttyflush all set priority level 5 internally using spltty.

Hardware applicability

Version applicability

SVR5 DDI compatibility

References