Add usrsctp component (sctplab/usrsctp + ESP-IDF lwIP integration) (IEC-545)

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -70,6 +70,7 @@ body:
         - thorvg
         - touch_element
         - unit-test-app
+        - usrsctp
         - zlib
         - libjpeg-turbo
         - Other

.github/workflows/upload_component.yml

@@ -72,6 +72,7 @@ jobs:
             thorvg
             touch_element
             unit-test-app
+            usrsctp
             zlib
             libpng
             libjpeg-turbo

.gitmodules

@@ -81,3 +81,6 @@
 [submodule "lua/lua"]
 	path = lua/lua
 	url = https://github.com/lua/lua.git
+[submodule "usrsctp/usrsctp"]
+	path = usrsctp/usrsctp
+	url = https://github.com/sctplab/usrsctp.git

.idf_build_apps.toml

@@ -36,6 +36,7 @@ manifest_file = [
     "quirc/.build-test-rules.yml",
     "thorvg/.build-test-rules.yml",
     "touch_element/.build-test-rules.yml",
+    "usrsctp/.build-test-rules.yml",
     "zlib/.build-test-rules.yml",
     "libjpeg-turbo/.build-test-rules.yml",
     ".build-test-rules.yml",

usrsctp/.build-test-rules.yml

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+#
+# usrsctp requires ESP-IDF 5.4+ (idf_component.yml `idf: ">=5.4"`). The
+# disable rules below skip the build on older IDF releases so the repo-wide
+# CI matrix (v5.1 / v5.2 / v5.3 / v5.4 / v5.5 / latest) doesn't try them.
+#
+# Path keys MUST be component-name-prefixed (`usrsctp/...`) — idf-build-apps
+# resolves these relative to the repo root, not the component root.
+
+usrsctp/examples/get_started:
+  enable:
+    - if: IDF_TARGET in ["esp32", "esp32c3", "esp32s3", "esp32c5", "esp32c6", "esp32p4"]
+      reason: "Build sanity on representative Xtensa + RISC-V targets."
+  disable:
+    - if: IDF_VERSION_MAJOR <= 5 and IDF_VERSION_MINOR < 4
+      reason: "usrsctp requires ESP-IDF 5.4+."
+
+usrsctp/test_apps:
+  enable:
+    - if: IDF_TARGET in ["esp32", "esp32c3"]
+      reason: "Sufficient to exercise one Xtensa and one RISC-V target."
+  disable:
+    - if: IDF_VERSION_MAJOR <= 5 and IDF_VERSION_MINOR < 4
+      reason: "usrsctp requires ESP-IDF 5.4+."
+
+usrsctp/host_test:
+  enable:
+    - if: IDF_TARGET == "linux"
+      reason: "Linux host build runs the usrsctp socket-lifecycle smoke test."
+  disable:
+    - if: IDF_VERSION_MAJOR <= 5 and IDF_VERSION_MINOR < 4
+      reason: "usrsctp requires ESP-IDF 5.4+."

usrsctp/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to ESP Component Registry
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'idf_component.yml'
+  workflow_dispatch:
+
+jobs:
+  upload:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (with submodules)
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Upload usrsctp
+        uses: espressif/upload-components-ci-action@v1
+        with:
+          name: usrsctp
+          namespace: vikramdattu
+          api_token: ${{ secrets.IDF_COMPONENT_API_TOKEN }}

usrsctp/.gitignore

@@ -0,0 +1,16 @@
+# build outputs
+build/
+build_*/
+dist/
+managed_components/
+dependencies.lock
+sdkconfig
+sdkconfig.old
+
+# OS / editor
+.DS_Store
+.vscode/
+.idea/
+*.swp
+*.swo
+*~

usrsctp/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 1.0.0
+
+- First release.
+- usrsctp wrapped as an ESP-IDF component. Submodule pins canonical
+  [sctplab/usrsctp](https://github.com/sctplab/usrsctp) at commit
+  `2e1ab10`; five ESP-IDF-specific patches are applied at build configure
+  time (see [`patches/README.md`](patches/README.md)).
+- Supports the full ESP32 family plus the IDF Linux target for
+  host-side testing.
+- Bundled patches add lwIP routing for the userspace conn layer,
+  thread-safe netif APIs, SPIRAM-backed worker-thread stacks, and
+  buildability on the IDF Linux target.
+- Embedded smoke test (`test_apps/`) and host-side socket-lifecycle
+  test (`host_test/`) included.

usrsctp/CMakeLists.txt

@@ -0,0 +1,133 @@
+# SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
+#
+# SPDX-License-Identifier: Apache-2.0
+
+set(usrsctp_root_dir ${CMAKE_CURRENT_SOURCE_DIR}/usrsctp)
+set(usrsctp_lib_dir ${usrsctp_root_dir}/usrsctplib)
+
+# Apply all patches in patches/*.patch onto the usrsctp submodule at
+# configure time. Idempotent: dry-run check skips already-applied patches.
+file(GLOB USRSCTP_PATCHES "${CMAKE_CURRENT_SOURCE_DIR}/patches/*.patch")
+list(SORT USRSCTP_PATCHES)
+foreach(_patch ${USRSCTP_PATCHES})
+    execute_process(
+        COMMAND git apply --check -p1 ${_patch}
+        WORKING_DIRECTORY ${usrsctp_root_dir}
+        RESULT_VARIABLE _check
+        ERROR_QUIET OUTPUT_QUIET
+    )
+    if(_check EQUAL 0)
+        execute_process(
+            COMMAND git apply -p1 ${_patch}
+            WORKING_DIRECTORY ${usrsctp_root_dir}
+            RESULT_VARIABLE _apply
+        )
+        if(NOT _apply EQUAL 0)
+            message(FATAL_ERROR "usrsctp: failed to apply ${_patch}")
+        endif()
+        message(STATUS "usrsctp: applied ${_patch}")
+    endif()
+endforeach()
+
+# Register our component with just the ESP-specific file
+idf_component_register(
+    SRCS
+        usrsctp_register.c # empty TU so idf_component_register has a source
+    INCLUDE_DIRS
+        ${usrsctp_lib_dir}
+        ${usrsctp_lib_dir}/netinet
+        ${usrsctp_lib_dir}/netinet6
+    REQUIRES
+        lwip
+        mbedtls
+        esp_common
+        pthread
+        freertos
+)
+
+# Set up environment for usrsctp. Use CACHE BOOL ... FORCE because the
+# inner usrsctp/CMakeLists.txt declares these as option() — without
+# CACHE our local set() gets overridden by option()'s default at
+# add_subdirectory time, and SCTP_USE_LWIP ends up defined on Linux
+# (which then drags in lwip-specific headers usrsctp's userspace path
+# can't satisfy on a host build).
+if(IDF_TARGET STREQUAL "linux")
+    set(sctp_use_lwip OFF CACHE BOOL "build with lwip" FORCE)
+    set(sctp_use_rtos OFF CACHE BOOL "build with rtos" FORCE)
+else()
+    set(sctp_use_lwip ON CACHE BOOL "build with lwip" FORCE)
+    set(sctp_use_rtos ON CACHE BOOL "build with rtos" FORCE)
+endif()
+
+# Add definitions needed by usrsctp
+add_definitions(-D__Userspace__)
+add_definitions(-DSCTP_PROCESS_LEVEL_LOCKS)
+add_definitions(-DSCTP_SIMPLE_ALLOCATOR)
+add_definitions(-DHAVE_SYS_QUEUE_H)
+add_definitions(-DHAVE_STDATOMIC_H)
+add_definitions(-DSCTP_DEBUG)
+add_definitions(-DESP_PLATFORM)
+
+if(sctp_use_lwip)
+    add_definitions(-DSCTP_USE_LWIP)
+endif()
+
+if(sctp_use_rtos)
+    add_definitions(-DSCTP_USE_RTOS)
+endif()
+
+if(NOT CONFIG_IDF_TARGET STREQUAL "linux")
+    add_definitions(-DHAVE_SCONN_LEN)
+endif()
+
+# Set up options for usrsctp
+set(sctp_build_programs OFF CACHE BOOL "Build usrsctp example programs" FORCE)
+set(sctp_build_shared_lib OFF CACHE BOOL "Build usrsctp as shared library" FORCE)
+set(sctp_invariants OFF CACHE BOOL "Add runtime checks" FORCE)
+set(sctp_inet ON CACHE BOOL "Support IPv4" FORCE)
+set(sctp_inet6 OFF CACHE BOOL "Support IPv6" FORCE)
+set(SCTP_USE_MBEDTLS_SHA1 ON CACHE BOOL "Build with mbedtls sha1 support" FORCE)
+set(sctp_werror OFF CACHE BOOL "Treat warning as error" FORCE)
+
+# Create a custom FindMbedTLS.cmake in the CMAKE_MODULE_PATH
+file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/FindMbedTLS.cmake" "
+# Custom FindMbedTLS.cmake for ESP-IDF
+set(MBEDTLS_FOUND TRUE)
+set(MBEDTLS_INCLUDE_DIRS \"${IDF_PATH}/components/mbedtls/mbedtls/include\" \"${IDF_PATH}/components/mbedtls/port/include\")
+set(MBEDTLS_LIBRARIES mbedtls mbedcrypto mbedx509)
+")
+
+# Add the directory with our custom FindMbedTLS.cmake to CMAKE_MODULE_PATH
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_BINARY_DIR}")
+
+# Add compiler flags to suppress warnings. Apple Clang doesn't know
+# about `maybe-uninitialized` (only GCC has that name; LLVM uses plain
+# `uninitialized`), and treats unknown warning options as errors under
+# -Werror. Probe the flag and only add it when supported.
+include(CheckCCompilerFlag)
+check_c_compiler_flag("-Wno-error=maybe-uninitialized" HAS_NO_ERROR_MAYBE_UNINIT)
+
+add_compile_options(
+    -Wno-address-of-packed-member
+    -Wno-unused-but-set-variable
+    -Wno-unused-variable
+    -Wno-unused-function
+    -Wno-pointer-sign
+    -Wno-implicit-function-declaration
+    -Wno-incompatible-pointer-types
+    -Wno-format
+    -Wno-pedantic
+    -Wno-error=pedantic
+)
+if(HAS_NO_ERROR_MAYBE_UNINIT)
+    add_compile_options(-Wno-error=maybe-uninitialized)
+endif()
+
+# Add usrsctp as a subdirectory
+add_subdirectory(${usrsctp_root_dir} ${CMAKE_CURRENT_BINARY_DIR}/usrsctp)
+
+# so that we can use pthread and heap functions in usrsctp
+target_link_libraries(usrsctp PRIVATE idf::pthread idf::heap)
+
+# Link against usrsctp library
+target_link_libraries(${COMPONENT_LIB} PUBLIC usrsctp)

usrsctp/Kconfig

@@ -0,0 +1,27 @@
+menu "usrsctp"
+
+    config USRSCTP_DEBUG
+        bool "Enable SCTP_DEBUG runtime tracing"
+        default n
+        help
+            Builds usrsctp with verbose runtime trace logging via SCTP_DEBUG.
+            Adds binary size; only useful during development.
+
+    config USRSCTP_THREAD_STACK_IN_SPIRAM
+        bool "Allocate usrsctp's internal pthread stacks from SPIRAM"
+        depends on SPIRAM
+        default y
+        help
+            Routes usrsctp's userspace-mode worker threads to SPIRAM.
+            Strongly recommended on memory-constrained chips
+            (esp32c6, esp32p4-eye) where internal RAM is at a premium.
+
+    config USRSCTP_USE_MBEDTLS_SHA1
+        bool "Use mbedTLS for SHA1 instead of usrsctp's bundled implementation"
+        default y
+        help
+            Uses ESP-IDF's mbedTLS (typically backed by the on-chip SHA
+            peripheral) for SHA-1 hashing inside usrsctp. Smaller binary
+            and faster than usrsctp's bundled software SHA-1.
+
+endmenu