# Networking Stack

BoredOS features a robust networking stack capable of handling Ethernet, IPv4, TCP, UDP, ICMP, DHCP, and DNS. The stack is built on top of the **lwIP (Lightweight IP)** library, which is integrated with a custom hardware driver layer.

## 1. Architecture Overview

The network stack is split into three main layers:
1. **Hardware/Driver Layer (`src/net/nic/`)**: Communicates with physical and virtual Network Interface Cards (NICs), handling raw Ethernet frame transmission and reception. Supported drivers include the Intel E1000 (`e1000.c`), Realtek RTL8139 (`rtl8139.c`), Realtek RTL8111 (`rtl8111.c`), and VirtIO network devices (`virtio_net.c`). A generic interface is provided via `nic.c`.
2. **Protocol Layer (lwIP)**: Processes Ethernet frames, handles ARP resolution, routes IPv4 packets, and manages TCP state machines.
3. **OS Interface Layer (`src/net/network.c`)**: Wraps the asynchronous lwIP API into a synchronous, easy-to-use API for BoredOS applications and the kernel.

## 2. Initialization & Polling

### `network_init()`
When the kernel boots, it initializes the network subsystem by:
1. Probing the PCI bus for supported NICs (e.g., the Intel E1000).
2. Initializing the lwIP core (`lwip_init()`) and DNS subsystem.
3. Binding the hardware NIC to lwIP using `netif_add`.
4. Automatically attempting to acquire an IP address via DHCP (`network_dhcp_acquire()`).

### The Polling Mechanism (`network_process_frames`)
Unlike some operating systems that process network packets entirely inside hardware interrupt handlers, BoredOS uses a **polled approach** to avoid re-entrancy issues in the TCP/IP stack. 

The `network_process_frames()` function is called periodically (e.g., from the Window Manager loop or during blocking network calls). It calls:
- `nic_netif_poll()`: Pulls raw packets from the NIC ring buffer and feeds them to lwIP (`ethernet_input`).
- `sys_check_timeouts()`: Fires lwIP internal timers for TCP retransmissions, ARP cache expiration, and DHCP lease renewals.

A `network_processing` flag acts as a lightweight spinlock to prevent nested execution of the network poll loop.

## 3. TCP Implementation & Application API

While lwIP provides a callback-based raw API, BoredOS wraps this into a sequential API for userland applications.

Currently, the OS supports **one active TCP connection globally across the entire system**. The connection state is managed via a global Protocol Control Block (`current_tcp_pcb`). To prevent unauthorized cleanup, the OS tracks which process initiated the connection (`tcp_owner_pid`). If a new process attempts to connect while a connection is active, the existing connection is forcefully aborted.

### `network_tcp_connect(ip, port)`
1. Allocates a new Protocol Control Block (`tcp_new()`).
2. Registers callbacks for receive (`tcp_recv_callback`), error, and connection success.
3. Blocks (while polling the network) until the connection succeeds or times out after 15 seconds.

### `network_tcp_recv(buf, max_len)`
When packets arrive, `tcp_recv_callback` chains them into a `tcp_recv_queue` (`struct pbuf`). 
The `network_tcp_recv` function blocks until data is available in this queue, then copies it into the application's buffer and frees the `pbuf`. A non-blocking variant (`network_tcp_recv_nb`) is also provided.

### Process Cleanup (`network_cleanup`)
If an application crashes or exits without closing its socket, the kernel's process manager calls `network_cleanup()`. This checks if the exiting process owns the current TCP PCB (`tcp_owner_pid`) and forcibly aborts the connection to prevent resource leaks.

## 4. Helper Protocols

- **DHCP:** Managed entirely by lwIP. BoredOS simply waits up to 10 seconds during boot for a lease.
- **DNS (`network_dns_lookup`):** Uses lwIP's `dns_gethostbyname`. It blocks and polls until the callback is triggered with the resolved IP address.
- **ICMP (Ping):** The kernel provides a `network_icmp_single_ping` function using an lwIP raw socket (`raw_pcb`) to construct, checksum, and transmit an ICMP Echo Request, blocking until a reply is received to calculate the Round-Trip Time (RTT).