Improve introductory XDP documentation with comprehensive getting started guide and enhanced API docs

.azure/templates/build.yml

@@ -51,7 +51,7 @@ jobs:
     inputs:
       restoreSolution: xdp.sln
       feedsToUse: config
-      nugetConfigPath: ./src/nuget.config
+      nugetConfigPath: ./tools/nuget.config
 
   - task: PowerShell@2
     displayName: Prepare for compiling eBPF programs

.github/copilot-instructions.md

@@ -0,0 +1,184 @@
+# Copilot Instructions for XDP for Windows
+
+## Repository Overview
+
+XDP for Windows is a high-performance Windows packet processing framework inspired by Linux XDP. It enables sending and receiving network packets at high rates by bypassing most of the OS networking stack.
+
+**Key facts:**
+- **Languages**: C (kernel drivers), C++ (user-mode tests/samples), PowerShell (build/test scripts)
+- **Frameworks**: Windows Driver Kit (WDK), NDIS, TAEF (test framework)
+- **Target**: Windows Server 2019/2022 and Prerelease builds, x64 and arm64 platforms
+- **Build Tool**: MSBuild via Visual Studio Developer Command Prompt
+
+## Build Instructions
+
+### Prerequisites
+- Visual Studio 2022+ with:
+  - "Desktop development with C++" workload
+  - Latest Spectre-mitigated libs
+  - C++ Address Sanitizer
+  - C++ Clang Compiler for Windows
+- NuGet CLI 6.3.1+
+- Git submodules initialized (`git submodule update --init --recursive`)
+
+### Building
+
+**Always run builds from a Visual Studio Developer Command Prompt.**
+
+1. Prepare the machine (downloads dependencies):
+   ```powershell
+   .\tools\prepare-machine.ps1 -ForBuild
+   ```
+
+2. Restore NuGet packages (required before every build if packages changed):
+   ```powershell
+   msbuild.exe xdp.sln /t:restore /p:RestoreConfigFile=tools/nuget.config /p:Configuration=Debug /p:Platform=x64
+   ```
+
+3. Prepare for eBPF compilation (if building eBPF programs):
+   ```powershell
+   .\tools\prepare-machine.ps1 -ForEbpfBuild
+   ```
+
+4. Build the solution:
+   ```powershell
+   msbuild xdp.sln /m /p:Configuration=Debug /p:Platform=x64 /p:SignMode=TestSign /p:IsAdmin=true /nodeReuse:false
+   ```
+
+**Or use the convenience script:**
+```powershell
+.\tools\build.ps1
+```
+
+**Important**: Use `/nodeReuse:false` to avoid cached state issues with WDK's build tasks.
+
+### Build Configurations
+- **Config**: `Debug` or `Release`
+- **Platform**: `x64` or `arm64`
+- **Build artifacts**: `artifacts\bin\{Platform}_{Config}\`
+
+## Testing
+
+All testing must occur on a separate test machine. Do not try to run tests locally.
+
+### Functional Tests
+
+1. Prepare test machine (requires admin, enables test signing, may require reboot):
+   ```powershell
+   .\tools\prepare-machine.ps1 -ForFunctionalTest
+   ```
+
+2. Run tests:
+   ```powershell
+   .\tools\functional.ps1 -Config Debug -Platform x64
+   ```
+
+3. Run specific test:
+   ```powershell
+   .\tools\functional.ps1 -TestCaseFilter "Name=GenericBinding"
+   ```
+
+4. List test cases:
+   ```powershell
+   .\tools\functional.ps1 -ListTestCases
+   ```
+
+5. Convert logs after test:
+   ```powershell
+   .\tools\log.ps1 -Convert -Name xdpfunc
+   ```
+
+### Stress Tests (spinxsk)
+
+```powershell
+.\tools\prepare-machine.ps1 -ForSpinxskTest
+.\tools\spinxsk.ps1 -XdpmpPollProvider FNDIS -QueueCount 2 -Minutes 10
+.\tools\log.ps1 -Convert -Name spinxsk
+```
+
+## Project Layout
+
+```
+xdp.sln                 # Main solution file
+src/                    # Source code
+  xdp/                  # Core XDP driver (xdp.sys)
+  xdplwf/               # LWF (Lightweight Filter) driver
+  xdpapi/               # User-mode API library (deprecated, use header-only API)
+  xdpetw/               # ETW manifest
+  xdpinstaller/         # MSI installer
+  xdpruntime/           # Runtime packaging
+published/external/     # Public API headers
+  afxdp.h               # AF_XDP socket API
+  afxdp_experimental.h  # Experimental AF_XDP features
+  xdpapi.h              # XDP control API
+  xdp/                  # XDP kernel/user shared definitions
+test/                   # Test code
+  functional/           # TAEF functional tests
+    lib/tests.cpp       # Test implementation
+    taef/tests.cpp      # TAEF wrappers
+  spinxsk/              # Stress test tool
+  xdpmp/                # Test miniport driver
+samples/                # Sample applications
+  rxfilter/             # RX filtering sample
+  xskfwd/               # XSK forwarding sample
+tools/                  # PowerShell scripts
+  build.ps1             # Build script
+  functional.ps1        # Functional test runner
+  prepare-machine.ps1   # Machine setup
+  setup.ps1             # Component installation
+submodules/             # Git submodules
+  cxplat/               # Cross-platform utilities
+  ndis-driver-library/  # NDIS helpers
+  wil/                  # Windows Implementation Libraries
+```
+
+## CI Pipeline
+
+GitHub Actions CI runs on pull requests (`.github/workflows/ci.yml`):
+1. **Build**: Debug/Release × x64/arm64
+2. **Functional Tests**: Windows 2022/Prerelease
+3. **Stress Tests (spinxsk)**: With driver verifier and fault injection
+4. **Performance Tests**: XSK perf, ring perf, RX filter perf
+5. **Fuzz Tests**: Packet parsing fuzzer (pktfuzz)
+6. **CodeQL**: Security analysis (on scheduled runs)
+
+CI uses test-signed drivers and requires test signing enabled on test machines.
+
+## Adding Tests
+
+When adding functional tests:
+1. Add test implementation to `test/functional/lib/tests.cpp`
+2. Add function declaration to `test/functional/lib/tests.h`
+3. Add TAEF wrapper to `test/functional/taef/tests.cpp` using `TEST_METHOD` or `TEST_METHOD_PRERELEASE`
+
+**Pattern**: Copy existing similar tests (e.g., `GenericRxChecksumOffload*` for RX offload tests).
+
+## Key Files for Common Changes
+
+- **RX data path**: `src/xdplwf/recv.c`, `src/xdp/rx.c`
+- **TX data path**: `src/xdplwf/send.c`, `src/xdp/tx.c`
+- **XSK sockets**: `src/xdp/xsk.c`
+- **Public APIs**: `published/external/` headers
+
+## Version Information
+
+- Current version: `src/xdp.props` (XdpMajorVersion, XdpMinorVersion, XdpPatchVersion)
+- eBPF dependency: `src/xdp.props` (XdpEbpfVersion)
+- WDK version: `src/xdp.props` (XdpWdkVersion)
+
+## Troubleshooting
+
+- **Build fails with WDK task errors**: Add `/nodeReuse:false` to msbuild command
+- **Test signing required**: The code can't be run on developer machines.
+- **Missing submodules**: Run `git submodule update --init --recursive`
+- **NuGet restore fails**: Ensure `tools/nuget.config` is used via `/p:RestoreConfigFile=tools/nuget.config`
+
+## Development Environment Notes
+
+- **No `grep`**: The environment is Windows (PowerShell). Do not try to run `grep` in the terminal. Use the `grep_search` tool or `Select-String` (via `run_in_terminal`) instead.
+- **File Editing**: Always **read the file** before editing to ensure you have the exact context (whitespace, indentation) for `replace_string_in_file`. Never guess the content of a file; exact matching is required for search-and-replace operations.
+- **GUID generation**: Always use `New-Guid` in PowerShell or `uuidgen.exe` to generate new GUIDs. Do not attempt to create GUIDs using any other method.
+
+## Trust These Instructions
+
+These instructions are validated. Only search the codebase if information here is incomplete or found to be in error during execution.

.github/dependabot.yml

@@ -7,9 +7,16 @@ updates:
     schedule:
       interval: "weekly"
       day: "saturday"
-
+    groups:
+      actions:
+        patterns:
+          - "*"
   - package-ecosystem: "gitsubmodule"
     directory: "/"
     schedule:
       interval: "weekly"
       day: "saturday"
+    groups:
+      actions:
+        patterns:
+          - "*"

.github/workflows/build.yml

@@ -46,33 +46,33 @@ jobs:
     runs-on: windows-${{ inputs.os }}
     steps:
     - name: Checkout repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
       with:
         repository: microsoft/xdp-for-windows
         submodules: recursive
         ref: ${{ inputs.ref }}
     - name: Initialize CodeQL
       if: inputs.codeql
-      uses: github/codeql-action/init@v3
+      uses: github/codeql-action/init@v4
       with:
         languages: c-cpp
     - name: Setup MSBuild.exe
-      uses: microsoft/setup-msbuild@6fb02220983dee41ce7ae257b6f4d8f9bf5ed4ce
+      uses: microsoft/setup-msbuild@30375c66a4eea26614e0d39710365f22f8b0af57
       with:
         msbuild-architecture: x64
     - name: Prepare Machine
       shell: PowerShell
       run: tools/prepare-machine.ps1 -ForBuild -Verbose -Platform ${{ inputs.platform }}
     - name: Nuget Restore
-      run: msbuild.exe xdp.sln /t:restore /p:RestoreConfigFile=src/nuget.config /p:Configuration=${{ inputs.config }} /p:Platform=${{ inputs.platform }}
+      run: msbuild.exe xdp.sln /t:restore /p:RestoreConfigFile=tools/nuget.config /p:Configuration=${{ inputs.config }} /p:Platform=${{ inputs.platform }}
     - name: Prepare for compiling eBPF programs
       run: tools/prepare-machine.ps1 -ForEbpfBuild -Verbose -Platform ${{ inputs.platform }}
     - name: Build
       # See /tools/build.ps1 for /nodeReuse:false discussion.
       run: msbuild xdp.sln /m /p:configuration=${{ inputs.config }} /p:platform=${{ inputs.platform }} /p:SignMode=TestSign /p:IsAdmin=true /nodeReuse:false
     - name: Upload Artifacts
       if: inputs.artifact_path != ''
-      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
       with:
         name: ${{inputs.artifact_path}}
         path: |
@@ -82,6 +82,6 @@ jobs:
           !artifacts/bin/**/*.lastcodeanalysissucceeded
     - name: Perform CodeQL Analysis
       if: inputs.codeql
-      uses: github/codeql-action/analyze@v3
+      uses: github/codeql-action/analyze@v4
       with:
         category: "/language:c-cpp"

.github/workflows/build_matrix.yml

@@ -45,5 +45,5 @@ jobs:
       os: ${{ matrix.os }}
       platform: ${{ matrix.platform }}
       ref: ${{ inputs.ref }}
-      codeql: ${{ inputs.codeql && github.event_name == 'schedule' }}
+      codeql: ${{ (inputs.codeql || false) && github.event_name == 'schedule' }}
       artifact_path: ${{ matrix.os == 2022 && format('bin_{0}_{1}{2}', matrix.config, matrix.platform, (inputs.id != '' && format('_{0}', inputs.id) || '')) || '' }}

.github/workflows/ci-release-branches.yml

@@ -0,0 +1,31 @@
+name: CI (Release Branches)
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '47 3 * * 1' # Weekly on Sunday night (3:47 AM UTC Monday); non-round minute to avoid thundering herd
+
+permissions: read-all
+
+jobs:
+  trigger:
+    name: Trigger CI for release branches
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      with:
+        repository: microsoft/xdp-for-windows
+        fetch-depth: 0
+    - name: Trigger CI for each supported release branch
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        branches=$(jq -r '.branches[] | select(.supported) | .branch' release-branches.json)
+        for branch in $branches; do
+          echo "Triggering CI for $branch"
+          gh workflow run ci.yml --ref "$branch"
+        done