From 03d82a71f4922e490cd5b8a51a0d03a185b95a38 Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Mon, 24 Aug 2026 17:51:35 +0200 Subject: [PATCH] Document raid_selftest startup execution and mode selection requirements --- raid/README | 14 +++++++++++--- raid/raid.h | 19 ++++++++++++++----- 2 files changed, 25 insertions(+), 8 deletions(-) diff --git a/raid/README b/raid/README index ca8566fe..c05883a1 100644 --- a/raid/README +++ b/raid/README @@ -16,7 +16,10 @@ Public API Header: #include "raid.h" Before invoking any generation or recovery functions, call raid_init() once to -detect CPU capabilities and initialize mode dispatch. +detect CPU capabilities and initialize mode dispatch. Then select the RAID mode +to use, if different from the default, and call raid_selftest(). raid_selftest() +verifies only the currently selected mode and is intended to be run at every +library startup before normal RAID operations. void raid_init(void) Initializes algorithm tables and detects hardware SIMD instruction sets @@ -71,7 +74,12 @@ detect CPU capabilities and initialize mode dispatch. int raid_selftest(void) Runs startup verification tests for parity generation, recovery, and - scanning across parity levels 1..6. Returns 0 on success, < 0 on failure. + scanning across parity levels supported by the currently selected mode. + It is intended to be called at every library startup after the RAID mode + has been selected, to verify the selected implementation on the current + CPU, compiler, and ABI. If the mode is changed later, the self test should + be run again before using the new mode. Returns 0 on success, < 0 on + failure. Memory, Alignment and Aliasing Requirements @@ -166,7 +174,7 @@ Testing and Benchmarks Standalone test applications located in raid/test/ provide verification and performance evaluation: - raid/test/selftest Quick startup self-test verifying basic correctness. + raid/test/selftest Quick startup self-test exercising raid_selftest(). raid/test/fulltest Exhaustive test suite testing all combinations of data disks (1..251) and single/multi-disk failure recovery. raid/test/invtest Matrix inversion test verifying non-singularity for all diff --git a/raid/raid.h b/raid/raid.h index d88fe8bb..a33e46bd 100644 --- a/raid/raid.h +++ b/raid/raid.h @@ -111,6 +111,9 @@ * * You must call this function before any other RAID function. * + * After selecting the RAID mode to use, raid_selftest() should be called + * before using the RAID system. + * * Initialization modifies global RAID state and must not be called * concurrently with any other RAID function. * @@ -140,12 +143,18 @@ int raid_mode(int mode); * * raid_init() must be called before this function. * - * If a mode different from the default is required, raid_mode() must be - * called before this function. The self test verifies the currently selected - * RAID mode. + * The RAID mode to use must be selected before calling this function. + * raid_init() selects RAID_MODE_CAUCHY_RAID by default; raid_mode() may be + * used to select a different mode. The self test verifies only the currently + * selected RAID mode. * - * The test is immediate, and it's intended to be run at application - * startup to check the integrity of the RAID system. + * The test is immediate and is intended to be run at every application + * startup after the RAID mode has been selected. It verifies the RAID + * implementation selected for the current mode, CPU, compiler, and ABI + * before it is used. + * + * If the RAID mode is changed later, this function should be called again + * before using the new mode. * * The test modifies global RAID state and must not be called concurrently * with any other RAID function.