[PATCH v2 08/68] eal: document when to use rte_memcpy

The choice between rte_memcpy() and memcpy() was not documented,
which has led to rte_memcpy() being used in places where it gives
no benefit, such as the control path and copies of a constant size.

Document the guidance: structure assignment for fixed size objects,
memcpy() for the control path and for constant sizes, and rte_memcpy()
only for variable size copies in the data path.

Suggested-by: Morten Brørup <[email protected]>
Signed-off-by: Stephen Hemminger <[email protected]>
---
 lib/eal/include/generic/rte_memcpy.h | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/lib/eal/include/generic/rte_memcpy.h b/lib/eal/include/generic/rte_memcpy.h
index da53b72ca8..e409c9bccc 100644
--- a/lib/eal/include/generic/rte_memcpy.h
+++ b/lib/eal/include/generic/rte_memcpy.h
@@ -96,6 +96,24 @@ rte_mov256(uint8_t *dst, const uint8_t *src);
 /**
  * Copy bytes from one location to another. The locations must not overlap.
  *
+ * This function exists because on some platforms the libc memcpy()
+ * does not generate optimal code for the copy sizes and alignments
+ * common in packet processing. It is not a general replacement for
+ * memcpy(); prefer the following, in order:
+ *
+ * - Use structure assignment when copying a fixed size object.
+ *   The compiler generates the best possible code, and the types
+ *   are checked.
+ * - Use memcpy() everywhere else, in particular in the control path,
+ *   and whenever the size is a compile time constant. For a constant
+ *   size the compiler inlines the copy, so rte_memcpy() gains nothing,
+ *   and memcpy() is understood by analysis tools such as the address
+ *   sanitizer, valgrind and _FORTIFY_SOURCE which can then detect
+ *   overlapping or out of bounds copies.
+ * - Use rte_memcpy() only in the data path, and only where the size is
+ *   variable at run time. This is the case for which it was written,
+ *   and where it can still be faster than the libc implementation.
+ *
  * @note This is implemented as a macro, so it's address should not be taken
  * and care is needed as parameter expressions may be evaluated multiple times.
  *
-- 
2.53.0