Skip to content

CPU Affinity Service via GenTL

Overview

CPU Affinity Service via GenTL is a Windows-only feature that helps improve GigE streaming stability by reserving selected CPU cores for Receive Side Scaling (RSS) workloads and temporarily pinning non-reserved workloads away from those cores during active streaming.

The same GenTL system surface also exposes media optimization control so applications can inspect privilege state and enable or disable media optimization programmatically.

In website guidance this broader workflow is referred to as the Spinnaker Multicore GigE Optimizer (RSS + CPU Affinity). This page focuses on the GenTL API surface for CPU affinity and media optimization control nodes.

This feature is exposed through GenTL system and interface nodes so applications can inspect state and control behavior programmatically.

Related components:

  • AdapterConfig (GUI and console)
  • Spinnaker CPU Affinity Windows service (service name: CpuAffinity)
  • GenTL system and interface node maps

Scope and Platform

  • Supported platform: Windows
  • Intended transport: GigE interfaces with RSS support
  • Privilege model: read access is generally available, control operations require admin privileges
  • Default state: CPU affinity optimization is disabled until explicitly enabled

GenTL Node Mapping

System-level CPU Affinity Nodes

These nodes are exposed from the GenTL System node map on supported Windows runtimes:

  • CpuAffinityPrivilege
    • Values: 0 = Unknown, 1 = None, 2 = Admin
    • Indicates whether privileged CPU affinity operations are currently allowed.
  • CpuAffinityServiceStatus
    • Values: 0 = Stopped, 1 = Running, 2 = Unknown
    • Reports the runtime state of the CPU affinity service.
  • CpuAffinityAvailableCores
    • Reports the number of available CPU cores for assignment.
  • CpuAffinityServiceStart
    • Command node to start the service.
    • Writability depends on privilege level (admin required to execute).
  • CpuAffinityServiceStop
    • Command node to stop the service.
    • Writability depends on privilege level (admin required to execute).

System-level Media Optimization Nodes

These nodes are exposed from the GenTL System node map on supported Windows runtimes:

  • MediaOptimizationPrivilege
    • Values: 0 = Unknown, 1 = None, 2 = Admin
    • Indicates whether privileged media optimization operations are currently allowed.
  • MediaOptimizationEnable
    • Enables or disables media optimization at the system level.
    • Readable for all users; writable with admin privileges.

Interface-level CPU Affinity Nodes

These nodes are exposed from the GenTL Interface node map on configurable GigE interfaces:

  • CpuAffinityPrivilege
    • Values: 0 = Unknown, 1 = None, 2 = Admin
    • Indicates whether privileged CPU affinity operations are currently allowed for interface control operations.
  • ReceiveSideScalingReservedCores
    • Comma-separated core list used as reserved RSS cores for the interface.
  • ReceiveSideScalingReservedCoresCount
    • Count of reserved cores currently configured.
  • CPUAffinityEnable
    • Enables or disables CPU affinity enforcement for the interface.
    • Setting this node to true starts enforcement behavior through the service path.
    • Node availability is interface-dependent; writability generally requires admin privileges.

Configuration File and Service Behavior

The CPU affinity configuration is stored in:

%ALLUSERSPROFILE%\Spinnaker\CpuAffinity.cfg

Format:

  • Line 1: streaming threshold percentage (integer)
  • Line 2+: one mapping per line in the format:
    • reservedCore,adapterMacAddress

Example:

5
2,001122334455
4,001122334455
6,A1B2C3D4E5F6

Behavior summary:

  1. AdapterConfig writes CpuAffinity.cfg using selected RSS core assignments.
  2. During active streaming, the service detects utilization against the configured threshold.
  3. If streaming is active, non-reserved workloads are restricted away from reserved RSS cores.
  4. When streaming stops, process affinity is restored.

Default behavior values used by the service implementation:

  • Network utilization threshold: 5%
  • Fast poll interval while not streaming: 2 seconds
  • Slow poll interval while streaming: 120 seconds

Typical GenTL Workflow

Recommended sequence for applications:

  1. Read system-level nodes:
    • CpuAffinityPrivilege
    • CpuAffinityServiceStatus
    • CpuAffinityAvailableCores
    • MediaOptimizationPrivilege
    • MediaOptimizationEnable
  2. Enumerate interfaces and inspect:
    • CpuAffinityPrivilege
    • ReceiveSideScalingReservedCores
    • ReceiveSideScalingReservedCoresCount
    • CPUAffinityEnable
  3. If admin privileges are present, update reserved core list and enable CPU affinity as needed.
  4. Optionally enable or disable media optimization through MediaOptimizationEnable.
  5. Optionally invoke CpuAffinityServiceStart or CpuAffinityServiceStop for explicit service control.
  6. Re-read status nodes to verify resulting state.

Reference Example

The Spinnaker C++ example CPUAffinity.cpp demonstrates:

  • Reading system-level CPU affinity nodes
  • Reading system-level media optimization nodes
  • Checking start/stop command writability
  • Enumerating interfaces and reading interface-level CPU affinity nodes
  • Optional write flow for MediaOptimizationEnable, ReceiveSideScalingReservedCores, and CPUAffinityEnable
  • Restoring original settings after test configuration

Use this example as the canonical reference for runtime node access patterns.

Troubleshooting

  • If control nodes are not writable:
    • Verify the process is running with admin privileges.
  • If media optimization nodes are missing:
    • Verify the installed runtime exposes MediaOptimizationPrivilege and MediaOptimizationEnable.
  • If service status remains stopped:
    • Check Windows Services for Spinnaker CPU Affinity / CpuAffinity.
  • If interface nodes are missing:
    • Verify the selected interface supports CPU affinity configuration.
  • If behavior does not match expected reserved cores:
    • Confirm CpuAffinity.cfg exists and has valid core/MAC mappings.
    • Avoid reserving CPU core 0.