2.8 KiB

Raw Permalink Blame History

Nexus Network Membrane (Grafted LwIP)

Status: Experimental / Grafted (Phase 1) Version: v0.1 (Hybrid Polling) Location: core/rumpk/libs/membrane

Overview

The Network Membrane is a userland networking stack running inside the init process (Subject Zero). It provides TCP/IP capabilities to the Nexus Sovereign Core by "grafting" the lightweight IP (LwIP) stack onto the Nexus ION (Input/Output Nexus) ring architecture.

This implementation follows SPEC-017 (The Network Membrane) and SPEC-701 (The Sovereign Network).

Architecture

1. The Graft (LwIP Integration)

Nexus avoids writing a TCP/IP stack from scratch for Phase 1. Instead, we compile LwIP as a static library (libnexus.a) linked into the userland payload.

Mode: NO_SYS (No OS threads). LwIP is driven by a single event loop.
Memory: Static buffers (Pbufs) managed by ion_client.

2. The Glue (`net_glue.nim`)

Bridging Nim userland and C LwIP:

pump_membrane_stack(): The heartbeat function. It must be called repeatedly by the main loop. It:
- Checks sys_now() for timer expiration (DHCP fine/coarse, TCP fast/slow).
- Polls ion_net_rx for inbound packets from the Kernel (NetSwitch).
- Injects packets into netif->input.
ion_linkoutput: The LwIP callback to send packets. Uses ion_net_tx to push packets to the Kernel.

3. Syscall Interface

LwIP requires system services provided via libc.nim and the SysTable:

sys_now(): Returns monotonic time in milliseconds using rdtime (via syscall_get_time_ns).
printf/abort: Mapped to console_write syscalls.

Current Limitations (v1.1.1)

1. The "Busy Wait" Workaround

Issue: The kernel Scheduler currently lacks a hardware Timer Driver for wfi (Wait For Interrupt). Symptom: Calling nanosleep (0x65) puts the fiber to sleep forever because no timer interrupt wakes the CPU. Workaround: init.nim uses a busy-wait loop (while sys_now() - start < 10: yield()). This keeps the network stack responsive but results in high CPU usage. Fix Planned: Implement ACLINT/SBI Timer driver in HAL.

2. No IP Acquisition (Ingress)

Issue: While Egress (DHCP DISCOVER) works and is verified, no Ingress packets (DHCP OFFER) are received. Suspected Cause: VirtIO interrupts might be masked or not delegated correctly, preventing NetSwitch from seeing inbound traffic.

Usage

The stack is initialized automatically by init:

import libs/membrane/net_glue

membrane_init()
while true:
  pump_membrane_stack()
  # Sleep/Yield

Logs & Debugging

Egress: grep for [Membrane] Egress Packet
Timers: grep for [Membrane] DHCP Fine Timer
Packet Dump: Enable LWIP_DEBUG in lwipopts.h (requires recompile).

2.8 KiB Raw Permalink Blame History