[PATCH] doc: clarify disabling AVX-512 when building on Haswell CPUs

[Khadem Ullah]

Some Intel Xeon processors (e.g., E5 v3 Haswell) do not support AVX-512
instructions, and building DPDK targeting 'native' instruction set can
fail with 'target specific option mismatch' errors.

This patch updates the build guide with instructions for configuring
Meson to disable AVX-512 and target the Haswell architecture.

Bugzilla ID: 1736
Cc: stable at dpdk.org

Signed-off-by: Khadem Ullah <14pwcse1224 at uetpeshawar.edu.pk>
---
 doc/guides/linux_gsg/build_dpdk.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst
index 9c0dd9daf6..57d3fd484b 100644
--- a/doc/guides/linux_gsg/build_dpdk.rst
+++ b/doc/guides/linux_gsg/build_dpdk.rst
@@ -123,6 +123,28 @@ The instruction set will be set automatically by default according to these rule
 
 To override what instruction set will be used, set the ``cpu_instruction_set``
 parameter to the instruction set of your choice (such as ``corei7``, ``power8``, etc.).
+.. note::
+
+   **Disabling AVX-512 instructions when targeting older Intel CPUs**
+
+   On some Intel CPUs (e.g., Xeon E5 v3 "Haswell"), building with
+   ``cpu_instruction_set=native`` or not specifying it at all can cause
+   errors like::
+
+       inlining failed in call to always_inline '_mm512_maskz_broadcast_i32x4': target specific option mismatch
+
+   or::
+
+       AVX512F vector return without AVX512F enabled
+
+   This happens because the compiler tries to use AVX-512 instructions that the CPU does not support.
+
+   To avoid these errors, you can disable AVX-512 explicitly and set the architecture to Haswell by configuring with:
+
+   .. code-block:: console
+
+      meson setup build -Dc_args="-march=haswell -mno-avx512f" -Dcpu_instruction_set=haswell
+
 
 ``cpu_instruction_set`` is not used in Arm builds, as setting the instruction set
 without other parameters leads to inferior builds. The way to tailor Arm builds
-- 
2.43.0