diff --git a/raid/README b/raid/README index e39eb4b6..64d0b302 100644 --- a/raid/README +++ b/raid/README @@ -32,32 +32,37 @@ detect CPU capabilities and initialize mode dispatch. void raid_zero(void *zero) Registers a read-only buffer filled with zeros of block size 'size'. - Required prior to calling raid_rec() or raid_data() for delta parity - computation. + The buffer must be aligned to a 64-byte boundary. Required prior to + calling raid_rec() or raid_data() for delta parity computation. void raid_gen(int nd, int np, size_t size, void **v) 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]). Data blocks are read-only; parity blocks are written. + v[nd..nd+np-1]). Each block must be aligned to a 64-byte boundary. + Data blocks are read-only; parity blocks are written. 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 - 'ir'. Indexes start at 0 (data 0..nd-1, parity nd..nd+np-1). Pointers in 'v' + 'ir'. Indexes start at 0 (data 0..nd-1, parity nd..nd+np-1). Each block + pointed to by 'v' must be aligned to a 64-byte boundary. Pointers in 'v' for good blocks are read; pointers for bad blocks are target destinations. Requires nr <= np. void raid_data(int nr, int *id, int *ip, int nd, size_t size, void **v) Recovers 'nr' failed data blocks listed in sorted array 'id', using - parities listed in sorted array 'ip'. Parity blocks in 'v' are unmodified. + parities listed in sorted array 'ip'. Each block pointed to by 'v' must + be aligned to a 64-byte boundary. Parity blocks in 'v' are unmodified. Requires nr <= nd and nr <= RAID_PARITY_MAX. int raid_check(int nr, int *ir, int nd, int np, size_t size, void **v) Validates whether candidate failed block set 'ir' matches available parity - redundancy. Returns 0 if candidate set matches, or -1 if invalid. Requires + redundancy. Each block pointed to by 'v' must be aligned to a 64-byte + boundary. Returns 0 if candidate set matches, or -1 if invalid. Requires nr < np. Does not modify data or parity blocks. 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. @@ -76,8 +81,10 @@ Memory and Alignment Requirements - Block Size: Parameter 'size' MUST be a multiple of 64 bytes (size % 64 == 0). - - Memory Alignment: Blocks should ideally be aligned on 16/32/64-byte - boundaries to optimize SIMD vector loads and stores. + - Memory Alignment: All data and parity blocks pointed to by 'v[]' + (as well as the zero buffer passed to raid_zero()) MUST be aligned to + a 64-byte boundary. This requirement applies to each individual block + buffer, not to the pointer array 'v' itself. - Sorted Index Arrays: Index arrays ('ir', 'id', 'ip') MUST be strictly sorted in ascending order (e.g. ir[0] < ir[1] < ... < ir[nr-1]). diff --git a/raid/raid.h b/raid/raid.h index 7e8a966a..50ecdb8d 100644 --- a/raid/raid.h +++ b/raid/raid.h @@ -133,6 +133,8 @@ int raid_mode(int mode); * Before calling raid_rec() and raid_data() you must provide a memory * buffer filled with zeros of the same size as the blocks to recover. * + * The buffer pointed to by @zero must be aligned to a 64-byte boundary. + * * This buffer is only read and never written. */ void raid_zero(void *zero); @@ -152,7 +154,7 @@ void raid_zero(void *zero); * It has (@nd + @np) elements. The starting elements are the blocks for * data, following with the parity blocks. * Data blocks are only read and not modified. Parity blocks are written. - * Each block has @size bytes. + * Each block has @size bytes and must be aligned to a 64-byte boundary. */ void raid_gen(int nd, int np, size_t size, void **v); @@ -187,7 +189,7 @@ void raid_gen(int nd, int np, size_t size, void **v); * @v Vector of pointers to the blocks of data and parity. * It has (@nd + @np) elements. The starting elements are the blocks * for data, following with the parity blocks. - * Each block has @size bytes. + * Each block has @size bytes and must be aligned to a 64-byte boundary. */ void raid_rec(int nr, int *ir, int nd, int np, size_t size, void **v); @@ -207,7 +209,7 @@ void raid_rec(int nr, int *ir, int nd, int np, size_t size, void **v); * @v Vector of pointers to the blocks of data and parity. * It has (@nd + @ip[@nr - 1] + 1) elements. The starting elements are the * blocks for data, following with the parity blocks. - * Each block has @size bytes. + * Each block has @size bytes and must be aligned to a 64-byte boundary. */ void raid_data(int nr, int *id, int *ip, int nd, size_t size, void **v); @@ -234,7 +236,7 @@ void raid_data(int nr, int *id, int *ip, int nd, size_t size, void **v); * @v Vector of pointers to the blocks of data and parity. * It has (@nd + @np) elements. The starting elements are the blocks * for data, following with the parity blocks. - * Each block has @size bytes. + * Each block has @size bytes and must be aligned to a 64-byte boundary. * @return 0 if the check is satisfied. -1 otherwise. */ int raid_check(int nr, int *ir, int nd, int np, size_t size, void **v); @@ -271,7 +273,7 @@ int raid_check(int nr, int *ir, int nd, int np, size_t size, void **v); * @v Vector of pointers to the blocks of data and parity. * It has (@nd + @np) elements. The starting elements are the blocks * for data, following with the parity blocks. - * Each block has @size bytes. + * 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.