Docs file normalization.
This commit is contained in:
parent
dd32143bf8
commit
619c2d0808
46 changed files with 3587 additions and 2579 deletions
|
|
@ -1,10 +1,12 @@
|
|||
# Engine correctness and reliability
|
||||
# Engine Correctness and Reliability
|
||||
|
||||
The existing engine was audited rather than extended with musical features. The
|
||||
review covers graph edits/compilation, offline DSP, plan publication, JACK
|
||||
callbacks/lifecycle, audio/MIDI source plans and the recorder handoff.
|
||||
|
||||
## Ownership and synchronization
|
||||
---
|
||||
|
||||
## Ownership and Synchronization
|
||||
|
||||
| Resource | Owner and lifetime |
|
||||
| --- | --- |
|
||||
|
|
@ -24,7 +26,9 @@ The public realtime API is SPSC: multiple producers, simultaneous process calls,
|
|||
collection from arbitrary threads, and destruction during processing are not
|
||||
supported. Atomics do not remove those ownership requirements.
|
||||
|
||||
## Bounded callback work
|
||||
---
|
||||
|
||||
## Bounded Callback Work
|
||||
|
||||
Compilation, topological sorting, asset I/O, allocation and native preparation
|
||||
are control-thread operations. Graph processing traverses at most 256 nodes,
|
||||
|
|
@ -50,13 +54,15 @@ callbacks are trusted: the host cannot prevent their allocation, blocking,
|
|||
crashes or excessive runtime. Maximum supported capacities are safety bounds,
|
||||
not a promise that every workload meets its audio deadline.
|
||||
|
||||
## Findings and regression coverage
|
||||
---
|
||||
|
||||
## Findings and Regression Coverage
|
||||
|
||||
Graph rendering previously mixed the left output before reading right-channel
|
||||
sources. With external input equal to the left output, the right pass could
|
||||
read already processed samples (gain applied twice). Both passes now finish
|
||||
source reads before either output is written. Tests check mono input aliasing
|
||||
and cross-channel source aliasing against exact expected samples. Output buffers
|
||||
sources. With external input equal to the left output, the right pass could read
|
||||
already processed samples (gain applied twice). Both passes now finish source
|
||||
reads before either output is written. Tests check mono input aliasing and
|
||||
cross-channel source aliasing against exact expected samples. Output buffers
|
||||
must not overlap each other. A redundant assignment in missing-asset preparation
|
||||
was also removed after Clang's dead-store diagnostic; behavior is unchanged.
|
||||
|
||||
|
|
@ -67,20 +73,23 @@ that failed replacement preserves output and revisions, and counts both stereo
|
|||
native instances through retirement, collection and destruction of a pending
|
||||
plan. It repeats this lifecycle 100 times. A maximum 256-node reverse-insertion
|
||||
chain checks dependency scheduling, long-cycle rejection/rollback and compiled
|
||||
snapshot independence. The pthread handoff test submits 2000 native graphs
|
||||
while processing, checks whole-block output/revision consistency, asserts that
|
||||
snapshot independence. The pthread handoff test submits 2000 native graphs while
|
||||
processing, checks whole-block output/revision consistency, asserts that
|
||||
prepare/destruction run on the control thread, and balances all native lifetimes
|
||||
after joining the consumer.
|
||||
|
||||
Existing backend fault tests cover repeated start/stop, partial registration,
|
||||
callback setup, open/activate/deactivate/close failures and retries, server loss,
|
||||
rate/buffer changes, missing buffers, MIDI disconnect/panic, and recorder detach.
|
||||
Other suites cover deterministic variable-block DSP, finite-output handling,
|
||||
project errors, record-ring saturation and concurrent draining, and crash/write
|
||||
failure preservation. No critical realtime safety defect remains known within
|
||||
these contracts; these tests are evidence for tested paths, not a formal proof.
|
||||
callback setup, open/activate/deactivate/close failures and retries, server
|
||||
loss, rate/buffer changes, missing buffers, MIDI disconnect/panic, and recorder
|
||||
detach. Other suites cover deterministic variable-block DSP, finite-output
|
||||
handling, project errors, record-ring saturation and concurrent draining, and
|
||||
crash/write failure preservation. No critical realtime safety defect remains
|
||||
known within these contracts; these tests are evidence for tested paths, not a
|
||||
formal proof.
|
||||
|
||||
## Reproducing the audit
|
||||
---
|
||||
|
||||
## Reproducing the Audit
|
||||
|
||||
From the repository root:
|
||||
|
||||
|
|
@ -92,22 +101,22 @@ make BUILD_DIR=build/audit test-gui test-gui-jack test-jack test-jack-audio test
|
|||
make BUILD_DIR=build/nojack PKG_CONFIG=false all test-reliability gui
|
||||
```
|
||||
|
||||
`test-sanitize` needs installed Clang and runs core, allocation-failure and recovery
|
||||
tests with ASan/UBSan and Linux's default ASan leak checking. `analyze` uses
|
||||
Clang's path-sensitive analyzer on every core translation unit, including JACK
|
||||
when its development files are available, and fails on diagnostics. Python and
|
||||
Clang are development tools, not new runtime dependencies. The allocation guard
|
||||
requires a GNU-compatible linker. Live tests require an existing JACK-compatible
|
||||
server; GUI tests use installed FLTK and Xvfb. No target installs dependencies or
|
||||
changes server/system configuration.
|
||||
`test-sanitize` needs installed Clang and runs core, allocation-failure and
|
||||
recovery tests with ASan/UBSan and Linux's default ASan leak checking. `analyze`
|
||||
uses Clang's path-sensitive analyzer on every core translation unit, including
|
||||
JACK when its development files are available, and fails on diagnostics. Python
|
||||
and Clang are development tools, not new runtime dependencies. The allocation
|
||||
guard requires a GNU-compatible linker. Live tests require an existing
|
||||
JACK-compatible server; GUI tests use installed FLTK and Xvfb. No target
|
||||
installs dependencies or changes server/system configuration.
|
||||
|
||||
Verification on GCC 16.2.1 / Clang 23.1.3 passed normal and no-JACK builds,
|
||||
all core tests, ASan/UBSan/leak checks, Clang static analysis, GUI/mock and live
|
||||
Verification on GCC 16.2.1 / Clang 23.1.3 passed normal and no-JACK builds, all
|
||||
core tests, ASan/UBSan/leak checks, Clang static analysis, GUI/mock and live
|
||||
JACK integrations, plus GCC TSan on the pthread native-publication and recorder
|
||||
concurrency tests. The GUI also passed ASan/UBSan with the existing
|
||||
`tests/integration/lsan.supp` fontconfig-only suppression; core tests use no leak
|
||||
suppression. The live graph test observed both replacement gains, ten restart
|
||||
cycles and zero xruns during its five-second software run.
|
||||
`tests/integration/lsan.supp` fontconfig-only suppression; core tests use no
|
||||
leak suppression. The live graph test observed both replacement gains, ten
|
||||
restart cycles and zero xruns during its five-second software run.
|
||||
|
||||
Physical audio devices, hard realtime scheduling, multi-hour endurance and
|
||||
arbitrary third-party native callbacks remain unqualified. Sanitizers change
|
||||
|
|
@ -115,7 +124,9 @@ timing and should not be used to measure production realtime performance. See
|
|||
PERFORMANCE.md for workload measurements, RECOVERY.md for process-crash limits,
|
||||
and NATIVE_API.md for the trusted extension boundary.
|
||||
|
||||
## Transition ownership
|
||||
---
|
||||
|
||||
## Transition Ownership
|
||||
|
||||
Source fade configuration is written before publication and immutable during
|
||||
rendering. The master ramp and stop-observed flag belong to the audio consumer
|
||||
|
|
@ -126,12 +137,15 @@ voices/flags. A completed callback continues silence/holds position until that
|
|||
deactivation. No callback waits or calls JACK control functions. Immediate
|
||||
stop/close handles faults or missing callbacks. See AUDIO_QUALITY.md.
|
||||
|
||||
## Repeatable development checks
|
||||
---
|
||||
|
||||
`make check-development` combines normal tests, capacity/endurance, deterministic
|
||||
benchmark-gate tests, static analysis and ASan/UBSan (including scale and soak).
|
||||
`make test-stress` repeats project/backend/publication faults under CPU contention;
|
||||
`make test-stress-plugins` adds the original LADSPA failure fixture. The reliability
|
||||
callback guard now also rejects common host file I/O and blocking mutex/condition
|
||||
calls. It audits directly linked host code, not arbitrary dynamic-plugin internals.
|
||||
See PERFORMANCE.md for exact workloads, metrics, profiles and qualification limits.
|
||||
## Repeatable Development Checks
|
||||
|
||||
`make check-development` combines normal tests, capacity/endurance,
|
||||
deterministic benchmark-gate tests, static analysis and ASan/UBSan (including
|
||||
scale and soak). `make test-stress` repeats project/backend/publication faults
|
||||
under CPU contention; `make test-stress-plugins` adds the original LADSPA
|
||||
failure fixture. The reliability callback guard now also rejects common host
|
||||
file I/O and blocking mutex/condition calls. It audits directly linked host
|
||||
code, not arbitrary dynamic-plugin internals. See PERFORMANCE.md for exact
|
||||
workloads, metrics, profiles and qualification limits.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue