Conversation
There was a problem hiding this comment.
Pull request overview
Adds documentation for how snapshot_restore_interval changes execution flow so users can correctly structure compiled-in harnesses for semi-persistent and fully persistent fuzzing.
Changes:
- Documented semi-persistent (
N > 1) and fully persistent (0) execution behavior in the compiled-in harnessing guide. - Added a cross-reference from the
snapshot_restore_intervalconfig option docs to the new harnessing section.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/src/harnessing/compiled-in.md | Adds a new section explaining semi/fully persistent execution and provides a harness structure example. |
| docs/src/config/common-options.md | Adds a note and link from snapshot_restore_interval to the new harnessing guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| When `snapshot_restore_interval` is set to a value other than `1`, the snapshot is not | ||
| restored at every iteration boundary. The target harness must therefore be structured as | ||
| a loop, with `HARNESS_START` and `HARNESS_STOP` inside it: | ||
|
|
||
| ```c | ||
| #include "tsffs.h" | ||
|
|
||
| int main() { | ||
| char buffer[20]; | ||
| size_t size = sizeof(buffer); | ||
|
|
||
| while (1) { | ||
| // Snapshot is taken here. TSFFS writes the testcase into buffer and size. | ||
| HARNESS_START(buffer, &size); | ||
|
|
||
| function_under_test(buffer, size); | ||
|
|
||
| HARNESS_STOP(); | ||
| } |
There was a problem hiding this comment.
The example and surrounding text suggest putting HARNESS_START inside the per-iteration loop. In the current implementation, HARNESS_START only captures the initial snapshot and writes the first testcase when no initial snapshot exists; subsequent testcases are written during HARNESS_STOP handling for the next iteration. Calling HARNESS_START every loop iteration will therefore introduce an extra stop/resume point that doesn’t provide a new testcase and will add overhead. Update the docs/example to call HARNESS_START once before the loop, and keep the loop around the body + HARNESS_STOP so semi/fully persistent mode can continue without restoring each time.
| the next iteration resumes if one exists. `snapshot_restore_interval` | ||
| controls only the restore behavior for normal iteration boundaries. | ||
|
|
||
| When using values other than `1`, the harness must be structured as a loop. See |
There was a problem hiding this comment.
This note links to the new section, but it may mislead readers into thinking HARNESS_START must be repeated every iteration. In semi/fully persistent mode, what’s required is that the harness’s control flow loops so execution can reach the next iteration without relying on a snapshot restore; HARNESS_START can be a one-time setup before the loop. Consider clarifying this wording to avoid unnecessary start-trigger stops each iteration.
| When using values other than `1`, the harness must be structured as a loop. See | |
| When using values other than `1`, the harness’s control flow must reach the start | |
| of each new iteration via a loop in your code (rather than relying solely on | |
| snapshot restores). `HARNESS_START` is typically a one-time setup that runs | |
| before this loop and does not need to be invoked again for every iteration. See |
Wenzel
force-pushed
the
docs/snapshot-restore-interval-loop
branch
from
11cdccc to
f1c6cad
Compare
No description provided.