From e808d8d56b7fd51f54bb7ebb007b91a31c9a1ceb Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 21 Sep 2026 18:26:13 +0100 Subject: [PATCH] docs: toolchains: point Clang instructions to Liam's fork README Align Clang toolchain documentation across getting started, CMake build system, and module integration guides to point to Liam Girdwood's llvm-project fork repository and its authoritative README.md. Changes: - In getting_started/index.rst, replace redundant/diverging inlined compiler build and workspace clone steps with a direct pointer to https://github.com/lgirdwood/llvm-project (branch llvm-stable) and its authoritative README.md. - In developer_guides/tech/cmake.rst, remove erroneous environment variables (ZEPHYR_TOOLCHAIN_VARIANT=llvm, LLVM_TOOLCHAIN_PATH) and manual 'west build ... app/' commands. Document that Clang builds are driven via 'xtensa-build-zephyr.py --llvm-clang', point to the fork README, and retain the mandatory Integrated Assembler (IAS) policy. - In developer_guides/firmware/module_integration_guide.rst, update the toolchain comparison table build command to use --llvm-clang and cross-reference the fork README. - In developer_guides/tech/images/cmake_build_pipeline_architecture.svg, update the toolchain box to reflect '--llvm-clang (Xtensa Fork)' and wrapper invocation. Signed-off-by: Liam Girdwood --- .../firmware/module_integration_guide.rst | 4 +- developer_guides/tech/cmake.rst | 41 ++++---- .../cmake_build_pipeline_architecture.svg | 6 +- getting_started/index.rst | 96 ++++--------------- 4 files changed, 45 insertions(+), 102 deletions(-) diff --git a/developer_guides/firmware/module_integration_guide.rst b/developer_guides/firmware/module_integration_guide.rst index fe349529..f504ddcc 100644 --- a/developer_guides/firmware/module_integration_guide.rst +++ b/developer_guides/firmware/module_integration_guide.rst @@ -805,8 +805,8 @@ SOF is an open-source firmware ecosystem deployed across diverse silicon platfor - Open-source GCC cross-compiler - ``ZEPHYR_TOOLCHAIN_VARIANT=zephyr ./scripts/xtensa-build-zephyr.py -p ptl`` * - **3. Experimental LLVM/Clang** - - Shared LLVM toolchain with mandatory IAS - - ``ZEPHYR_TOOLCHAIN_VARIANT=llvm ./scripts/xtensa-build-zephyr.py -p ptl`` + - Open-source Xtensa Clang with IAS (`fork README `_) + - ``./scripts/xtensa-build-zephyr.py -p ptl --llvm-clang /path/to/llvm-project/build --build-dir-suffix -llvm`` --- diff --git a/developer_guides/tech/cmake.rst b/developer_guides/tech/cmake.rst index 6929566a..5a94114e 100644 --- a/developer_guides/tech/cmake.rst +++ b/developer_guides/tech/cmake.rst @@ -390,38 +390,37 @@ out-of-tree Xtensa architecture target developed for Sound Open Firmware. and audio DSP intrinsics within an open-source toolchain. * **Experimental Status**: The LLVM Xtensa backend is currently experimental and undergoing active upstreaming and compiler validation. +* **Authoritative Toolchain & Instructions**: + The Xtensa LLVM/Clang compiler, Windowed ABI runtime builtins, and required branch integrations + are maintained in Liam Girdwood's fork: + + * **Repository**: `lgirdwood/llvm-project `_ + * **Development Branch**: ``llvm-stable`` + * **Setup Guide**: Follow the `llvm-project README.md `_ + for step-by-step instructions on building the compiler, building ``compiler-rt`` builtins, and checking out + the required ``llvm-stable`` branches across ``sof``, ``zephyr``, and ``modules/hal/xtensa``. + * **Mandatory Integrated Assembler (IAS) Policy**: All Clang builds for Xtensa DSP targets must utilize Clang's native Integrated Assembler (``-fintegrated-as``). The legacy GNU external assembler (``as``) is strictly prohibited. Firmware assembly source files (``.S``) must strictly comply with LLVM MC assembly syntax. -**Environment Setup**: - -.. code-block:: bash - - # Configure LLVM toolchain environment - export ZEPHYR_TOOLCHAIN_VARIANT=llvm - export LLVM_TOOLCHAIN_PATH=${HOME}/work/llvm-project/build - **Building SOF with LLVM / Clang**: -* **Single-Target Build with West**: - - .. code-block:: bash +Compilation targeting Intel ADSP platforms via Clang is invoked through ``xtensa-build-zephyr.py`` using the +``--llvm-clang`` flag pointing to the LLVM build directory. The build script automatically generates the +target compiler wrapper that translates compiler flags and configures the LLVM Integrated Assembler: - # Build Panther Lake (PTL) with experimental LLVM HiFi SIMD - ZEPHYR_TOOLCHAIN_VARIANT=llvm \ - LLVM_TOOLCHAIN_PATH=${HOME}/work/llvm-project/build \ - west build -b intel_adsp_ace30_ptl -d build-ptl-llvm app/ +.. code-block:: bash -* **Multi-Target Batch Build**: + cd ${SOF_WORKSPACE} + source .venv/bin/activate - .. code-block:: bash + # Single-target build (Panther Lake / ACE 3.0) + ./sof/scripts/xtensa-build-zephyr.py -p ptl --llvm-clang ${HOME}/work/llvm-project/build --build-dir-suffix -llvm - # Batch compile with experimental LLVM backend - ZEPHYR_TOOLCHAIN_VARIANT=llvm \ - LLVM_TOOLCHAIN_PATH=${HOME}/work/llvm-project/build \ - ./scripts/xtensa-build-zephyr.py ptl + # Multi-target batch build + ./sof/scripts/xtensa-build-zephyr.py -p tgl mtl ptl --llvm-clang ${HOME}/work/llvm-project/build --build-dir-suffix -llvm Kconfig Customization & Snippets -------------------------------- diff --git a/developer_guides/tech/images/cmake_build_pipeline_architecture.svg b/developer_guides/tech/images/cmake_build_pipeline_architecture.svg index ab0908d7..a28218ca 100644 --- a/developer_guides/tech/images/cmake_build_pipeline_architecture.svg +++ b/developer_guides/tech/images/cmake_build_pipeline_architecture.svg @@ -92,7 +92,7 @@ Target Toolchain Selection - ZEPHYR_TOOLCHAIN_VARIANT= + Toolchain Selection & Invocation: xt-clang (Cadence - Default) @@ -103,8 +103,8 @@ Compliant binaries / No Xtensa SIMD - llvm (Clang - Experimental) - Experimental / HiFi Xtensa SIMD + IAS + --llvm-clang (Xtensa Fork) + Wraps Clang + HiFi SIMD + IAS diff --git a/getting_started/index.rst b/getting_started/index.rst index 53ba27c8..c073fc0e 100644 --- a/getting_started/index.rst +++ b/getting_started/index.rst @@ -263,94 +263,38 @@ The SOF build script ``xtensa-build-zephyr.py`` automatically checks for ``XTENS Optional: LLVM / Clang Xtensa Toolchain (Open-Source Fork) ---------------------------------------------------------- -For open-source development on Intel ADSP Xtensa targets without a Cadence license, use the open-source Xtensa LLVM/Clang development fork (`llvm-project `_). +For open-source development on Intel ADSP Xtensa targets without a Cadence license, Sound Open Firmware supports the open-source Xtensa LLVM/Clang toolchain maintained in Liam Girdwood's fork: -1. **Clone and Build LLVM/Clang Compiler**: +* **Repository**: `lgirdwood/llvm-project `_ +* **Development Branch**: ``llvm-stable`` +* **Setup Guide & Instructions**: `llvm-project README.md `_ - .. code-block:: bash - - cd ${SOF_WORKSPACE} - - # Clone the Xtensa development fork (llvm-stable branch) - git clone -b llvm-stable https://github.com/lgirdwood/llvm-project.git - cd llvm-project - - # Configure and build LLVM and Clang - cmake -G Ninja -S llvm -B build \ - -DCMAKE_BUILD_TYPE=Release \ - -DLLVM_ENABLE_PROJECTS="clang;lld" \ - -DLLVM_TARGETS_TO_BUILD="host" \ - -DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD="Xtensa" \ - -DLLVM_ENABLE_ASSERTIONS=OFF \ - -DLLVM_OPTIMIZED_TABLEGEN=ON - - ninja -C build - -2. **Build compiler-rt Builtins**: - - Intel ADSP targets require specific builtins to be compiled with correct target features (windowed ABI, HiFi coprocessor disabled to prevent boot-time exceptions): - - .. code-block:: bash +.. important:: - # Compile and install compiler-rt builtins for Xtensa Windowed ABI - ./scripts/build_windowed_rt.sh + The `fork README `_ is the authoritative Single Source of Truth for building and configuring the Xtensa Clang toolchain. Always refer directly to the README for the exact, up-to-date instructions on: - # (Optional) For Call0 ABI if needed: - # ./scripts/build_call0_rt.sh + 1. **Configuring and Building LLVM/Clang**: Building LLVM, Clang, and LLD with the experimental Xtensa target enabled (``-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD="Xtensa"``). + 2. **Compiling compiler-rt Builtins**: Running ``./scripts/build_windowed_rt.sh`` to build required runtime builtins for the Xtensa Windowed ABI with HiFi coprocessors disabled at boot. + 3. **Integrating Workspace Branches**: Pulling the required ``llvm-stable`` development branches into your workspace repositories (``sof``, ``zephyr``, and ``modules/hal/xtensa``). + 4. **Building SOF Firmware**: Invoking the SOF build script with ``--llvm-clang``: -3. **Integrate Fork Development Branches into Workspace**: - - Pull the required ``llvm-stable`` development branches into your workspace repositories: - - .. code-block:: bash - - cd ${SOF_WORKSPACE} - - # 1. SOF repository - cd sof - git remote add lgirdwood https://github.com/lgirdwood/sof.git - git fetch lgirdwood llvm-stable - git checkout -b llvm-stable-work - git pull lgirdwood llvm-stable - cd .. - - # 2. Zephyr repository - cd zephyr - git remote add lgirdwood https://github.com/lgirdwood/zephyr.git - git fetch lgirdwood llvm-stable - git checkout -b llvm-stable-work - git pull lgirdwood llvm-stable - cd .. - - # 3. Xtensa HAL repository (modules/hal/xtensa) - cd modules/hal/xtensa - git remote add lgirdwood https://github.com/lgirdwood/hal_xtensa.git - git fetch lgirdwood llvm-stable - git checkout -b llvm-stable-work - git pull lgirdwood llvm-stable - cd ../../.. - -4. **Build SOF Using Clang**: - - Pass ``--llvm-clang`` pointing to your LLVM build directory: - - .. code-block:: bash + .. code-block:: bash - cd ${SOF_WORKSPACE} - source .venv/bin/activate + cd ${SOF_WORKSPACE} + source .venv/bin/activate - # Meteor Lake / Arrow Lake (mtl / arl) - ./sof/scripts/xtensa-build-zephyr.py -p mtl --llvm-clang ${SOF_WORKSPACE}/llvm-project/build --build-dir-suffix -llvm + # Meteor Lake / Arrow Lake (mtl / arl) + ./sof/scripts/xtensa-build-zephyr.py -p mtl --llvm-clang /path/to/llvm-project/build --build-dir-suffix -llvm - # Tiger Lake (tgl) - ./sof/scripts/xtensa-build-zephyr.py -p tgl --llvm-clang ${SOF_WORKSPACE}/llvm-project/build --build-dir-suffix -llvm + # Tiger Lake (tgl) + ./sof/scripts/xtensa-build-zephyr.py -p tgl --llvm-clang /path/to/llvm-project/build --build-dir-suffix -llvm - # Panther Lake (ptl) - ./sof/scripts/xtensa-build-zephyr.py -p ptl --llvm-clang ${SOF_WORKSPACE}/llvm-project/build --build-dir-suffix -llvm + # Panther Lake (ptl) + ./sof/scripts/xtensa-build-zephyr.py -p ptl --llvm-clang /path/to/llvm-project/build --build-dir-suffix -llvm .. note:: - **Integrated Assembler (IAS) Mandatory Policy**: All compilation targeting Xtensa via LLVM Clang must use the LLVM Integrated Assembler (IAS) (enabled by default with ``-fintegrated-as -mtext-section-literals -mlongcalls``). Never pass ``-fno-integrated-as``, as legacy GNU Assembler (GAS) cannot resolve label-difference relocations on Xtensa branch trampolines. + **Integrated Assembler (IAS) Mandatory Policy**: All compilation targeting Xtensa via LLVM Clang must use the LLVM Integrated Assembler (IAS) (enabled by default with ``-fintegrated-as -mtext-section-literals -mlongcalls``). Never pass ``-fno-integrated-as``, as the legacy external GNU Assembler (GAS) cannot resolve label-difference relocations on Xtensa branch trampolines. Step 4: Build Firmware Images =============================