Add explanation of recent build configuration changes for Arm SoCs and
instructions for adding a build configuration for a new Arm SoC.
Signed-off-by: Doug Foster <doug.fos...@arm.com>
Reviewed-by: Wathsala Vithanage <wathsala.vithan...@arm.com>
Reviewed-by: Dhruv Tripathi <dhruv.tripa...@arm.com>
---
doc/guides/linux_gsg/build_dpdk.rst | 116 ++++++++++++++++++++++++++++
1 file changed, 116 insertions(+)
diff --git a/doc/guides/linux_gsg/build_dpdk.rst
b/doc/guides/linux_gsg/build_dpdk.rst
index 9c0dd9daf6..aa5b518821 100644
--- a/doc/guides/linux_gsg/build_dpdk.rst
+++ b/doc/guides/linux_gsg/build_dpdk.rst
@@ -149,6 +149,122 @@ When `-Dexamples=all` is set as a meson option, meson
will check each example ap
and add all which can be built to the list of tasks in the ninja build
configuration file.
+.. _building_new_arm_soc:
+
+Building DPDK for a New ARM SoC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The DPDK build system for ARM platforms has been updated to improve clarity,
usability,
+and performance optimization.
+Previously, the ARM build process utilized a mixture of compiler flags
(``-mcpu``,
+``-march``, and ``-mtune``), which could inadvertently cause the compiler to
fall back
+to older instruction sets, resulting in suboptimal performance.
+Following Arm's official guidance, the recommended practice is to prioritize
the
+``-mcpu`` flag whenever the compiler supports the targeted CPU.
+The ``-mcpu`` option specifies the exact CPU, enabling the compiler to
optimize code
+generation, select appropriate instruction sets, and fine-tune performance
+characteristics explicitly for the given processor.
+In contrast, ``-march`` defines the general architecture, and ``-mtune``
optimizes
+performance for a specific CPU but does not allow the compiler to make
assumptions
+about available instructions.
+Prioritizing ``-mcpu`` ensures the build system generates optimized binaries
tailored
+precisely for the intended CPU.
+The changes also include explicit build failures if the compiler does not
support the
+specified CPU setting, avoiding unintended fallbacks to lower-performing
architectures.
+
+
+**Summary of Changes and Impact**
+
+* For CPUs directly supported by a compiler's ``-mcpu`` option, references to
+ ``-march`` and related features have been eliminated to simplify and improve
the
+ build configuration.
+
+* Introduction of Pseudo-CPU Definitions: For CPUs lacking direct compiler
support,
+ pseudo-CPU definitions explicitly specify architecture (``march``) and
extensions
+ (``march_extensions``) to ensure optimal performance without unintended
downgrades.
+
+* Explicit Build Failures: Builds now explicitly fail when unsupported
``-mcpu``,
+ ``march``, or extensions are specified, providing guidance to resolve the
issue
+ without silent fallbacks.
+
+
+**Adding Support for a New SoC**
+
+If building DPDK for an ARM SoC that is not already supported, follow the
guidelines
+below to add support for a new SoC based on compiler support.
+
+* Compiler ``-mcpu`` option supports the SoC
+
+ #. In the appropriate ``part_number_config`` dictionary (located in
+ ``config/arm/meson.build``), assign to ``mcpu`` the SoC supported by the
compiler
+ ``-mcpu`` option.
+ The following example is for SoC *foo* where the compiler supports
``-mcpu=foo``.
+
+ .. code-block:: meson
+
+ '<Part_Number>': {
+ 'mcpu': 'foo',
+ 'flags': [
+ ['RTE_MACHINE', '"Foo"'],
+ # Additional flags as needed
+ ]
+ },
+
+* Compiler lacks specific ``-mcpu`` support or features (pseudo-CPU required)
+
+ If the compiler does not fully support your SoC, perform the following steps:
+
+ #. Assign a pseudo-CPU name:
+
+ In the appropriate ``part_number_config`` dictionary (located in
+ ``config/arm/meson.build``), assign to ``mcpu`` a unique pseudo-CPU name
+ prefixed with ``mcpu_``.
+ This name should clearly represent your SoC.
+ The following example is for SoC *foo*.
+
+ .. code-block:: meson
+
+ '<Part_Number>': {
+ 'mcpu': 'mcpu_foo',
+ 'flags': [
+ ['RTE_MACHINE', '"Foo"'],
+ # Additional flags as needed
+ ]
+ },
+
+ #. Define the pseudo-CPU details:
+
+ In the ``mcpu_defs`` dictionary, add your pseudo-CPU definition.
+ Clearly specify the architecture (``march``) and list any
compiler-supported
+ extensions (``march_extensions``).
+ Extensions such as ``sve`` or ``crypto`` are examples.
+ It is acceptable to leave ``march_extensions`` empty if no specific
extensions
+ are required.
+
+ .. code-block:: meson
+
+ 'mcpu_foo': {
+ 'march': 'armv8.x-a',
+ 'march_extensions': ['sve', 'crypto']
+ },
+
+ Replace ``armv8.x-a`` and the listed extensions with the appropriate ISA
and
+ features for your SoC.
+
+* Older compiler without specific ``-mcpu`` support
+
+ #. Upgrade your compiler to a newer version that supports the required CPU.
+
+ #. Alternatively, utilize a generic build configuration:
+
+ .. code-block:: console
+
+ meson setup -Dplatform=generic build
+
+By adhering to these guidelines, you will ensure the most optimized build for
+ARM-based DPDK targets.
+
+
Building 32-bit DPDK on 64-bit Systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--
2.34.1
