vectorgrp · RainerZ · Jul 8, 2026 · Jul 8, 2026 · Jul 8, 2026 · Jul 8, 2026
diff --git a/.gitignore b/.gitignore
@@ -26,6 +26,7 @@ RecycleBin.ini
 test_bintool
 *.bak
 *.log
+*.pcap
 
 # Other
 .vscode
@@ -36,3 +37,4 @@ test_bintool
 /docs/SUBMODULE_GUIDE.md
 /shm_*.sh
 wlan.h
+/TODO_old.md
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -23,5 +23,9 @@
     "cmake.configureOnOpen": false,
     "rust-analyzer.linkedProjects": [
         "${workspaceFolder}/tools/xcpclient/Cargo.toml"
-    ]
+    ],
+    "[rust]": {
+        "editor.defaultFormatter": "rust-lang.rust-analyzer",
+        "editor.formatOnSave": true
+    }
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -89,7 +89,10 @@ src/queue*.c                    Lock-free/mutex transmit queue implementations (
 src/cal.c/.h                    Calibration segment RCU implementation (page switching, locks)
 src/a2l.c, src/a2l_writer.c     Runtime A2L file generation
 src/persistence.c/.h            Binary (.bin) parameter/event persistence across restarts
-src/platform.c/.h               OS abstraction (threads, sockets, clock, atomics) — Linux/macOS/QNX/Windows/FreeRTOS
+src/platform.c/.h               OS abstraction (threads, clock, mutex, atomics) — Linux/macOS/QNX/Windows/FreeRTOS
+src/sockets.c/.h                Socket abstraction over the OS socket API (all standard platforms)
+src/socket_raw.c                Raw-Ethernet UDP/IPv4 transport (OPTION_ENABLE_UDP_RAW), see docs/SOCKET_RAW.md
+src/socket_raw_hal.h            Raw Ethernet HAL interface; socket_raw_hal_linux.c is the AF_PACKET backend
 src/util.c/.h                   Shared helpers
 ```
 
@@ -119,7 +122,9 @@ XCPlite encodes *where* a measured/calibrated variable lives (global, stack, hea
 - `xcp_evts` section — `tXcpEventDescriptor` constants emitted by `DaqCreateEvent`/`DaqCreateAndTriggerEvent`
 - `xcp_cals` section — `tXcpCalSegDescriptor` constants emitted by `CalSegDecl`+`CalSegCreate`
 
-and DWARF scope anchors named `trg__<mode-letters>__<event-name>` (e.g. `trg__AAS__foo`, letter position = address-extension value [0..]: `A`=absolute, `C`=cal-segment-relative, `S`=stack-relative, `D`=dynamic/heap) emitted by the trigger macros, to reconstruct addressing without any runtime A2L calls. Full details, including what changes if you modify the trigger macros, are in `docs/TECHNICAL.md`.
+and DWARF scope anchors named `trg__<mode-letters>__<event-name>` (e.g. `trg__AAS__foo`, letter position = address-extension value [0..]: `A`=absolute, `C`=cal-segment-relative, `S`=stack-relative, `D`=dynamic/heap) emitted by the trigger macros, to reconstruct addressing without any runtime A2L calls. The marker contract (sections, marker names, trigger anchor naming) is in `docs/TECHNICAL.md`, the tool side (workflow, naming rules, symbol resolution, supported types) in `docs/OFFLINE_A2L.md`.
+
+The generator reads ELF files only. Executables built on macOS are Mach-O and carry no DWARF (the linker leaves it in the `.o` files / `.dSYM`), so `xcpclient` rejects them with an explicit "macOS is not supported" error and exit status 1 — A2L files for `no_a2l`/`rtos` builds must be generated from a Linux build, which is what the examples' `create_a2l.sh` scripts do via a remote build on a Linux target.
 
 ### Shared-memory (SHM) multi-application mode (`docs/SHM.md`)
 

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,7 +1,7 @@
 
 cmake_minimum_required(VERSION 3.14)
 
-project(xcplite VERSION 2.1.2 LANGUAGES C CXX)
+project(xcplite VERSION 2.2.1 LANGUAGES C CXX)
 
 
 
@@ -16,22 +16,24 @@ project(xcplite VERSION 2.1.2 LANGUAGES C CXX)
 #   cmake -B build-ptp    -S . -DXCPLITE_CONFIGURATION=ptp
 #   cmake -B build-shm    -S . -DXCPLITE_CONFIGURATION=shm
 #   cmake -B build-rtos   -S . -DXCPLITE_CONFIGURATION=rtos
+#   cmake -B build-raw    -S . -DXCPLITE_CONFIGURATION=raw
 #
 # Configuration descriptions (see src/xcplib_<name>_cfg.h for details):
 #   default  - 64-bit, on-target A2L generation, filesystem, Ethernet UDP/TCP
 #   no_a2l   - Like default without on-target A2L; A2L generated from ELF by xcpclient
 #   ptp      - Like default with socket hardware timestamps (ptptool, Linux only)
 #   shm      - Shared-memory multi-application mode (shmtool, xcpdaemon)
 #   rtos     - Embedded RTOS targets (FreeRTOS), reduced footprint, no filesystem
+#   raw      - Raw Ethernet transport, UDP/IPv4 inside xcplib, no TCP/IP stack (Linux only)
 # =============================================================================
 set(XCPLITE_CONFIGURATION "default" CACHE STRING
-    "Library build configuration: default | no_a2l | ptp | shm | rtos")
-set_property(CACHE XCPLITE_CONFIGURATION PROPERTY STRINGS default no_a2l ptp shm rtos)
+    "Library build configuration: default | no_a2l | ptp | shm | rtos | raw")
+set_property(CACHE XCPLITE_CONFIGURATION PROPERTY STRINGS default no_a2l ptp shm rtos raw)
 
-if(NOT XCPLITE_CONFIGURATION MATCHES "^(default|no_a2l|ptp|shm|rtos)$")
+if(NOT XCPLITE_CONFIGURATION MATCHES "^(default|no_a2l|ptp|shm|rtos|raw)$")
     message(FATAL_ERROR
         "Invalid XCPLITE_CONFIGURATION='${XCPLITE_CONFIGURATION}'. "
-        "Must be one of: default, no_a2l, ptp, shm, rtos")
+        "Must be one of: default, no_a2l, ptp, shm, rtos, raw")
 endif()
 
 # Resolve configuration override header (empty = use default xcplib_cfg.h)
@@ -43,6 +45,8 @@ elseif(XCPLITE_CONFIGURATION STREQUAL "shm")
     set(_xcplib_cfg_override "xcplib_shm_cfg.h")
 elseif(XCPLITE_CONFIGURATION STREQUAL "rtos")
     set(_xcplib_cfg_override "xcplib_rtos_cfg.h")
+elseif(XCPLITE_CONFIGURATION STREQUAL "raw")
+    set(_xcplib_cfg_override "xcplib_raw_cfg.h")
 else()
     set(_xcplib_cfg_override "")
 endif()
@@ -176,7 +180,7 @@ elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC")
 endif()
 
 # xcplite sources
-set(xcplite_SOURCES src/xcpappl.c src/xcplite.c src/xcpethserver.c src/xcpethtl.c src/queue32m.c src/queue32.c src/queue64v.c src/queue64f.c src/shm.c src/cal.c src/a2l.c src/a2l_writer.c src/persistence.c src/platform.c src/util.c )
+set(xcplite_SOURCES src/xcpappl.c src/xcplite.c src/xcpethserver.c src/xcpethtl.c src/queue32m.c src/queue32.c src/queue64v.c src/queue64f.c src/shm.c src/cal.c src/a2l.c src/a2l_writer.c src/persistence.c src/platform.c src/sockets.c src/socket_raw.c src/socket_raw_hal_linux.c src/util.c )
 
 # Create xcplite library
 add_library(xcplite ${xcplite_SOURCES})
@@ -314,6 +318,19 @@ if(XCPLITE_BUILD_EXAMPLES)
         # Build it separately: cd examples/silkit_demo && cmake -B build -DSilKit_DIR=... -Dxcplite_DIR=...
         message(STATUS "silkit_demo: not built from root (standalone project, see examples/silkit_demo/)")
 
+    elseif(XCPLITE_CONFIGURATION STREQUAL "raw")
+
+        # udp_raw_demo: XCP over the raw Ethernet transport (UDP/IPv4 inside xcplib).
+        # Linux only - the HAL backend uses AF_PACKET and needs CAP_NET_RAW.
+        # See docs/SOCKET_RAW.md for the network setup used to test it.
+        if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+            add_executable(udp_raw_demo examples/udp_raw_demo/src/main.c)
+            target_link_libraries(udp_raw_demo PRIVATE xcplite)
+            message(STATUS "udp_raw_demo: building for raw configuration (Linux)")
+        else()
+            message(STATUS "udp_raw_demo: skipped (Linux only, raw Ethernet HAL uses AF_PACKET)")
+        endif()
+
     elseif(XCPLITE_CONFIGURATION STREQUAL "rtos")
 
         # freertos_demo: FreeRTOS POSIX simulator for testing FreeRTOS xcplite support on the host.
@@ -373,6 +390,27 @@ if(XCPLITE_BUILD_TESTS)
         target_link_libraries(clock_test PRIVATE xcplite)
         message(STATUS "clock_test: building for ptp configuration")
 
+    elseif(XCPLITE_CONFIGURATION STREQUAL "raw")
+
+        # Unit tests for the raw Ethernet transport: checksums, wire layout, frame build,
+        # receive filter, ARP and ICMP responders. No network and no HAL involved -
+        # src/socket_raw.c is compiled into the test with a fake Ethernet HAL (src/stubs.c),
+        # so this does not link against xcplite and needs no privileges.
+        if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+            add_executable(socket_raw_test test/socket_raw_test/src/main.c test/socket_raw_test/src/stubs.c)
+            target_include_directories(socket_raw_test PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/src" "${CMAKE_CURRENT_SOURCE_DIR}/inc")
+            # This target deliberately does not link xcplite (it supplies its own fake
+            # Ethernet HAL), so it does not inherit the PUBLIC _GNU_SOURCE from that target
+            target_compile_definitions(socket_raw_test PRIVATE
+                "XCPLITE_CONFIGURATION=\"raw\""
+                "XCPLIB_CFG_OVERRIDE=\"xcplib_raw_cfg.h\""
+                $<$<PLATFORM_ID:Linux>:_GNU_SOURCE>
+            )
+            message(STATUS "socket_raw_test: building for raw configuration")
+        else()
+            message(STATUS "socket_raw_test: skipped (Linux only, raw Ethernet HAL uses AF_PACKET)")
+        endif()
+
     else()
         message(STATUS "XCPLITE_BUILD_TESTS=ON: no test targets defined for configuration '${XCPLITE_CONFIGURATION}'")
     endif()
@@ -483,6 +521,10 @@ install(DIRECTORY inc/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} FILES_MATCHING PA
 # Install xcplib_cfg.h (default configuration) and platform.h
 install(FILES src/xcplib_cfg.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
 install(FILES src/platform.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+install(FILES src/sockets.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+# Raw Ethernet HAL interface, needed by applications which provide their own backend
+# (OPTION_UDP_RAW_HAL_EXTERNAL), e.g. an ASAM CMP implementation
+install(FILES src/socket_raw_hal.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
 
 # Install the active configuration override header (if not default)
 # This documents which configuration was compiled into the installed library.

diff --git a/README.md b/README.md
@@ -43,7 +43,7 @@ For save operation, the client tool must respect fixed event definitions and han
 
 If a tool understands ABI details of complex data instances, it may still perform the usual address calculations to access individual fields of composite types, array elements, or merge memory ranges to optimize upload, download, and data acquisition.
 
-General-purpose A2L editors/creators typically cannot reconstruct XCPlite-specific relative address encoding automatically. In this case, you are limited to use only global memory objects. For full featured offline A2L generation, you may use the XCPlite-aware xcpclient tool workflow described in the [technical documentation](docs/TECHNICAL.md).
+General-purpose A2L editors/creators typically cannot reconstruct XCPlite-specific relative address encoding automatically. In this case, you are limited to use only global memory objects. For full featured offline A2L generation, use the XCPlite-aware xcpclient tool, see [Offline A2L Generation](docs/OFFLINE_A2L.md).
 
 Support for A2L TYPEDEF and shared axis references with `this.` is beneficial, but not strictly required.
 
@@ -105,7 +105,8 @@ Details how to build for Linux, QNX, macOS, and Windows are in the [building doc
 - **[API Reference](docs/xcplib.md)** - XCP instrumentation API
 - **[Configuration](docs/xcplib_cfg.md)** - Configuration options
 - **[Examples](examples/README.md)** - Example applications and CANape setup
-- **[Technical Details](docs/TECHNICAL.md)** - Addressing modes, A2L generation, instrumentation costs
+- **[Technical Details](docs/TECHNICAL.md)** - Addressing modes, on-target A2L generation, instrumentation costs and markers
+- **[Offline A2L Generation](docs/OFFLINE_A2L.md)** - A2L generation from the ELF file with xcpclient
 - **[Building](docs/BUILDING.md)** - Detailed build instructions
 - **[XCP Introduction](docs/XCP_INTRODUCTION.md)** - What is XCP?
 

diff --git a/build.sh b/build.sh
@@ -28,6 +28,7 @@ show_usage() {
     echo "  ptp       build-ptp/       Hardware socket timestamps for PTP (Linux, PTP-capable NIC)"
     echo "  shm       build-shm/       Shared-memory multi-application mode"
     echo "  rtos      build-rtos/      FreeRTOS POSIX simulator (Linux/macOS only)"
+    echo "  raw       build-raw/       Raw Ethernet transport, UDP/IPv4 inside xcplib (Linux only)"
     echo ""
     echo "Target (default: examples) — what to build within the configuration:"
     echo "  lib          Library only"
@@ -64,6 +65,7 @@ show_usage() {
     echo "  $0 shm tools                        # shm config: shmtool + xcpdaemon"
     echo "  $0 ptp tools                        # ptp config: ptptool (Linux only)"
     echo "  $0 no_a2l examples                  # no_a2l config: no_a2l_demo, no_a2l_demo_cpp"
+    echo "  $0 raw examples                     # raw config: udp_raw_demo (Linux only)"
     echo "  $0 rtos examples                    # rtos config: freertos_demo (Linux/macOS only)"
     echo "  $0 lib install                      # Library only, install to build/install"
     echo "  $0 release lib install=/usr/local   # Release build, install to /usr/local"
@@ -98,7 +100,7 @@ for arg in "$@"; do
         relwithdebinfo) BUILD_TYPE="RelWithDebInfo" ;;
 
         # Configuration
-        default|no_a2l|ptp|shm|rtos) CONFIGURATION="$arg_lower" ;;
+        default|no_a2l|ptp|shm|rtos|raw) CONFIGURATION="$arg_lower" ;;
 
         # Target (multiple targets may be combined, e.g. "tools examples")
         lib)        _ANY_TARGET=true ;;  # library only: all extras remain false
@@ -113,7 +115,7 @@ for arg in "$@"; do
         clean)   CLEAN_BUILD=true ;;
         cleanall)
             echo "Cleaning all build directories..."
-            rm -rf build build-no_a2l build-ptp build-shm build-rtos
+            rm -rf build build-no_a2l build-ptp build-shm build-rtos build-raw
             # Also clean legacy directory names from older builds
             rm -rf build_no_a2l_demo build_freertos build_ptptool build_shm
             rm -f ./*.bin ./*.hex ./*.log ./*.mf4 ./*.a2l
@@ -262,10 +264,12 @@ if [[ "$RUN_CLANG_TIDY" == true && "$BUILD_SUCCESS" == true ]]; then
         if [[ ! -f "$BUILD_DIR/compile_commands.json" ]]; then
             cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -S . -B "$BUILD_DIR"
         fi
+        # Keep in sync with xcplite_SOURCES in CMakeLists.txt
         XCPLITE_SOURCES=(
             src/xcpappl.c src/xcplite.c src/xcpethserver.c src/xcpethtl.c
-            src/queue32.c src/queue64v.c src/queue64f.c src/shm.c
-            src/cal.c src/a2l.c src/a2l_writer.c src/persistence.c src/platform.c src/util.c
+            src/queue32.c src/queue32m.c src/queue64v.c src/queue64f.c src/shm.c
+            src/cal.c src/a2l.c src/a2l_writer.c src/persistence.c src/platform.c
+            src/sockets.c src/socket_raw.c src/socket_raw_hal_linux.c src/util.c
         )
         for src in "${XCPLITE_SOURCES[@]}"; do
             [[ -f "$SCRIPT_DIR/$src" ]] || { echo "Warning: not found: $src"; continue; }
@@ -324,6 +328,13 @@ case "$CONFIGURATION" in
         echo "  Tests         : (none for rtos configuration)"
         echo "  Tools         : (none for rtos configuration)"
         ;;
+    raw)
+        [[ "$CMAKE_BUILD_EXAMPLES" == "ON" ]] && echo "  Examples      : udp_raw_demo (Linux only, needs CAP_NET_RAW)" \
+            || echo "  Examples      : (not built)"
+        [[ "$CMAKE_BUILD_TESTS" == "ON" ]]    && echo "  Tests         : socket_raw_test" \
+            || echo "  Tests         : (not built)"
+        echo "  Tools         : (none for raw configuration)"
+        ;;
 esac
 
 [[ "$CMAKE_BUILD_RUST" == "ON" ]] && echo "  Rust tools    : xcpclient, bintool" \

diff --git a/docs/BUILDING.md b/docs/BUILDING.md
@@ -19,6 +19,7 @@ The library has **mutually exclusive build configurations** selected via `XCPLIT
 | `ptp` | `build-ptp/` | `xcplib_ptp_cfg.h` | Like default with socket hardware timestamps; requires Linux and a PTP-capable NIC |
 | `shm` | `build-shm/` | `xcplib_shm_cfg.h` | Shared-memory multi-application mode (shmtool, xcpdaemon) |
 | `rtos` | `build-rtos/` | `xcplib_rtos_cfg.h` | FreeRTOS embedded targets: reduced footprint, no filesystem, 32-bit |
+| `raw` | `build-raw/` | `xcplib_raw_cfg.h` | Raw Ethernet transport: UDP/IPv4 inside xcplib, no TCP/IP stack (Linux only) |
 
 Each `src/xcplib_<name>_cfg.h` header documents the exact overrides applied on top of the defaults in `src/xcplib_cfg.h`.
 
@@ -45,6 +46,7 @@ Within a chosen configuration, the following options control what gets built:
 | `ptp` | ptp4l_demo¹ | clock_test | ptptool¹ |
 | `shm` | hello_xcp (SHM), hello_xcp_cpp (SHM) | *(none)* | shmtool, xcpdaemon³ |
 | `rtos` | freertos_emu_demo³ (downloads FreeRTOS-Kernel) | *(none)* | *(none)* |
+| `raw` | udp_raw_demo (Linux only) | socket_raw_test | *(none)* |
 
 ¹ Linux only  ² requires libbpf  ³ not supported on Windows
 
@@ -71,7 +73,7 @@ These examples have their own `CMakeLists.txt` and use `find_package(xcplite)` a
 | Argument group | Values | Default |
 |----------------|--------|---------|
 | Build type | `debug` \| `release` \| `relwithdebinfo` | `debug` |
-| Configuration | `default` \| `no_a2l` \| `ptp` \| `shm` \| `rtos` | `default` |
+| Configuration | `default` \| `no_a2l` \| `ptp` \| `shm` \| `rtos` \| `raw` | `default` |
 | Target | `lib` \| `examples` \| `tests` \| `tools` \| `rust_tools` \| `all` | `examples` |
 | Options | `clean` `cleanall` `install` `install=<path>` `cargo_install` `tidy` | — |
 
@@ -111,6 +113,9 @@ Examples:
 # rtos config: freertos_demo (Linux/macOS only)
 ./build.sh rtos examples
 
+# raw config: udp_raw_demo, raw Ethernet transport (Linux only, needs CAP_NET_RAW)
+./build.sh raw examples
+
 # Library only, install to build/install
 ./build.sh lib install
 
@@ -173,6 +178,10 @@ cmake --build build-shm --parallel
 cmake -B build-rtos -S . -DXCPLITE_CONFIGURATION=rtos -DXCPLITE_BUILD_EXAMPLES=ON
 cmake --build build-rtos --parallel
 
+# raw configuration — udp_raw_demo, raw Ethernet transport (Linux only)
+cmake -B build-raw -S . -DXCPLITE_CONFIGURATION=raw -DXCPLITE_BUILD_EXAMPLES=ON
+cmake --build build-raw --parallel
+
 # Build a specific target
 cmake --build build --target hello_xcp
 
@@ -341,5 +350,6 @@ To test all configurations:
 ./build.sh ptp tools               # ptp config, tools (Linux only)
 ./build.sh no_a2l examples         # no_a2l config
 ./build.sh rtos examples           # rtos config (Linux/macOS only)
+./build.sh raw examples            # raw config (Linux only, see docs/SOCKET_RAW.md)
 ```