Add macOS user-mode networking support

This enables SLIRP (userspace networking) and vmnet backend for macOS,
providing both privileged (vmnet) and unprivileged (user) networking
options.
- virtio-net: Fix user mode RX/TX/refresh for cross-platform support
- virtio-net: Fix vmnet RX path (vnet_iovec_write return value)
- netdev: Add user mode initialization for macOS, fix error handling
- netdev: Move Linux-only helpers inside platform guards
- netdev-vmnet: Add vmnet.framework backend (C with Blocks)
- ci: Enable recursive submodule checkout

User mode (SLIRP) works without sudo on both Linux and macOS. vmnet mode
requires sudo but provides better performance.

Tested on macOS 14.6 arm64 - ping successful, 0% packet loss.

Close #33

Author: jserv

.ci/detect-vmnet-network.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+
+# Detect vmnet shared network parameters (gateway IP, prefix)
+# Outputs: "<guest_ip> <gateway_ip> <prefix_len>"
+
+set -euo pipefail
+
+timeout="${VMNET_DETECT_TIMEOUT:-30}"
+guest_octet="${VMNET_GUEST_HOST_OCTET:-10}"
+guest_ip_override="${VMNET_GUEST_IP_OVERRIDE:-}"
+target_bridge="${VMNET_BRIDGE:-}"
+
+convert_netmask_to_prefix() {
+    local mask="$1"
+    case "${mask}" in
+        0xffffff00) echo 24 ;;
+        0xfffffe00) echo 23 ;;
+        0xfffffc00) echo 22 ;;
+        0xfffff800) echo 21 ;;
+        0xfffff000) echo 20 ;;
+        0xffffe000) echo 19 ;;
+        0xffffc000) echo 18 ;;
+        0xffff8000) echo 17 ;;
+        0xffff0000) echo 16 ;;
+        0xfffe0000) echo 15 ;;
+        0xfffc0000) echo 14 ;;
+        0xfff80000) echo 13 ;;
+        0xfff00000) echo 12 ;;
+        0xffe00000) echo 11 ;;
+        0xffc00000) echo 10 ;;
+        0xff800000) echo 9 ;;
+        0xff000000) echo 8 ;;
+        *) echo 24 ;;
+    esac
+}
+
+detect_bridge() {
+    local candidates=""
+    if [[ -n "${target_bridge}" ]]; then
+        candidates="${target_bridge}"
+    else
+        candidates="$(ifconfig -l)"
+    fi
+
+    local candidate
+    for candidate in ${candidates}; do
+        if [[ -n "${target_bridge}" ]] || [[ "${candidate}" =~ ^bridge[0-9]+$ ]]; then
+            local inet_line
+            inet_line="$(ifconfig "${candidate}" 2>/dev/null | awk '/inet /{print $0; exit}')"
+            if [[ -n "${inet_line}" ]]; then
+                echo "${candidate}|${inet_line}"
+                return 0
+            fi
+        fi
+    done
+
+    return 1
+}
+
+while (( timeout > 0 )); do
+    if bridge_info="$(detect_bridge)"; then
+        bridge_name="${bridge_info%%|*}"
+        inet_line="${bridge_info#*|}"
+
+        gateway="$(awk '{print $2}' <<<"${inet_line}")"
+        netmask="$(awk '{print $4}' <<<"${inet_line}")"
+        prefix="$(convert_netmask_to_prefix "${netmask}")"
+
+        IFS=. read -r o1 o2 o3 o4 <<<"${gateway}"
+        if [[ -z "${o1:-}" || -z "${o2:-}" || -z "${o3:-}" ]]; then
+            echo "Error: Unexpected gateway format: ${gateway}" >&2
+            exit 1
+        fi
+
+        guest_ip="${guest_ip_override}"
+        if [[ -z "${guest_ip}" ]]; then
+            guest_ip="${o1}.${o2}.${o3}.${guest_octet}"
+        fi
+
+        printf "%s %s %s\n" "${guest_ip}" "${gateway}" "${prefix}"
+        exit 0
+    fi
+
+    sleep 1
+    timeout=$((timeout - 1))
+done
+
+echo "Error: vmnet gateway not detected within timeout" >&2
+exit 1

.ci/test-netdev.sh

@@ -2,6 +2,7 @@
 
 # Source common functions and settings
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+export SCRIPT_DIR
 source "${SCRIPT_DIR}/common.sh"
 
 # Override timeout for netdev tests
@@ -21,44 +22,118 @@ esac
 # Clean up any existing semu processes before starting tests
 cleanup
 
-# Test network device functionality
-TEST_NETDEV() {
-    local NETDEV="$1"
-    local CMD_PREFIX=""
+# Platform detection
+UNAME_S=$(uname -s)
+
+# Check if running on macOS
+if [[ ${UNAME_S} == "Darwin" ]]; then
+    IS_MACOS=1
+else
+    IS_MACOS=0
+fi
 
-    if [ "$NETDEV" = "tap" ]; then
-        CMD_PREFIX="sudo "
+# Network device to test (can be overridden by NETDEV environment variable)
+NETDEV=${NETDEV:-""}
+
+# Check for root privileges based on network device
+REQUIRES_SUDO=0
+if [[ ${IS_MACOS} -eq 1 && "${NETDEV}" == "vmnet" ]]; then
+    REQUIRES_SUDO=1
+    SUDO_REASON="vmnet.framework requires root privileges"
+elif [[ ${IS_MACOS} -eq 0 && "${NETDEV}" == "tap" ]]; then
+    REQUIRES_SUDO=1
+    SUDO_REASON="TAP device requires root privileges"
+fi
+
+# Check for root privileges if required
+if [[ ${REQUIRES_SUDO} -eq 1 ]]; then
+    if [[ $EUID -ne 0 ]]; then
+        echo "Error: This script must be run with sudo for ${NETDEV} mode"
+        echo "Reason: ${SUDO_REASON}"
+        echo ""
+        echo "Usage: sudo $0"
+        echo "Or use NETDEV=user for no-sudo mode (macOS/Linux)"
+        exit 1
     fi
+fi
+
+# Test network device functionality
+TEST_NETDEV() {
+    local NETDEV=$1
 
     ASSERT expect <<DONE
     set timeout ${TIMEOUT}
-    spawn ${CMD_PREFIX}make check NETDEV=${NETDEV}
-    expect "buildroot login:" { send "root\n" } timeout { exit 1 }
-    expect "# " { send "uname -a\n" } timeout { exit 2 }
+    spawn make check NETDEV=${NETDEV}
+    expect "buildroot login:" { send "root\\n" } timeout { exit 1 }
+    expect "# " { send "uname -a\\n" } timeout { exit 2 }
+
     if { "$NETDEV" == "tap" } {
-        exec sudo ip addr add 192.168.10.1/24 dev tap0
-        exec sudo ip link set tap0 up
-        expect "riscv32 GNU/Linux" { send "ip l set eth0 up\n" } timeout { exit 3 }
-        expect "# " { send "ip a add 192.168.10.2/24 dev eth0\n" }
-        expect "# " { send "ping -c 3 192.168.10.1\n" }
+        exec ip addr add 192.168.10.1/24 dev tap0
+        exec ip link set tap0 up
+        expect "riscv32 GNU/Linux" { send "ip l set eth0 up\\n" } timeout { exit 3 }
+        expect "# " { send "ip a add 192.168.10.2/24 dev eth0\\n" }
+        expect "# " { send "ping -c 3 192.168.10.1\\n" }
         expect "3 packets transmitted, 3 packets received, 0% packet loss" { } timeout { exit 4 }
     } elseif { "$NETDEV" == "user" } {
-        expect "riscv32 GNU/Linux" { send "ip addr add 10.0.2.15/24 dev eth0\n" } timeout { exit 3 }
-        expect "# " { send "ip link set eth0 up\n"}
-        expect "# " { send "ip route add default via 10.0.2.2\n"}
-        expect "# " { send "ping -c 3 10.0.2.2\n" }
+        expect "riscv32 GNU/Linux" { send "ip addr add 10.0.2.15/24 dev eth0\\n" } timeout { exit 3 }
+        expect "# " { send "ip link set eth0 up\\n"}
+        expect "# " { send "ip route add default via 10.0.2.2\\n"}
+        expect "# " { send "ping -c 3 10.0.2.2\\n" }
+        expect "3 packets transmitted, 3 packets received, 0% packet loss" { } timeout { exit 4 }
+    } elseif { "$NETDEV" == "vmnet" } {
+        # vmnet (macOS): detect host-provided gateway and configure statically
+        set vmnet_info [exec \$env(SCRIPT_DIR)/detect-vmnet-network.sh]
+        set vmnet_guest_ip [lindex \$vmnet_info 0]
+        set vmnet_gateway [lindex \$vmnet_info 1]
+        set vmnet_prefix [lindex \$vmnet_info 2]
+
+        expect "riscv32 GNU/Linux" { send "ip link set eth0 up\\n" } timeout { exit 3 }
+        expect "# " { send "ip addr flush dev eth0\\n" }
+        expect "# " { send "ip addr add \$vmnet_guest_ip/\$vmnet_prefix dev eth0\\n" }
+        expect "# " { send "ip route replace default via \$vmnet_gateway\\n" }
+        expect "# " { send "for i in 1 2 3 4 5; do ping -c 1 -W 3 \$vmnet_gateway && break; sleep 1; done\\n" }
+        expect "# " { send "ping -c 3 \$vmnet_gateway\\n" }
         expect "3 packets transmitted, 3 packets received, 0% packet loss" { } timeout { exit 4 }
     }
 DONE
 }
 
-# Network devices to test
-NETWORK_DEVICES=(tap user)
+# Determine network devices to test based on platform
+if [[ -n "${NETDEV}" ]]; then
+    # NETDEV environment variable specified - test only that device
+    NETWORK_DEVICES=(${NETDEV})
+elif [[ ${IS_MACOS} -eq 1 ]]; then
+    # macOS: test both user (no sudo) and vmnet (requires sudo)
+    # Default to user if not running as root
+    if [[ $EUID -eq 0 ]]; then
+        NETWORK_DEVICES=(user vmnet)
+    else
+        NETWORK_DEVICES=(user)
+        echo "Note: Running without sudo, testing user mode only"
+        echo "Run with 'sudo' to test vmnet mode"
+    fi
+else
+    # Linux: test tap (requires sudo) and user (no sudo)
+    if [[ $EUID -eq 0 ]]; then
+        NETWORK_DEVICES=(tap user)
+    else
+        NETWORK_DEVICES=(user)
+        echo "Note: Running without sudo, testing user mode only"
+        echo "Run with 'sudo' to test tap mode"
+    fi
+fi
+
+echo "Platform: ${UNAME_S}"
+echo "Network devices to test: ${NETWORK_DEVICES[@]}"
 
 for NETDEV in "${NETWORK_DEVICES[@]}"; do
     cleanup
-    echo "Test network device: $NETDEV"
-    TEST_NETDEV "$NETDEV"
+    echo ""
+    echo "========================================="
+    echo "Testing network device: $NETDEV"
+    echo "========================================="
+    TEST_NETDEV $NETDEV
+    echo "✓ $NETDEV test passed"
 done
 
 ret="$?"

.github/workflows/main.yml

@@ -66,7 +66,7 @@ jobs:
       shell: bash
       timeout-minutes: 10
     - name: netdev test
-      run: .ci/test-netdev.sh
+      run: sudo .ci/test-netdev.sh
       shell: bash
       timeout-minutes: 10
 
@@ -104,6 +104,20 @@ jobs:
       run: .ci/autorun.sh
       shell: bash
       timeout-minutes: 15
+    - name: netdev test
+      # NOTE: vmnet requires sudo privileges which may not be available in GitHub Actions
+      # This test is conditional and will be skipped if sudo is not available
+      run: |
+            if sudo -n true 2>/dev/null; then
+              echo "sudo available, running netdev test"
+              sudo .ci/test-netdev.sh
+            else
+              echo "Skipping netdev test: sudo not available in GitHub Actions runner"
+              echo "vmnet.framework requires root privileges or com.apple.vm.networking entitlement"
+            fi
+      shell: bash
+      timeout-minutes: 20
+      if: ${{ success() }}
 
   coding_style:
     runs-on: ubuntu-24.04
@@ -112,6 +126,8 @@ jobs:
       pull-requests: write
     steps:
     - uses: actions/checkout@v4
+      with:
+        submodules: recursive
     - name: cache apt packages
       uses: actions/cache@v4
       with:

.gitmodules

@@ -4,7 +4,7 @@
     shallow = true
 [submodule "minislirp"]
     path = minislirp
-    url = https://github.com/edubart/minislirp
+    url = https://github.com/sysprog21/minislirp
     shallow = true
 [submodule "portaudio"]
     path = portaudio

Makefile

@@ -53,14 +53,31 @@ endif
 NETDEV ?= tap
 # virtio-net
 ENABLE_VIRTIONET ?= 1
-ifneq ($(UNAME_S),Linux)
+ifeq ($(UNAME_S),Darwin)
+    # macOS: auto-select backend when using default TAP setting
+    ifeq ($(NETDEV),tap)
+        NETDEV :=
+    endif
+else ifneq ($(UNAME_S),Linux)
+    # Other platforms: disable virtio-net
     ENABLE_VIRTIONET := 0
 endif
+
 $(call set-feature, VIRTIONET)
 ifeq ($(call has, VIRTIONET), 1)
     OBJS_EXTRA += virtio-net.o
     OBJS_EXTRA += netdev.o
-	OBJS_EXTRA += slirp.o
+
+    ifeq ($(UNAME_S),Darwin)
+        # macOS: support both vmnet and user (slirp) backends
+        OBJS_EXTRA += netdev-vmnet.o
+        OBJS_EXTRA += slirp.o
+        CFLAGS += -fblocks
+        LDFLAGS += -framework vmnet
+    else
+        # Linux: use tap/slirp backends
+        OBJS_EXTRA += slirp.o
+    endif
 endif
 
 # virtio-snd
@@ -168,10 +185,16 @@ ifeq ($(call has, VIRTIONET), 1)
 MINISLIRP_DIR := minislirp
 MINISLIRP_LIB := minislirp/src/libslirp.a
 LDFLAGS += $(MINISLIRP_LIB)
+# macOS: workaround for swab redefinition and add resolv library
+MINISLIRP_CFLAGS :=
+ifeq ($(UNAME_S),Darwin)
+    MINISLIRP_CFLAGS := MYCFLAGS="-D_DARWIN_C_SOURCE"
+    LDFLAGS += -lresolv
+endif
 $(MINISLIRP_DIR)/src/Makefile:
 	git submodule update --init $(MINISLIRP_DIR)
 $(MINISLIRP_LIB): $(MINISLIRP_DIR)/src/Makefile
-	$(MAKE) -C $(dir $<)
+	$(MAKE) -C $(dir $<) $(MINISLIRP_CFLAGS)
 $(OBJS): $(MINISLIRP_LIB)
 endif
 
@@ -243,7 +266,7 @@ $(SHARED_DIRECTORY):
 
 check: $(BIN) minimal.dtb $(KERNEL_DATA) $(INITRD_DATA) $(DISKIMG_FILE) $(SHARED_DIRECTORY)
 	@$(call notice, Ready to launch Linux kernel. Please be patient.)
-	$(Q)./$(BIN) -k $(KERNEL_DATA) -c $(SMP) -b minimal.dtb -i $(INITRD_DATA) -n $(NETDEV) $(OPTS)
+	$(Q)./$(BIN) -k $(KERNEL_DATA) -c $(SMP) -b minimal.dtb -i $(INITRD_DATA) $(if $(NETDEV),-n $(NETDEV)) $(OPTS)
 
 build-image:
 	scripts/build-image.sh

README.md

@@ -86,6 +86,8 @@ You can exit the emulator using: \<Ctrl-a x\>. (press Ctrl+A, leave it, afterwar
 * `disk-image` is optional, as it specifies the path of a disk image in ext4 file system for the virtio-blk device.
 * `shared-directory` is optional, as it specifies the path of a directory on the host that will be shared with the guest operating system through virtio-fs, enabling file access from the guest via a virtual filesystem mount.
 
+For detailed networking guidance, see [`docs/networking.md`](docs/networking.md).
+
 ## Mount and unmount a directory in semu
 
 To mount the directory in semu:

common.h

@@ -17,6 +17,8 @@ static inline int ilog2(int x)
     return 31 - __builtin_clz(x | 1);
 }
 
+#define MIN(a, b) (((a) < (b)) ? (a) : (b))
+
 /* Range check
  * For any variable range checking:
  *     if (x >= minx && x <= maxx) ...