From 209b9023019a40b55f265399a82086b37ec86a7f Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Wed, 16 Sep 2026 12:24:42 +0200 Subject: [PATCH] Clarify raid_malloc documentation --- raid/memory.c | 6 +++--- raid/memory.h | 26 +++++++++++++++++++++++--- 2 files changed, 26 insertions(+), 6 deletions(-) diff --git a/raid/memory.c b/raid/memory.c index 6303e709..3b575c70 100644 --- a/raid/memory.c +++ b/raid/memory.c @@ -120,7 +120,7 @@ static const unsigned STRIDE_NOISE[16] = { 1, 4, 0, 7, 3, 6, 2, 5 }; -void **raid_malloc_vector_align(int n, size_t size, size_t align_size, size_t displacement_size, size_t wrap_size, void **freeptr) +void **raid_malloc_vector_align(int n, size_t size, size_t base_align_size, size_t displacement_size, size_t wrap_size, void **freeptr) { void **v; uint8_t *va; @@ -138,10 +138,10 @@ void **raid_malloc_vector_align(int n, size_t size, size_t align_size, size_t di /* * The allocated buffer must safely hold the disk chunks, the L1 fixed displacement, * and the variable STRIDE_NOISE. Because the maximum noise multiplier in the array - * is 7, reserving 8 * RAID_WRAP_SIZE per disk guarantees the pointer will never overflow + * is 7, reserving 8 * wrap_size per disk guarantees the pointer will never overflow * the allocated memory block. */ - va = raid_malloc_align(n * (size + displacement_size + 8 * wrap_size), align_size, freeptr); + va = raid_malloc_align(n * (size + displacement_size + 8 * wrap_size), base_align_size, freeptr); if (!va) { /* LCOV_EXCL_START */ free(v); diff --git a/raid/memory.h b/raid/memory.h index a13d518b..19aa8af1 100644 --- a/raid/memory.h +++ b/raid/memory.h @@ -92,23 +92,43 @@ void *raid_malloc(size_t size, void **freeptr); void *raid_malloc_align(size_t size, size_t align_size, void **freeptr); /** - * Aligned vector allocation. + * Cache-displaced vector allocation. * * Allocates an array of @n pointers, each one pointing to a block of * the specified @size with optimal L1 displacement and stride perturbation. * + * The first block is aligned to RAID_MALLOC_ALIGN. If @size is a multiple of + * 64, every block is aligned to at least 64 bytes because the displacement and + * stride perturbation are also multiples of 64. Later blocks are deliberately + * not realigned to RAID_MALLOC_ALIGN, as that would alter their cache-set + * displacement. + * * Freeing requires two calls: free(*freeptr) for the data buffer, * and free(v) for the pointer vector. */ void **raid_malloc_vector(int n, size_t size, void **freeptr); /** - * Arbitrary aligned vector allocation. + * Base-aligned vector allocation with caller-defined spacing. + * + * Allocates an array of @n pointers. The first block, which is the base of the + * usable data area, is aligned to @base_align_size bytes. Subsequent block + * addresses are obtained by adding @size, @displacement_size, and an integer + * multiple of @wrap_size; they are not individually realigned. + * + * All blocks retain @base_align_size alignment if: + * + * (@size + @displacement_size) % @base_align_size == 0 + * @wrap_size % @base_align_size == 0 + * + * @base_align_size must be greater than 0. Callers requiring a specific + * alignment for every block must select spacing values that satisfy these + * conditions. * * Freeing requires two calls: free(*freeptr) for the data buffer, * and free(v) for the pointer vector. */ -void **raid_malloc_vector_align(int n, size_t size, size_t align_size, size_t displacement_size, size_t wrap_size, void **freeptr); +void **raid_malloc_vector_align(int n, size_t size, size_t base_align_size, size_t displacement_size, size_t wrap_size, void **freeptr); /** * Fills the memory vector with pseudo-random data based on the specified seed.