Add QUIC_PARAM_GLOBAL_WORKER_STATISTICS for per-worker statistics

Adds a preview global parameter to retrieve per-worker active and wall
time statistics. Active time is tracked via timestamps in the platform
worker loop. Kernel mode returns QUIC_STATUS_NOT_SUPPORTED.

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

Author: guhetier

src/core/library.c

@@ -1506,6 +1506,56 @@ QuicLibrarySetGlobalParam(
     return Status;
 }
 
+#ifndef _KERNEL_MODE
+//
+// Fills the caller's buffer with the per-worker statistics from the worker pool.
+//
+_IRQL_requires_max_(PASSIVE_LEVEL)
+QUIC_STATUS
+QuicLibraryGetGlobalWorkerStatistics(
+    _Inout_ uint32_t* BufferLength,
+    _Out_writes_bytes_opt_(*BufferLength)
+        void* Buffer
+    )
+{
+    if (MsQuicLib.WorkerPool == NULL) {
+        return QUIC_STATUS_INVALID_STATE;
+    }
+
+    uint32_t WorkerCount = CxPlatWorkerPoolGetCount(MsQuicLib.WorkerPool);
+    uint32_t RequiredSize =
+        sizeof(QUIC_WORKER_STATISTICS_LIST) +
+        WorkerCount * sizeof(QUIC_WORKER_STATISTICS);
+
+    if (*BufferLength < RequiredSize) {
+        *BufferLength = RequiredSize;
+        return QUIC_STATUS_BUFFER_TOO_SMALL;
+    }
+
+    if (Buffer == NULL) {
+        return QUIC_STATUS_INVALID_PARAMETER;
+    }
+
+    QUIC_WORKER_STATISTICS_LIST* List = (QUIC_WORKER_STATISTICS_LIST*)Buffer;
+    List->WorkerCount = WorkerCount;
+    List->WorkerStatsSize = sizeof(QUIC_WORKER_STATISTICS);
+
+    QUIC_WORKER_STATISTICS* Stats =
+        (QUIC_WORKER_STATISTICS*)((uint8_t*)Buffer + sizeof(QUIC_WORKER_STATISTICS_LIST));
+
+    for (uint32_t i = 0; i < WorkerCount; i++) {
+        CXPLAT_WORKER_STATISTICS WorkerStats = {0};
+        CxPlatWorkerPoolGetStatistics(MsQuicLib.WorkerPool, i, &WorkerStats);
+        Stats[i].IdealProcessor = WorkerStats.IdealProcessor;
+        Stats[i].CumulativeActiveTimeUs = WorkerStats.CumulativeActiveTimeUs;
+        Stats[i].CumulativeWallTimeUs = WorkerStats.CumulativeWallTimeUs;
+    }
+
+    *BufferLength = RequiredSize;
+    return QUIC_STATUS_SUCCESS;
+}
+#endif // !_KERNEL_MODE
+
 _IRQL_requires_max_(PASSIVE_LEVEL)
 QUIC_STATUS
 QuicLibraryGetGlobalParam(
@@ -1876,6 +1926,19 @@ QuicLibraryGetGlobalParam(
         break;
     }
 
+    case QUIC_PARAM_GLOBAL_WORKER_STATISTICS: {
+#ifdef _KERNEL_MODE
+        //
+        // Worker statistics are not supported in kernel mode, where the worker
+        // threads are not owned by the platform worker pool.
+        //
+        Status = QUIC_STATUS_NOT_SUPPORTED;
+#else
+        Status = QuicLibraryGetGlobalWorkerStatistics(BufferLength, Buffer);
+#endif
+        break;
+    }
+
     default:
         Status = QUIC_STATUS_INVALID_PARAMETER;
         break;

src/inc/msquic.h

@@ -370,6 +370,27 @@ typedef struct QUIC_XDP_MAP_CONFIG {
 
 #endif // QUIC_API_ENABLE_PREVIEW_FEATURES
 
+#ifdef QUIC_API_ENABLE_PREVIEW_FEATURES
+
+//
+// Per-worker statistics.
+//
+typedef struct QUIC_WORKER_STATISTICS {
+    uint64_t CumulativeActiveTimeUs;     // total time the worker spent active (not idle)
+    uint64_t CumulativeWallTimeUs;       // wall time since the worker thread started
+    uint16_t IdealProcessor;             // CPU the partition is affinitized to
+
+    // -- append-only beyond this point --
+} QUIC_WORKER_STATISTICS;
+
+typedef struct QUIC_WORKER_STATISTICS_LIST {
+    uint32_t WorkerCount;        // number of QUIC_WORKER_STATISTICS entries that follow
+    uint32_t WorkerStatsSize;    // sizeof(QUIC_WORKER_STATISTICS) as written by this msquic
+    // QUIC_WORKER_STATISTICS Workers[WorkerCount];   // stride == WorkerStatsSize
+} QUIC_WORKER_STATISTICS_LIST;
+
+#endif // QUIC_API_ENABLE_PREVIEW_FEATURES
+
 typedef struct QUIC_REGISTRATION_CONFIG { // All fields may be NULL/zero.
     const char* AppName;
     QUIC_EXECUTION_PROFILE ExecutionProfile;
@@ -996,6 +1017,7 @@ void
 #define QUIC_PARAM_GLOBAL_STATELESS_RETRY_CONFIG        0x0100000D  // QUIC_STATELESS_RETRY_CONFIG
 #ifdef QUIC_API_ENABLE_PREVIEW_FEATURES
 #define QUIC_PARAM_GLOBAL_XDP_MAP_CONFIG                0x0100000E  // QUIC_XDP_MAP_CONFIG[]
+#define QUIC_PARAM_GLOBAL_WORKER_STATISTICS             0x0100000F  // QUIC_WORKER_STATISTICS_LIST
 #endif
 
 //

src/inc/quic_platform.h

@@ -557,6 +557,22 @@ CxPlatWorkerPoolWorkerPoll(
     _In_ QUIC_EXECUTION* Execution
     );
 
+typedef struct CXPLAT_WORKER_STATISTICS {
+    uint64_t CumulativeActiveTimeUs;    // Time the worker spent active (not idle).
+    uint64_t CumulativeWallTimeUs;      // Wall time since the worker thread started.
+    uint16_t IdealProcessor;            // CPU the worker is affinitized to.
+} CXPLAT_WORKER_STATISTICS;
+
+//
+// Gets the statistics for a worker in the pool
+//
+void
+CxPlatWorkerPoolGetStatistics(
+    _In_ CXPLAT_WORKER_POOL* WorkerPool,
+    _In_ uint32_t Index,
+    _Out_ CXPLAT_WORKER_STATISTICS* Stats
+    );
+
 //
 // Supports more dynamic operations, but must be submitted to the platform worker
 // to manage.

src/platform/platform_worker.c

@@ -102,6 +102,26 @@ typedef struct QUIC_CACHEALIGN CXPLAT_WORKER {
     //
     BOOLEAN Running;
 
+    //
+    // Statistics tracking for active time measurement.
+    //
+    struct {
+        //
+        // Timestamp (in microseconds) when the worker thread started.
+        //
+        uint64_t StartedTimeUs;
+
+        //
+        // Timestamp (in microseconds) when the current active period started.
+        //
+        uint64_t ActiveStartTimeUs;
+
+        //
+        // Cumulative time (in microseconds) the worker was active (not waiting or yielding).
+        //
+        uint64_t CumulativeActiveTimeUs;
+    } Stats;
+
 } CXPLAT_WORKER;
 
 typedef struct CXPLAT_WORKER_POOL {
@@ -734,12 +754,23 @@ CxPlatProcessEvents(
     )
 {
     CXPLAT_CQE Cqes[16];
+
+    if (Worker->State.WaitTime > 0) {
+        Worker->Stats.CumulativeActiveTimeUs +=
+            CxPlatTimeDiff64(Worker->Stats.ActiveStartTimeUs, CxPlatTimeUs64());
+    }
+
     uint32_t CqeCount =
         CxPlatEventQDequeue(
             &Worker->EventQ,
             Cqes,
             ARRAYSIZE(Cqes),
             Worker->State.WaitTime);
+
+    if (Worker->State.WaitTime > 0) {
+        Worker->Stats.ActiveStartTimeUs = CxPlatTimeUs64();
+    }
+
     uint32_t CurrentCqeCount = CqeCount;
     CXPLAT_CQE* CurrentCqe = Cqes;
 
@@ -796,6 +827,8 @@ CXPLAT_THREAD_CALLBACK(CxPlatWorkerThread, Context)
 
     Worker->State.ThreadID = CxPlatCurThreadID();
     Worker->Running = TRUE;
+    Worker->Stats.StartedTimeUs = CxPlatTimeUs64();
+    Worker->Stats.ActiveStartTimeUs = Worker->Stats.StartedTimeUs;
 
     while (!Worker->StoppedThread) {
 
@@ -816,7 +849,10 @@ CXPLAT_THREAD_CALLBACK(CxPlatWorkerThread, Context)
         if (Worker->State.NoWorkCount == 0) {
             Worker->State.LastWorkTime = Worker->State.TimeNow;
         } else if (Worker->State.NoWorkCount > CXPLAT_WORKER_IDLE_WORK_THRESHOLD_COUNT) {
+            Worker->Stats.CumulativeActiveTimeUs +=
+                CxPlatTimeDiff64(Worker->Stats.ActiveStartTimeUs, CxPlatTimeUs64());
             CxPlatSchedulerYield();
+            Worker->Stats.ActiveStartTimeUs = CxPlatTimeUs64();
             Worker->State.NoWorkCount = 0;
         }
 
@@ -826,6 +862,8 @@ CXPLAT_THREAD_CALLBACK(CxPlatWorkerThread, Context)
         }
     }
 
+    Worker->Stats.CumulativeActiveTimeUs +=
+        CxPlatTimeDiff64(Worker->Stats.ActiveStartTimeUs, CxPlatTimeUs64());
     Worker->Running = FALSE;
 
 #if DEBUG
@@ -839,3 +877,25 @@ CXPLAT_THREAD_CALLBACK(CxPlatWorkerThread, Context)
 
     CXPLAT_THREAD_RETURN(0);
 }
+
+void
+CxPlatWorkerPoolGetStatistics(
+    _In_ CXPLAT_WORKER_POOL* WorkerPool,
+    _In_ uint32_t Index,
+    _Out_ CXPLAT_WORKER_STATISTICS* Stats
+    )
+{
+    CXPLAT_DBG_ASSERT(Index < WorkerPool->WorkerCount);
+
+    const uint64_t Now = CxPlatTimeUs64();
+    const CXPLAT_WORKER* Worker = &WorkerPool->Workers[Index];
+
+    Stats->IdealProcessor = Worker->IdealProcessor;
+    Stats->CumulativeWallTimeUs = CxPlatTimeDiff64(Worker->Stats.StartedTimeUs, Now);
+    Stats->CumulativeActiveTimeUs = Worker->Stats.CumulativeActiveTimeUs;
+
+    const uint64_t ActiveStartTime = Worker->Stats.ActiveStartTimeUs;
+    if (ActiveStartTime < Now) {
+        Stats->CumulativeActiveTimeUs += CxPlatTimeDiff64(ActiveStartTime, Now);
+    }
+}

src/rs/ffi/linux_bindings.rs

@@ -176,6 +176,7 @@ pub const QUIC_PARAM_GLOBAL_STATELESS_RESET_KEY: u32 = 16777227;
 pub const QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES: u32 = 16777228;
 pub const QUIC_PARAM_GLOBAL_STATELESS_RETRY_CONFIG: u32 = 16777229;
 pub const QUIC_PARAM_GLOBAL_XDP_MAP_CONFIG: u32 = 16777230;
+pub const QUIC_PARAM_GLOBAL_WORKER_STATISTICS: u32 = 16777231;
 pub const QUIC_PARAM_CONFIGURATION_SETTINGS: u32 = 50331648;
 pub const QUIC_PARAM_CONFIGURATION_TICKET_KEYS: u32 = 50331649;
 pub const QUIC_PARAM_CONFIGURATION_VERSION_SETTINGS: u32 = 50331650;
@@ -519,6 +520,42 @@ const _: () = {
 };
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
+pub struct QUIC_WORKER_STATISTICS {
+    pub CumulativeActiveTimeUs: u64,
+    pub CumulativeWallTimeUs: u64,
+    pub IdealProcessor: u16,
+}
+#[allow(clippy::unnecessary_operation, clippy::identity_op)]
+const _: () = {
+    ["Size of QUIC_WORKER_STATISTICS"][::std::mem::size_of::<QUIC_WORKER_STATISTICS>() - 24usize];
+    ["Alignment of QUIC_WORKER_STATISTICS"]
+        [::std::mem::align_of::<QUIC_WORKER_STATISTICS>() - 8usize];
+    ["Offset of field: QUIC_WORKER_STATISTICS::CumulativeActiveTimeUs"]
+        [::std::mem::offset_of!(QUIC_WORKER_STATISTICS, CumulativeActiveTimeUs) - 0usize];
+    ["Offset of field: QUIC_WORKER_STATISTICS::CumulativeWallTimeUs"]
+        [::std::mem::offset_of!(QUIC_WORKER_STATISTICS, CumulativeWallTimeUs) - 8usize];
+    ["Offset of field: QUIC_WORKER_STATISTICS::IdealProcessor"]
+        [::std::mem::offset_of!(QUIC_WORKER_STATISTICS, IdealProcessor) - 16usize];
+};
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct QUIC_WORKER_STATISTICS_LIST {
+    pub WorkerCount: u32,
+    pub WorkerStatsSize: u32,
+}
+#[allow(clippy::unnecessary_operation, clippy::identity_op)]
+const _: () = {
+    ["Size of QUIC_WORKER_STATISTICS_LIST"]
+        [::std::mem::size_of::<QUIC_WORKER_STATISTICS_LIST>() - 8usize];
+    ["Alignment of QUIC_WORKER_STATISTICS_LIST"]
+        [::std::mem::align_of::<QUIC_WORKER_STATISTICS_LIST>() - 4usize];
+    ["Offset of field: QUIC_WORKER_STATISTICS_LIST::WorkerCount"]
+        [::std::mem::offset_of!(QUIC_WORKER_STATISTICS_LIST, WorkerCount) - 0usize];
+    ["Offset of field: QUIC_WORKER_STATISTICS_LIST::WorkerStatsSize"]
+        [::std::mem::offset_of!(QUIC_WORKER_STATISTICS_LIST, WorkerStatsSize) - 4usize];
+};
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
 pub struct QUIC_REGISTRATION_CONFIG {
     pub AppName: *const ::std::os::raw::c_char,
     pub ExecutionProfile: QUIC_EXECUTION_PROFILE,

src/rs/ffi/win_bindings.rs

@@ -170,6 +170,7 @@ pub const QUIC_PARAM_GLOBAL_STATELESS_RESET_KEY: u32 = 16777227;
 pub const QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES: u32 = 16777228;
 pub const QUIC_PARAM_GLOBAL_STATELESS_RETRY_CONFIG: u32 = 16777229;
 pub const QUIC_PARAM_GLOBAL_XDP_MAP_CONFIG: u32 = 16777230;
+pub const QUIC_PARAM_GLOBAL_WORKER_STATISTICS: u32 = 16777231;
 pub const QUIC_PARAM_CONFIGURATION_SETTINGS: u32 = 50331648;
 pub const QUIC_PARAM_CONFIGURATION_TICKET_KEYS: u32 = 50331649;
 pub const QUIC_PARAM_CONFIGURATION_VERSION_SETTINGS: u32 = 50331650;
@@ -517,6 +518,42 @@ const _: () = {
 };
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
+pub struct QUIC_WORKER_STATISTICS {
+    pub CumulativeActiveTimeUs: u64,
+    pub CumulativeWallTimeUs: u64,
+    pub IdealProcessor: u16,
+}
+#[allow(clippy::unnecessary_operation, clippy::identity_op)]
+const _: () = {
+    ["Size of QUIC_WORKER_STATISTICS"][::std::mem::size_of::<QUIC_WORKER_STATISTICS>() - 24usize];
+    ["Alignment of QUIC_WORKER_STATISTICS"]
+        [::std::mem::align_of::<QUIC_WORKER_STATISTICS>() - 8usize];
+    ["Offset of field: QUIC_WORKER_STATISTICS::CumulativeActiveTimeUs"]
+        [::std::mem::offset_of!(QUIC_WORKER_STATISTICS, CumulativeActiveTimeUs) - 0usize];
+    ["Offset of field: QUIC_WORKER_STATISTICS::CumulativeWallTimeUs"]
+        [::std::mem::offset_of!(QUIC_WORKER_STATISTICS, CumulativeWallTimeUs) - 8usize];
+    ["Offset of field: QUIC_WORKER_STATISTICS::IdealProcessor"]
+        [::std::mem::offset_of!(QUIC_WORKER_STATISTICS, IdealProcessor) - 16usize];
+};
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct QUIC_WORKER_STATISTICS_LIST {
+    pub WorkerCount: u32,
+    pub WorkerStatsSize: u32,
+}
+#[allow(clippy::unnecessary_operation, clippy::identity_op)]
+const _: () = {
+    ["Size of QUIC_WORKER_STATISTICS_LIST"]
+        [::std::mem::size_of::<QUIC_WORKER_STATISTICS_LIST>() - 8usize];
+    ["Alignment of QUIC_WORKER_STATISTICS_LIST"]
+        [::std::mem::align_of::<QUIC_WORKER_STATISTICS_LIST>() - 4usize];
+    ["Offset of field: QUIC_WORKER_STATISTICS_LIST::WorkerCount"]
+        [::std::mem::offset_of!(QUIC_WORKER_STATISTICS_LIST, WorkerCount) - 0usize];
+    ["Offset of field: QUIC_WORKER_STATISTICS_LIST::WorkerStatsSize"]
+        [::std::mem::offset_of!(QUIC_WORKER_STATISTICS_LIST, WorkerStatsSize) - 4usize];
+};
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
 pub struct QUIC_REGISTRATION_CONFIG {
     pub AppName: *const ::std::os::raw::c_char,
     pub ExecutionProfile: QUIC_EXECUTION_PROFILE,

src/test/MsQuicTests.h

@@ -91,6 +91,7 @@ void QuicTestStreamParam();
 void QuicTestGetPerfCounters();
 #ifdef QUIC_API_ENABLE_PREVIEW_FEATURES
 void QuicTestValidateEncryptDecryptPerfCounters();
+void QuicTestGetWorkerStatistics();
 #endif
 void QuicTestVersionSettings();
 void QuicTestValidateParamApi();

src/test/bin/quic_gtest.cpp

@@ -399,6 +399,15 @@ TEST(ParameterValidation, ValidateEncryptDecryptPerfCounters) {
         QuicTestValidateEncryptDecryptPerfCounters();
     }
 }
+
+TEST(ParameterValidation, ValidateGetWorkerStatistics) {
+    TestLogger Logger("QuicTestGetWorkerStatistics");
+    if (TestingKernelMode) {
+        ASSERT_TRUE(InvokeKernelTest(FUNC(QuicTestGetWorkerStatistics)));
+    } else {
+        QuicTestGetWorkerStatistics();
+    }
+}
 #endif // QUIC_API_ENABLE_PREVIEW_FEATURES
 
 TEST(ParameterValidation, ValidateConfiguration) {

src/test/bin/winkernel/control.cpp

@@ -465,6 +465,7 @@ ExecuteTestRequest(
     RegisterTestFunction(QuicTestGetPerfCounters);
 #ifdef QUIC_API_ENABLE_PREVIEW_FEATURES
     RegisterTestFunction(QuicTestValidateEncryptDecryptPerfCounters);
+    RegisterTestFunction(QuicTestGetWorkerStatistics);
 #endif
     RegisterTestFunction(QuicTestValidateConfiguration);
     RegisterTestFunction(QuicTestValidateListener);