Time-Sensitive Networking (TSN)

IEEE 802.1 TSN support for deterministic Ethernet communication with priority tagging, scheduled transmission, and capability detection.

Linux Only

Full TSN support requires Linux (kernel >= 4.19 for SO_TXTIME). Other platforms use a stub backend that returns unsupported errors.

Overview

TSN extends standard Ethernet with deterministic delivery guarantees. HDDS integrates with Linux TSN infrastructure to provide:

Priority tagging -- SO_PRIORITY mapped to traffic classes (mqprio) and VLAN PCP
Scheduled TX -- SO_TXTIME + SCM_TXTIME for "send-at-time" (LaunchTime)
Capability detection -- Runtime probe of TSN features (ETF, TAPRIO, HW timestamping)

Architecture

+---------------------------------------------------------+
|                     Application                          |
|  write() / write_at(txtime) / write_with(WriteOptions)  |
+---------------------+-----------------------------------+
                      |
+---------------------v-----------------------------------+
|                  DataWriter                              |
|  TsnConfig (from TopicQos or WriterQos override)        |
+---------------------+-----------------------------------+
                      |
+---------------------v-----------------------------------+
|                 UdpTransport                             |
|  TX Socket Pool (keyed by SocketProfile)                |
|  TsnBackend (LinuxTsnBackend / NullTsnBackend)          |
+---------------------------------------------------------+

Configuration

TsnConfig

use hdds::transport::tsn::{TsnConfig, TsnEnforcement, TxTimePolicy};
use std::time::Duration;

// Enable TSN with priority tagging
let config = TsnConfig::new()
    .with_priority(6)  // PCP 6 (high priority)
    .strict();         // Fail if TSN not available

// With scheduled TX
let config = TsnConfig::new()
    .with_priority(6)
    .with_txtime(TxTimePolicy::Mandatory)
    .with_lead_time(Duration::from_micros(500));

Priority Presets

HDDS provides preset configurations mapping to standard priority levels.

Preset	PCP	Priority Level	Use Case
`high_priority()`	6	P0	Commands, safety-critical
`normal_priority()`	4	P1	Normal data
`low_priority()`	2	P2	Telemetry, best-effort

use hdds::transport::tsn::TsnConfig;

let high = TsnConfig::high_priority();    // PCP 6
let normal = TsnConfig::normal_priority(); // PCP 4
let low = TsnConfig::low_priority();      // PCP 2

Configuration Options

Option	Default	Description
`enabled`	`false`	Master switch for TSN features
`enforcement`	`BestEffort`	Behavior when capabilities are missing
`pcp`	`None`	VLAN Priority Code Point (0-7)
`dscp`	`None`	IP DSCP value (0-63) for L3 QoS
`traffic_class`	`None`	mqprio traffic class index
`tx_time`	`Disabled`	Timed send policy
`clock_id`	`Tai`	Reference clock for txtime
`lead_time_ns`	500,000 (500 us)	Delta added to now() for auto txtime
`strict_deadline`	`false`	Drop if txtime is exceeded
`srp_stream_id`	`None`	802.1Qat stream reservation ID
`frer`	`None`	802.1CB Frame Replication config (future)

Enforcement Modes

Mode	Description
`BestEffort`	Degrade silently if TSN unavailable (counter + debug log)
`Strict`	Error if prerequisites are missing

use hdds::transport::tsn::{TsnConfig, TsnEnforcement};

// Best-effort: works everywhere, degrades gracefully
let config = TsnConfig::new().with_priority(6);

// Strict: fail fast if TSN is not properly configured
let config = TsnConfig::new().with_priority(6).strict();

TX Time Policies

Control how HDDS uses SO_TXTIME for scheduled transmission.

Policy	Description
`Disabled`	Standard sendto(), no txtime (default)
`Opportunistic`	Use SO_TXTIME if available, fall back to sendto()
`Mandatory`	Require SO_TXTIME, error if unavailable

use hdds::transport::tsn::{TsnConfig, TxTimePolicy};
use std::time::Duration;

let config = TsnConfig::new()
    .with_priority(6)
    .with_txtime(TxTimePolicy::Mandatory)
    .with_lead_time(Duration::from_micros(500));

Clock Sources

The reference clock determines how txtime values are computed.

use hdds::transport::tsn::TsnClockId;

TsnClockId::Tai       // CLOCK_TAI (PTP-synced, recommended for production)
TsnClockId::Monotonic // CLOCK_MONOTONIC (dev/test, not synced across hosts)
TsnClockId::Realtime  // CLOCK_REALTIME (avoid -- leap second issues)
TsnClockId::Phc(path) // Direct PHC device (e.g., "/dev/ptp0")

Clock Selection

For production TSN deployments, use TsnClockId::Tai with PTP synchronization. CLOCK_MONOTONIC is acceptable for development and testing but is not synchronized across hosts. Avoid CLOCK_REALTIME due to leap second discontinuities.

Capability Detection

Probe the system for TSN support at runtime.

use hdds::transport::tsn::TsnProbe;

let caps = TsnProbe::probe("eth0")?;
println!("SO_TXTIME: {:?}", caps.so_txtime);
println!("ETF qdisc: {:?}", caps.etf_configured);
println!("TAPRIO qdisc: {:?}", caps.taprio_configured);
println!("mqprio: {:?}", caps.mqprio_configured);
println!("HW timestamping: {:?}", caps.hw_timestamping);
println!("PHC device: {:?}", caps.phc_device);

Support Levels

Each capability reports one of:

Level	Description
`Unsupported`	Feature not available
`Supported`	Feature available (software)
`SupportedWithOffload`	Feature available with hardware offload

System Requirements

Linux kernel >= 4.19 for SO_TXTIME support
ETF qdisc configured for scheduled transmission
TAPRIO qdisc for time-aware scheduling
mqprio qdisc for traffic class mapping
PTP synchronization for cross-host time coordination

Traffic Policy

HDDS maps DDS priority levels to TSN traffic policies.

use hdds::transport::tsn::{Priority, TrafficPolicy, DropPolicy};

// P0: critical traffic (PCP 6) -- immediate, retransmit
// P1: normal traffic (PCP 4) -- batched, no retransmit
// P2: telemetry (PCP 2) -- batched, drop on congestion

Priority	PCP	Drop Policy	Description
P0	6	`BestEffort`	Critical/reliable, immediate flush
P1	4	`BestEffort`	Important, batched
P2	2	`DropIfLate`	Telemetry, dropped on congestion

TSN Metrics

HDDS tracks TSN-related metrics via atomic counters.

// Metrics snapshot includes:
// - priority_set: number of sockets with SO_PRIORITY set
// - txtime_enabled: number of sockets with SO_TXTIME
// - txtime_sends: successful timed sends
// - regular_sends: standard sends (no txtime)
// - dropped_late: packets dropped due to late txtime
// - dropped_other: packets dropped for other reasons
// - txtime_fallbacks: txtime-to-regular fallbacks
// - txtime_failures: txtime send failures
// - probes: capability probes performed
// - error_queue_drains: error queue drain operations

The TsnMetricsSnapshot provides derived metrics:

txtime_ratio() -- ratio of timed sends to total sends
drop_rate() -- ratio of drops to total sends

Linux Network Setup

TSN requires proper network configuration. Here is a minimal setup example:

mqprio (Traffic Class Mapping)

# Map 3 traffic classes to hardware queues
sudo tc qdisc add dev eth0 root handle 1: mqprio \
    num_tc 3 \
    map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 \
    queues 1@0 1@1 1@2 \
    hw 0

ETF (Earliest TxTime First)

# Configure ETF on queue 0 with CLOCK_TAI
sudo tc qdisc add dev eth0 parent 1:1 etf \
    clockid CLOCK_TAI \
    delta 500000 \
    offload

TAPRIO (Time-Aware Priority)

# Configure TAPRIO with a 1ms cycle
sudo tc qdisc replace dev eth0 parent root handle 100 taprio \
    num_tc 3 \
    map 2 2 1 0 2 2 2 2 2 2 2 2 2 2 2 2 \
    queues 1@0 1@1 1@2 \
    base-time 0 \
    sched-entry S 01 300000 \
    sched-entry S 02 300000 \
    sched-entry S 04 400000 \
    clockid CLOCK_TAI

Platform Support

Platform	Status	Details
Linux	Full support	SO_PRIORITY, SO_TXTIME, ETF/TAPRIO detection
Others	Stub backend	`NullTsnBackend` returns unsupported errors

Limitations

Limitation	Description
Linux only	Full TSN requires Linux kernel >= 4.19
Network config	Requires proper qdisc setup (mqprio, ETF, TAPRIO)
PTP sync	Cross-host txtime requires PTP synchronization
PHC clock	`Phc` clock requires fd-to-clockid conversion (not yet automated)
802.1CB FRER	Frame Replication config is reserved for future use
No C FFI	TSN configuration is not yet exposed in the C API

Next Steps

Advanced Transport Features -- DSCP, network filtering
TCP Transport -- Reliable transport for non-TSN networks
Shared Memory Transport -- Zero-copy local IPC

Overview​

Architecture​

Configuration​

TsnConfig​

Priority Presets​

Configuration Options​

Enforcement Modes​

TX Time Policies​

Clock Sources​

Capability Detection​

Support Levels​

System Requirements​

Traffic Policy​

TSN Metrics​

Linux Network Setup​

mqprio (Traffic Class Mapping)​

ETF (Earliest TxTime First)​

TAPRIO (Time-Aware Priority)​

Platform Support​

Limitations​

Next Steps​