Media-Transport-Library

MTL Unit Tests

In-process tests for the Media Transport Library that find real bugs without requiring a NIC, hugepages, root, or PTP hardware.

ASan No hardware


What this is

A gtest binary (UnitTest) that drives MTL’s RX session and pipeline code paths directly — using real DPDK mbufs from a no-hugepage EAL — and asserts on production behaviour. The suite covers ST 2110-20 (video), ST 2110-30 (audio), ST 2110-40 (ancillary), and the ST 2110-40 pipeline. Tests run on any developer laptop in a fraction of a second.

TX packet building/queueing on a NIC, DMA copy engines, AF_XDP, and multi-process scenarios are out of scope — see tests/integration_tests/ and tests/acceptance/ for those. Covered here through seams: TX epoch/pacing math, frame completion, destination update and rate-limit lookup (session/st20_tx_harness.c), the ST 2110-40 packet builders, including the fast metadata mode (session/st40_tx_harness.c), the kernel-socket TX send path over loopback (datapath/mt_dp_socket_harness.c), RX queue selection without a flow (datapath/mt_queue_harness.c), the DMA map table (dma/mt_map_harness.c), the MTL_FLAG_DMA_AUTO probe over a fake PCI device tree (dma/mt_dma_auto_harness.c), port stats locking (dev/mt_dev_harness.c) and the MtlManager IPC send (main/mt_instance_harness.c).

What makes this different

Property Value
Hardware required None — no NIC, no PTP clock, no hugepages
Privileges required None — runs as a regular user
Memory checking Partial — libmtl.so only, not this binary; see below
Code under test The production .c files (not a separate test build)
Determinism Synthetic input; some cases spawn threads
Isolation One ut_eal_init() per process; per-test ring/state reset

If a test fails it’s a real defect, unless a case with a wall-clock budget ran over it under load — an overrun that reproduces on an idle box is a defect. Only the eight *Concurrency* suites, St20PipelineTxBlocking, WaitSites/St20PipelineRxBlocking, the three *WakePostedBeforeWaitIsNotLost cases of St22PipelineRxBlocking / St22PipelineTxEncodeBlocking, the five *FrameReadyWakesABlockedGet cases of St22PipelineRxBlocking / St22PipelineTxEncodeBlocking / St30PipelineRxBlocking / St40PipelineRxBlocking, the two *FirstFrameEndsANotReadyWait cases of St22PipelineRxBlocking / St22PipelineTxEncodeBlocking, the eight *DestroyEndsEveryBlockedGet cases of St22PipelineRxBlocking / St30PipelineRxBlocking / St40PipelineRxBlocking / St22PipelineTxBlocking / St22PipelineTxEncodeBlocking / St30PipelineTxBlocking / St40PipelineTxBlocking, PipelineTxWakeBlock, St20PipelineRxBlockingConvert, St22PipelineRxBlocking.WakeBlockEndsTheBlockedGetDespiteAFastPathGet, St30PipelineRxBlocking.WakeBlockForABlockedGetIsNotSpentByAnotherFastPathGet, St40PipelineRxBlocking.FastPathGetDoesNotStealTheWakeOfABlockedGet, St20TxSessionLockTimeoutTest.GetTimeoutGivesUpOnAPassThatNeverEnds, St20TxSessionLockCallbackTest, and the MtSchQuiescentTest and MtSchQuiescentPassTest suites carry a budget; the exception reaches no other case. There are no flaky network-timing tests in this binary.

Quick start

./build.sh unit

This configures build_unit/ with -Denable_unit_tests=true, builds it, and runs tests/unit/UnitTest.

AddressSanitizer covers this tier only in part. ./build.sh debug unit and MTL_BUILD_ENABLE_ASAN=true ./build.sh unit set -Denable_asan=true, which lib/meson.build adds to the libmtl.so compile arguments only. Both commands build and run the whole suite.

Coverage also splits: no UnitTest object gets -fsanitize=address, so the production .c files this suite #includes into harness .c files are unchecked. Any libmtl.so symbol that UnitTest also defines, whether from an included .c or a harness stub, resolves to that uninstrumented copy.

libmtl.so is instrumented, so the symbols UnitTest resolves from it are checked — that covers any file no harness includes, such as st2110/st_ancillary.c. build.sh preloads the ASan runtime so the instrumented libmtl.so does not fault on an init-order interposition.

To list the shadowed symbols and those resolved from libmtl.so, run nm over the built tree:

cd build_unit
nm --defined-only tests/unit/UnitTest.p/*.o | grep -oP '^\S+ [A-Z] \K\S+' | sort -u > own
nm -D --defined-only lib/libmtl.so | grep -oP '^\S+ [A-Z] \K\S+' | sort -u > dso
nm -u tests/unit/UnitTest.p/*.o | grep -oP '^ +U \K\S+' | sort -u > undef
comm -12 own dso                     # shadowed: uninstrumented
comm -12 undef dso | comm -23 - own  # resolved from libmtl.so: instrumented

The same option also forks an allocator API. -DMTL_HAS_ASAN rides in mtl_c_args next to the sanitizer flag, and lib/src/mt_mem.h keys on it to switch mt_rte_zmalloc_socket() and its siblings from static inline DPDK wrappers to extern tracked allocators. The harness copies never see the macro, so they compile the static inline branch, which emits no global symbol — the two implementations name one set of allocators but never collide at link time, and no linker flag is involved. For ASan over library code, use tests/integration_tests/.

To configure/build/run manually, or to filter tests (see below):

# 1. configure (one-time)
meson setup build_unit -Denable_unit_tests=true

# 2. build
ninja -C build_unit

# 3. run (an enable_asan build needs the runtime preloaded — see Troubleshooting)
./build_unit/tests/unit/UnitTest

Filter to a single suite or test:

# one suite
./build_unit/tests/unit/UnitTest --gtest_filter='St40RxRedundancyTest.*'

# one test
./build_unit/tests/unit/UnitTest \
    --gtest_filter='St20RxErrPacketsTest.WrongPtCountedAsErr'

# everything related to err_packets across all media
./build_unit/tests/unit/UnitTest --gtest_filter='*ErrPackets*'

# list everything without running
./build_unit/tests/unit/UnitTest --gtest_list_tests

# run the known-bug tests (UT_KNOWN_BUG in common/ut_known_bug.h) to see them still fail
UT_RUN_KNOWN_BUGS=1 ./build_unit/tests/unit/UnitTest

ST20 continuation bounds regression

St20RxHeaderValidationTest.FinalRowContinuationPastFrameDropped feeds the production RFC 4175 frame handler a continuation SRD whose second row begins past its frame buffer. It needs no NIC, root, hugepages, or packet injector.

meson setup build_unit -Denable_unit_tests=true
ninja -C build_unit tests/unit/UnitTest
./build_unit/tests/unit/UnitTest \
    --gtest_filter='St20RxHeaderValidationTest.FinalRowContinuationPastFrameDropped'

The test geometry is two 40-byte rows with a padded 48-byte stride, making an 80-byte frame. It sends row 1 with a 12-byte first SRD and a 12-byte continuation. The original offset check accepts the first copy, while the second copy would begin at byte 96. Correct behavior is a negative return and one stat_pkts_offset_dropped increment. Before the continuation bound check, this test fails with rc equal to 0 and the drop counter equal to 0.

St20RxHeaderValidationTest.PaddedLineContinuationAccepted is the companion positive test. It verifies a valid padded continuation remains accepted.

Why LD_PRELOAD=libasan.so? libmtl.so is built with AddressSanitizer when enable_unit_tests=true. Preloading the runtime first prevents init-order interposition issues between gtest, libstdc++, and libasan.

Test layout

Tests are organised per-media. Each session type has its own subdirectory under session/, with per-feature files inside:

The shared per-media gtest fixture lives in <media>/<media>_rx_test_base.h; each per-feature file derives a thin subclass so --gtest_filter selects only that feature’s tests.

For the always-current list of suites and tests:

./build_unit/tests/unit/UnitTest --gtest_list_tests

Troubleshooting

Symptom Likely cause Fix
ASan runtime does not come first in initial library list An enable_asan=true libmtl.so, launched without LD_PRELOAD=libasan.so Launch through ./build.sh debug unit or MTL_BUILD_ENABLE_ASAN=true ./build.sh unit; both preload it
libasan: failed to find runtime library Wrong libasan major (e.g. .so.5 vs .so.6) cc -print-file-name=libasan.so gives the right path
Linker: multiple definition of <symbol> Two harness objects in unit_sources each #include a production .c defining that symbol Rename it in one of them with #define/#undef around the #include, as pipeline/st22p_harness.c does
Test passes alone, fails in suite Shared ring or session state not drained Add cleanup to fixture TearDown(); never rely on test order
New test green but suite total didn’t grow The .cpp was not added to unit_sources Add to tests/unit/meson.build