[2/3] Integrate XSK maps into the core XDP datapath (#6003)

## Description

**Full E2E demo using tools from this [PR
](#5999
[DEMO](https://microsoft.sharepoint.com/:v:/t/OSPlatformNetworking/cQoKsihSVC3kQ63QHixCTQ7hEgUCS3dPKZahhfyXC9GFfx8OFQ?nav=eyJyZWZlcnJhbEluZm8iOnsicmVmZXJyYWxBcHAiOiJTdHJlYW1XZWJBcHAiLCJyZWZlcnJhbFZpZXciOiJTaGFyZURpYWxvZy1MaW5rIiwicmVmZXJyYWxBcHBQbGF0Zm9ybSI6IldlYiIsInJlZmVycmFsTW9kZSI6InZpZXcifX0=&)

Part 2 of the plan: #5982
Fixes #5972

Adds the core msquic datapath integrations for the new API contract
defined in #5983

**Key design decisions:**
- If map mode is enabled, then we do not create the WinSock or Epoll or
.... datapaths. No more best effort!
- Init failures in map mode hard fails the datapath initialization. No
silent failures!

## Testing

Added datapath unit tests. See the E2E demo.

Additionally, the plan is to leverage some supporting PRs that included
code to ingest the latest XDP version, and kicking off a couple of
manual CI runs based on that:
https://github.com/microsoft/msquic/actions/runs/27313685557/job/80690420168

## Documentation

Will come as part 3 in the plan:
#5982

---------

Co-authored-by: Guillaume Hetier <guhetier@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

.github/workflows/test.yml

@@ -144,6 +144,7 @@ jobs:
           { config: "Debug", plat: "windows", os: "windows-2022", arch: "x64", tls: "schannel", xdp: "xdp-v1.1", sanitize: "-SanitizeAddress", build: "-Test" },
           { config: "Debug", plat: "windows", os: "windows-2022", arch: "x64", tls: "schannel", xdp: "xdp-v1.1", qtip: "-UseQtip", sanitize: "-SanitizeAddress", build: "-Test" },
           { config: "Debug", plat: "windows", os: "windows-2022", arch: "x64", tls: "schannel", xdp: "xdp-prerelease", build: "-Test" },
+          { config: "Debug", plat: "windows", os: "windows-2022", arch: "x64", tls: "schannel", xdp: "xdp-prerelease", qtip: "-UseQtip", build: "-Test" },
           { config: "Debug", plat: "windows", os: "windows-2022", arch: "x64", tls: "quictls", build: "-Test", log: "Full.Verbose" },
           { config: "Debug", plat: "windows", os: "windows-2022", arch: "x64", tls: "quictls", xdp: "xdp-v1.1", build: "-Test" },
           { config: "Debug", plat: "windows", os: "windows-2022", arch: "x64", tls: "quictls", xdp: "xdp-v1.1", qtip: "-UseQtip", build: "-Test" },
@@ -202,16 +203,21 @@ jobs:
       shell: pwsh
       timeout-minutes: 120
       run: scripts/test.ps1 -Config ${{ matrix.vec.config }} -Arch ${{ matrix.vec.arch }} -Tls ${{ matrix.vec.tls }} -GHA -LogProfile ${{ matrix.vec.log || (inputs.log_level || 'Full.Light') }} -GenerateXmlResults ${{ matrix.vec.xdp && '-UseXdp' }} ${{ matrix.vec.xdp }} ${{ matrix.vec.qtip }} ${{ inputs.filter && '-Filter' }} ${{ inputs.filter || '' }}
+    - name: Test (Map Mode Tests Only)
+      if: matrix.vec.xdp == 'xdp-prerelease'
+      shell: pwsh
+      timeout-minutes: 120
+      run: scripts/test.ps1 -Config ${{ matrix.vec.config }} -Arch ${{ matrix.vec.arch }} -Tls ${{ matrix.vec.tls }} -OsRunner ${{ matrix.vec.os }} -GHA -LogProfile ${{ matrix.vec.log || (inputs.log_level || 'Full.Light') }} -GenerateXmlResults ${{ matrix.vec.xdp && '-UseXdp' }} ${{ matrix.vec.xdp }} ${{ matrix.vec.qtip }} -Filter '*XdpMapMode*' -XdpMapMode
     - name: Test
       if: matrix.vec.os != 'WinServerPrerelease'
       shell: pwsh
       timeout-minutes: 120
-      run: scripts/test.ps1 -Config ${{ matrix.vec.config }} -Arch ${{ matrix.vec.arch }} -Tls ${{ matrix.vec.tls }} -OsRunner ${{ matrix.vec.os }} -GHA -LogProfile ${{ matrix.vec.log || (inputs.log_level || 'Full.Light') }} -GenerateXmlResults ${{ matrix.vec.xdp && '-UseXdp' }} ${{ matrix.vec.xdp }} ${{ matrix.vec.qtip }} ${{ inputs.filter && '-Filter' }} ${{ inputs.filter || '' }}
+      run: scripts/test.ps1 -Config ${{ matrix.vec.config }} -Arch ${{ matrix.vec.arch }} -Tls ${{ matrix.vec.tls }} -OsRunner ${{ matrix.vec.os }} -GHA -LogProfile ${{ matrix.vec.log || (inputs.log_level || 'Full.Light') }} -GenerateXmlResults ${{ matrix.vec.xdp && '-UseXdp' }} ${{ matrix.vec.xdp }} ${{ matrix.vec.qtip }} ${{ matrix.vec.xdpmapmode }} ${{ inputs.filter && '-Filter' }} ${{ inputs.filter || '' }}
     - name: Upload on Failure or Cancellation
       uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
       if: failure() || cancelled()
       with:
-        name: BVT-${{ matrix.vec.config }}-${{ matrix.vec.plat }}-${{ matrix.vec.os }}-${{ matrix.vec.arch }}-${{ matrix.vec.tls }}${{ matrix.vec.xdp }}${{ matrix.vec.iouring }}${{ matrix.vec.qtip }}${{ matrix.vec.systemcrypto }}${{ matrix.vec.sanitize }}
+        name: BVT-${{ matrix.vec.config }}-${{ matrix.vec.plat }}-${{ matrix.vec.os }}-${{ matrix.vec.arch }}-${{ matrix.vec.tls }}${{ matrix.vec.xdp }}${{ matrix.vec.iouring }}${{ matrix.vec.qtip }}${{ matrix.vec.xdpmapmode }}${{ matrix.vec.systemcrypto }}${{ matrix.vec.sanitize }}
         path: artifacts
 
   bvt-kernel:

scripts/run-gtest.ps1

@@ -62,6 +62,9 @@ as necessary.
 .PARAMETER DuoNic
     Uses DuoNic instead of loopback.
 
+.PARAMETER XdpMapMode
+    Uses XDP map mode with DuoNic.
+
 #>
 
 param (
@@ -133,6 +136,9 @@ param (
     [Parameter(Mandatory = $false)]
     [switch]$DuoNic = $false,
 
+    [Parameter(Mandatory = $false)]
+    [switch]$XdpMapMode = $false,
+
     [Parameter(Mandatory = $false)]
     [string]$OsRunner = "",
 
@@ -403,6 +409,9 @@ function Start-TestCase([String]$Name) {
     if ($DuoNic) {
         $Arguments += " --duoNic"
     }
+    if ($XdpMapMode) {
+        $Arguments += " --xdpMapMode"
+    }
     if ($UseQtip) {
         $Arguments += " --useQTIP"
     }
@@ -450,6 +459,9 @@ function Start-AllTestCases {
     if ($DuoNic) {
         $Arguments += " --duoNic"
     }
+    if ($XdpMapMode) {
+        $Arguments += " --xdpMapMode"
+    }
     if ($UseQtip) {
         $Arguments += " --useQTIP"
     }

scripts/test.ps1

@@ -70,6 +70,9 @@ This script runs the MsQuic tests.
 .Parameter DuoNic
     Uses DuoNic instead of loopback (DuoNic must already be installed via 'prepare-machine.ps1 -InstallDuoNic').
 
+.Parameter XdpMapMode
+    Uses XDP map mode with DuoNic (Windows user-mode only, requires XDP + DuoNic).
+
 .Parameter NumIterations
     Number of times to run this particular command. Catches tricky edge cases due to random nature of networks.
 
@@ -178,6 +181,9 @@ param (
     [Parameter(Mandatory = $false)]
     [switch]$DuoNic = $false,
 
+    [Parameter(Mandatory = $false)]
+    [switch]$XdpMapMode = $false,
+
     [Parameter(Mandatory = $false)]
     [string]$UseXdp = "",
 
@@ -230,9 +236,14 @@ $Tls = $BuildConfig.Tls
 $Arch = $BuildConfig.Arch
 $RootArtifactDir = $BuildConfig.ArtifactsDir
 
+if ($XdpMapMode) {
+    if ([string]::IsNullOrEmpty($UseXdp)) {
+        Write-Error "-XdpMapMode requires -UseXdp to specify an XDP version (e.g. 'xdp-prerelease')."
+    }
+}
+
 if ($UseXdp) {
-    # Helper for XDP usage (every XDP version runs over the same datapath; only
-    # the installed driver differs).
+    # XDP usage (and map mode) implies DuoNic.
     $DuoNic = $true
 }
 
@@ -299,6 +310,9 @@ $TestArguments =  "-IsolationMode $IsolationMode -PfxPath $PfxFile"
 if ($DuoNic) {
     $TestArguments += " -DuoNic"
 }
+if ($XdpMapMode) {
+    $TestArguments += " -XdpMapMode"
+}
 if ($Kernel) {
     $TestArguments += " -Kernel $KernelPath"
 }

scripts/update-sidecar.ps1

@@ -33,10 +33,15 @@ if (Test-Path $OutputDir) {
     }
 }
 
+$TmpOutputDir = Join-Path $RootDir "build" "tmp"
+
+# Clean stale generated files so removed/renamed sources don't leave orphans
+if (Test-Path $TmpOutputDir) {
+    Remove-Item $TmpOutputDir -Recurse -Force
+}
+
 $Sidecar = Join-Path $SrcDir "manifest" "clog.sidecar"
 $ConfigFile = Join-Path $SrcDir "manifest" "msquic.clog_config"
-
-$TmpOutputDir = Join-Path $RootDir "build" "tmp"
 $ClogDir = Join-Path $RootDir "build" "clog"
 
 # Create directories

src/core/library.c

@@ -915,6 +915,8 @@ QuicLibraryLazyInitialize(
 
     CXPLAT_DATAPATH_INIT_CONFIG InitConfig = {0};
     InitConfig.EnableDscpOnRecv = MsQuicLib.EnableDscpOnRecv;
+    InitConfig.XdpMapConfigs = MsQuicLib.XdpMapConfigs;
+    InitConfig.XdpMapConfigCount = MsQuicLib.XdpMapConfigCount;
 
     Status =
         CxPlatDataPathInitialize(
@@ -1057,6 +1059,34 @@ QuicLibApplyLoadBalancingSetting(
         MsQuicLib.CidTotalLength);
 }
 
+static
+void
+QuicLibXdpMapConfigToPlat(
+    _Out_writes_(Count) CXPLAT_XDP_MAP_CONFIG* Dest,
+    _In_reads_(Count) const QUIC_XDP_MAP_CONFIG* Src,
+    _In_ uint32_t Count
+    )
+{
+    for (uint32_t i = 0; i < Count; i++) {
+        Dest[i].InterfaceIndex = Src[i].InterfaceIndex;
+        Dest[i].MapHandle = Src[i].MapHandle;
+    }
+}
+
+static
+void
+QuicLibXdpMapConfigFromPlat(
+    _Out_writes_(Count) QUIC_XDP_MAP_CONFIG* Dest,
+    _In_reads_(Count) const CXPLAT_XDP_MAP_CONFIG* Src,
+    _In_ uint32_t Count
+    )
+{
+    for (uint32_t i = 0; i < Count; i++) {
+        Dest[i].InterfaceIndex = Src[i].InterfaceIndex;
+        Dest[i].MapHandle = Src[i].MapHandle;
+    }
+}
+
 _IRQL_requires_max_(PASSIVE_LEVEL)
 QUIC_STATUS
 QuicLibrarySetGlobalParam(
@@ -1473,20 +1503,23 @@ QuicLibrarySetGlobalParam(
             break;
         }
 
-        QUIC_XDP_MAP_CONFIG* NewConfigs =
-            CXPLAT_ALLOC_NONPAGED(BufferLength, QUIC_POOL_XDP_MAP_CONFIG);
+        const size_t AllocSize = Count * sizeof(CXPLAT_XDP_MAP_CONFIG);
+        CXPLAT_XDP_MAP_CONFIG* NewConfigs =
+            CXPLAT_ALLOC_NONPAGED(
+                AllocSize,
+                QUIC_POOL_XDP_MAP_CONFIG);
         if (NewConfigs == NULL) {
             CxPlatLockRelease(&MsQuicLib.Lock);
             QuicTraceEvent(
                 AllocFailure,
                 "Allocation of '%s' failed. (%llu bytes)",
                 "XDP map config",
-                BufferLength);
+                AllocSize);
             Status = QUIC_STATUS_OUT_OF_MEMORY;
             break;
         }
 
-        CxPlatCopyMemory(NewConfigs, Configs, BufferLength);
+        QuicLibXdpMapConfigToPlat(NewConfigs, Configs, Count);
 
         if (MsQuicLib.XdpMapConfigs != NULL) {
             CXPLAT_FREE(MsQuicLib.XdpMapConfigs, QUIC_POOL_XDP_MAP_CONFIG);
@@ -1507,6 +1540,7 @@ QuicLibrarySetGlobalParam(
 }
 
 _IRQL_requires_max_(PASSIVE_LEVEL)
+_Success_(return == QUIC_STATUS_SUCCESS)
 QUIC_STATUS
 QuicLibraryGetGlobalParam(
     _In_ uint32_t Param,
@@ -1871,7 +1905,10 @@ QuicLibraryGetGlobalParam(
             break;
         }
         *BufferLength = RequiredLength;
-        CxPlatCopyMemory(Buffer, MsQuicLib.XdpMapConfigs, RequiredLength);
+        QuicLibXdpMapConfigFromPlat(
+            (QUIC_XDP_MAP_CONFIG*)Buffer,
+            MsQuicLib.XdpMapConfigs,
+            MsQuicLib.XdpMapConfigCount);
         CxPlatLockRelease(&MsQuicLib.Lock);
         Status = QUIC_STATUS_SUCCESS;
         break;

src/core/library.h

@@ -208,7 +208,7 @@ typedef struct QUIC_LIBRARY {
     // Set via QUIC_PARAM_GLOBAL_XDP_MAP_CONFIG before any registration.
     // May be updated multiple times before the first registration is opened.
     //
-    const QUIC_XDP_MAP_CONFIG* XdpMapConfigs;
+    const CXPLAT_XDP_MAP_CONFIG* XdpMapConfigs;
     uint32_t XdpMapConfigCount;
 
     //
@@ -538,6 +538,7 @@ QuicLibrarySetGlobalParam(
     );
 
 _IRQL_requires_max_(PASSIVE_LEVEL)
+_Success_(return == QUIC_STATUS_SUCCESS)
 QUIC_STATUS
 QuicLibraryGetGlobalParam(
     _In_ uint32_t Param,

src/core/settings.c

@@ -712,6 +712,18 @@ QuicSettingApply(
         Destination->IsSet.ReliableResetEnabled = TRUE;
     }
 
+    //
+    // If XDP map mode is active (XdpMapConfigCount > 0), XDP is implicitly
+    // enabled for all sockets. Reject an explicit XdpEnabled = FALSE since
+    // it contradicts map mode — there is no OS datapath to fall back to.
+    //
+    if (Source->IsSet.XdpEnabled && !Source->XdpEnabled && MsQuicLib.XdpMapConfigCount > 0) {
+        QuicTraceLogError(
+            SettingXdpDisabledInMapMode,
+            "[ lib] Error: Xdp must be enabled when an XDP map was configured.");
+        return FALSE;
+    }
+
     if (Source->IsSet.XdpEnabled && (!Destination->IsSet.XdpEnabled || OverWrite)) {
         Destination->XdpEnabled = Source->XdpEnabled;
         Destination->IsSet.XdpEnabled = TRUE;

src/generated/linux/datapath_raw.c.clog.h

@@ -14,13 +14,35 @@
 #include "datapath_raw.c.clog.h.lttng.h"
 #endif
 #include <lttng/tracepoint-event.h>
+#ifndef _clog_MACRO_QuicTraceLogVerbose
+#define _clog_MACRO_QuicTraceLogVerbose  1
+#define QuicTraceLogVerbose(a, ...) _clog_CAT(_clog_ARGN_SELECTOR(__VA_ARGS__), _clog_CAT(_,a(#a, __VA_ARGS__)))
+#endif
 #ifndef _clog_MACRO_QuicTraceEvent
 #define _clog_MACRO_QuicTraceEvent  1
 #define QuicTraceEvent(a, ...) _clog_CAT(_clog_ARGN_SELECTOR(__VA_ARGS__), _clog_CAT(_,a(#a, __VA_ARGS__)))
 #endif
 #ifdef __cplusplus
 extern "C" {
 #endif
+/*----------------------------------------------------------
+// Decoder Ring for DatapathRawMapInsertFail
+// [  dp] XDP map mode: failed to insert XSK sockets into map, status:%d
+// QuicTraceLogVerbose(
+                DatapathRawMapInsertFail,
+                "[  dp] XDP map mode: failed to insert XSK sockets into map, status:%d",
+                Status);
+// arg2 = arg2 = Status = arg2
+----------------------------------------------------------*/
+#ifndef _clog_3_ARGS_TRACE_DatapathRawMapInsertFail
+#define _clog_3_ARGS_TRACE_DatapathRawMapInsertFail(uniqueId, encoded_arg_string, arg2)\
+tracepoint(CLOG_DATAPATH_RAW_C, DatapathRawMapInsertFail , arg2);\
+
+#endif
+
+
+
+
 /*----------------------------------------------------------
 // Decoder Ring for AllocFailure
 // Allocation of '%s' failed. (%llu bytes)

src/generated/linux/datapath_raw.c.clog.h.lttng.h

@@ -1,6 +1,25 @@
 
 
 
+/*----------------------------------------------------------
+// Decoder Ring for DatapathRawMapInsertFail
+// [  dp] XDP map mode: failed to insert XSK sockets into map, status:%d
+// QuicTraceLogVerbose(
+                DatapathRawMapInsertFail,
+                "[  dp] XDP map mode: failed to insert XSK sockets into map, status:%d",
+                Status);
+// arg2 = arg2 = Status = arg2
+----------------------------------------------------------*/
+TRACEPOINT_EVENT(CLOG_DATAPATH_RAW_C, DatapathRawMapInsertFail,
+    TP_ARGS(
+        int, arg2), 
+    TP_FIELDS(
+        ctf_integer(int, arg2, arg2)
+    )
+)
+
+
+
 /*----------------------------------------------------------
 // Decoder Ring for AllocFailure
 // Allocation of '%s' failed. (%llu bytes)