Skip to content

Docs: snapshot restore interval loop #314

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Wenzel wants to merge 2 commits into
base: main
Choose a base branch
from
+33 −0
Open

Docs: snapshot restore interval loop #314

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
020ce4f
docs: document harness loop requirement for non-default snapshot_rest…
Wenzel Mar 27, 2026
f1c6cad
docs: add cross-link to harness loop docs from snapshot_restore_inter…
Wenzel Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/src/config/common-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,9 @@ breakpoint-triggered solutions, always restore the initial snapshot before
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
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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

Copilot uses AI. Check for mistakes.
[Semi-Persistent and Fully Persistent Execution](../harnessing/compiled-in.md#semi-persistent-and-fully-persistent-execution).

### Adding Tokens From Target Software

The fuzzer has a mutator which will insert, remove, and mutate tokens in testcases. This
Expand Down
30 changes: 30 additions & 0 deletions docs/src/harnessing/compiled-in.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
- [Using Provided Headers](#using-provided-headers)
- [Multiple Harnesses in One Binary](#multiple-harnesses-in-one-binary)
- [Alternative Start Harnesses](#alternative-start-harnesses)
- [Semi-Persistent and Fully Persistent Execution](#semi-persistent-and-fully-persistent-execution)
- [Troubleshooting](#troubleshooting)
- [Compile Errors About Temporaries](#compile-errors-about-temporaries)

Expand Down Expand Up @@ -148,6 +149,35 @@ different target software to be used with as little modification as possible.
not initially have `*size_ptr` set to the maximum size, but still needs to
read the actual buffer size.

## Semi-Persistent and Fully Persistent Execution

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();
}
Comment on lines +154 to +172
Copy link

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.
}
```

For `snapshot_restore_interval = N` (semi-persistent), the snapshot is restored every N
iterations. For `snapshot_restore_interval = 0` (fully persistent), the snapshot is
never restored; any per-iteration state (allocated memory, open handles, etc.) must be
cleaned up manually inside the loop.

## Troubleshooting

### Compile Errors About Temporaries
Expand Down
Loading