Hardware Emulation Module

If a stream supports a terminal interface, a driver or module that understands all ioctls is needed to support terminal semantics (specified by termio(7I) and termiox(7I). If there is no hardware driver that understands all ioctl commands downstream from the ldterm module, a hardware emulation module must be placed downstream from the line-discipline module. The function of the hardware emulation module is to understand and acknowledge the ioctls that may be sent to the process at the stream head and to mediate the passage of control information downstream. Together, the line-discipline module and the hardware emulation module behave as if there was an actual terminal on that stream.

The hardware emulation module is necessary whenever there is no TTY driver at the end of the stream. For example, the module is necessary in a pseudo-TTY situation where there is process-to-process communication on one system (discussed in "STREAMS-based Pseudo-Terminal Subsystem"), or in a network situation where a termio interface is expected (for example, remote login) but there is no TTY driver on the stream.

Most of the actions taken by the hardware emulation module are the same regardless of the underlying architecture. However, there are some actions that are different, depending on whether the communication is local or remote and whether the underlying transport protocol is used to support the remote connection.

Each hardware emulation module has an open, close, read queue put procedure, and write queue put procedure.

The hardware emulation module does the following:

Processes, if appropriate, and acknowledges receipt of the following ioctls on its write queue by sending an M_IOCACK message back upstream: TCSETA, TCSETAW, TCSETAF, TCSETS, TCSETSW, TCSETSF, TCGETA, TCGETS, and TCSBRK.
Acknowledges the Extended UNIX Code (EUC) ioctl(2).
If the environment supports windowing, it acknowledges the windowing TIOCSWINSZ, TIOCGWINSZ, and JWINSIZE ioctl(2)s. If the environment does not support windowing, an M_IOCNAK message is sent upstream.
If another ioctl(2) is received on its write queue, it sends an M_IOCNAK message upstream. It doesn't pass any unrecognized ioctls to the slave driver.
When the hardware emulation module receives an M_IOCTL message of type TCSBRK on its write queue, it sends an M_IOCACK message upstream and the appropriate message downstream. For example, an M_BREAK message could be sent downstream.
When the hardware emulation module receives an M_IOCTL message on its write queue to set the baud rate to 0 (TCSETAW with CBAUD set to B0), it sends an M_IOCACK message upstream and an appropriate message downstream; for networking situations this will probably be an M_PROTO message, which is a TPI T_DISCON_REQ message requesting the transport provider to disconnect.
All other messages (M_DATA, for instance) not mentioned here are passed to the next module or driver in the stream.

The hardware emulation module processes messages in a way consistent with the driver that exists.

STREAMS-based Pseudo-Terminal Subsystem

The STREAMS-based pseudo-terminal subsystem provides the user with an interface that is identical to the STREAMS-based terminal subsystem described earlier in this chapter. The pseudo-terminal subsystem (pseudo-TTY) supports a pair of STREAMS-based devices called the master device and slave device. The slave device provides processes with an interface that is identical to the terminal interface. However, where devices that provide the terminal interface have some kind of hardware device behind them, the slave device has another process manipulating it through the master half of the pseudo-terminal. Anything written on the master device is given to the slave as an input, and anything written on the slave device is presented as an input on the master side.

Figure C-2 illustrates the architecture of the STREAMS-based pseudo-terminal subsystem. The master driver (called ptm) is accessed through the clone driver and is the controlling part of the system. The slave driver (called pts) works with the line discipline module and the hardware emulation module to provide a terminal interface to the user process. An optional packetizing module (called pckt) is also provided. It can be pushed on the master side to support packet mode (this is discussed in "Packet Mode").

The number of pseudo-TTY devices that can be installed on a system depends on available memory.

Line-Discipline Module

In the pseudo-TTY subsystem, the line discipline module is pushed on the slave side to present the user with the terminal interface.

ldterm(7M) can turn off the processing of the c_iflag, c_oflag, and c_lflag fields to allow processing to take place elsewhere. The ldterm(7M) module can also turn off all canonical processing when it receives an M_CTL message with the MC_NO_CANON command to support remote mode. Although ldterm(7M) passes through messages without processing them, the appropriate flags are set when an ioctl(2), such as TCGETA or TCGETS, is issued to indicate that canonical processing is being performed.

Figure C-2 Pseudo-TTY Subsystem Architecture

Pseudo-TTY Emulation Module: `ptem`

Because the pseudo-TTY subsystem has no hardware driver downstream from the ldterm(7M) module to process the terminal ioctl(2) calls, another module that understands the ioctl commands is placed downstream from the ldterm(7M). This module, ptem(7M), processes all of the terminal ioctl(2)calls and mediates the passage of control information downstream.

ldterm(7M) and ptem(7M) together behave like a real terminal. Since there is no real terminal or modem in the pseudo-TTY subsystem, some of the ioctl(2) commands are ignored and cause only an acknowledgment of the command. ptem(7M) keeps track of the terminal parameters set by the various set commands such as TCSETA or TCSETAW but does not usually perform any action. For example, if a "set" ioctl is called, none of the bits in the c_cflag field of termio(7I) has any effect on the pseudo-terminal unless the baud rate is set to 0. Setting the baud rate to 0 has the effect of hanging up the pseudo-terminal.

The pseudo-terminal does not recognize parity, so none of the flags in the c_iflag that control the processing of parity errors have any effect. The delays specified in the c_oflag field are also not supported.

ptem(7M) does the following:

Processes, if appropriate, and acknowledges receipt of the following ioctls on its write queue by sending an M_IOCACK message back upstream: TCSETA, TCSETAW, TCSETAF, TCSETS, TCSETSW, TCSETSF, TCGETA, TCGETS, and TCSBRK.
Keeps track of the window size; information needed for the TIOCSWINSZ, TIOCGWINSZ, and JWINSIZE ioctl.
When it receives an ioctl, other than for TIOCSWINSZ, TIOCGWINSZ, or JWINSIZE on its write queue, it sends an M_IOCNAK message upstream.
It passes downstream the following ioctls after processing them: TCSETA, TCSETAW, TCSETAF, TCSETS, TCSETSW, TCSETSF, TCSBRK, and TIOCSWINSZ.
Frees any M_IOCNAK messages it receives on its read queue in case the pckt module (pckt(7M) (described in the section "Packet Mode") is not on the pseudo-terminal subsystem and the TCSETA, TCSETAW, TCSETAF, TCSETS, TCSETSW, TCSETSF, TCSBRK, or TIOCSWINSZioctls get to the master's stream head which then sends an M_IOCNAK message.
In its open routine, ptem sends an M_SETOPTS message upstream requesting allocation of a controlling TTY.
When ptem receives an M_IOCTL message of type TCSBRK on its read queue, it sends an M_IOCACK message downstream and an M_BREAK message upstream.
When ptem receives an ioctl(2) message on its write queue to set the baud rate to 0 (TCSETAW with CBAUD set to B0), it sends an M_IOCACK message upstream and a zero-length message downstream.
When ptem receives an M_IOCTL of type TIOCSIGNAL on its read queue, it sends an M_IOCACK downstream and an M_PCSIG upstream, where the signal number is the same as in the M_IOCTL message.
When ptem receives an M_IOCTL of type TIOCREMOTE on its read queue, it sends an M_IOCACK message downstream and the appropriate M_CTL message upstream to enable or disable canonical processing.
When ptem receives an M_DELAY message on its read or write queue, it discards the message and does not act on it.
When ptem receives an M_IOCTL of type JWINSIZE on its write queue, and if the values in its jwinsize structure are not zero, it sends an M_IOCACK message upstream with the jwinsize structure. If the values are zero, it sends an M_IOCNAK message upstream.
When ptem receives an M_IOCTL message of type TIOCGWINSZ on its write queue and the values in the winsize structure are not zero, it sends an M_IOCACK message upstream with the winsize structure. If the values are zero, it sends an M_IOCNAK message upstream. It also saves the information passed to it in the winsize structure and sends a STREAMS signal message for signal SIGWINCH upstream to the slave process if the size changed.
When ptem(7M) receives an M_IOCTL message with type TIOCGWINSZ on its read queue and the values in the winsize structure are not zero, it sends an M_IOCACK message downstream with the winsize structure. If the values are zero, it sends an M_IOCNAK message downstream. It also saves the information passed to it in the winsize structure and sends a STREAMS signal message for signal SIGWINCH upstream to the slave process if the size changed.
All other messages are passed to the next module or driver.


C. STREAMS-Based Terminal Subsystem Overview of Terminal Subsystem Line-Discipline Module EUC Handling in `ldterm`


	Hardware Emulation Module If a stream supports a terminal interface, a driver or module that understands all `ioctls` is needed to support terminal semantics (specified by `termio`(7I) and `termiox`(7I). If there is no hardware driver that understands all `ioctl` commands downstream from the `ldterm` module, a hardware emulation module must be placed downstream from the line-discipline module. The function of the hardware emulation module is to understand and acknowledge the `ioctl`s that may be sent to the process at the stream head and to mediate the passage of control information downstream. Together, the line-discipline module and the hardware emulation module behave as if there was an actual terminal on that stream. The hardware emulation module is necessary whenever there is no TTY driver at the end of the stream. For example, the module is necessary in a pseudo-TTY situation where there is process-to-process communication on one system (discussed in "STREAMS-based Pseudo-Terminal Subsystem"), or in a network situation where a `termio` interface is expected (for example, remote login) but there is no TTY driver on the stream. Most of the actions taken by the hardware emulation module are the same regardless of the underlying architecture. However, there are some actions that are different, depending on whether the communication is local or remote and whether the underlying transport protocol is used to support the remote connection. Each hardware emulation module has an `open`, `close`, `read` queue `put` procedure, and write queue `put` procedure. The hardware emulation module does the following: Processes, if appropriate, and acknowledges receipt of the following `ioctls` on its write queue by sending an `M_IOCACK` message back upstream: `TCSETA`, `TCSETAW`, `TCSETAF`, `TCSETS`, `TCSETSW`, `TCSETSF`, `TCGETA`, `TCGETS`, and `TCSBRK`. Acknowledges the Extended UNIX Code (EUC) `ioctl`(2). If the environment supports windowing, it acknowledges the windowing `TIOCSWINSZ`, `TIOCGWINSZ`, and `JWINSIZE` `ioctl`(2)s. If the environment does not support windowing, an `M_IOCNAK` message is sent upstream. If another `ioctl`(2) is received on its write queue, it sends an `M_IOCNAK` message upstream. It doesn't pass any unrecognized `ioctl`s to the slave driver. When the hardware emulation module receives an `M_IOCTL` message of type `TCSBRK` on its write queue, it sends an `M_IOCACK` message upstream and the appropriate message downstream. For example, an `M_BREAK` message could be sent downstream. When the hardware emulation module receives an `M_IOCTL` message on its write queue to set the baud rate to 0 (`TCSETAW` with `CBAUD` set to `B0`), it sends an `M_IOCACK` message upstream and an appropriate message downstream; for networking situations this will probably be an M_PROTO message, which is a `TPI T_DISCON_REQ` message requesting the transport provider to disconnect. All other messages (`M_DATA`, for instance) not mentioned here are passed to the next module or driver in the stream. The hardware emulation module processes messages in a way consistent with the driver that exists. STREAMS-based Pseudo-Terminal Subsystem The STREAMS-based pseudo-terminal subsystem provides the user with an interface that is identical to the STREAMS-based terminal subsystem described earlier in this chapter. The pseudo-terminal subsystem (pseudo-TTY) supports a pair of STREAMS-based devices called the master device and slave device. The slave device provides processes with an interface that is identical to the terminal interface. However, where devices that provide the terminal interface have some kind of hardware device behind them, the slave device has another process manipulating it through the master half of the pseudo-terminal. Anything written on the master device is given to the slave as an input, and anything written on the slave device is presented as an input on the master side. Figure C-2 illustrates the architecture of the STREAMS-based pseudo-terminal subsystem. The master driver (called `ptm`) is accessed through the clone driver and is the controlling part of the system. The slave driver (called `pts`) works with the line discipline module and the hardware emulation module to provide a terminal interface to the user process. An optional packetizing module (called `pckt`) is also provided. It can be pushed on the master side to support packet mode (this is discussed in "Packet Mode"). The number of pseudo-TTY devices that can be installed on a system depends on available memory. Line-Discipline Module In the pseudo-TTY subsystem, the line discipline module is pushed on the slave side to present the user with the terminal interface. `ldterm`(7M) can turn off the processing of the `c_iflag`, `c_oflag`, and `c_lflag` fields to allow processing to take place elsewhere. The `ldterm`(7M) module can also turn off all canonical processing when it receives an `M_CTL` message with the `MC_NO_CANON` command to support remote mode. Although `ldterm`(7M) passes through messages without processing them, the appropriate flags are set when an `ioctl`(2), such as `TCGETA` or `TCGETS`, is issued to indicate that canonical processing is being performed. Figure C-2 Pseudo-TTY Subsystem Architecture Pseudo-TTY Emulation Module: `ptem` Because the pseudo-TTY subsystem has no hardware driver downstream from the `ldterm`(7M) module to process the terminal `ioctl`(2) calls, another module that understands the `ioctl` commands is placed downstream from the `ldterm`(7M). This module, `ptem`(7M), processes all of the terminal `ioctl`(2)calls and mediates the passage of control information downstream. `ldterm`(7M) and `ptem`(7M) together behave like a real terminal. Since there is no real terminal or modem in the pseudo-TTY subsystem, some of the `ioctl`(2) commands are ignored and cause only an acknowledgment of the command. `ptem`(7M) keeps track of the terminal parameters set by the various set commands such as `TCSETA` or `TCSETAW` but does not usually perform any action. For example, if a "set" `ioctl` is called, none of the bits in the `c_cflag` field of `termio`(7I) has any effect on the pseudo-terminal unless the baud rate is set to 0. Setting the baud rate to 0 has the effect of hanging up the pseudo-terminal. The pseudo-terminal does not recognize parity, so none of the flags in the `c_iflag` that control the processing of parity errors have any effect. The delays specified in the `c_oflag` field are also not supported. `ptem`(7M) does the following: Processes, if appropriate, and acknowledges receipt of the following `ioctls` on its write queue by sending an `M_IOCACK` message back upstream: `TCSETA`, `TCSETAW`, `TCSETAF`, `TCSETS`, `TCSETSW`, `TCSETSF`, `TCGETA`, `TCGETS`, and `TCSBRK`. Keeps track of the window size; information needed for the `TIOCSWINSZ`, `TIOCGWINSZ`, and `JWINSIZE` `ioctl`. When it receives an `ioctl`, other than for `TIOCSWINSZ`, `TIOCGWINSZ`, or `JWINSIZE` on its write queue, it sends an `M_IOCNAK` message upstream. It passes downstream the following `ioctl`s after processing them: `TCSETA`, `TCSETAW`, `TCSETAF`, `TCSETS`, `TCSETSW`, `TCSETSF`, `TCSBRK`, and `TIOCSWINSZ`. Frees any `M_IOCNAK` messages it receives on its read queue in case the `pckt` module (`pckt`(7M) (described in the section "Packet Mode") is not on the pseudo-terminal subsystem and the `TCSETA`, `TCSETAW`, `TCSETAF`, `TCSETS`, `TCSETSW`, `TCSETSF`, `TCSBRK`, or `TIOCSWINSZioctl`s get to the master's stream head which then sends an `M_IOCNAK` message. In its open routine, `ptem` sends an `M_SETOPTS` message upstream requesting allocation of a controlling TTY. When `ptem` receives an `M_IOCTL` message of type `TCSBRK` on its read queue, it sends an `M_IOCACK` message downstream and an `M_BREAK` message upstream. When `ptem` receives an `ioctl`(2) message on its write queue to set the baud rate to 0 (`TCSETA`W with `CBAUD` set to `B0`), it sends an `M_IOCACK` message upstream and a zero-length message downstream. When `ptem` receives an `M_IOCTL` of type `TIOCSIGNAL` on its read queue, it sends an `M_IOCACK` downstream and an `M_PCSIG` upstream, where the signal number is the same as in the `M_IOCTL` message. When `ptem` receives an `M_IOCTL` of type `TIOCREMOTE` on its read queue, it sends an `M_IOCACK` message downstream and the appropriate `M_CTL` message upstream to enable or disable canonical processing. When `ptem` receives an `M_DELAY` message on its read or write queue, it discards the message and does not act on it. When `ptem` receives an `M_IOCTL` of type `JWINSIZE` on its write queue, and if the values in its `jwinsize` structure are not zero, it sends an `M_IOCACK` message upstream with the `jwinsize` structure. If the values are zero, it sends an `M_IOCNAK` message upstream. When `ptem` receives an `M_IOCTL` message of type `TIOCGWINSZ` on its write queue and the values in the `winsize` structure are not zero, it sends an `M_IOCACK` message upstream with the `winsize` structure. If the values are zero, it sends an `M_IOCNAK` message upstream. It also saves the information passed to it in the `winsize` structure and sends a STREAMS signal message for signal `SIGWINCH` upstream to the slave process if the size changed. When `ptem`(7M) receives an `M_IOCTL` message with type `TIOCGWINSZ` on its read queue and the values in the `winsize` structure are not zero, it sends an `M_IOCACK` message downstream with the `winsize` structure. If the values are zero, it sends an `M_IOCNAK` message downstream. It also saves the information passed to it in the `winsize` structure and sends a STREAMS signal message for signal `SIGWINCH` upstream to the slave process if the size changed. All other messages are passed to the next module or driver.

Hardware Emulation Module

STREAMS-based Pseudo-Terminal Subsystem

Line-Discipline Module

Pseudo-TTY Emulation Module: ptem

Pseudo-TTY Emulation Module: `ptem`