In-process tests for the Media Transport Library that find real bugs without requiring a NIC, hugepages, root, or PTP hardware.
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).
| 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.
./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
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.sois built with AddressSanitizer whenenable_unit_tests=true. Preloading the runtime first prevents init-order interposition issues between gtest, libstdc++, and libasan.
Tests are organised per-media. Each session type has its own subdirectory
under session/, with per-feature files inside:
session/st20/ — ST 2110-20 (video)session/st30/ — ST 2110-30 (audio)session/st40/ — ST 2110-40 (ancillary)pipeline/ — pipeline layer (frame assembly above the session filter)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
| 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 |