TTY PTY

Why this phase matters

Give userspace programs a real terminal abstraction. The kernel’s raw stdin buffer and hardcoded stdin_feeder_task are replaced by a proper TTY layer with a configurable line discipline. Programs can switch between cooked and raw mode via tcgetattr / tcsetattr, query the window size via TIOCGWINSZ, and detect whether they are attached to a terminal via isatty. The phase also lays the infrastructure for a future PTY master/slave pair.

How it works in m3OS

The roadmap entry defines the learning scope for this phase; a deeper implementation doc has not been matched yet.

How it builds on earlier phases

This phase builds on Ion Shell and turns that foundation into TTY PTY.

Implementation outline

• Define the Termios struct in a shared userspace library crate matching the Linux layout (c_iflag, c_oflag, c_cflag, c_lflag, c_cc[NCCS]). Use the same field sizes and byte order as the Linux x86_64 ABI so that musl-compiled code can pass the struct directly through ioctl.
• Create tty_server as a ring-3 server binary. Add it to the xtask image build so it is included in the disk image. Have init spawn it before the shell and wire stdin/stdout fds through it via capability grants.
• Implement the cooked-mode line discipline in tty_server: read raw bytes from kbd_server, maintain an edit buffer, apply erase (^H / DEL), kill (^U), and word-erase (^W) processing, and deliver a complete line to the read buffer when \n or ^D (EOF) is received.
• Implement echo: in cooked mode, each accepted character is written back to console_server. Echo is suppressed when ECHO is clear in c_lflag.
• Implement raw mode: when ICANON is clear in c_lflag, bypass line buffering and deliver bytes to the read buffer immediately; respect VMIN and VTIME from c_cc to control minimum read size and timeout.
• Implement cbreak mode: ICANON clear but ISIG set, so ^C and ^Z still generate signals while reads return individual bytes.
• Add ioctl dispatch in the syscall gate for TCGETS (0x5401), TCSETS (0x5402), TCSETSW (0x5403), TCSETSF (0x5404); route each to tty_server via a synchronous IPC call and copy the Termios struct through a shared page.
• Implement TIOCGWINSZ (0x5413) and TIOCSWINSZ (0x5414) storage in tty_server. When TIOCSWINSZ is called with new dimensions, send SIGWINCH to the foreground process group.
• Fix isatty path: ioctl(fd, TCGETS, NULL) on a non-TTY fd must return ENOTTY (-25). Ensure the fd table distinguishes TTY fds from plain file fds so the syscall gate returns the right error without forwarding to tty_server.
• Add PTY allocation stubs: posix_openpt opens /dev/ptmx and allocates a PtyPair in tty_server; grantpt / unlockpt are no-ops; ptsname returns a /dev/pts/N path string. Opening the slave path returns a second fd backed by the same PtyPair. Full bidirectional data routing between master and slave is deferred.
• Regression-test the shell: readline-style editing, Ctrl-C, Ctrl-Z, Ctrl-D (EOF), and piped input all work correctly through the new layer without behavioral changes compared to Phase 20.

Task progress snapshot

No checklist tasks were discovered for this phase yet.

Documentation targets

• Documentation deliverables have not been listed yet.

Deferred follow-on work

• Full PTY data path between master and slave (needed for terminal multiplexers, SSH, script)
• /dev/pts devpts filesystem (dynamic slave device nodes)
• VSTART / VSTOP (XON/XOFF) software flow control
• Modem control lines (DTR, RTS, CTS) and TIOCMGET / TIOCMSET
• Session leaders and controlling terminals (TIOCSCTTY, setsid)
• Packet mode (TIOCPKT) for terminal multiplexers
• Multiple simultaneous TTY instances beyond the single console TTY
• openpty libc helper (depends on full PTY data path)

Source materials

• Roadmap entry
• Implementation document
• Task list