Add multicast UDP sockets

.github/workflows/multicast-interop.yml

@@ -0,0 +1,41 @@
+name: Multicast interop tests
+
+on:
+  push:
+    branches: [ 'master', 'main', 'release/**' ]
+  pull_request:
+    branches: [ '*' ]
+
+jobs:
+  multicast:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential check libwolfssl-dev pkg-config
+          sudo modprobe tun
+
+      - name: Build and run multicast unit tests
+        timeout-minutes: 5
+        run: |
+          set -euo pipefail
+          make unit-multicast
+          timeout --preserve-status 5m ./build/test/unit
+
+      - name: Build and run multicast TAP interop
+        timeout-minutes: 3
+        run: |
+          set -euo pipefail
+          make build/test-multicast-interop
+          timeout --preserve-status 3m sudo ./build/test-multicast-interop
+
+      - name: Cleanup TAP state
+        if: always()
+        run: sudo ip link del wmcast0 2>/dev/null || true

Makefile

@@ -242,6 +242,16 @@ build/test-evloop-tun: $(OBJ) build/test/test_eventloop_tun.o build/port/posix/l
 	@echo "[LD] $@"
 	@$(CC) $(CFLAGS) -o $@ $(BEGIN_GROUP) $(^) $(LDFLAGS) $(END_GROUP)
 
+build/test-multicast-interop: CFLAGS+=-DIP_MULTICAST
+build/test-multicast-interop: build/multicast/wolfip.o build/test/test_multicast_interop.o build/port/posix/tap_linux.o
+	@echo "[LD] $@"
+	@$(CC) $(CFLAGS) -o $@ $(BEGIN_GROUP) $(^) $(LDFLAGS) $(END_GROUP)
+
+build/multicast/wolfip.o: src/wolfip.c
+	@mkdir -p `dirname $@` || true
+	@echo "[CC] $< (multicast)"
+	@$(CC) $(CFLAGS) -DIP_MULTICAST -c $< -o $@
+
 build/test-dns: $(OBJ) build/test/test_dhcp_dns.o
 	@echo "[LD] $@"
 	@$(CC) $(CFLAGS) -o $@ $(BEGIN_GROUP) $(^) $(LDFLAGS) $(END_GROUP)
@@ -374,7 +384,8 @@ UNIT_TEST_SRCS:=src/test/unit/unit.c \
 	src/test/unit/unit_tests_dns_dhcp.c \
 	src/test/unit/unit_tests_tcp_ack.c \
 	src/test/unit/unit_tests_tcp_flow.c \
-	src/test/unit/unit_tests_proto.c
+	src/test/unit/unit_tests_proto.c \
+	src/test/unit/unit_tests_multicast.c
 
 unit: build/test/unit
 
@@ -385,6 +396,9 @@ build/test/unit: $(UNIT_TEST_SRCS)
 	@echo "[LD] $@"
 	@$(CC) build/test/unit.o -o build/test/unit $(UNIT_LDFLAGS) $(LDFLAGS)
 
+unit-multicast: CFLAGS+=-DIP_MULTICAST
+unit-multicast: clean-unit unit
+
 ESP_UNIT_CHECK_CFLAGS := $(CHECK_PKG_CFLAGS)
 ifeq ($(UNAME_S),Darwin)
 	ifneq ($(CHECK_PREFIX),)
@@ -445,6 +459,8 @@ unit-leaksan: clean-unit build/test/unit
 COV_DIR:=build/coverage
 COV_UNIT:=$(COV_DIR)/unit
 COV_UNIT_O:=$(COV_DIR)/unit.o
+COV_MCAST_UNIT:=$(COV_DIR)/unit-multicast
+COV_MCAST_UNIT_O:=$(COV_DIR)/unit-multicast.o
 
 $(COV_UNIT_O): $(UNIT_TEST_SRCS)
 	@mkdir -p $(COV_DIR)
@@ -456,6 +472,16 @@ $(COV_UNIT): $(COV_UNIT_O)
 	@echo "[LD] $@"
 	@$(CC) $(COV_UNIT_O) -o $(COV_UNIT) $(UNIT_LDFLAGS) $(LDFLAGS)
 
+$(COV_MCAST_UNIT_O): $(UNIT_TEST_SRCS)
+	@mkdir -p $(COV_DIR)
+	@echo "[CC] unit.c (multicast coverage)"
+	@$(CC) $(UNIT_CFLAGS) $(CFLAGS) -DIP_MULTICAST --coverage -c src/test/unit/unit.c -o $(COV_MCAST_UNIT_O)
+
+$(COV_MCAST_UNIT): LDFLAGS+=--coverage $(UNIT_LIBS)
+$(COV_MCAST_UNIT): $(COV_MCAST_UNIT_O)
+	@echo "[LD] $@"
+	@$(CC) $(COV_MCAST_UNIT_O) -o $(COV_MCAST_UNIT) $(UNIT_LDFLAGS) $(LDFLAGS)
+
 cov: unit $(COV_UNIT)
 	@echo "[RUN] unit (coverage)"
 	@rm -f $(COV_DIR)/*.gcda
@@ -473,6 +499,14 @@ autocov: unit $(COV_UNIT)
 	@mkdir -p build/coverage
 	@gcovr -r . --exclude "src/test/unit/.*" --html-details -o build/coverage/index.html
 
+autocov-multicast: unit-multicast $(COV_MCAST_UNIT)
+	@echo "[RUN] unit multicast (coverage)"
+	@rm -f $(COV_DIR)/*.gcda
+	@$(COV_MCAST_UNIT)
+	@echo "[COV] gcovr multicast html"
+	@mkdir -p build/coverage
+	@gcovr -r . --exclude "src/test/unit/.*" --html-details -o build/coverage/multicast.html
+
 # Install dynamic library to re-link linux applications
 #
 install:
@@ -571,7 +605,7 @@ build/test/test-wolfguard-interop: src/test/test_wolfguard_interop.c src/port/po
 clean-test-wolfguard-interop:
 	@rm -f build/test/test-wolfguard-interop build/test/test_wolfguard_interop.o build/test/linux_tun.o
 
-.PHONY: clean all static cppcheck cov autocov unit-asan unit-ubsan unit-leaksan clean-unit \
+.PHONY: clean all static cppcheck cov autocov autocov-multicast unit-multicast unit-asan unit-ubsan unit-leaksan clean-unit \
         unit-esp-asan unit-esp-ubsan unit-esp-leaksan clean-unit-esp \
         unit-wolfguard unit-wolfguard-asan unit-wolfguard-ubsan clean-unit-wolfguard \
         test-wolfguard-loopback test-wolfguard-loopback-asan test-wolfguard-loopback-ubsan \

README.md

@@ -17,6 +17,7 @@ configured to forward traffic between multiple network interfaces.
   - Pre-allocated buffers for packet processing in static memory
 - Multi-interface support
 - Optional IPv4-forwarding
+- Optional IPv4 UDP multicast with IGMPv3 ASM membership reports
 
 ## Supported socket types
 
@@ -39,8 +40,9 @@ wolfIP exposes a BSD-like `socket(2)` API for IPv4 sockets:
 | **Network** | IPv4 | Datagram delivery, TTL handling | [RFC 791](https://datatracker.ietf.org/doc/html/rfc791) |
 | **Network** | IPv4 Forwarding | Multi-interface routing (optional) | [RFC 1812](https://datatracker.ietf.org/doc/html/rfc1812) |
 | **Network** | ICMP | Echo request/reply, TTL exceeded | [RFC 792](https://datatracker.ietf.org/doc/html/rfc792) |
+| **Network** | IGMPv3 | ASM membership reports for IPv4 multicast (optional) | [RFC 3376](https://datatracker.ietf.org/doc/html/rfc3376) |
 | **Network** | IPsec | ESP Transport mode | [RFC 4303](https://datatracker.ietf.org/doc/html/rfc4303) |
-| **Transport** | UDP | Unicast datagrams, checksum | [RFC 768](https://datatracker.ietf.org/doc/html/rfc768) |
+| **Transport** | UDP | Unicast datagrams, checksum, optional IPv4 multicast | [RFC 768](https://datatracker.ietf.org/doc/html/rfc768) |
 | **Transport** | TCP | Connection management, reliable delivery | [RFC 793](https://datatracker.ietf.org/doc/html/rfc793), [RFC 9293](https://datatracker.ietf.org/doc/html/rfc9293) |
 | **Transport** | TCP | Maximum Segment Size negotiation | [RFC 793](https://datatracker.ietf.org/doc/html/rfc793) |
 | **Transport** | TCP | TCP Timestamps, RTT measurement, PAWS, Window Scaling | [RFC 7323](https://datatracker.ietf.org/doc/html/rfc7323) |
@@ -139,6 +141,32 @@ The `-I wtcp0` flag pins the test to the injected interface and `-c5`
 generates five echo requests.  Successful replies confirm the ICMP
 datagram socket support end-to-end through the tap device.
 
+## Optional UDP Multicast
+
+IPv4 UDP multicast is compiled out by default. Define `IP_MULTICAST` to enable
+BSD-style multicast socket options and IGMPv3 ASM membership reports:
+
+- `WOLFIP_IP_ADD_MEMBERSHIP`
+- `WOLFIP_IP_DROP_MEMBERSHIP`
+- `WOLFIP_IP_MULTICAST_IF`
+- `WOLFIP_IP_MULTICAST_TTL`
+- `WOLFIP_IP_MULTICAST_LOOP`
+
+The implementation supports any-source multicast joins and leaves. Source
+filter APIs such as `MCAST_JOIN_SOURCE_GROUP` are not implemented.
+
+```sh
+make unit-multicast
+./build/test/unit
+
+make build/test-multicast-interop
+sudo ./build/test-multicast-interop
+```
+
+The multicast interop test creates a Linux TAP interface (`wmcast0`) and
+validates both directions: Linux sending to a wolfIP multicast receiver, and
+wolfIP sending to a Linux multicast receiver.
+
 ## FreeRTOS Port
 
 wolfIP now includes a dedicated FreeRTOS wrapper port at:

docs/API.md

@@ -16,7 +16,7 @@ wolfIP is a minimal TCP/IP stack designed for resource-constrained embedded syst
   - ICMP (RFC 792) - ping replies only
   - DHCP (RFC 2131) - client only
   - DNS (RFC 1035) - client only
-  - UDP (RFC 768) - unicast only
+  - UDP (RFC 768) - unicast, optional IPv4 multicast with `IP_MULTICAST`
   - TCP (RFC 793) with options (Timestamps, MSS)
 
 ## Core Data Structures