From 4659d0e82343e6c061261f0a2aa977b0d00f199d Mon Sep 17 00:00:00 2001 From: Dave Wallace Date: Thu, 13 Dec 2018 12:29:44 -0500 Subject: docs: clarify vector element alignment description. Change-Id: I6da153779010263e6fc4b51c64b01444aaadca17 Signed-off-by: Dave Wallace --- docs/gettingstarted/developers/infrastructure.md | 13 ++++++++----- src/vppinfra/vec.h | 14 ++++++++------ 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/docs/gettingstarted/developers/infrastructure.md b/docs/gettingstarted/developers/infrastructure.md index 0361a632c37..b99460732c5 100644 --- a/docs/gettingstarted/developers/infrastructure.md +++ b/docs/gettingstarted/developers/infrastructure.md @@ -48,13 +48,16 @@ macro! It's smart about NULL pointers.\] Typically, the user header is not present. User headers allow for other data structures to be built atop vppinfra vectors. Users may specify the -alignment for data elements via the [vec]()\*\_aligned macros. +alignment for first data element of a vector via the [vec]()\*\_aligned +macros. -Vectors elements can be any C type e.g. (int, double, struct bar). This +Vector elements can be any C type e.g. (int, double, struct bar). This is also true for data types built atop vectors (e.g. heap, pool, etc.). -Many macros have \_a variants supporting alignment of vector data and -\_h variants supporting non-zero-length vector headers. The \_ha -variants support both. +Many macros have \_a variants supporting alignment of vector elements +and \_h variants supporting non-zero-length vector headers. The \_ha +variants support both. Additionally cacheline alignment within a +vector element structure can be specified using the +[CLIB_CACHE_LINE_ALIGN_MARK]() macro. Inconsistent usage of header and/or alignment related macro variants will cause delayed, confusing failures. diff --git a/src/vppinfra/vec.h b/src/vppinfra/vec.h index 470a4f190c2..6f0e7e9148b 100644 --- a/src/vppinfra/vec.h +++ b/src/vppinfra/vec.h @@ -70,16 +70,18 @@ Typically, the header is not present. Headers allow for other data structures to be built atop CLIB vectors. - Users may specify the alignment for data elements via the - vec_*_aligned macros. + Users may specify the alignment for first data element of a vector + via the vec_*_aligned macros. - Vectors elements can be any C type e.g. (int, double, struct bar). + Vector elements can be any C type e.g. (int, double, struct bar). This is also true for data types built atop vectors (e.g. heap, pool, etc.). - Many macros have _a variants supporting alignment of vector data - and _h variants supporting non zero length vector headers. - The _ha variants support both. + Many macros have \_a variants supporting alignment of vector elements + and \_h variants supporting non-zero-length vector headers. The \_ha + variants support both. Additionally cacheline alignment within a + vector element structure can be specified using the + CLIB_CACHE_LINE_ALIGN_MARK() macro. Standard programming error: memorize a pointer to the ith element of a vector then expand it. Vectors expand by 3/2, so such code -- cgit 1.2.3-korg