From nobody Tue Dec 16 19:55:00 2025 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 05301C71133 for ; Fri, 25 Aug 2023 17:38:41 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S240474AbjHYRiJ (ORCPT ); Fri, 25 Aug 2023 13:38:09 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38122 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239147AbjHYRiH (ORCPT ); Fri, 25 Aug 2023 13:38:07 -0400 Received: from mail-yw1-x1149.google.com (mail-yw1-x1149.google.com [IPv6:2607:f8b0:4864:20::1149]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 798292128 for ; Fri, 25 Aug 2023 10:38:04 -0700 (PDT) Received: by mail-yw1-x1149.google.com with SMTP id 00721157ae682-58cbf62bae8so16811907b3.3 for ; Fri, 25 Aug 2023 10:38:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20221208; t=1692985083; x=1693589883; h=cc:to:from:subject:message-id:mime-version:date:from:to:cc:subject :date:message-id:reply-to; bh=nW0lHbEH2B08cVP1PWHu98ltXXBWNNKQyHzU/WWXVBg=; b=vn4NLE80Ek9GDI0l8rmwhGAFZ6JE/I3eUGF3uLS3egRG40IHqIQPHIsjSutvU8y5xL Njj/tLMcKkb15HZWuZFzflfPCy7+B8iPSh9ZgnfJgZh0Kw60IZroSrw4BgDeFiOsH3OI yuiAWyJ1pcGeBsx1rZieeM5ZlBicl0471NqKG4ALCHozh8MN0fiHKxVPnnaHmmkhpvdF tyM/kkDeSXNVDdI9OsrIJVAGF48h9ehJCDz5PH/O7naQnt5MFca9GG8GHFf00+hcu+eO KaehujKdOBagy0UPqXO5wxuhodsw9nST+n4coH1oZT18/NyAallpETLm8eWbEru5rcyD bxUg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1692985083; x=1693589883; h=cc:to:from:subject:message-id:mime-version:date:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=nW0lHbEH2B08cVP1PWHu98ltXXBWNNKQyHzU/WWXVBg=; b=cHE8D2AcpkVOf7tVYDvn7CGIsrW1hYhEMSlqjK/37qpZ0NodnNUWnhmltS8uXspGr7 1AlkJoWBk80vp6Uk+5hvKiE9+4KcUORyLQkVIR4aBfFk9r6lTigdsimRRiNNmHEYbL11 PEWdHh71lW8YArzvVkACpyIhN6ZmPBQnUQiGT8JmvDxs/D3CnMvzlvcBzBoBci7X/Eh8 QDJBEWdR20DqRmdi576FALCyGBRV1dqH/91jPZbbijzma8EPuMrLbHfbTb+BvNPqRhUZ Y/WeFSkEZHVM6/HGJBFeySZpbDOD9qG8Y5F5800JlSaGTtptHGqJ6cjit9WocLbD4Zr+ ByQw== X-Gm-Message-State: AOJu0YxQhS8XBB4uA6sSKRyQObOhF5JAU+lSBa94CzBs6hdOglRNd/oH pRCaHuql7niaoEGzN4MYI+6F5GzVx/DWQkFin/I= X-Google-Smtp-Source: AGHT+IHh4uVC5aH+i5xEI7dEkjUEt+yyAPTH2Q365Oe63akHuYT/y05k9vHwgZxXbnuGD7oaMh2+4z+0vlx0AQ24A5M= X-Received: from ndesaulniers-desktop.svl.corp.google.com ([2620:15c:2d1:203:dd9c:e8e8:b275:92e3]) (user=ndesaulniers job=sendgmr) by 2002:a25:3284:0:b0:d5d:6bfe:76d6 with SMTP id y126-20020a253284000000b00d5d6bfe76d6mr460590yby.8.1692985083762; Fri, 25 Aug 2023 10:38:03 -0700 (PDT) Date: Fri, 25 Aug 2023 10:38:01 -0700 Mime-Version: 1.0 X-B4-Tracking: v=1; b=H4sIAPjm6GQC/22MwQ7CIBAFf6XZsxiW0kI8+R/GQwtLS6LFgCGah n+X9qbxOC9vZoVE0VOCU7NCpOyTD0uF9tCAmYdlIuZtZRBctFwLyWwwiRlUQ2dJOeQt1OsjkvO vPXO5Vp59eob43qsZt/UnkJEh6xXxHoXSo3bnKYTpRkcT7rAVsvhniWppqYfR9R2ill9WKeUDw 9hoTs8AAAA= X-Developer-Key: i=ndesaulniers@google.com; a=ed25519; pk=eMOZeIQ4DYNKvsNmDNzVbQZqpdex34Aww3b8Ah957X4= X-Developer-Signature: v=1; a=ed25519-sha256; t=1692985082; l=9234; i=ndesaulniers@google.com; s=20230823; h=from:subject:message-id; bh=eNHemkeELfQC57dQP3CgrFEDRhCWp3y52DYMEFkhFy4=; b=dTfxeajlSMkHazbF+bce+tV9cZMKgDf0kPy8dBaNmvhbNxmmtqvJK15nn/4/QVVk0vgRK2He7 rdNI+uwdKIYBJF1kQqyy0w4Q/4IAJnbTNOadhGrkW+XCACgxHmjqN0q X-Mailer: b4 0.12.3 Message-ID: <20230825-docs-v3-1-384048d32a51@google.com> Subject: [PATCH v3] Documentation/llvm: refresh docs From: ndesaulniers@google.com To: Nathan Chancellor , Masahiro Yamada Cc: Tom Rix , Nicolas Schier , Jonathan Corbet , Paul Walmsley , Palmer Dabbelt , Albert Ou , llvm@lists.linux.dev, linux-kbuild@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, Nick Desaulniers Content-Type: text/plain; charset="utf-8" Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Transfer-Encoding: quoted-printable Recent fixes for an embargoed hardware security vulnerability failed to link with ld.lld (LLVM's linker). [0] To be fair, our documentation mentions ``CC=3Dclang`` foremost with ``LLVM=3D1`` being buried "below the fold." We want to encourage the use of ``LLVM=3D1`` rather than just ``CC=3Dclang``. Make that suggestion "above the fold" and "front and center" in our docs. While here, the following additional changes were made: - remove the bit about CROSS_COMPILE setting --target=3D, that's no longer true. - Add ARCH=3Dloongarch to the list of maintained targets (though we're still working on getting defconfig building cleanly at the moment; we're pretty close). - Bump ARCH=3Dpowerpc from CC=3Dclang to LLVM=3D1 status. - Promote ARCH=3Driscv from being Maintained to being Supported. Android is working towards supporting RISC-V, and we have excellent support from multiple companies in this regard. - Note that the toolchain distribution on kernel.org has been built with profile data from kernel builds. - Note how to use ccache with clang. Link: https://github.com/ClangBuiltLinux/linux/issues/1907 [0] Reviewed-by: Nathan Chancellor Signed-off-by: Nick Desaulniers --- Changes in v3: - Note why kernel.org toolchains are shiny. - Add note about ccache to doc and commit message. - Link to v2: https://lore.kernel.org/r/20230824-docs-v2-1-848abf651184@goo= gle.com Changes in v2: - Commit message changes: - Put SOB tag above the fold. - Mention PPC change in commit message. - Fix typos in commit message. - Add Nathan's RB tag to commit message. - Fix kernel doc warnings - Reword s390 example under `The LLVM=3D argument`. - Reword and add examples to `The LLVM_IAS=3D argument`. - Link to v1: https://lore.kernel.org/r/20230824-docs-v1-1-67e061278b8f@goo= gle.com --- Documentation/kbuild/llvm.rst | 124 +++++++++++++++++++++++++++-----------= ---- 1 file changed, 80 insertions(+), 44 deletions(-) diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index c3851fe1900d..384622dd36b7 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -25,50 +25,38 @@ objects `_. Clan= g is a front-end to LLVM that supports C and the GNU C extensions required by the kernel, and is pronounced "klang," not "see-lang." =20 -Clang ------ - -The compiler used can be swapped out via ``CC=3D`` command line argument t= o ``make``. -``CC=3D`` should be set when selecting a config and during a build. :: - - make CC=3Dclang defconfig - - make CC=3Dclang +Building with LLVM +------------------ =20 -Cross Compiling ---------------- +Invoke ``make`` via:: =20 -A single Clang compiler binary will typically contain all supported backen= ds, -which can help simplify cross compiling. :: - - make ARCH=3Darm64 CC=3Dclang CROSS_COMPILE=3Daarch64-linux-gnu- + make LLVM=3D1 =20 -``CROSS_COMPILE`` is not used to prefix the Clang compiler binary, instead -``CROSS_COMPILE`` is used to set a command line flag: ``--target=3D``. For -example: :: +to compile for the host target. For cross compiling:: =20 - clang --target=3Daarch64-linux-gnu foo.c + make LLVM=3D1 ARCH=3Darm64 =20 -LLVM Utilities --------------- +The LLVM=3D argument +------------------ =20 -LLVM has substitutes for GNU binutils utilities. They can be enabled indiv= idually. -The full list of supported make variables:: +LLVM has substitutes for GNU binutils utilities. They can be enabled +individually. The full list of supported make variables:: =20 make CC=3Dclang LD=3Dld.lld AR=3Dllvm-ar NM=3Dllvm-nm STRIP=3Dllvm-strip \ OBJCOPY=3Dllvm-objcopy OBJDUMP=3Dllvm-objdump READELF=3Dllvm-readelf \ HOSTCC=3Dclang HOSTCXX=3Dclang++ HOSTAR=3Dllvm-ar HOSTLD=3Dld.lld =20 -To simplify the above command, Kbuild supports the ``LLVM`` variable:: - - make LLVM=3D1 +``LLVM=3D1`` expands to the above. =20 If your LLVM tools are not available in your PATH, you can supply their location using the LLVM variable with a trailing slash:: =20 make LLVM=3D/path/to/llvm/ =20 -which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc. +which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc. The +following may also be used:: + + PATH=3D/path/to/llvm:$PATH make LLVM=3D1 =20 If your LLVM tools have a version suffix and you want to test with that explicit version rather than the unsuffixed executables like ``LLVM=3D1``,= you @@ -78,31 +66,72 @@ can pass the suffix using the ``LLVM`` variable:: =20 which will use ``clang-14``, ``ld.lld-14``, etc. =20 +To support combinations of out of tree paths with version suffixes, we +recommend:: + + PATH=3D/path/to/llvm/:$PATH make LLVM=3D-14 + ``LLVM=3D0`` is not the same as omitting ``LLVM`` altogether, it will beha= ve like -``LLVM=3D1``. If you only wish to use certain LLVM utilities, use their re= spective -make variables. +``LLVM=3D1``. If you only wish to use certain LLVM utilities, use their +respective make variables. + +The same value used for ``LLVM=3D`` should be set for each invocation of `= `make`` +if configuring and building via distinct commands. ``LLVM=3D`` should also= be set +as an environment variable when running scripts that will eventually run +``make``. =20 -The integrated assembler is enabled by default. You can pass ``LLVM_IAS=3D= 0`` to -disable it. +Cross Compiling +--------------- =20 -Omitting CROSS_COMPILE +A single Clang compiler binary (and corresponding LLVM utilities) will +typically contain all supported back ends, which can help simplify cross +compiling especially when ``LLVM=3D1`` is used. If you use only LLVM tools, +``CROSS_COMPILE`` or target-triple-prefixes become unnecessary. Example:: + + make LLVM=3D1 ARCH=3Darm64 + +As an example of mixing LLVM and GNU utilities, for a target like ``ARCH= =3Ds390`` +which does not yet have ``ld.lld`` or ``llvm-objcopy`` support, you could +invoke ``make`` via:: + + make LLVM=3D1 ARCH=3Ds390 LD=3Ds390x-linux-gnu-ld.bfd \ + OBJCOPY=3Ds390x-linux-gnu-objcopy + +This example will invoke ``s390x-linux-gnu-ld.bfd`` as the linker and +``s390x-linux-gnu-objcopy``, so ensure those are reachable in your ``$PATH= ``. + +``CROSS_COMPILE`` is not used to prefix the Clang compiler binary (or +corresponding LLVM utilities) as is the case for GNU utilities when ``LLVM= =3D1`` +is not set. + +The LLVM_IAS=3D argument ---------------------- =20 -As explained above, ``CROSS_COMPILE`` is used to set ``--target=3D= ``. +Clang can assemble assembler code. You can pass ``LLVM_IAS=3D0`` to disabl= e this +behavior and have Clang invoke the corresponding non-integrated assembler +instead. Example:: + + make LLVM=3D1 LLVM_IAS=3D0 + +``CROSS_COMPILE`` is necessary when cross compiling and ``LLVM_IAS=3D0`` +is used in order to set ``--prefix=3D`` for the compiler to find the +corresponding non-integrated assembler (typically, you don't want to use t= he +system assembler when targeting another architecture). Example:: =20 -If ``CROSS_COMPILE`` is not specified, the ``--target=3D`` is infe= rred -from ``ARCH``. + make LLVM=3D1 ARCH=3Darm LLVM_IAS=3D0 CROSS_COMPILE=3Darm-linux-gnueabi- =20 -That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessa= ry. =20 -For example, to cross-compile the arm64 kernel:: +Ccache +------ =20 - make ARCH=3Darm64 LLVM=3D1 +``ccache`` can be used with ``clang`` to improve subsequent builds, (though +KBUILD_BUILD_TIMESTAMP_ should be set to a deterministic value between bui= lds +in order to avoid 100% cache misses, see Reprocible_builds_ for more info): =20 -If ``LLVM_IAS=3D0`` is specified, ``CROSS_COMPILE`` is also used to derive -``--prefix=3D`` to search for the GNU assembler and linker. :: + KBUILD_BUILD_TIMESTAMP=3D'' make LLVM=3D1 CC=3D"ccache clang" =20 - make ARCH=3Darm64 LLVM=3D1 LLVM_IAS=3D0 CROSS_COMPILE=3Daarch64-linux-gnu- +.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp +.. _Reproducible_builds: reproducible-builds.html#timestamps =20 Supported Architectures ----------------------- @@ -135,14 +164,17 @@ yet. Bug reports are always welcome at the issue trac= ker below! * - hexagon - Maintained - ``LLVM=3D1`` + * - loongarch + - Maintained + - ``LLVM=3D1`` * - mips - Maintained - ``LLVM=3D1`` * - powerpc - Maintained - - ``CC=3Dclang`` + - ``LLVM=3D1`` * - riscv - - Maintained + - Supported - ``LLVM=3D1`` * - s390 - Maintained @@ -171,7 +203,11 @@ Getting Help Getting LLVM ------------- =20 -We provide prebuilt stable versions of LLVM on `kernel.org `_. +We provide prebuilt stable versions of LLVM on `kernel.org +`_. These have been optimized with pro= file +data for building Linux kernels, which should improve kernel build times +relative to other distributions of LLVM. + Below are links that may be useful for building LLVM from source or procur= ing it through a distribution's package manager. =20 --- base-commit: 93f5de5f648d2b1ce3540a4ac71756d4a852dc23 change-id: 20230824-docs-c17a5de7f103 Best regards, --=20 Nick Desaulniers