From e5ca862a37a7c5d5cc0d4873c536529f8e812e89 Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Thu, 20 Aug 2026 20:56:48 +0200 Subject: [PATCH] Correct raid_scan documentation on candidate search and return semantics --- raid/README | 9 ++++++--- raid/raid.h | 14 +++++++++++--- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/raid/README b/raid/README index 44018421..d67c4d0a 100644 --- a/raid/README +++ b/raid/README @@ -62,9 +62,12 @@ detect CPU capabilities and initialize mode dispatch. int raid_scan(int *ir, int nd, int np, size_t size, void **v) Searches for up to 'np - 1' failed blocks using available redundancy. - Each block pointed to by 'v' must be aligned to a 64-byte boundary. - Fills 'ir' with failed block indexes and returns the number of failures - found (0 if no error), or -1 if failed blocks cannot be uniquely located. + Candidates are tested with an increasing number of failures, and the + first combination matching the redundancy is returned. If multiple + combinations match, the first one encountered is returned without + checking uniqueness. Each block pointed to by 'v' must be aligned to a + 64-byte boundary. Fills 'ir' with the matching block indexes and returns + their number (0 if no error), or -1 if no compatible combination is found. int raid_selftest(void) Runs startup verification tests for parity generation, recovery, and diff --git a/raid/raid.h b/raid/raid.h index 2a63ab13..a36f59e5 100644 --- a/raid/raid.h +++ b/raid/raid.h @@ -267,8 +267,16 @@ int raid_check(int nr, int *ir, int nd, int np, size_t size, void **v); /** * Scan for failed blocks. * - * This function identifies the failed data and parity blocks using the - * available redundancy. + * This function searches for a set of failed data and parity blocks + * compatible with the available redundancy. + * + * It first checks for no failures, and then tries candidate combinations + * with an increasing number of failures, from 1 up to @np - 1. The first + * combination satisfying the redundancy information is returned. + * + * If multiple combinations satisfy the redundancy information, only the + * first one encountered is returned. This function does not check that the + * returned combination is unique. * * It uses a brute force method, and then the call can be expensive. * The expected execution time is proportional to the binomial coefficient @@ -299,7 +307,7 @@ int raid_check(int nr, int *ir, int nd, int np, size_t size, void **v); * Each block has @size bytes and must be aligned to a 64-byte boundary. * @return Number of block indexes returned in the @ir vector. * 0 if no error is detected. - * -1 if it's not possible to identify the failed disks. + * -1 if no compatible combination with fewer than @np failures is found. */ int raid_scan(int *ir, int nd, int np, size_t size, void **v);