Functions
void	test_init_and_verify (void)
	Init seals and verification passes.
void	test_read_roundtrip (void)
	Read returns the sealed value.
void	test_write_reseals (void)
	Write replaces the payload and reseals.
void	test_update_commits (void)
	Update commits a mutator transaction.
void	test_update_abort_keeps_integrity (void)
	Aborted update leaves a consistent container.
void	test_section_scope (void)
	SAFE_SECTION reseals at scope exit.
void	test_detects_corruption (void)
	Payload corruption detected; verification is pure.
void	test_verify_repair_fixes_in_place (void)
	verify_repair restores the payload in place
void	test_commit_reseals_external_write (void)
	Unchecked commit reseals an external modification.
void	test_stale_tag_recovers (void)
	Stale tag with consistent data recovers.
void	test_double_fault_unrecoverable (void)
	Double fault is unrecoverable.
void	test_null_args (void)
	NULL and zero-size arguments are rejected.
void	test_reduced_api_surface (void)
	Optional API surface matches the configuration.
void	test_concurrent_access_is_serialised (void)
	Concurrent access never yields torn snapshots.
void	test_selftest (void)
	Self-test reports a healthy mechanism.
void	test_stats_count_events (void)
	Statistics count every integrity event.
void	test_fault_handler_events (void)
	Registered handler receives all event kinds.
void	test_update_clamps_positive_mutator_return (void)
	Positive mutator return is clamped and aborted.
void	test_write_observes_overwritten_corruption (void)
	Write observes corruption before overwriting.
void	test_lock_timeout_is_bounded_and_reported (void)
	Blocked access fails within the lock bound.

Detailed Description

Function Documentation

◆ test_init_and_verify()

void test_init_and_verify ( void )

active

Init seals and verification passes.

SAFE_INIT seals the freshly written payload; SAFE_VERIFY on the untouched container returns 0.

Test ID: TC_SAFE_DATA_INIT_AND_VERIFY

Test Status: Active

Definition at line 44 of file main.c.

Verifies requirements SD-REQ-001 (Sealing on initialisation), and SD-REQ-003 (Pure verification).

◆ test_read_roundtrip()

void test_read_roundtrip ( void )

active

Read returns the sealed value.

A value written through SAFE_WRITE is returned bit-exact by a validated SAFE_READ.

Test ID: TC_SAFE_DATA_READ_ROUNDTRIP

Test Status: Active

Definition at line 61 of file main.c.

Verifies requirements SD-REQ-005 (Validated read), and SD-REQ-006 (Atomic sealed write).

◆ test_write_reseals()

void test_write_reseals ( void )

obsolete

Write replaces the payload and reseals.

After SAFE_WRITE the container verifies clean and a subsequent read returns the new value: the tag can never go stale across a write.

Status obsolete (demonstration of status handling): superseded by TC_SAFE_DATA_READ_ROUNDTRIP, which checks the resealed write through a validated read. The test still runs.

Test ID: TC_SAFE_DATA_WRITE_RESEALS

Test Status: Obsolete

Definition at line 86 of file main.c.

Verifies requirement SD-REQ-006 (Atomic sealed write).

◆ test_update_commits()

void test_update_commits ( void )

active

Update commits a mutator transaction.

SAFE_UPDATE runs the mutator under the lock and reseals on a zero return; the committed value is visible to the next read.

Test ID: TC_SAFE_DATA_UPDATE_COMMITS

Test Status: Active

Definition at line 125 of file main.c.

Verifies requirement SD-REQ-007 (Transactional read-modify-write).

◆ test_update_abort_keeps_integrity()

void test_update_abort_keeps_integrity ( void )

active

Aborted update leaves a consistent container.

A mutator returning a negative errno aborts the transaction. With the redundant shadow the payload is rolled back to the pre-update value; without it the partial write is detectable via the (not resealed) tag.

Test ID: TC_SAFE_DATA_UPDATE_ABORT_KEEPS_INTEGRITY

Test Status: Active

Definition at line 147 of file main.c.

Verifies requirement SD-REQ-007 (Transactional read-modify-write).

◆ test_section_scope()

void test_section_scope ( void )

active

SAFE_SECTION reseals at scope exit.

Modifications made through the typed pointer inside a SAFE_SECTION block are sealed automatically on normal scope exit and visible to the next read.

Test ID: TC_SAFE_DATA_SECTION_SCOPE

Depends on: CONFIG_SAFE_DATA_GNU_EXTENSIONS

Test Status: Active

Definition at line 181 of file main.c.

Verifies requirement SD-REQ-021 (Scoped access block).

◆ test_detects_corruption()

void test_detects_corruption ( void )

active

Payload corruption detected; verification is pure.

Out-of-band payload corruption is detected by SAFE_VERIFY without modifying the payload (pure check). With the shadow copy the subsequent locked read repairs and reseals; without it the fault is unrecoverable.

Test ID: TC_SAFE_DATA_DETECTS_CORRUPTION

Test Status: Active

Definition at line 212 of file main.c.

Verifies requirements SD-REQ-003 (Pure verification), and SD-REQ-009 (Single-copy fault recovery).

◆ test_verify_repair_fixes_in_place()

void test_verify_repair_fixes_in_place ( void )

active

verify_repair restores the payload in place

safe_data_verify_repair() (lock-held contract) restores a corrupted payload from the shadow copy in place; the container verifies clean afterwards.

Test ID: TC_SAFE_DATA_VERIFY_REPAIR_FIXES_IN_PLACE

Depends on: CONFIG_SAFE_DATA_REDUNDANT

Test Status: Active

Definition at line 250 of file main.c.

Verifies requirements SD-REQ-004 (In-place repair under mutual exclusion), and SD-REQ-009 (Single-copy fault recovery).

◆ test_commit_reseals_external_write()

void test_commit_reseals_external_write ( void )

active

Unchecked commit reseals an external modification.

SAFE_COMMIT re-tags the current contents after an audited direct modification of the storage (only available with CONFIG_SAFE_DATA_ALLOW_UNCHECKED_COMMIT).

Test ID: TC_SAFE_DATA_COMMIT_RESEALS_EXTERNAL_WRITE

Depends on: CONFIG_SAFE_DATA_ALLOW_UNCHECKED_COMMIT

Test Status: Active

Definition at line 282 of file main.c.

Verifies requirement SD-REQ-022 (Unchecked commit).

◆ test_stale_tag_recovers()

void test_stale_tag_recovers ( void )

draft

Stale tag with consistent data recovers.

When only the stored tag is corrupted (payload and shadow agree), the fault is recoverable; a locked read makes the reseal durable.

Status draft (demonstration of status handling): SD-REQ-009 is also verified by TC_SAFE_DATA_DETECTS_CORRUPTION and TC_SAFE_DATA_VERIFY_REPAIR_FIXES_IN_PLACE. The test still runs.

Test ID: TC_SAFE_DATA_STALE_TAG_RECOVERS

Depends on: CONFIG_SAFE_DATA_REDUNDANT

Test Status: Draft

Definition at line 319 of file main.c.

Verifies requirement SD-REQ-009 (Single-copy fault recovery).

◆ test_double_fault_unrecoverable()

void test_double_fault_unrecoverable ( void )

active

Double fault is unrecoverable.

Inconsistent corruption of payload AND shadow leaves no copy to vouch for the data: verification reports -EILSEQ.

Test ID: TC_SAFE_DATA_DOUBLE_FAULT_UNRECOVERABLE

Depends on: CONFIG_SAFE_DATA_REDUNDANT

Test Status: Active

Definition at line 353 of file main.c.

Verifies requirement SD-REQ-010 (Double-fault detection).

◆ test_null_args()

void test_null_args ( void )

active

NULL and zero-size arguments are rejected.

Every API entry point rejects missing required pointers and zero-length payloads with -EINVAL (a NULL lock is legal: locking is optional). Each entry point is called once per required pointer and once with a zero length; the locked entry points are also called with a NULL lock and valid arguments, which must succeed.

Test ID: TC_SAFE_DATA_NULL_ARGS

Test Status: Active

Definition at line 394 of file main.c.

Verifies requirement SD-REQ-002 (Argument validation).

◆ test_reduced_api_surface()

void test_reduced_api_surface ( void )

active

Optional API surface matches the configuration.

SAFE_COMMIT and safe_data_commit() exist only with CONFIG_SAFE_DATA_ALLOW_UNCHECKED_COMMIT, and SAFE_SECTION only with CONFIG_SAFE_DATA_GNU_EXTENSIONS. Where an option is disabled, the macro is not defined and the image links no safe_data_commit(), so a use fails at build time. At the Strict level both are absent.

Test ID: TC_SAFE_DATA_REDUCED_API_SURFACE

Test Status: Active

Definition at line 482 of file main.c.

Verifies requirement SD-REQ-020 (Reduced API surface at the Strict level).

◆ test_concurrent_access_is_serialised()

void test_concurrent_access_is_serialised ( void )

active

Concurrent access never yields torn snapshots.

A producer mutating dependent fields under SAFE_UPDATE and a consumer using SAFE_READ run concurrently for many iterations; the consumer never observes a snapshot violating the payload invariant.

Test ID: TC_SAFE_DATA_CONCURRENT_ACCESS_IS_SERIALISED

Test Status: Active

Definition at line 593 of file main.c.

Verifies requirement SD-REQ-016 (Serialised access — no torn snapshots).

◆ test_selftest()

void test_selftest ( void )

active

Self-test reports a healthy mechanism.

safe_data_selftest() passes on a healthy system: CRC known-answer test plus a seal/corrupt/detect(/recover) round trip on a scratch container.

Test ID: TC_SAFE_DATA_SELFTEST

Depends on: CONFIG_SAFE_DATA_SELFTEST

Test Status: Active

Definition at line 633 of file main.c.

Verifies requirement SD-REQ-017 (Integrity-mechanism self-test).

◆ test_stats_count_events()

void test_stats_count_events ( void )

active

Statistics count every integrity event.

Recovered-payload, recovered-tag and unrecoverable detections each increment their dedicated counter exactly once per detection.

Test ID: TC_SAFE_DATA_STATS_COUNT_EVENTS

Depends on: CONFIG_SAFE_DATA_STATS

Test Status: Active

Definition at line 653 of file main.c.

Verifies requirement SD-REQ-012 (Integrity-event statistics).

◆ test_fault_handler_events()

void test_fault_handler_events ( void )

active

Registered handler receives all event kinds.

safe_data_fault_handler_register() accepts one callback (second registration is rejected with -EALREADY, re-registration is idempotent) and the callback receives recovery events as well as unrecoverable faults with a populated event descriptor.

Test ID: TC_SAFE_DATA_FAULT_HANDLER_EVENTS

Test Status: Active

Definition at line 721 of file main.c.

Verifies requirements SD-REQ-011 (Configurable unrecoverable-fault reaction), and SD-REQ-013 (Fault-handler registration and event reporting).

◆ test_update_clamps_positive_mutator_return()

void test_update_clamps_positive_mutator_return ( void )

active

Positive mutator return is clamped and aborted.

A mutator returning a positive value violates the contract: SAFE_UPDATE returns -EINVAL, the transaction aborts (rollback with shadow), and the violation is counted.

Test ID: TC_SAFE_DATA_UPDATE_CLAMPS_POSITIVE_MUTATOR_RETURN

Test Status: Active

Definition at line 777 of file main.c.

Verifies requirement SD-REQ-008 (Mutator contract enforcement).

◆ test_write_observes_overwritten_corruption()

void test_write_observes_overwritten_corruption ( void )

active

Write observes corruption before overwriting.

With CONFIG_SAFE_DATA_WRITE_CHECKS_OLD a write over corrupted contents still succeeds, but the destroyed evidence is counted in the statistics first.

Test ID: TC_SAFE_DATA_WRITE_OBSERVES_OVERWRITTEN_CORRUPTION

Depends on

CONFIG_SAFE_DATA_WRITE_CHECKS_OLD

CONFIG_SAFE_DATA_STATS

Test Status: Active

Definition at line 815 of file main.c.

Verifies requirement SD-REQ-018 (Write may not silently mask corruption).

◆ test_lock_timeout_is_bounded_and_reported()

void test_lock_timeout_is_bounded_and_reported ( void )

active

Blocked access fails within the lock bound.

While another thread holds the container lock, every locked operation (read, write, update, and commit and SAFE_SECTION where configured) fails with -ETIMEDOUT within CONFIG_SAFE_DATA_LOCK_TIMEOUT_MS and each timeout is counted; the container is usable again after the holder releases.

Test ID: TC_SAFE_DATA_LOCK_TIMEOUT_IS_BOUNDED_AND_REPORTED

Depends on

CONFIG_SAFE_DATA_LOCK_TIMEOUT_MS > 0

CONFIG_SAFE_DATA_LOCKING

Test Status: Active

Definition at line 871 of file main.c.

Verifies requirement SD-REQ-014 (Bounded lock acquisition).

Safe Data API Test Specification Annotated ztest sources of the Safe Data API
v0.0-dev+gbb519af

Functions

Detailed Description

Function Documentation

◆ test_init_and_verify()

◆ test_read_roundtrip()

◆ test_write_reseals()

◆ test_update_commits()

◆ test_update_abort_keeps_integrity()

◆ test_section_scope()

◆ test_detects_corruption()

◆ test_verify_repair_fixes_in_place()

◆ test_commit_reseals_external_write()

◆ test_stale_tag_recovers()

◆ test_double_fault_unrecoverable()

◆ test_null_args()

◆ test_reduced_api_surface()

◆ test_concurrent_access_is_serialised()

◆ test_selftest()

◆ test_stats_count_events()

◆ test_fault_handler_events()

◆ test_update_clamps_positive_mutator_return()

◆ test_write_observes_overwritten_corruption()

◆ test_lock_timeout_is_bounded_and_reported()