From bfe5ee7643e0fa64c406d22baf5a0591951fb4da Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Wed, 16 Sep 2026 08:39:22 +0200 Subject: [PATCH] Document streaming parameter as a strict 0 or 1 value --- raid/NOTES | 4 ++-- raid/README | 8 ++++---- raid/internal.h | 3 ++- raid/module.c | 2 +- raid/raid.h | 5 +++-- 5 files changed, 12 insertions(+), 10 deletions(-) diff --git a/raid/NOTES b/raid/NOTES index 8aca639b..20028207 100644 --- a/raid/NOTES +++ b/raid/NOTES @@ -160,11 +160,11 @@ MOVNT / non-temporal stores vs cached generation -------------------------------------------------- * raid_gen(..., streaming) allows the caller to select between non-temporal - streaming stores (streaming != 0, using MOVNTDQ/VMOVNTDQ + sfence on x86) and + streaming stores (streaming == 1, using MOVNTDQ/VMOVNTDQ + sfence on x86) and normal temporal/cached stores (streaming == 0, using MOVDQA/VMOVDQA without sfence). * Generation backends select MOVNTDQ / VMOVNTDQ for parity output when - streaming != 0 is requested. + streaming == 1 is requested. Values other than 0 and 1 are invalid. * The synthetic speedtest naturally favors non-temporal stores because generated parity is not consumed afterwards. This benchmark therefore measures producer diff --git a/raid/README b/raid/README index 3382cf57..f79fc3a3 100644 --- a/raid/README +++ b/raid/README @@ -37,10 +37,10 @@ library startup before normal RAID operations. Computes 'np' parity blocks from 'nd' data blocks. Vector 'v' contains 'nd + np' block pointers (data blocks v[0..nd-1], parity blocks v[nd..nd+np-1]). Each block must be aligned to a 64-byte boundary. - Data blocks are read-only; parity blocks are written. If 'streaming' is - non-zero, non-temporal streaming stores are used where supported to avoid - polluting the CPU cache when parity is written directly to disk. If - 'streaming' is zero, normal cached stores are used. + Data blocks are read-only; parity blocks are written. 'streaming' must be + either 0 or 1. If it is 1, non-temporal streaming stores are used where + supported to avoid polluting the CPU cache when parity is written directly + to disk. If it is 0, normal cached stores are used. void raid_rec(int nr, int *ir, int nd, int np, size_t size, void **v) Recovers 'nr' failed blocks (data or parity) listed in sorted index array diff --git a/raid/internal.h b/raid/internal.h index 05a148fb..4fbe9b89 100644 --- a/raid/internal.h +++ b/raid/internal.h @@ -278,7 +278,8 @@ void raid_rec6_neon32(int nr, int *id, int *ip, int nd, size_t size, void **vv); * It has (@nd + #parities) elements. The starting elements are the blocks * for data, following with the parity blocks. * Each block has @size bytes. - * @streaming Nonzero for streaming/non-temporal stores where supported, 0 for cached stores. + * @streaming 1 for streaming/non-temporal stores where supported, 0 for cached stores. + * No other values are valid. */ typedef void (raid_gen_fn)(int nd, size_t size, void **vv, int streaming); diff --git a/raid/module.c b/raid/module.c index e8d4c467..63efafa1 100644 --- a/raid/module.c +++ b/raid/module.c @@ -88,7 +88,7 @@ void raid_gen(int nd, int np, size_t size, void **v, int streaming) /* enforce valid vector */ BUG_ON(v == 0); - /* enforce valid streaming flag */ + /* enforce the documented 0/1 store policy */ BUG_ON(streaming != 0 && streaming != 1); BUG_ON(raid_gen_ptr[np - 1] == 0); diff --git a/raid/raid.h b/raid/raid.h index f8a7f94d..b8ce9e11 100644 --- a/raid/raid.h +++ b/raid/raid.h @@ -200,9 +200,10 @@ int raid_selftest(void); * data, following with the parity blocks. * Data entries are used as inputs and parity entries as outputs. * Entries may point to the same block buffer. - * @streaming Store policy hint: nonzero for streaming / non-temporal stores + * @streaming Store policy hint: 1 for streaming / non-temporal stores * (bypassing cache) where supported, or 0 for normal cached / temporal stores. - * Use nonzero when generated output will not be read immediately by the CPU + * No other values are valid. + * Use 1 when generated output will not be read immediately by the CPU * (e.g., parity queued for disk writes during sync), avoiding cache pollution. * Use 0 when output will be consumed immediately by the CPU (e.g., in-memory * parity verification or single-disk data recovery).