fuzz_defs.h File Reference

Shared constants, the input layout, and the command descriptor type for SDK fuzz harnesses. More...

#include <stddef.h>
#include <stdint.h>
#include "exceptions.h"

Include dependency graph for fuzz_defs.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	fuzz_command_spec_t
	Describes one APDU command the harness may synthesise and dispatch. More...

Macros
#define	FUZZ_CTRL_LEN   4
	Bytes 0..3 steer the harness; byte 4 onwards is payload.
#define	FUZZ_STRUCTURED_LANE_THRESHOLD   102
	Control byte 0 above this value selects the structured lane; at or below it the harness takes the raw lane.
#define	FUZZ_CMD_HAS_DATA   (1u << 0)
#define	FUZZ_COMMAND_COUNT()    const size_t fuzz_n_commands = sizeof(fuzz_commands) / sizeof(fuzz_commands[0])
	Derive fuzz_n_commands from the app's fuzz_commands[] table.

Variables
Framework-owned runtime symbols
Declared here and defined in mock/fuzz_runtime.c, which every target links through the shared mock library. The framework writes them; an app never declares or defines them.
const uint8_t *	fuzz_tail_ptr
	The APDU payload for the current iteration (NULL when empty).
size_t	fuzz_tail_len
	Length of fuzz_tail_ptr in bytes.
const size_t	fuzz_absolution_prefix_size
	Size in bytes of Absolution's sampled state prefix.
try_context_t	fuzz_exit_jump_ctx
	longjmp landing pad the harness unwinds os_exit() through.

Detailed Description

Shared constants, the input layout, and the command descriptor type for SDK fuzz harnesses.

Input layout

A fuzzer input is Absolution's sampled global state followed by the part the harness sees:

[ Absolution prefix: FUZZ_PREFIX_SIZE bytes ][ harness input ]
                opaque sampled state            layout below

sample_invariant() consumes the prefix and passes the rest to fuzz_entry(), so every offset a harness or the mutator cares about is relative to the start of the harness input.

byte	meaning
0	lane selector (> FUZZ_STRUCTURED_LANE_THRESHOLD)
1	command index (taken modulo the app's command count)
2	P1 (clamped to the command's p1_max)
3	P2 (clamped to the command's p2_max)
4..	app header, FUZZ_APP_HEADER_LEN bytes (0 by default)
then	APDU payload, exposed to the app as fuzz_tail_ptr/len

An app that needs its own control or entropy bytes defines FUZZ_APP_HEADER_LEN and reads them at data[FUZZ_CTRL_LEN]. The payload then starts after them, so builders keep a stable base at fuzz_tail_ptr[0].

Definition in file fuzz_defs.h.

Macro Definition Documentation

FUZZ_CMD_HAS_DATA

#define FUZZ_CMD_HAS_DATA   (1u << 0)

fuzz_command_spec_t flag: the command carries an APDU payload.

Definition at line 92 of file fuzz_defs.h.

FUZZ_COMMAND_COUNT

#define FUZZ_COMMAND_COUNT

(

)

const size_t fuzz_n_commands = sizeof(fuzz_commands) / sizeof(fuzz_commands[0])

Derive fuzz_n_commands from the app's fuzz_commands[] table.

Definition at line 104 of file fuzz_defs.h.

FUZZ_CTRL_LEN

#define FUZZ_CTRL_LEN   4

Bytes 0..3 steer the harness; byte 4 onwards is payload.

Definition at line 73 of file fuzz_defs.h.

FUZZ_STRUCTURED_LANE_THRESHOLD

#define FUZZ_STRUCTURED_LANE_THRESHOLD   102

Control byte 0 above this value selects the structured lane; at or below it the harness takes the raw lane.

Structured lane (data[0] > 102): the harness picks a command from the table via data[1], clamps P1/P2, and builds a valid APDU — drives the happy path. Raw lane (≤ 102): all APDU fields come straight from the input bytes without clamping — exercises parsing edges and error paths.

The value 102 gives a ≈40/60 raw/structured split across 0–255; apps do not tune it. Most apps define one fuzz_commands[] and let both lanes share it. Override FUZZ_PICK_COMMAND_STRUCTURED / FUZZ_PICK_COMMAND_RAW only when two structurally different entry paths need separate tables.

Definition at line 89 of file fuzz_defs.h.

Variable Documentation

fuzz_absolution_prefix_size

const size_t fuzz_absolution_prefix_size

extern

Size in bytes of Absolution's sampled state prefix.

Defined in a one-line translation unit the build generates from the generated fuzzer (see cmake/EmitPrefixSize.cmake).

fuzz_exit_jump_ctx

try_context_t fuzz_exit_jump_ctx

extern

longjmp landing pad the harness unwinds os_exit() through.

Defined in mock/os/os_exceptions.c. Declared here because fuzz_harness.h uses it, so an app's mock/mocks.h does not need to.

fuzz_tail_len

size_t fuzz_tail_len

extern

Length of fuzz_tail_ptr in bytes.

fuzz_tail_ptr

const uint8_t* fuzz_tail_ptr

extern

The APDU payload for the current iteration (NULL when empty).