Socket API

Why this phase matters

Expose the kernel’s existing TCP/IP stack to userspace via standard Linux socket syscalls. At the end of this phase a userspace program can open a TCP connection, send an HTTP/1.0 request, and receive the response — entirely from ring-3 code, with no kernel modifications needed for each new network program. The ping shell builtin moves out of the kernel and into a standalone userspace ELF.

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 ANSI Escape and turns that foundation into Socket API.

Implementation outline

• Define a SocketHandle type in the kernel and add a socket slot to the per-process fd table alongside file and pipe slots. A socket fd must be indistinguishable from a file fd from userspace; close, read, and write must all work on it via the existing fd dispatch path.
• Add a sys_socket dispatch path in the syscall gate: validate the domain (AF_INET only), type (SOCK_STREAM or SOCK_DGRAM), and protocol; allocate a SocketHandle; send a NET_SOCKET_CREATE IPC message to net_server; and return the new fd number.
• Implement sys_bind and sys_connect as thin syscall stubs that copy the sockaddr_in from userspace, forward it to net_server via IPC, and block the calling task until the operation completes or returns an error code.
• Implement sys_listen and sys_accept. accept blocks the calling task in the kernel; net_server unblocks it and returns the peer address and a new socket fd when the TCP handshake completes.
• Implement sys_send / sys_sendto and sys_recv / sys_recvfrom. For TCP, net_server may need to buffer partial sends across multiple IPC messages; for UDP, each call maps to one datagram. Copy data through a shared page capability to avoid copying through the IPC message payload.
• Implement sys_shutdown, sys_getsockname, sys_getpeername, sys_setsockopt, and sys_getsockopt. Support at minimum SOL_SOCKET options SO_REUSEADDR, SO_KEEPALIVE, SO_RCVBUF, SO_SNDBUF, and IPPROTO_TCP option TCP_NODELAY.
• Extend sys_poll to handle socket fds. Teach net_server to track per-socket readiness state and send a notification to the kernel when a socket becomes readable or writable so a blocked poll call can be woken.
• Add SOCK_DGRAM / IPPROTO_ICMP support to net_server’s socket dispatch. Sending on such a socket constructs an ICMP echo request; receiving delivers the first matching ICMP echo reply. No raw socket privilege check is required for ICMP DGRAM in this phase.
• Write userspace/ping/ as a standalone ELF binary. Open an ICMP DGRAM socket, send echo requests in a loop, use poll to wait for replies with a timeout, and print each round-trip time to stdout.
• Remove the ping builtin from kernel/src/main.rs and delete the associated dead-code paths.
• Remove the #[allow(dead_code)] annotations from the network stack modules in kernel/src/net/ now that they are reachable from userspace through net_server.

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

• AF_UNIX (Unix domain sockets)
• AF_INET6 (IPv6)
• Raw sockets (SOCK_RAW) for userspace
• epoll and epoll_wait
• sendfile and zero-copy I/O
• Multicast group membership (IP_ADD_MEMBERSHIP)
• SO_REUSEPORT for multi-process listeners
• Non-blocking sockets (O_NONBLOCK) and EAGAIN handling
• DNS resolution (getaddrinfo / /etc/resolv.conf)
• TLS / DTLS
• TCP retransmission and congestion control improvements
• recvmsg / sendmsg with ancillary data (cmsg)

Source materials

• Roadmap entry
• Implementation document
• Task list