https://github.com/rnk updated https://github.com/llvm/llvm-project/pull/210209
>From 514d746b987add517cc0f5a8a0c94092d6d924a7 Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Thu, 16 Jul 2026 22:08:47 +0000 Subject: [PATCH 1/2] [docs] Convert selected rst docs with rst2myst --- compiler-rt/docs/ASanABI.md | 78 ++++--- compiler-rt/docs/BuildingCompilerRT.md | 53 +++-- compiler-rt/docs/TestingGuide.md | 70 +++--- flang/docs/CommandGuide/index.md | 82 +++---- libsycl/docs/CodingGuidelines.md | 42 ++-- libsycl/docs/index.md | 212 +++++++++--------- libunwind/docs/BuildingLibunwind.md | 84 ++++--- libunwind/docs/index.md | 90 ++++---- lldb/source/Plugins/TraceExporter/docs/htr.md | 36 +-- llvm-libgcc/docs/LLVMLibgcc.md | 151 ++++++------- offload/docs/index.md | 29 ++- 11 files changed, 467 insertions(+), 460 deletions(-) diff --git a/compiler-rt/docs/ASanABI.md b/compiler-rt/docs/ASanABI.md index 6fc2594f91ae9..eed765e69a354 100644 --- a/compiler-rt/docs/ASanABI.md +++ b/compiler-rt/docs/ASanABI.md @@ -1,51 +1,49 @@ -.. _BuildingCompilerRT: +(buildingcompilerrt)= -============================ -Darwin Sanitizers Stable ABI -============================ +# Darwin Sanitizers Stable ABI Some OSes like Darwin want to include the AddressSanitizer runtime by establishing a stable ASan ABI. lib/asan_abi contains a secondary stable ABI for Darwin use and potentially others. The Stable ABI has minimal impact on the community, prioritizing stability over performance. -The Stable ABI is isolated by a “shim” layer which maps the unstable ABI to the stable ABI. It consists of a static library (libclang_rt.asan_abi_osx.a) that contains simple mappings of the existing ASan ABI to the smaller Stable ABI. After linking with the static shim library, only calls to the Stable ABI remain. +The Stable ABI is isolated by a “shim” layer which maps the unstable ABI to the stable ABI. It consists of a static library (libclang_rt.asan_abi_osx.a) that contains simple mappings of the existing ASan ABI to the smaller Stable ABI. After linking with the static shim library, only calls to the Stable ABI remain. - Sample content of the shim: +> Sample content of the shim: +> +> ```c +> void __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); } +> void __asan_load2(uptr p) { __asan_abi_loadn(p, 2, true); } +> void __asan_noabort_load16(uptr p) { __asan_abi_loadn(p, 16, false); } +> void __asan_poison_cxx_array_cookie(uptr p) { __asan_abi_pac(p); } +> ``` - .. code-block:: c +The shim library is only used when `-fsanitize-stable-abi` is specified in the Clang driver and the emitted instrumentation favors runtime calls over inline expansion. - void __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); } - void __asan_load2(uptr p) { __asan_abi_loadn(p, 2, true); } - void __asan_noabort_load16(uptr p) { __asan_abi_loadn(p, 16, false); } - void __asan_poison_cxx_array_cookie(uptr p) { __asan_abi_pac(p); } - -The shim library is only used when ``-fsanitize-stable-abi`` is specified in the Clang driver and the emitted instrumentation favors runtime calls over inline expansion. - -Maintenance ------------ +## Maintenance The maintenance burden on the sanitizer developer community should be negligible. Stable ABI tests should always pass for non-Darwin platforms. Changes to the existing ABI requiring changes to the shim should been infrequent as the existing ASan ABI has long been relatively stable anyway. Rarely, when a change that impacts the contract between LLVM and the shim occurs, some simple responses should suffice. Among such foreseeable changes are: 1) changes to a function signature, 2) additions of new functions, or 3) deprecation of an existing function. - Following are some examples of reasonable responses to such changes: - - * An existing ABI function is changed to return the input parameter on success or NULL on failure. In this scenario, a reasonable change to the shim would be to modify the function signature appropriately and to simply guess at a common-sense implementation. - - .. code-block:: c - - uptr __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); return p; } - - * An additional function is added for performance reasons. It has a very similar function signature to other similarly named functions and logically is an extension of that same pattern. In this case it would make sense to apply the same logic as the existing entry points: - - .. code-block:: c - - void __asan_load128(uptr p) { __asan_abi_loadn(p, 128, true); } - - * An entry point is added to the existing ABI for which there is no obvious stable ABI implementation: In this case, doing nothing in a no-op stub would be acceptable, assuming existing features of ASan can still work without an actual implementation of this new function. - - .. code-block:: c - - void __asan_prefetch(uptr p) { } - - * An entrypoint in the existing ABI is deprecated and/or deleted: - - .. code-block:: c +> Following are some examples of reasonable responses to such changes: +> +> - An existing ABI function is changed to return the input parameter on success or NULL on failure. In this scenario, a reasonable change to the shim would be to modify the function signature appropriately and to simply guess at a common-sense implementation. +> +> ```c +> uptr __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); return p; } +> ``` +> +> - An additional function is added for performance reasons. It has a very similar function signature to other similarly named functions and logically is an extension of that same pattern. In this case it would make sense to apply the same logic as the existing entry points: +> +> ```c +> void __asan_load128(uptr p) { __asan_abi_loadn(p, 128, true); } +> ``` +> +> - An entry point is added to the existing ABI for which there is no obvious stable ABI implementation: In this case, doing nothing in a no-op stub would be acceptable, assuming existing features of ASan can still work without an actual implementation of this new function. +> +> ```c +> void __asan_prefetch(uptr p) { } +> ``` +> +> - An entrypoint in the existing ABI is deprecated and/or deleted: +> +> ```c +> (Delete the entrypoint from the shim.) +> ``` - (Delete the entrypoint from the shim.) diff --git a/compiler-rt/docs/BuildingCompilerRT.md b/compiler-rt/docs/BuildingCompilerRT.md index 98f54ae444123..133275ef0cee2 100644 --- a/compiler-rt/docs/BuildingCompilerRT.md +++ b/compiler-rt/docs/BuildingCompilerRT.md @@ -1,13 +1,12 @@ -.. _BuildingCompilerRT: +(buildingcompilerrt)= -=============== -Building Compiler-RT -=============== +# Building Compiler-RT -.. contents:: - :local: +```{contents} +:local: true +``` -.. _build instructions: +(build-instructions)= The instructions on this page are aimed at vendors who ship Compiler-RT as part of an operating system distribution, a toolchain or similar shipping vehicles. If you @@ -15,31 +14,32 @@ are a user merely trying to use Compiler-RT in your program, you most likely wan refer to your vendor's documentation, or to the general documentation for using LLVM, Clang, the various santizers, etc. -CMake Options -============= +## CMake Options Here are some of the CMake variables that are used often, along with a brief explanation and LLVM-specific notes. For full documentation, check the -CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. +CMake docs or execute `cmake --help-variable VARIABLE_NAME`. **CMAKE_BUILD_TYPE**:STRING - Sets the build type for ``make`` based generators. Possible values are + +: Sets the build type for `make` based generators. Possible values are Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio the user sets the build type with the IDE settings. **CMAKE_INSTALL_PREFIX**:PATH - Path where LLVM will be installed if "make install" is invoked or the + +: Path where LLVM will be installed if "make install" is invoked or the "INSTALL" target is built. **CMAKE_CXX_COMPILER**:STRING - The C++ compiler to use when building and testing Compiler-RT. +: The C++ compiler to use when building and testing Compiler-RT. -.. _compiler-rt-specific options: +(compiler-rt-specific-options)= -Compiler-RT specific options ------------------------ +### Compiler-RT specific options +`````{eval-rst} .. option:: COMPILER_RT_INSTALL_PATH:PATH **Default**: ```` (empty relative path) @@ -51,42 +51,54 @@ Compiler-RT specific options ``-DCOMPILER_RT_INSTALL_PATH:PATH=...`` not ``-DCOMPILER_RT_INSTALL_PATH=...``, otherwise CMake will convert the path to an absolute path. +````` +```{eval-rst} .. option:: COMPILER_RT_INSTALL_LIBRARY_DIR:PATH **Default**: ``lib`` Path where built Compiler-RT libraries should be installed. If a relative path, relative to ``COMPILER_RT_INSTALL_PATH``. +``` +```{eval-rst} .. option:: COMPILER_RT_INSTALL_BINARY_DIR:PATH **Default**: ``bin`` Path where built Compiler-RT executables should be installed. If a relative path, relative to ``COMPILER_RT_INSTALL_PATH``. +``` +```{eval-rst} .. option:: COMPILER_RT_INSTALL_INCLUDE_DIR:PATH **Default**: ``include`` Path where Compiler-RT headers should be installed. If a relative path, relative to ``COMPILER_RT_INSTALL_PATH``. +``` +```{eval-rst} .. option:: COMPILER_RT_INSTALL_DATA_DIR:PATH **Default**: ``share`` Path where Compiler-RT data should be installed. If a relative path, relative to ``COMPILER_RT_INSTALL_PATH``. +``` +```{eval-rst} .. option:: COMPILER_RT_INCLUDE_TESTS:BOOL **Default**: ``LLVM_INCLUDE_TESTS`` in LLVM builds, ``OFF`` in standalone builds. Generate and build compiler-rt tests. If ``OFF``, ``COMPILER_RT_ENABLE_TEST_SUITES`` has no effect. +``` +```{eval-rst} .. option:: COMPILER_RT_ENABLE_TEST_SUITES:STRING **Default**: ``all`` @@ -94,14 +106,17 @@ Compiler-RT specific options Semicolon-separated list of test suites to enable, or ``all`` to enable all test suites. Example: ``-DCOMPILER_RT_ENABLE_TEST_SUITES="asan;ubsan;lsan"`` +``` -.. _LLVM-specific variables: +(llvm-specific-variables)= -LLVM-specific options ---------------------- +### LLVM-specific options +```{eval-rst} .. option:: LLVM_LIBDIR_SUFFIX:STRING Extra suffix to append to the directory where libraries are to be installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` to install libraries to ``/usr/lib64``. +``` + diff --git a/compiler-rt/docs/TestingGuide.md b/compiler-rt/docs/TestingGuide.md index a1419ede02fed..d008c55cd9711 100644 --- a/compiler-rt/docs/TestingGuide.md +++ b/compiler-rt/docs/TestingGuide.md @@ -1,67 +1,65 @@ -======================================== -Compiler-rt Testing Infrastructure Guide -======================================== +# Compiler-rt Testing Infrastructure Guide -.. contents:: - :local: +```{contents} +:local: true +``` -Overview -======== +## Overview This document is the reference manual for the compiler-rt modifications to the testing infrastructure. Documentation for the infrastructure itself can be found at -:ref:`llvm_testing_guide`. +{ref}`llvm_testing_guide`. -LLVM testing infrastructure organization -======================================== +## LLVM testing infrastructure organization The compiler-rt testing infrastructure contains regression tests which are run -as part of the usual ``make check-all`` and are expected to always pass -- they +as part of the usual `make check-all` and are expected to always pass -- they should be run before every commit. -Quick start -=========== +## Quick start The regressions tests are in the "compiler-rt" module and are normally checked -out in the directory ``llvm/projects/compiler-rt/test``. Use ``make check-all`` +out in the directory `llvm/projects/compiler-rt/test`. Use `make check-all` to run the regression tests after building compiler-rt. -REQUIRES, XFAIL, etc. ---------------------- +### REQUIRES, XFAIL, etc. Sometimes it is necessary to restrict a test to a specific target or mark it as -an "expected fail" or XFAIL. This is normally achieved using ``REQUIRES:`` or -``XFAIL:`` and the ``target=<target-triple>`` feature, typically with a regular +an "expected fail" or XFAIL. This is normally achieved using `REQUIRES:` or +`XFAIL:` and the `target=<target-triple>` feature, typically with a regular expression matching an appropriate substring of the triple. Unfortunately, the behaviour of this is somewhat quirky in compiler-rt. There are two main pitfalls to avoid. The first pitfall is that these regular expressions may inadvertently match -more triples than expected. For example, ``XFAIL: target=mips{{.*}}`` matches -``mips-linux-gnu``, ``mipsel-linux-gnu``, ``mips64-linux-gnu``, and -``mips64el-linux-gnu``. Including a trailing ``-`` such as in -``XFAIL: target=mips-{{.*}}`` can help to mitigate this quirk but even that has +more triples than expected. For example, `XFAIL: target=mips{{.*}}` matches +`mips-linux-gnu`, `mipsel-linux-gnu`, `mips64-linux-gnu`, and +`mips64el-linux-gnu`. Including a trailing `-` such as in +`XFAIL: target=mips-{{.*}}` can help to mitigate this quirk but even that has issues as described below. The second pitfall is that the default target triple is often inappropriate for compiler-rt tests since compiler-rt tests may be compiled for multiple targets. -For example, a typical build on an ``x86_64-linux-gnu`` host will often run the -tests for both x86_64 and i386. In this situation ``XFAIL: target=x86_64{{{.*}}`` -will mark both the x86_64 and i386 tests as an expected failure while -``XFAIL: target=i386{{.*}}`` will have no effect at all. +For example, a typical build on an `x86_64-linux-gnu` host will often run the +tests for both x86_64 and i386. In this situation `XFAIL: target=x86_64{{{.*}}` +will mark both the x86_64 and i386 tests as an expected failure while +`XFAIL: target=i386{{.*}}` will have no effect at all. To remedy both pitfalls, compiler-rt tests provide a feature string which can be used to specify a single target. This string is of the form -``target-is-${arch}`` where ``${arch}}`` is one of the values from the -following lines of the CMake output:: +`target-is-${arch}` where `${arch}}` is one of the values from the +following lines of the CMake output: - -- Compiler-RT supported architectures: x86_64;i386 - -- Builtin supported architectures: i386;x86_64 +``` +-- Compiler-RT supported architectures: x86_64;i386 +-- Builtin supported architectures: i386;x86_64 +``` -So for example ``XFAIL: target-is-x86_64`` will mark a test as expected to fail -on x86_64 without also affecting the i386 test and ``XFAIL: target-is-i386`` +So for example `XFAIL: target-is-x86_64` will mark a test as expected to fail +on x86_64 without also affecting the i386 test and `XFAIL: target-is-i386` will mark a test as expected to fail on i386 even if the default target triple -is ``x86_64-linux-gnu``. Directives that use these ``target-is-${arch}`` string -require exact matches so ``XFAIL: target-is-mips``, -``XFAIL: target-is-mipsel``, ``XFAIL: target-is-mips64``, and -``XFAIL: target-is-mips64el`` all refer to different MIPS targets. +is `x86_64-linux-gnu`. Directives that use these `target-is-${arch}` string +require exact matches so `XFAIL: target-is-mips`, +`XFAIL: target-is-mipsel`, `XFAIL: target-is-mips64`, and +`XFAIL: target-is-mips64el` all refer to different MIPS targets. + diff --git a/flang/docs/CommandGuide/index.md b/flang/docs/CommandGuide/index.md index 1ba97464242e4..32b7c48f75df5 100644 --- a/flang/docs/CommandGuide/index.md +++ b/flang/docs/CommandGuide/index.md @@ -1,63 +1,67 @@ -flang - the Flang Fortran compiler -================================== +# flang - the Flang Fortran compiler -SYNOPSIS --------- +## SYNOPSIS -:program:`flang` [*options*] *filename ...* +{program}`flang` \[*options*\] *filename ...* -DESCRIPTION ------------ +## DESCRIPTION -:program:`flang` is a Fortran compiler which supports all of the Fortran 95 and +{program}`flang` is a Fortran compiler which supports all of the Fortran 95 and many newer language features. Flang supports OpenMP and has some support for OpenACC and CUDA. It encompasses preprocessing, parsing, optimization, code -generation, assembly, and linking. Depending on the options passed in, Flang +generation, assembly, and linking. Depending on the options passed in, Flang will perform only some, or all, of these actions. While Flang is highly integrated, it is important to understand the stages of compilation in order to -understand how to invoke it. These stages are: +understand how to invoke it. These stages are: Driver - The flang executable is actually a small driver that orchestrates the - execution of other tools such as the compiler, assembler and linker. - Typically you do not need to interact with the driver, but you - transparently use it to run the other tools. + +: The flang executable is actually a small driver that orchestrates the + execution of other tools such as the compiler, assembler and linker. + Typically you do not need to interact with the driver, but you + transparently use it to run the other tools. Preprocessing - This stage performs tokenization of the input source file, macro expansion, - #include expansion and handles other preprocessor directives. + +: This stage performs tokenization of the input source file, macro expansion, + #include expansion and handles other preprocessor directives. Parsing and Semantic Analysis - This stage parses the input file, translating preprocessor tokens into a - parse tree. Once in the form of a parse tree, it applies semantic - analysis to compute types for expressions and determine whether - the code is well formed. Parse errors and most compiler warnings - are generated by this stage. + +: This stage parses the input file, translating preprocessor tokens into a + parse tree. Once in the form of a parse tree, it applies semantic + analysis to compute types for expressions and determine whether + the code is well formed. Parse errors and most compiler warnings + are generated by this stage. Code Generation and Optimization - This stage translates the parse tree into intermediate code (known as - "LLVM IR") and, ultimately, machine code. It also optimizes this - intermediate code and handles target-specific code generation. The output - of this stage is typically a ".s" file, referred to as an "assembly" file. - Flang also supports the use of an integrated assembler, in which the code - generator produces object files directly. This avoids the overhead of - generating the ".s" file and calling the target assembler explicitly. +: This stage translates the parse tree into intermediate code (known as + "LLVM IR") and, ultimately, machine code. It also optimizes this + intermediate code and handles target-specific code generation. The output + of this stage is typically a ".s" file, referred to as an "assembly" file. + + Flang also supports the use of an integrated assembler, in which the code + generator produces object files directly. This avoids the overhead of + generating the ".s" file and calling the target assembler explicitly. Assembler - This stage runs the target assembler to translate the output of the - compiler into a target object file. The output of this stage is typically - a ".o" file, referred to as an "object" file. + +: This stage runs the target assembler to translate the output of the + compiler into a target object file. The output of this stage is typically + a ".o" file, referred to as an "object" file. Linker - This stage runs the target linker to merge multiple object files into an - executable or dynamic library. The output of this stage is typically - an "a.out", ".dylib" or ".so" file. -OPTIONS -------- +: This stage runs the target linker to merge multiple object files into an + executable or dynamic library. The output of this stage is typically + an "a.out", ".dylib" or ".so" file. + +## OPTIONS + +```{toctree} +:maxdepth: 1 -.. toctree:: - :maxdepth: 1 +FlangCommandLineOptions +``` - FlangCommandLineOptions diff --git a/libsycl/docs/CodingGuidelines.md b/libsycl/docs/CodingGuidelines.md index 7aece05a3e50b..8decbe4e76828 100644 --- a/libsycl/docs/CodingGuidelines.md +++ b/libsycl/docs/CodingGuidelines.md @@ -1,39 +1,33 @@ -======================== -Libsycl Coding Standards -======================== +# Libsycl Coding Standards -.. contents:: - :local: +```{contents} +:local: true +``` -Introduction -============ +## Introduction -The ``libsycl`` project follows the -`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_ with +The `libsycl` project follows the +[LLVM Coding Standards](https://llvm.org/docs/CodingStandards.html) with exceptions as described in this document. -Naming ------- +### Naming -Names of Macros, Types, Functions, Variables, and Enumerators -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +#### Names of Macros, Types, Functions, Variables, and Enumerators Entities specified by the SYCL specification are named as required by the SYCL specification. Names of all other entities follow the guidance in the LLVM Coding Standards. -Names of Files and Directories -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +#### Names of Files and Directories -* **Directory Names** should be in snake case (e.g. ``test_e2e``) except in +- **Directory Names** should be in snake case (e.g. `test_e2e`) except in cases where LLVM project wide conventions are used. For example, LIT tests - often use an ``Inputs`` directory to hold files that are used by tests but + often use an `Inputs` directory to hold files that are used by tests but that should be excluded from test discovery. - -* **File Names in snake case** should be used for all C++ implementation files. - For example files in directories ``include``, ``src``, ``test``, ``utils``, - and ``tools`` should be named in snake case. - -* **File Names in camel case** should be used for most other files. For example - files in directories ``cmake/modules`` and ``docs`` should be named in camel +- **File Names in snake case** should be used for all C++ implementation files. + For example files in directories `include`, `src`, `test`, `utils`, + and `tools` should be named in snake case. +- **File Names in camel case** should be used for most other files. For example + files in directories `cmake/modules` and `docs` should be named in camel case. + diff --git a/libsycl/docs/index.md b/libsycl/docs/index.md index aa23be0138a48..19cc14e7c1de2 100644 --- a/libsycl/docs/index.md +++ b/libsycl/docs/index.md @@ -1,140 +1,148 @@ -=========================== -SYCL runtime implementation -=========================== +# SYCL runtime implementation -.. contents:: - :local: +```{contents} +:local: true +``` -.. _index: +(index)= -Current Status -============== +## Current Status The implementation is in the very early stages of upstreaming. The first milestone is to get support for a simple SYCL application with device code using Unified Shared Memory: -.. code-block:: c++ - - #include <sycl/sycl.hpp> - - class TestKernel; - - int main() { - sycl::queue q; - - const size_t dataSize = 32; - int *dataPtr = sycl::malloc_shared<int>(32, q); - for (int i = 0; i < dataSize; ++i) - dataPtr[i] = 0; - - q.submit([&](sycl::handler &cgh) { - cgh.parallel_for<TestKernel>( - sycl::range<1>(dataSize), - [=](sycl::id<1> idx) { dataPtr[idx] = idx[0]; }); - }); - q.wait(); - - bool error = false; - for (int i = 0; i < dataSize; ++i) - if (dataPtr[i] != i) error = true; - - free(dataPtr, q); - - return error; - } +```c++ +#include <sycl/sycl.hpp> + +class TestKernel; + +int main() { + sycl::queue q; + + const size_t dataSize = 32; + int *dataPtr = sycl::malloc_shared<int>(32, q); + for (int i = 0; i < dataSize; ++i) + dataPtr[i] = 0; + + q.submit([&](sycl::handler &cgh) { + cgh.parallel_for<TestKernel>( + sycl::range<1>(dataSize), + [=](sycl::id<1> idx) { dataPtr[idx] = idx[0]; }); + }); + q.wait(); + + bool error = false; + for (int i = 0; i < dataSize; ++i) + if (dataPtr[i] != i) error = true; + + free(dataPtr, q); + + return error; +} +``` This requires at least partial support of the following functionality on the libsycl side: -* ``sycl::platform`` class -* ``sycl::device`` class -* ``sycl::context`` class -* ``sycl::queue`` class -* ``sycl::handler`` class -* ``sycl::id`` and ``sycl::range`` classes -* Unified shared memory allocation/deallocation -* Program manager, an internal component for retrieving and using device images +- `sycl::platform` class +- `sycl::device` class +- `sycl::context` class +- `sycl::queue` class +- `sycl::handler` class +- `sycl::id` and `sycl::range` classes +- Unified shared memory allocation/deallocation +- Program manager, an internal component for retrieving and using device images from the multi-architectural binaries -Build steps -=========== +## Build steps To build LLVM with libsycl runtime enabled the following script can be used. -.. code-block:: console - - #!/bin/sh - - build_llvm=`pwd`/build-llvm - installprefix=`pwd`/install - llvm=`pwd` - mkdir -p $build_llvm - mkdir -p $installprefix +```console +#!/bin/sh - cmake -G Ninja -S $llvm/llvm -B $build_llvm \ - -DLLVM_ENABLE_PROJECTS="clang" \ - -DLLVM_INSTALL_UTILS=ON \ - -DCMAKE_INSTALL_PREFIX=$installprefix \ - -DLLVM_ENABLE_RUNTIMES="offload;openmp;libsycl" \ - -DCMAKE_BUILD_TYPE=Release \ - # must be default and configured in liboffload, - # requires level zero, see offload/cmake/Modules/LibomptargetGetDependencies.cmake - -DLIBOMPTARGET_PLUGINS_TO_BUILD=level_zero +build_llvm=`pwd`/build-llvm +installprefix=`pwd`/install +llvm=`pwd` +mkdir -p $build_llvm +mkdir -p $installprefix - ninja -C $build_llvm install +cmake -G Ninja -S $llvm/llvm -B $build_llvm \ + -DLLVM_ENABLE_PROJECTS="clang" \ + -DLLVM_INSTALL_UTILS=ON \ + -DCMAKE_INSTALL_PREFIX=$installprefix \ + -DLLVM_ENABLE_RUNTIMES="offload;openmp;libsycl" \ + -DCMAKE_BUILD_TYPE=Release \ + # must be default and configured in liboffload, + # requires level zero, see offload/cmake/Modules/LibomptargetGetDependencies.cmake + -DLIBOMPTARGET_PLUGINS_TO_BUILD=level_zero +ninja -C $build_llvm install +``` -Limitations -=========== +## Limitations Libsycl is not currently supported on Windows because it depends on liboffload which doesn't currently support Windows. -TODO for added SYCL classes -=========================== +## TODO for added SYCL classes + +- `exception`: methods with context are not implemented, to add once context is ready + +- `platform`: deprecated info descriptor is not implemented (<info::platform::extensions>), to implement on RT level with `device::get_info<info::device::aspects>()` + +- `device`: + + - `get_info`: to find an efficient way to map descriptors to liboffload types, add other descriptors, add cache of info data + - `has(aspect)`: same as get_info + - `create_sub_devices`: partitioning is not supported by liboffload now, blocked + - `has_extension`: deprecated API, to implement on RT level with `device::has` + +- device selection: to add compatibility with old SYCL 1.2.1 device selectors, still part of SYCL 2020 specification + +- `context`: to implement get_info, properties & public constructors once context support is added to liboffload + +- `queue`: + + - to implement USM methods + + - `memcpy`: enable the host-to-host case (blocked by liboffload limitations) + + - to implement synchronization methods + + - to implement submit & copy with accessors (low priority) + + - get_info & properties + + - ctors that accepts context (blocked by lack of liboffload support) + + - nd_range kernel submissions: offset is not supported by liboffload now, SYCL2020 deprecated feature -* ``exception``: methods with context are not implemented, to add once context is ready -* ``platform``: deprecated info descriptor is not implemented (info::platform::extensions), to implement on RT level with ``device::get_info<info::device::aspects>()`` -* ``device``: + - cross-context events wait (host tasks are needed) - * ``get_info``: to find an efficient way to map descriptors to liboffload types, add other descriptors, add cache of info data - * ``has(aspect)``: same as get_info - * ``create_sub_devices``: partitioning is not supported by liboffload now, blocked - * ``has_extension``: deprecated API, to implement on RT level with ``device::has`` + - implement check if lambda arguments are device copyable (requires clang support of corresponding builtins) unless FE will fully cover it -* device selection: to add compatibility with old SYCL 1.2.1 device selectors, still part of SYCL 2020 specification -* ``context``: to implement get_info, properties & public constructors once context support is added to liboffload -* ``queue``: + - kernel instantiating on host (debugging purposes) - * to implement USM methods +- `property_list`: to fully implement and integrate with existing SYCL runtime classes supporting it - * ``memcpy``: enable the host-to-host case (blocked by liboffload limitations) +- usm allocations: - * to implement synchronization methods - * to implement submit & copy with accessors (low priority) - * get_info & properties - * ctors that accepts context (blocked by lack of liboffload support) - * nd_range kernel submissions: offset is not supported by liboffload now, SYCL2020 deprecated feature - * cross-context events wait (host tasks are needed) - * implement check if lambda arguments are device copyable (requires clang support of corresponding builtins) unless FE will fully cover it - * kernel instantiating on host (debugging purposes) + - add aligned functions (blocked by liboffload support) + - forward templated funcs to alignment methods (rewrite current impl) + - handle sub devices once they are implemented (blocked by liboffload support) -* ``property_list``: to fully implement and integrate with existing SYCL runtime classes supporting it -* usm allocations: +- `event`: - * add aligned functions (blocked by liboffload support) - * forward templated funcs to alignment methods (rewrite current impl) - * handle sub devices once they are implemented (blocked by liboffload support) + - get_info, get_profiling_info (no liboffload support) are not implemented + - get_wait_list should be aligned with the results of this discussion: <https://github.com/KhronosGroup/SYCL-Docs/issues/1017> -* ``event``: +- `range`, `id` - \_\_SYCL_DISABLE_ID_TO_INT_CONV\_\_ and \_\_SYCL_ASSUME_ID_RANGE optimizations are not implemented - * get_info, get_profiling_info (no liboffload support) are not implemented - * get_wait_list should be aligned with the results of this discussion: https://github.com/KhronosGroup/SYCL-Docs/issues/1017 +- general opens: -* ``range``, ``id`` - __SYCL_DISABLE_ID_TO_INT_CONV__ and __SYCL_ASSUME_ID_RANGE optimizations are not implemented -* general opens: + - define a way to report errors from object dtors + - unittests: add functions to reset libsycl internal state completely (static variables) - * define a way to report errors from object dtors - * unittests: add functions to reset libsycl internal state completely (static variables) diff --git a/libunwind/docs/BuildingLibunwind.md b/libunwind/docs/BuildingLibunwind.md index c231587fd5022..3bc831d3c906f 100644 --- a/libunwind/docs/BuildingLibunwind.md +++ b/libunwind/docs/BuildingLibunwind.md @@ -1,16 +1,14 @@ -.. _BuildingLibunwind: +(buildinglibunwind)= -================== -Building libunwind -================== +# Building libunwind -.. contents:: - :local: +```{contents} +:local: true +``` -.. _build instructions: +(build-instructions)= -Getting Started -=============== +## Getting Started On Mac OS, the easiest way to get this library is to link with -lSystem. However if you want to build tip-of-trunk from here (getting the bleeding @@ -18,116 +16,134 @@ edge), read on. The basic steps needed to build libunwind are: -#. Checkout LLVM, libunwind, and related projects: +1. Checkout LLVM, libunwind, and related projects: - * ``cd where-you-want-llvm-to-live`` - * ``git clone https://github.com/llvm/llvm-project.git`` + - `cd where-you-want-llvm-to-live` + - `git clone https://github.com/llvm/llvm-project.git` -#. Configure and build libunwind: +2. Configure and build libunwind: CMake is the only supported configuration system. Clang is the preferred compiler when building and using libunwind. - * ``cd where you want to build llvm`` - * ``mkdir build`` - * ``cd build`` - * ``cmake -G <generator> -DLLVM_ENABLE_RUNTIMES=libunwind [options] <llvm-monorepo>/runtimes`` + - `cd where you want to build llvm` + - `mkdir build` + - `cd build` + - `cmake -G <generator> -DLLVM_ENABLE_RUNTIMES=libunwind [options] <llvm-monorepo>/runtimes` - For more information about configuring libunwind see :ref:`CMake Options`. + For more information about configuring libunwind see {ref}`CMake Options`. - * ``make unwind`` --- will build libunwind. - * ``make check-unwind`` --- will run the test suite. + - `make unwind` --- will build libunwind. + - `make check-unwind` --- will run the test suite. Shared and static libraries for libunwind should now be present in llvm/build/lib. -#. **Optional**: Install libunwind +3. **Optional**: Install libunwind If your system already provides an unwinder, it is important to be careful - not to replace it. Remember Use the CMake option ``CMAKE_INSTALL_PREFIX`` to + not to replace it. Remember Use the CMake option `CMAKE_INSTALL_PREFIX` to select a safe place to install libunwind. - * ``make install-unwind`` --- Will install the libraries and the headers + - `make install-unwind` --- Will install the libraries and the headers +(cmake-options)= -.. _CMake Options: - -CMake Options -============= +## CMake Options Here are some of the CMake variables that are used often, along with a brief explanation and LLVM-specific notes. For full documentation, check the -CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. +CMake docs or execute `cmake --help-variable VARIABLE_NAME`. **CMAKE_BUILD_TYPE**:STRING - Sets the build type for ``make`` based generators. Possible values are + +: Sets the build type for `make` based generators. Possible values are Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio the user sets the build type with the IDE settings. **CMAKE_INSTALL_PREFIX**:PATH - Path where LLVM will be installed if "make install" is invoked or the + +: Path where LLVM will be installed if "make install" is invoked or the "INSTALL" target is built. **CMAKE_CXX_COMPILER**:STRING - The C++ compiler to use when building and testing libunwind. +: The C++ compiler to use when building and testing libunwind. -.. _libunwind-specific options: +(libunwind-specific-options)= -libunwind specific options --------------------------- +### libunwind specific options +```{eval-rst} .. option:: LIBUNWIND_ENABLE_ASSERTIONS:BOOL **Default**: ``ON`` Toggle assertions independent of the build mode. +``` +```{eval-rst} .. option:: LIBUNWIND_ENABLE_PEDANTIC:BOOL **Default**: ``ON`` Compile with -Wpedantic. +``` +```{eval-rst} .. option:: LIBUNWIND_ENABLE_WERROR:BOOL **Default**: ``OFF`` Compile with -Werror +``` +```{eval-rst} .. option:: LIBUNWIND_ENABLE_SHARED:BOOL **Default**: ``ON`` Build libunwind as a shared library. +``` +```{eval-rst} .. option:: LIBUNWIND_ENABLE_STATIC:BOOL **Default**: ``ON`` Build libunwind as a static archive. +``` +```{eval-rst} .. option:: LIBUNWIND_ENABLE_CROSS_UNWINDING:BOOL **Default**: ``OFF`` Enable cross-platform unwinding support. +``` +```{eval-rst} .. option:: LIBUNWIND_ENABLE_ARM_WMMX:BOOL **Default**: ``OFF`` Enable unwinding support for ARM WMMX registers. +``` +```{eval-rst} .. option:: LIBUNWIND_ENABLE_THREADS:BOOL **Default**: ``ON`` Build libunwind with threading support. +``` +```{eval-rst} .. option:: LIBUNWIND_INSTALL_LIBRARY_DIR:PATH **Default**: ``lib${LIBUNWIND_LIBDIR_SUFFIX}`` Path where built libunwind libraries should be installed. If a relative path, relative to ``CMAKE_INSTALL_PREFIX``. +``` + diff --git a/libunwind/docs/index.md b/libunwind/docs/index.md index 0354246401146..f9e7fe9de134b 100644 --- a/libunwind/docs/index.md +++ b/libunwind/docs/index.md @@ -1,11 +1,8 @@ -.. _index: +(index)= -======================= -libunwind LLVM Unwinder -======================= +# libunwind LLVM Unwinder -Overview -======== +## Overview libunwind is an implementation of the interface defined by the HP libunwind project. It was contributed by Apple as a way to enable clang++ to port to @@ -18,16 +15,15 @@ functions which implement functionality required by `__cxa_*` exception functions. The low level APIs are the `unw_*` functions which are an interface defined by the old HP libunwind project. -Getting Started with libunwind ------------------------------- +### Getting Started with libunwind -.. toctree:: - :maxdepth: 2 +```{toctree} +:maxdepth: 2 - BuildingLibunwind +BuildingLibunwind +``` -Current Status --------------- +### Current Status libunwind is a production-quality unwinder, with platform support for DWARF unwind info, SjLj, and ARM EHABI. @@ -36,66 +32,60 @@ The low level libunwind API was designed to work either in-process (aka local) or to operate on another process (aka remote), but only the local path has been implemented. Remote unwinding remains as future work. -Platform and Compiler Support ------------------------------ +### Platform and Compiler Support libunwind is known to work on the following platforms: -============ ======================== ============ ======================== -OS Arch Compilers Unwind Info -============ ======================== ============ ======================== -Any i386, x86_64, ARM Clang SjLj -Bare Metal ARM Clang, GCC EHABI -FreeBSD i386, x86_64, ARM64 Clang DWARF CFI -iOS ARM Clang SjLj -Linux ARM Clang, GCC EHABI -Linux i386, x86_64, ARM64 Clang, GCC DWARF CFI -macOS i386, x86_64 Clang, GCC DWARF CFI -NetBSD x86_64 Clang, GCC DWARF CFI -Windows i386, x86_64, ARM, ARM64 Clang DWARF CFI -============ ======================== ============ ======================== +| OS | Arch | Compilers | Unwind Info | +| ---------- | ------------------------ | ---------- | ----------- | +| Any | i386, x86_64, ARM | Clang | SjLj | +| Bare Metal | ARM | Clang, GCC | EHABI | +| FreeBSD | i386, x86_64, ARM64 | Clang | DWARF CFI | +| iOS | ARM | Clang | SjLj | +| Linux | ARM | Clang, GCC | EHABI | +| Linux | i386, x86_64, ARM64 | Clang, GCC | DWARF CFI | +| macOS | i386, x86_64 | Clang, GCC | DWARF CFI | +| NetBSD | x86_64 | Clang, GCC | DWARF CFI | +| Windows | i386, x86_64, ARM, ARM64 | Clang | DWARF CFI | The following minimum compiler versions are strongly recommended. -* Clang 3.5 and above -* GCC 4.7 and above. +- Clang 3.5 and above +- GCC 4.7 and above. Anything older *may* work. -Notes and Known Issues ----------------------- +### Notes and Known Issues -* TODO +- TODO +## Getting Involved -Getting Involved -================ - -First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__ -and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__. +First please review our [Developer's Policy](https://llvm.org/docs/DeveloperPolicy.html) +and [Getting started with LLVM](https://llvm.org/docs/GettingStarted.html). **Bug Reports** If you think you've found a bug in libunwind, please report it using -the `LLVM bug tracker`_. If you're not sure, you -can ask for support on the `Runtimes forum`_ or on Discord. +the [LLVM bug tracker]. If you're not sure, you +can ask for support on the [Runtimes forum] or on Discord. Please use the tag "libunwind" for new threads. **Patches** If you want to contribute a patch to libunwind, please start by reading the LLVM -`documentation about contributing <https://www.llvm.org/docs/Contributing.html>`__. +[documentation about contributing](https://www.llvm.org/docs/Contributing.html). **Discussion and Questions** -Send discussions and questions to the `Runtimes forum`_. Please add the tag "libunwind" to your post. +Send discussions and questions to the [Runtimes forum]. Please add the tag "libunwind" to your post. + +## Quick Links +- [LLVM Homepage](https://llvm.org/) +- [LLVM Bug Tracker](https://github.com/llvm/llvm-project/labels/libunwind/) +- [Clang Discourse Forums](https://discourse.llvm.org/c/clang/6) +- [cfe-commits Mailing List](http://lists.llvm.org/mailman/listinfo/cfe-commits) +- [Runtimes Forum](https://discourse.llvm.org/tags/c/runtimes) +- [Browse libunwind Sources](https://github.com/llvm/llvm-project/blob/main/libunwind/) -Quick Links -=========== -* `LLVM Homepage <https://llvm.org/>`_ -* `LLVM Bug Tracker <https://github.com/llvm/llvm-project/labels/libunwind/>`_ -* `Clang Discourse Forums <https://discourse.llvm.org/c/clang/6>`_ -* `cfe-commits Mailing List <http://lists.llvm.org/mailman/listinfo/cfe-commits>`_ -* `Runtimes Forum <https://discourse.llvm.org/tags/c/runtimes>`_ -* `Browse libunwind Sources <https://github.com/llvm/llvm-project/blob/main/libunwind/>`_ diff --git a/lldb/source/Plugins/TraceExporter/docs/htr.md b/lldb/source/Plugins/TraceExporter/docs/htr.md index beee14dce25af..4470be803d498 100644 --- a/lldb/source/Plugins/TraceExporter/docs/htr.md +++ b/lldb/source/Plugins/TraceExporter/docs/htr.md @@ -1,33 +1,33 @@ -Hierarchical Trace Representation (HTR) -====================================== +# Hierarchical Trace Representation (HTR) + The humongous amount of data processor traces like the ones obtained with Intel PT contain is not digestible to humans in its raw form. Given this, it is useful to summarize these massive traces by extracting useful information. Hierarchical Trace Representation (HTR) is the way lldb represents a summarized trace internally. HTR efficiently stores trace data and allows the trace data to be transformed in a way akin to compiler passes. -Concepts --------- +## Concepts + **Block:** One or more contiguous units of the trace. At minimum, the unit of a trace is the load address of an instruction. **Block Metadata:** Metadata associated with each *block*. For processor traces, some metadata examples are the number of instructions in the block or information on what functions are called in the block. **Layer:** The representation of trace data between passes. For Intel PT there are two types of layers: - **Instruction Layer:** Composed of the load addresses of the instructions in the trace. In an effort to save space, - metadata is only stored for instructions that are of interest, not every instruction in the trace. HTR contains a - single instruction layer. - - **Block Layer:** Composed of blocks - a block in *layer n* refers to a sequence of blocks in *layer n - 1*. A block in - *layer 1* refers to a sequence of instructions in *layer 0* (the instruction layer). Metadata is stored for each block in - a block layer. HTR contains one or more block layers. +> **Instruction Layer:** Composed of the load addresses of the instructions in the trace. In an effort to save space, +> metadata is only stored for instructions that are of interest, not every instruction in the trace. HTR contains a +> single instruction layer. +> +> **Block Layer:** Composed of blocks - a block in *layer n* refers to a sequence of blocks in *layer n - 1*. A block in +> *layer 1* refers to a sequence of instructions in *layer 0* (the instruction layer). Metadata is stored for each block in +> a block layer. HTR contains one or more block layers. **Pass:** A transformation applied to a *layer* that generates a new *layer* that is a more summarized, consolidated representation of the trace data. A pass merges instructions/blocks based on its specific purpose - for example, a pass designed to summarize a processor trace by function calls would merge all the blocks of a function into a single block representing the entire function. The image below illustrates the transformation of a trace's representation (HTR) -.. image:: media/htr-example.png +```{image} media/htr-example.png +``` +## Passes -Passes ------- A *pass* is applied to a *layer* to extract useful information (summarization) and compress the trace representation into a new *layer*. The idea is to have a series of passes where each pass specializes in extracting certain information about the trace. Some examples of potential passes include: identifying functions, identifying loops, or a more general purpose such as identifying long sequences of instructions that are repeated (i.e. Basic Super Block). Below you will find a description of each pass currently implemented in lldb. **Basic Super Block Reduction** @@ -36,13 +36,15 @@ A “basic super block” is the longest sequence of blocks that always occur in The image below shows the "basic super blocks" of the sequence. Each unique "basic super block" is marked with a different color -.. image:: media/basic_super_block_pass.png +```{image} media/basic_super_block_pass.png +``` *Procedure to find all super blocks:* - For each block, compute the number of distinct predecessor and successor blocks. - - **Predecessor** - the block that occurs directly before (to the left of) the current block - - **Successor** - the block that occurs directly after (to the right of) the current block +> - **Predecessor** - the block that occurs directly before (to the left of) the current block +> - **Successor** - the block that occurs directly after (to the right of) the current block - A block with more than one distinct successor is always the start of a super block, the super block will continue until the next block with more than one distinct predecessor or successor. + diff --git a/llvm-libgcc/docs/LLVMLibgcc.md b/llvm-libgcc/docs/LLVMLibgcc.md index 22dae7afaa6cf..dcba84cb54f9e 100644 --- a/llvm-libgcc/docs/LLVMLibgcc.md +++ b/llvm-libgcc/docs/LLVMLibgcc.md @@ -1,33 +1,31 @@ -.. llvm-libgcc: +% llvm-libgcc: -=========== -llvm-libgcc -=========== +# llvm-libgcc -.. contents:: - :local: +```{contents} +:local: true +``` **Note that these instructions assume a Linux and bash-friendly environment. YMMV if you’re on a non Linux-based platform.** -.. _introduction: +(introduction)= -Motivation -============ +## Motivation Enabling libunwind as a replacement for libgcc on Linux has proven to be challenging since libgcc_s.so is a required dependency in the [Linux standard base][5]. Some software is transitively dependent on libgcc because glibc makes hardcoded calls to functions in libgcc_s. For example, the function -``__GI___backtrace`` eventually makes its way to a [hardcoded dlopen to libgcc_s' -_Unwind_Backtrace][1]. Since libgcc_{eh.a,s.so} and libunwind have the same ABI, +`__GI___backtrace` eventually makes its way to a [hardcoded dlopen to libgcc_s' +\_Unwind_Backtrace][1]. Since libgcc\_{eh.a,s.so} and libunwind have the same ABI, but different implementations, the two libraries end up [cross-talking, which ultimately results in a segfault][2]. To solve this problem, libunwind needs libgcc "front" that is, link the necessary functions from compiler-rt and libunwind into an archive and shared -object that advertise themselves as ``libgcc.a``, ``libgcc_eh.a``, and -``libgcc_s.so``, so that glibc’s baked calls are diverted to the correct objects +object that advertise themselves as `libgcc.a`, `libgcc_eh.a`, and +`libgcc_s.so`, so that glibc’s baked calls are diverted to the correct objects in memory. Fortunately for us, compiler-rt and libunwind use the same ABI as the libgcc family, so the problem is solvable at the llvm-project configuration level: no program source needs to be edited. Thus, the end result is for a @@ -37,22 +35,20 @@ libunwind with all the symbols necessary for compiler-rt to emulate the libgcc family, and then generate symlinks named for our "libgcc" that point to their corresponding libunwind counterparts. -.. _alternatives +% _alternatives -Alternatives -============ +## Alternatives We alternatively considered patching glibc so that the source doesn't directly -refer to libgcc, but rather _defaults_ to libgcc, so that a system preferring +refer to libgcc, but rather \_defaults\_ to libgcc, so that a system preferring compiler-rt/libunwind can point to these libraries at the config stage instead. Even if we modified the Linux standard base, this alternative won't work because binaries that are built using libgcc will still end up having cross-talk between the differing implementations. -.. _target audience: +(target-audience)= -Target audience -=============== +## Target audience llvm-libgcc is not for the casual LLVM user. It is intended to be used by distro managers who want to replace libgcc with compiler-rt and libunwind, but cannot @@ -60,85 +56,72 @@ fully abandon the libgcc family (e.g. because they are dependent on glibc). Such managers must have worked out their compatibility requirements ahead of using llvm-libgcc. -.. _cmake options: +(cmake-options)= -CMake options -============= +## CMake options +```{eval-rst} .. option:: `LLVM_LIBGCC_EXPLICIT_OPT_IN` **Required** Since llvm-libgcc is such a fundamental, low-level component, we have made it difficult to accidentally build, by requiring you to set an opt-in flag. +``` -.. _Building llvm-libgcc +% _Building llvm-libgcc -Building llvm-libgcc --------------------- +### Building llvm-libgcc The first build tree is a mostly conventional build tree and gets you a Clang build with these compiler-rt symbols exposed. -.. code-block:: bash - # Assumes $(PWD) is /path/to/llvm-project - $ cmake -GNinja -S llvm -B build-primary \ - -DCMAKE_BUILD_TYPE=Release \ - -DCMAKE_CROSSCOMPILING=On \ - -DCMAKE_INSTALL_PREFIX=/tmp/aarch64-unknown-linux-gnu \ - -DLLVM_ENABLE_PROJECTS='clang' \ - -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;llvm-libgcc" \ - -DLLVM_TARGETS_TO_BUILD=AArch64 \ - -DLLVM_DEFAULT_TARGET_TRIPLE=aarch64-unknown-linux-gnu \ - -DLLVM_LIBGCC_EXPLICIT_OPT_IN=Yes - $ ninja -C build-primary install - -It's very important to notice that neither ``compiler-rt``, nor ``libunwind``, -are listed in ``LLVM_ENABLE_RUNTIMES``. llvm-libgcc makes these subprojects, and +```bash # Assumes $(PWD) is /path/to/llvm-project $ cmake -GNinja -S llvm -B build-primary \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_CROSSCOMPILING=On \ -DCMAKE_INSTALL_PREFIX=/tmp/aarch64-unknown-linux-gnu \ -DLLVM_ENABLE_PROJECTS='clang' \ -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;llvm-libgcc" \ -DLLVM_TARGETS_TO_BUILD=AArch64 \ -DLLVM_DEFAULT_TARGET_TRIPLE=aarch64-unknown-linux-gnu \ -DLLVM_LIBGCC_EXPLICIT_OPT_IN=Yes $ ninja -C build-primary install + +``` + +It's very important to notice that neither `compiler-rt`, nor `libunwind`, +are listed in `LLVM_ENABLE_RUNTIMES`. llvm-libgcc makes these subprojects, and adding them to this list will cause you problems due to there being duplicate targets. As such, configuring the runtimes build will reject explicitly mentioning -either project with ``llvm-libgcc``. +either project with `llvm-libgcc`. -To avoid issues when building with ``-DLLVM_ENABLE_RUNTIMES=all``, ``llvm-libgcc`` +To avoid issues when building with `-DLLVM_ENABLE_RUNTIMES=all`, `llvm-libgcc` is not included, and all runtimes targets must be manually listed. -## Verifying your results +\## Verifying your results This gets you a copy of libunwind with the libgcc symbols. You can verify this -using ``readelf``. - -.. code-block:: bash - - $ llvm-readelf -W --dyn-syms "${LLVM_LIBGCC_SYSROOT}/lib/libunwind.so" | grep FUNC | grep GCC_3.0 +using `readelf`. +```bash +$ llvm-readelf -W --dyn-syms "${LLVM_LIBGCC_SYSROOT}/lib/libunwind.so" | grep FUNC | grep GCC_3.0 +``` -Roughly sixty symbols should appear, all suffixed with ``@@GCC_3.0``. You can -replace ``GCC_3.0`` with any of the supported version names in the version +Roughly sixty symbols should appear, all suffixed with `@@GCC_3.0`. You can +replace `GCC_3.0` with any of the supported version names in the version script you’re exporting to verify that the symbols are exported. +(supported-platforms)= -.. _supported platforms: - -Supported platforms -=================== +## Supported platforms llvm-libgcc currently supports the following target triples: -* ``aarch64-*-*-*`` -* ``armv7a-*-*-gnueabihf`` -* ``i386-*-*-*`` -* ``x86_64-*-*-*`` +- `aarch64-*-*-*` +- `armv7a-*-*-gnueabihf` +- `i386-*-*-*` +- `x86_64-*-*-*` -If you would like to support another triple (e.g. ``powerpc64-*-*-*``), you'll -need to generate a new version script, and then edit ``lib/gcc_s.ver``. +If you would like to support another triple (e.g. `powerpc64-*-*-*`), you'll +need to generate a new version script, and then edit `lib/gcc_s.ver`. -.. _Generating a new version script +% _Generating a new version script -Generating a new version script -------------------------------- +### Generating a new version script To generate a new version script, we need to generate the list of symbols that -exist in the set (``clang-builtins.a`` ∪ ``libunwind.a``) ∩ ``libgcc_s.so.1``. +exist in the set (`clang-builtins.a` ∪ `libunwind.a`) ∩ `libgcc_s.so.1`. The prerequisites for generating a version script are a binaries for the three aforementioned libraries targeting your architecture (without having built llvm-libgcc). @@ -146,42 +129,42 @@ llvm-libgcc). Once these libraries are in place, to generate a new version script, run the following command. -.. code-block:: bash - - /path/to/llvm-project - $ export ARCH=powerpc64 - $ llvm/tools/llvm-libgcc/generate_version_script.py \ - --compiler_rt=/path/to/libclang_rt.builtins-${ARCH}.a \ - --libunwind=/path/to/libunwind.a \ - --libgcc_s=/path/to/libgcc_s.so.1 \ - --output=${ARCH} +```bash +/path/to/llvm-project +$ export ARCH=powerpc64 +$ llvm/tools/llvm-libgcc/generate_version_script.py \ + --compiler_rt=/path/to/libclang_rt.builtins-${ARCH}.a \ + --libunwind=/path/to/libunwind.a \ + --libgcc_s=/path/to/libgcc_s.so.1 \ + --output=${ARCH} +``` This will generate a new version script a la -``/path/to/llvm-project/llvm/tools/llvm-libgcc/gcc_s-${ARCH}.ver``, which we use +`/path/to/llvm-project/llvm/tools/llvm-libgcc/gcc_s-${ARCH}.ver`, which we use in the next section. -.. _Editing ``lib/gcc_s.ver`` +% _Editing ``lib/gcc_s.ver`` -Editing ``lib/gcc_s.ver`` -------------------------- +### Editing `lib/gcc_s.ver` Our freshly generated version script is unique to the specific architecture that it was generated for, but a lot of the symbols are shared among many platforms. As such, we don't check in unique version scripts, but rather have a single version script that's run through the C preprocessor to prune symbols we won't -be using in ``lib/gcc_s.ver``. +be using in `lib/gcc_s.ver`. Working out which symbols are common is largely a manual process at the moment, because some symbols may be shared across different architectures, but not in -the same versions of libgcc. As such, a symbol appearing in ``lib/gcc_s.ver`` +the same versions of libgcc. As such, a symbol appearing in `lib/gcc_s.ver` doesn't guarantee that the symbol is available for our new architecture: we need to verify that the versions are the same, and if they're not, add the symbol to the new version section, with the appropriate include guards. There are a few macros that aim to improve readability. -* ``ARM_GNUEABIHF``, which targets exactly ``arm-*-*-gnueabihf``. -* ``GLOBAL_X86``, which should be used to target both x86 and x86_64, regardless +- `ARM_GNUEABIHF`, which targets exactly `arm-*-*-gnueabihf`. +- `GLOBAL_X86`, which should be used to target both x86 and x86_64, regardless of the triple. -* ``GLOBAL_32BIT``, which is be used to target 32-bit platforms. -* ``GLOBAL_64BIT``, which is be used to target 64-bit platforms. +- `GLOBAL_32BIT`, which is be used to target 32-bit platforms. +- `GLOBAL_64BIT`, which is be used to target 64-bit platforms. + diff --git a/offload/docs/index.md b/offload/docs/index.md index 481d1f7ddd8b8..ef6756fe5d942 100644 --- a/offload/docs/index.md +++ b/offload/docs/index.md @@ -1,21 +1,20 @@ -.. Offload documentation master file, created by - sphinx-quickstart on Fri Jul 4 14:59:13 2025. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +% Offload documentation master file, created by +% sphinx-quickstart on Fri Jul 4 14:59:13 2025. +% You can adapt this file completely to your liking, but it should at least +% contain the root `toctree` directive. -Welcome to Offload's documentation! -=================================== +# Welcome to Offload's documentation! -.. toctree:: - :maxdepth: 2 - :caption: Contents: +```{toctree} +:caption: 'Contents:' +:maxdepth: 2 - offload-api +offload-api +``` +# Indices and tables -Indices and tables -================== +- {ref}`genindex` +- {ref}`modindex` +- {ref}`search` -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` >From 104701ce30af0ae82830026f45bc7a8e2d4b72a8 Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Thu, 16 Jul 2026 22:11:35 +0000 Subject: [PATCH 2/2] [docs] Finish MyST migration for selected docs --- compiler-rt/docs/ASanABI.md | 66 +++++++++++++------------- compiler-rt/docs/BuildingCompilerRT.md | 44 +++++++---------- compiler-rt/docs/TestingGuide.md | 4 +- flang/docs/CommandGuide/index.md | 4 +- libsycl/docs/CodingGuidelines.md | 4 +- libsycl/docs/index.md | 9 ++-- libunwind/docs/BuildingLibunwind.md | 52 ++++++++------------ libunwind/docs/index.md | 4 +- llvm-libgcc/docs/LLVMLibgcc.md | 44 ++++++++--------- offload/docs/conf.py | 1 + offload/docs/index.md | 4 +- 11 files changed, 108 insertions(+), 128 deletions(-) diff --git a/compiler-rt/docs/ASanABI.md b/compiler-rt/docs/ASanABI.md index eed765e69a354..5d2f701f44331 100644 --- a/compiler-rt/docs/ASanABI.md +++ b/compiler-rt/docs/ASanABI.md @@ -6,14 +6,14 @@ Some OSes like Darwin want to include the AddressSanitizer runtime by establishi The Stable ABI is isolated by a “shim” layer which maps the unstable ABI to the stable ABI. It consists of a static library (libclang_rt.asan_abi_osx.a) that contains simple mappings of the existing ASan ABI to the smaller Stable ABI. After linking with the static shim library, only calls to the Stable ABI remain. -> Sample content of the shim: -> -> ```c -> void __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); } -> void __asan_load2(uptr p) { __asan_abi_loadn(p, 2, true); } -> void __asan_noabort_load16(uptr p) { __asan_abi_loadn(p, 16, false); } -> void __asan_poison_cxx_array_cookie(uptr p) { __asan_abi_pac(p); } -> ``` +Sample content of the shim: + +```c +void __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); } +void __asan_load2(uptr p) { __asan_abi_loadn(p, 2, true); } +void __asan_noabort_load16(uptr p) { __asan_abi_loadn(p, 16, false); } +void __asan_poison_cxx_array_cookie(uptr p) { __asan_abi_pac(p); } +``` The shim library is only used when `-fsanitize-stable-abi` is specified in the Clang driver and the emitted instrumentation favors runtime calls over inline expansion. @@ -21,29 +21,29 @@ The shim library is only used when `-fsanitize-stable-abi` is specified in the C The maintenance burden on the sanitizer developer community should be negligible. Stable ABI tests should always pass for non-Darwin platforms. Changes to the existing ABI requiring changes to the shim should been infrequent as the existing ASan ABI has long been relatively stable anyway. Rarely, when a change that impacts the contract between LLVM and the shim occurs, some simple responses should suffice. Among such foreseeable changes are: 1) changes to a function signature, 2) additions of new functions, or 3) deprecation of an existing function. -> Following are some examples of reasonable responses to such changes: -> -> - An existing ABI function is changed to return the input parameter on success or NULL on failure. In this scenario, a reasonable change to the shim would be to modify the function signature appropriately and to simply guess at a common-sense implementation. -> -> ```c -> uptr __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); return p; } -> ``` -> -> - An additional function is added for performance reasons. It has a very similar function signature to other similarly named functions and logically is an extension of that same pattern. In this case it would make sense to apply the same logic as the existing entry points: -> -> ```c -> void __asan_load128(uptr p) { __asan_abi_loadn(p, 128, true); } -> ``` -> -> - An entry point is added to the existing ABI for which there is no obvious stable ABI implementation: In this case, doing nothing in a no-op stub would be acceptable, assuming existing features of ASan can still work without an actual implementation of this new function. -> -> ```c -> void __asan_prefetch(uptr p) { } -> ``` -> -> - An entrypoint in the existing ABI is deprecated and/or deleted: -> -> ```c -> (Delete the entrypoint from the shim.) -> ``` +Following are some examples of reasonable responses to such changes: + +- An existing ABI function is changed to return the input parameter on success or NULL on failure. In this scenario, a reasonable change to the shim would be to modify the function signature appropriately and to simply guess at a common-sense implementation. + + ```c + uptr __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); return p; } + ``` + +- An additional function is added for performance reasons. It has a very similar function signature to other similarly named functions and logically is an extension of that same pattern. In this case it would make sense to apply the same logic as the existing entry points: + + ```c + void __asan_load128(uptr p) { __asan_abi_loadn(p, 128, true); } + ``` + +- An entry point is added to the existing ABI for which there is no obvious stable ABI implementation: In this case, doing nothing in a no-op stub would be acceptable, assuming existing features of ASan can still work without an actual implementation of this new function. + + ```c + void __asan_prefetch(uptr p) { } + ``` + +- An entrypoint in the existing ABI is deprecated and/or deleted: + + ```c + (Delete the entrypoint from the shim.) + ``` diff --git a/compiler-rt/docs/BuildingCompilerRT.md b/compiler-rt/docs/BuildingCompilerRT.md index 133275ef0cee2..eec7574dcea34 100644 --- a/compiler-rt/docs/BuildingCompilerRT.md +++ b/compiler-rt/docs/BuildingCompilerRT.md @@ -2,9 +2,9 @@ # Building Compiler-RT -```{contents} +:::{contents} :local: true -``` +::: (build-instructions)= @@ -39,8 +39,7 @@ CMake docs or execute `cmake --help-variable VARIABLE_NAME`. ### Compiler-RT specific options -`````{eval-rst} -.. option:: COMPILER_RT_INSTALL_PATH:PATH +:::{option} COMPILER_RT_INSTALL_PATH:PATH **Default**: ```` (empty relative path) @@ -51,72 +50,65 @@ CMake docs or execute `cmake --help-variable VARIABLE_NAME`. ``-DCOMPILER_RT_INSTALL_PATH:PATH=...`` not ``-DCOMPILER_RT_INSTALL_PATH=...``, otherwise CMake will convert the path to an absolute path. -````` +::: -```{eval-rst} -.. option:: COMPILER_RT_INSTALL_LIBRARY_DIR:PATH +:::{option} COMPILER_RT_INSTALL_LIBRARY_DIR:PATH **Default**: ``lib`` Path where built Compiler-RT libraries should be installed. If a relative path, relative to ``COMPILER_RT_INSTALL_PATH``. -``` +::: -```{eval-rst} -.. option:: COMPILER_RT_INSTALL_BINARY_DIR:PATH +:::{option} COMPILER_RT_INSTALL_BINARY_DIR:PATH **Default**: ``bin`` Path where built Compiler-RT executables should be installed. If a relative path, relative to ``COMPILER_RT_INSTALL_PATH``. -``` +::: -```{eval-rst} -.. option:: COMPILER_RT_INSTALL_INCLUDE_DIR:PATH +:::{option} COMPILER_RT_INSTALL_INCLUDE_DIR:PATH **Default**: ``include`` Path where Compiler-RT headers should be installed. If a relative path, relative to ``COMPILER_RT_INSTALL_PATH``. -``` +::: -```{eval-rst} -.. option:: COMPILER_RT_INSTALL_DATA_DIR:PATH +:::{option} COMPILER_RT_INSTALL_DATA_DIR:PATH **Default**: ``share`` Path where Compiler-RT data should be installed. If a relative path, relative to ``COMPILER_RT_INSTALL_PATH``. -``` +::: -```{eval-rst} -.. option:: COMPILER_RT_INCLUDE_TESTS:BOOL +:::{option} COMPILER_RT_INCLUDE_TESTS:BOOL **Default**: ``LLVM_INCLUDE_TESTS`` in LLVM builds, ``OFF`` in standalone builds. Generate and build compiler-rt tests. If ``OFF``, ``COMPILER_RT_ENABLE_TEST_SUITES`` has no effect. -``` +::: -```{eval-rst} -.. option:: COMPILER_RT_ENABLE_TEST_SUITES:STRING +:::{option} COMPILER_RT_ENABLE_TEST_SUITES:STRING **Default**: ``all`` Semicolon-separated list of test suites to enable, or ``all`` to enable all test suites. Example: ``-DCOMPILER_RT_ENABLE_TEST_SUITES="asan;ubsan;lsan"`` -``` +::: (llvm-specific-variables)= ### LLVM-specific options -```{eval-rst} -.. option:: LLVM_LIBDIR_SUFFIX:STRING +:::{option} LLVM_LIBDIR_SUFFIX:STRING Extra suffix to append to the directory where libraries are to be installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` to install libraries to ``/usr/lib64``. -``` +::: diff --git a/compiler-rt/docs/TestingGuide.md b/compiler-rt/docs/TestingGuide.md index d008c55cd9711..a94ed6d65f9b8 100644 --- a/compiler-rt/docs/TestingGuide.md +++ b/compiler-rt/docs/TestingGuide.md @@ -1,8 +1,8 @@ # Compiler-rt Testing Infrastructure Guide -```{contents} +:::{contents} :local: true -``` +::: ## Overview diff --git a/flang/docs/CommandGuide/index.md b/flang/docs/CommandGuide/index.md index 32b7c48f75df5..93473b7a9fc9e 100644 --- a/flang/docs/CommandGuide/index.md +++ b/flang/docs/CommandGuide/index.md @@ -59,9 +59,9 @@ Linker ## OPTIONS -```{toctree} +:::{toctree} :maxdepth: 1 FlangCommandLineOptions -``` +::: diff --git a/libsycl/docs/CodingGuidelines.md b/libsycl/docs/CodingGuidelines.md index 8decbe4e76828..0709c556d78fa 100644 --- a/libsycl/docs/CodingGuidelines.md +++ b/libsycl/docs/CodingGuidelines.md @@ -1,8 +1,8 @@ # Libsycl Coding Standards -```{contents} +:::{contents} :local: true -``` +::: ## Introduction diff --git a/libsycl/docs/index.md b/libsycl/docs/index.md index 19cc14e7c1de2..de14261322039 100644 --- a/libsycl/docs/index.md +++ b/libsycl/docs/index.md @@ -1,8 +1,8 @@ # SYCL runtime implementation -```{contents} +:::{contents} :local: true -``` +::: (index)= @@ -91,7 +91,7 @@ which doesn't currently support Windows. - `exception`: methods with context are not implemented, to add once context is ready -- `platform`: deprecated info descriptor is not implemented (<info::platform::extensions>), to implement on RT level with `device::get_info<info::device::aspects>()` +- `platform`: deprecated info descriptor is not implemented (`info::platform::extensions`), to implement on RT level with `device::get_info<info::device::aspects>()` - `device`: @@ -139,10 +139,9 @@ which doesn't currently support Windows. - get_info, get_profiling_info (no liboffload support) are not implemented - get_wait_list should be aligned with the results of this discussion: <https://github.com/KhronosGroup/SYCL-Docs/issues/1017> -- `range`, `id` - \_\_SYCL_DISABLE_ID_TO_INT_CONV\_\_ and \_\_SYCL_ASSUME_ID_RANGE optimizations are not implemented +- `range`, `id` - `__SYCL_DISABLE_ID_TO_INT_CONV__` and `__SYCL_ASSUME_ID_RANGE` optimizations are not implemented - general opens: - define a way to report errors from object dtors - unittests: add functions to reset libsycl internal state completely (static variables) - diff --git a/libunwind/docs/BuildingLibunwind.md b/libunwind/docs/BuildingLibunwind.md index 3bc831d3c906f..7287eb0f901b7 100644 --- a/libunwind/docs/BuildingLibunwind.md +++ b/libunwind/docs/BuildingLibunwind.md @@ -2,9 +2,9 @@ # Building libunwind -```{contents} +:::{contents} :local: true -``` +::: (build-instructions)= @@ -32,7 +32,7 @@ The basic steps needed to build libunwind are: - `cd build` - `cmake -G <generator> -DLLVM_ENABLE_RUNTIMES=libunwind [options] <llvm-monorepo>/runtimes` - For more information about configuring libunwind see {ref}`CMake Options`. + For more information about configuring libunwind see [CMake Options](#cmake-options). - `make unwind` --- will build libunwind. - `make check-unwind` --- will run the test suite. @@ -74,76 +74,66 @@ CMake docs or execute `cmake --help-variable VARIABLE_NAME`. ### libunwind specific options -```{eval-rst} -.. option:: LIBUNWIND_ENABLE_ASSERTIONS:BOOL +:::{option} LIBUNWIND_ENABLE_ASSERTIONS:BOOL **Default**: ``ON`` Toggle assertions independent of the build mode. -``` +::: -```{eval-rst} -.. option:: LIBUNWIND_ENABLE_PEDANTIC:BOOL +:::{option} LIBUNWIND_ENABLE_PEDANTIC:BOOL **Default**: ``ON`` Compile with -Wpedantic. -``` +::: -```{eval-rst} -.. option:: LIBUNWIND_ENABLE_WERROR:BOOL +:::{option} LIBUNWIND_ENABLE_WERROR:BOOL **Default**: ``OFF`` Compile with -Werror -``` +::: -```{eval-rst} -.. option:: LIBUNWIND_ENABLE_SHARED:BOOL +:::{option} LIBUNWIND_ENABLE_SHARED:BOOL **Default**: ``ON`` Build libunwind as a shared library. -``` +::: -```{eval-rst} -.. option:: LIBUNWIND_ENABLE_STATIC:BOOL +:::{option} LIBUNWIND_ENABLE_STATIC:BOOL **Default**: ``ON`` Build libunwind as a static archive. -``` +::: -```{eval-rst} -.. option:: LIBUNWIND_ENABLE_CROSS_UNWINDING:BOOL +:::{option} LIBUNWIND_ENABLE_CROSS_UNWINDING:BOOL **Default**: ``OFF`` Enable cross-platform unwinding support. -``` +::: -```{eval-rst} -.. option:: LIBUNWIND_ENABLE_ARM_WMMX:BOOL +:::{option} LIBUNWIND_ENABLE_ARM_WMMX:BOOL **Default**: ``OFF`` Enable unwinding support for ARM WMMX registers. -``` +::: -```{eval-rst} -.. option:: LIBUNWIND_ENABLE_THREADS:BOOL +:::{option} LIBUNWIND_ENABLE_THREADS:BOOL **Default**: ``ON`` Build libunwind with threading support. -``` +::: -```{eval-rst} -.. option:: LIBUNWIND_INSTALL_LIBRARY_DIR:PATH +:::{option} LIBUNWIND_INSTALL_LIBRARY_DIR:PATH **Default**: ``lib${LIBUNWIND_LIBDIR_SUFFIX}`` Path where built libunwind libraries should be installed. If a relative path, relative to ``CMAKE_INSTALL_PREFIX``. -``` - +::: diff --git a/libunwind/docs/index.md b/libunwind/docs/index.md index f9e7fe9de134b..f47f1d2d13592 100644 --- a/libunwind/docs/index.md +++ b/libunwind/docs/index.md @@ -17,11 +17,11 @@ defined by the old HP libunwind project. ### Getting Started with libunwind -```{toctree} +:::{toctree} :maxdepth: 2 BuildingLibunwind -``` +::: ### Current Status diff --git a/llvm-libgcc/docs/LLVMLibgcc.md b/llvm-libgcc/docs/LLVMLibgcc.md index dcba84cb54f9e..cedb9ff72f908 100644 --- a/llvm-libgcc/docs/LLVMLibgcc.md +++ b/llvm-libgcc/docs/LLVMLibgcc.md @@ -1,10 +1,8 @@ -% llvm-libgcc: - # llvm-libgcc -```{contents} +:::{contents} :local: true -``` +::: **Note that these instructions assume a Linux and bash-friendly environment. YMMV if you’re on a non Linux-based platform.** @@ -18,7 +16,7 @@ challenging since libgcc_s.so is a required dependency in the [Linux standard base][5]. Some software is transitively dependent on libgcc because glibc makes hardcoded calls to functions in libgcc_s. For example, the function `__GI___backtrace` eventually makes its way to a [hardcoded dlopen to libgcc_s' -\_Unwind_Backtrace][1]. Since libgcc\_{eh.a,s.so} and libunwind have the same ABI, +_Unwind_Backtrace][1]. Since `libgcc_{eh.a,s.so}` and libunwind have the same ABI, but different implementations, the two libraries end up [cross-talking, which ultimately results in a segfault][2]. @@ -35,12 +33,10 @@ libunwind with all the symbols necessary for compiler-rt to emulate the libgcc family, and then generate symlinks named for our "libgcc" that point to their corresponding libunwind counterparts. -% _alternatives - ## Alternatives We alternatively considered patching glibc so that the source doesn't directly -refer to libgcc, but rather \_defaults\_ to libgcc, so that a system preferring +refer to libgcc, but rather *defaults* to libgcc, so that a system preferring compiler-rt/libunwind can point to these libraries at the config stage instead. Even if we modified the Linux standard base, this alternative won't work because binaries that are built using libgcc will still end up having cross-talk between @@ -60,24 +56,31 @@ llvm-libgcc. ## CMake options -```{eval-rst} -.. option:: `LLVM_LIBGCC_EXPLICIT_OPT_IN` +:::{option} `LLVM_LIBGCC_EXPLICIT_OPT_IN` - **Required** - - Since llvm-libgcc is such a fundamental, low-level component, we have made it - difficult to accidentally build, by requiring you to set an opt-in flag. -``` +**Required** -% _Building llvm-libgcc +Since llvm-libgcc is such a fundamental, low-level component, we have made it +difficult to accidentally build, by requiring you to set an opt-in flag. +::: ### Building llvm-libgcc The first build tree is a mostly conventional build tree and gets you a Clang build with these compiler-rt symbols exposed. -```bash # Assumes $(PWD) is /path/to/llvm-project $ cmake -GNinja -S llvm -B build-primary \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_CROSSCOMPILING=On \ -DCMAKE_INSTALL_PREFIX=/tmp/aarch64-unknown-linux-gnu \ -DLLVM_ENABLE_PROJECTS='clang' \ -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;llvm-libgcc" \ -DLLVM_TARGETS_TO_BUILD=AArch64 \ -DLLVM_DEFAULT_TARGET_TRIPLE=aarch64-unknown-linux-gnu \ -DLLVM_LIBGCC_EXPLICIT_OPT_IN=Yes $ ninja -C build-primary install - +```bash +# Assumes $(PWD) is /path/to/llvm-project +$ cmake -GNinja -S llvm -B build-primary \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_CROSSCOMPILING=On \ + -DCMAKE_INSTALL_PREFIX=/tmp/aarch64-unknown-linux-gnu \ + -DLLVM_ENABLE_PROJECTS='clang' \ + -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;llvm-libgcc" \ + -DLLVM_TARGETS_TO_BUILD=AArch64 \ + -DLLVM_DEFAULT_TARGET_TRIPLE=aarch64-unknown-linux-gnu \ + -DLLVM_LIBGCC_EXPLICIT_OPT_IN=Yes +$ ninja -C build-primary install ``` It's very important to notice that neither `compiler-rt`, nor `libunwind`, @@ -116,8 +119,6 @@ llvm-libgcc currently supports the following target triples: If you would like to support another triple (e.g. `powerpc64-*-*-*`), you'll need to generate a new version script, and then edit `lib/gcc_s.ver`. -% _Generating a new version script - ### Generating a new version script To generate a new version script, we need to generate the list of symbols that @@ -143,8 +144,6 @@ This will generate a new version script a la `/path/to/llvm-project/llvm/tools/llvm-libgcc/gcc_s-${ARCH}.ver`, which we use in the next section. -% _Editing ``lib/gcc_s.ver`` - ### Editing `lib/gcc_s.ver` Our freshly generated version script is unique to the specific architecture that @@ -167,4 +166,3 @@ There are a few macros that aim to improve readability. of the triple. - `GLOBAL_32BIT`, which is be used to target 32-bit platforms. - `GLOBAL_64BIT`, which is be used to target 64-bit platforms. - diff --git a/offload/docs/conf.py b/offload/docs/conf.py index ca6ec5b8039c0..fdbc46c905d7f 100644 --- a/offload/docs/conf.py +++ b/offload/docs/conf.py @@ -18,6 +18,7 @@ ".rst": "restructuredtext", ".md": "markdown", } +myst_enable_extensions = ["colon_fence"] templates_path = ["_templates"] exclude_patterns = [] diff --git a/offload/docs/index.md b/offload/docs/index.md index ef6756fe5d942..0f4412120c302 100644 --- a/offload/docs/index.md +++ b/offload/docs/index.md @@ -5,12 +5,12 @@ # Welcome to Offload's documentation! -```{toctree} +:::{toctree} :caption: 'Contents:' :maxdepth: 2 offload-api -``` +::: # Indices and tables _______________________________________________ lldb-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
