Cold-Air-Networks/mirror-llvm-project
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 7

[docs] Finish misc MyST migration (#210209)

Browse source 
Tracking issue: #201242
See the [migration guide] for more information.

[migration guide]:
https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines

This is a stacked PR based on #210208, which is the standalone rename
commit for this miscellaneous Markdown migration batch.

This was prepared with rst2myst plus LLM-assisted cleanup. LLDB man
pages are intentionally left as reStructuredText because LLDB man-page
building should not take on Markdown parser dependencies.

Unfortunately, many of these miscellaneous docs do not have working
standalone doc build targets, so I was not able to render HTML for all
of them. I think the scope is small enough that this is reviewable by
hand.
This commit is contained in:
Reid Kleckner 2026-07-17 11:56:59 -07:00 committed by GitHub
parent 714d124d0a
commit 93b1240309
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
12 changed files with 462 additions and 474 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

60
compiler-rt/docs/ASanABI.md
View file

@ -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. 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:
.. code-block:: c ```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); }
```
void __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); } 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_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. 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: 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. - 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 ```c
uptr __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); return p; }
```
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:
* 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); }
```
.. code-block:: c - 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.
void __asan_load128(uptr p) { __asan_abi_loadn(p, 128, true); } ```c
void __asan_prefetch(uptr p) { }
```
* 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. - An entrypoint in the existing ABI is deprecated and/or deleted:
.. code-block:: c ```c
(Delete the entrypoint from the shim.)
```
void __asan_prefetch(uptr p) { }
* An entrypoint in the existing ABI is deprecated and/or deleted:
.. code-block:: c
(Delete the entrypoint from the shim.)

61
compiler-rt/docs/BuildingCompilerRT.md
View file

@ -1,13 +1,12 @@
.. _BuildingCompilerRT: (buildingcompilerrt)=
=============== # Building Compiler-RT
Building Compiler-RT
===============
.. contents:: :::{contents}
:local: :local: true
:::
.. _build instructions: (build-instructions)=
The instructions on this page are aimed at vendors who ship Compiler-RT as part of an 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 operating system distribution, a toolchain or similar shipping vehicles. If you
@ -15,32 +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 refer to your vendor's documentation, or to the general documentation for using
LLVM, Clang, the various santizers, etc. LLVM, Clang, the various santizers, etc.
CMake Options ## CMake Options
=============
Here are some of the CMake variables that are used often, along with a 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 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 **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 Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio
the user sets the build type with the IDE settings. the user sets the build type with the IDE settings.
**CMAKE_INSTALL_PREFIX**:PATH **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. "INSTALL" target is built.
**CMAKE_CXX_COMPILER**:STRING **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
-----------------------
.. option:: COMPILER_RT_INSTALL_PATH:PATH :::{option} COMPILER_RT_INSTALL_PATH:PATH
**Default**: ```` (empty relative path) **Default**: ```` (empty relative path)
@ -51,57 +50,65 @@ Compiler-RT specific options
``-DCOMPILER_RT_INSTALL_PATH:PATH=...`` not ``-DCOMPILER_RT_INSTALL_PATH:PATH=...`` not
``-DCOMPILER_RT_INSTALL_PATH=...``, otherwise CMake will convert the ``-DCOMPILER_RT_INSTALL_PATH=...``, otherwise CMake will convert the
path to an absolute path. path to an absolute path.
:::
.. option:: COMPILER_RT_INSTALL_LIBRARY_DIR:PATH :::{option} COMPILER_RT_INSTALL_LIBRARY_DIR:PATH
**Default**: ``lib`` **Default**: ``lib``
Path where built Compiler-RT libraries should be installed. If a relative Path where built Compiler-RT libraries should be installed. If a relative
path, relative to ``COMPILER_RT_INSTALL_PATH``. path, relative to ``COMPILER_RT_INSTALL_PATH``.
:::
.. option:: COMPILER_RT_INSTALL_BINARY_DIR:PATH :::{option} COMPILER_RT_INSTALL_BINARY_DIR:PATH
**Default**: ``bin`` **Default**: ``bin``
Path where built Compiler-RT executables should be installed. If a relative Path where built Compiler-RT executables should be installed. If a relative
path, relative to ``COMPILER_RT_INSTALL_PATH``. path, relative to ``COMPILER_RT_INSTALL_PATH``.
:::
.. option:: COMPILER_RT_INSTALL_INCLUDE_DIR:PATH :::{option} COMPILER_RT_INSTALL_INCLUDE_DIR:PATH
**Default**: ``include`` **Default**: ``include``
Path where Compiler-RT headers should be installed. If a relative Path where Compiler-RT headers should be installed. If a relative
path, relative to ``COMPILER_RT_INSTALL_PATH``. path, relative to ``COMPILER_RT_INSTALL_PATH``.
:::
.. option:: COMPILER_RT_INSTALL_DATA_DIR:PATH :::{option} COMPILER_RT_INSTALL_DATA_DIR:PATH
**Default**: ``share`` **Default**: ``share``
Path where Compiler-RT data should be installed. If a relative Path where Compiler-RT data should be installed. If a relative
path, relative to ``COMPILER_RT_INSTALL_PATH``. path, relative to ``COMPILER_RT_INSTALL_PATH``.
:::
.. option:: COMPILER_RT_INCLUDE_TESTS:BOOL :::{option} COMPILER_RT_INCLUDE_TESTS:BOOL
**Default**: ``LLVM_INCLUDE_TESTS`` in LLVM builds, ``OFF`` in standalone builds. **Default**: ``LLVM_INCLUDE_TESTS`` in LLVM builds, ``OFF`` in standalone builds.
Generate and build compiler-rt tests. If ``OFF``, Generate and build compiler-rt tests. If ``OFF``,
``COMPILER_RT_ENABLE_TEST_SUITES`` has no effect. ``COMPILER_RT_ENABLE_TEST_SUITES`` has no effect.
:::
.. option:: COMPILER_RT_ENABLE_TEST_SUITES:STRING :::{option} COMPILER_RT_ENABLE_TEST_SUITES:STRING
**Default**: ``all`` **Default**: ``all``
Semicolon-separated list of test suites to enable, or ``all`` to enable all Semicolon-separated list of test suites to enable, or ``all`` to enable all
test suites. test suites.
Example: ``-DCOMPILER_RT_ENABLE_TEST_SUITES="asan;ubsan;lsan"`` Example: ``-DCOMPILER_RT_ENABLE_TEST_SUITES="asan;ubsan;lsan"``
:::
.. _LLVM-specific variables: (llvm-specific-variables)=
LLVM-specific options ### LLVM-specific options
---------------------
.. option:: LLVM_LIBDIR_SUFFIX:STRING :::{option} LLVM_LIBDIR_SUFFIX:STRING
Extra suffix to append to the directory where libraries are to be 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`` installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
to install libraries to ``/usr/lib64``. to install libraries to ``/usr/lib64``.
:::

70
compiler-rt/docs/TestingGuide.md
View file

@ -1,67 +1,65 @@
======================================== # Compiler-rt Testing Infrastructure Guide
Compiler-rt Testing Infrastructure Guide
========================================
.. contents:: :::{contents}
:local: :local: true
:::
Overview ## Overview
========
This document is the reference manual for the compiler-rt modifications to the This document is the reference manual for the compiler-rt modifications to the
testing infrastructure. Documentation for the infrastructure itself can be found at 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 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. should be run before every commit.
Quick start ## Quick start
===========
The regressions tests are in the "compiler-rt" module and are normally checked 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. 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 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 an "expected fail" or XFAIL. This is normally achieved using `REQUIRES:` or
``XFAIL:`` and the ``target=<target-triple>`` feature, typically with a regular `XFAIL:` and the `target=<target-triple>` feature, typically with a regular
expression matching an appropriate substring of the triple. Unfortunately, the expression matching an appropriate substring of the triple. Unfortunately, the
behaviour of this is somewhat quirky in compiler-rt. There are two main behaviour of this is somewhat quirky in compiler-rt. There are two main
pitfalls to avoid. pitfalls to avoid.
The first pitfall is that these regular expressions may inadvertently match The first pitfall is that these regular expressions may inadvertently match
more triples than expected. For example, ``XFAIL: target=mips{{.*}}`` matches more triples than expected. For example, `XFAIL: target=mips{{.*}}` matches
``mips-linux-gnu``, ``mipsel-linux-gnu``, ``mips64-linux-gnu``, and `mips-linux-gnu`, `mipsel-linux-gnu`, `mips64-linux-gnu`, and
``mips64el-linux-gnu``. Including a trailing ``-`` such as in `mips64el-linux-gnu`. Including a trailing `-` such as in
``XFAIL: target=mips-{{.*}}`` can help to mitigate this quirk but even that has `XFAIL: target=mips-{{.*}}` can help to mitigate this quirk but even that has
issues as described below. issues as described below.
The second pitfall is that the default target triple is often inappropriate for 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. 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 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{{{.*}}`` 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 will mark both the x86_64 and i386 tests as an expected failure while
``XFAIL: target=i386{{.*}}`` will have no effect at all. `XFAIL: target=i386{{.*}}` will have no effect at all.
To remedy both pitfalls, compiler-rt tests provide a feature string which can 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 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 `target-is-${arch}` where `${arch}}` is one of the values from the
following lines of the CMake output:: 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 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`` 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 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 is `x86_64-linux-gnu`. Directives that use these `target-is-${arch}` string
require exact matches so ``XFAIL: target-is-mips``, require exact matches so `XFAIL: target-is-mips`,
``XFAIL: target-is-mipsel``, ``XFAIL: target-is-mips64``, and `XFAIL: target-is-mipsel`, `XFAIL: target-is-mips64`, and
``XFAIL: target-is-mips64el`` all refer to different MIPS targets. `XFAIL: target-is-mips64el` all refer to different MIPS targets.

82
flang/docs/CommandGuide/index.md
View file

@ -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 many newer language features. Flang supports OpenMP and has some support for
OpenACC and CUDA. It encompasses preprocessing, parsing, optimization, code 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 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 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 Driver
The flang executable is actually a small driver that orchestrates the
execution of other tools such as the compiler, assembler and linker. : The flang executable is actually a small driver that orchestrates the
Typically you do not need to interact with the driver, but you execution of other tools such as the compiler, assembler and linker.
transparently use it to run the other tools. Typically you do not need to interact with the driver, but you
transparently use it to run the other tools.
Preprocessing 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 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 : This stage parses the input file, translating preprocessor tokens into a
analysis to compute types for expressions and determine whether parse tree. Once in the form of a parse tree, it applies semantic
the code is well formed. Parse errors and most compiler warnings analysis to compute types for expressions and determine whether
are generated by this stage. the code is well formed. Parse errors and most compiler warnings
are generated by this stage.
Code Generation and Optimization 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 : This stage translates the parse tree into intermediate code (known as
generator produces object files directly. This avoids the overhead of "LLVM IR") and, ultimately, machine code. It also optimizes this
generating the ".s" file and calling the target assembler explicitly. 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 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 : This stage runs the target assembler to translate the output of the
a ".o" file, referred to as an "object" file. compiler into a target object file. The output of this stage is typically
a ".o" file, referred to as an "object" file.
Linker 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.
.. toctree:: ## OPTIONS
:maxdepth: 1
:::{toctree}
:maxdepth: 1
FlangCommandLineOptions
:::
FlangCommandLineOptions

42
libsycl/docs/CodingGuidelines.md
View file

@ -1,39 +1,33 @@
======================== # Libsycl Coding Standards
Libsycl Coding Standards
========================
.. contents:: :::{contents}
:local: :local: true
:::
Introduction ## Introduction
============
The ``libsycl`` project follows the The `libsycl` project follows the
`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_ with [LLVM Coding Standards](https://llvm.org/docs/CodingStandards.html) with
exceptions as described in this document. 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 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 specification. Names of all other entities follow the guidance in the LLVM
Coding Standards. 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 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. that should be excluded from test discovery.
- **File Names in snake case** should be used for all C++ implementation files.
* **File Names in snake case** should be used for all C++ implementation files. For example files in directories `include`, `src`, `test`, `utils`,
For example files in directories ``include``, ``src``, ``test``, ``utils``, and `tools` should be named in snake case.
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 camel case** should be used for most other files. For example
files in directories ``cmake/modules`` and ``docs`` should be named in camel
case. case.

209
libsycl/docs/index.md
View file

@ -1,140 +1,147 @@
=========================== # SYCL runtime implementation
SYCL runtime implementation
===========================
.. contents:: :::{contents}
:local: :local: true
:::
.. _index: (index)=
Current Status ## Current Status
==============
The implementation is in the very early stages of upstreaming. The first The implementation is in the very early stages of upstreaming. The first
milestone is to get milestone is to get
support for a simple SYCL application with device code using Unified Shared support for a simple SYCL application with device code using Unified Shared
Memory: Memory:
.. code-block:: c++ ```c++
#include <sycl/sycl.hpp>
#include <sycl/sycl.hpp> class TestKernel;
class TestKernel; int main() {
sycl::queue q;
int main() {
sycl::queue q; const size_t dataSize = 32;
int *dataPtr = sycl::malloc_shared<int>(32, q);
const size_t dataSize = 32; for (int i = 0; i < dataSize; ++i)
int *dataPtr = sycl::malloc_shared<int>(32, q); dataPtr[i] = 0;
for (int i = 0; i < dataSize; ++i)
dataPtr[i] = 0; q.submit([&](sycl::handler &cgh) {
cgh.parallel_for<TestKernel>(
q.submit([&](sycl::handler &cgh) { sycl::range<1>(dataSize),
cgh.parallel_for<TestKernel>( [=](sycl::id<1> idx) { dataPtr[idx] = idx[0]; });
sycl::range<1>(dataSize), });
[=](sycl::id<1> idx) { dataPtr[idx] = idx[0]; }); q.wait();
});
q.wait(); bool error = false;
for (int i = 0; i < dataSize; ++i)
bool error = false; if (dataPtr[i] != i) error = true;
for (int i = 0; i < dataSize; ++i)
if (dataPtr[i] != i) error = true; free(dataPtr, q);
free(dataPtr, q); return error;
}
return error; ```
}
This requires at least partial support of the following functionality on the This requires at least partial support of the following functionality on the
libsycl side: libsycl side:
* ``sycl::platform`` class - `sycl::platform` class
* ``sycl::device`` class - `sycl::device` class
* ``sycl::context`` class - `sycl::context` class
* ``sycl::queue`` class - `sycl::queue` class
* ``sycl::handler`` class - `sycl::handler` class
* ``sycl::id`` and ``sycl::range`` classes - `sycl::id` and `sycl::range` classes
* Unified shared memory allocation/deallocation - Unified shared memory allocation/deallocation
* Program manager, an internal component for retrieving and using device images - Program manager, an internal component for retrieving and using device images
from the multi-architectural binaries from the multi-architectural binaries
Build steps ## Build steps
===========
To build LLVM with libsycl runtime enabled the following script can be used. To build LLVM with libsycl runtime enabled the following script can be used.
.. code-block:: console ```console
#!/bin/sh
#!/bin/sh build_llvm=`pwd`/build-llvm
installprefix=`pwd`/install
llvm=`pwd`
mkdir -p $build_llvm
mkdir -p $installprefix
build_llvm=`pwd`/build-llvm cmake -G Ninja -S $llvm/llvm -B $build_llvm \
installprefix=`pwd`/install -DLLVM_ENABLE_PROJECTS="clang" \
llvm=`pwd` -DLLVM_INSTALL_UTILS=ON \
mkdir -p $build_llvm -DCMAKE_INSTALL_PREFIX=$installprefix \
mkdir -p $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
cmake -G Ninja -S $llvm/llvm -B $build_llvm \ ninja -C $build_llvm install
-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 Libsycl is not currently supported on Windows because it depends on liboffload
which doesn't currently support Windows. 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 - `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 - `platform`: deprecated info descriptor is not implemented (`info::platform::extensions`), to implement on RT level with `device::get_info<info::device::aspects>()`
* ``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 - `device`:
* ``context``: to implement get_info, properties & public constructors once context support is added to liboffload
* ``queue``:
* to implement USM methods - `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`
* ``memcpy``: enable the host-to-host case (blocked by liboffload limitations) - device selection: to add compatibility with old SYCL 1.2.1 device selectors, still part of SYCL 2020 specification
* to implement synchronization methods - `context`: to implement get_info, properties & public constructors once context support is added to liboffload
* 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)
* ``property_list``: to fully implement and integrate with existing SYCL runtime classes supporting it - `queue`:
* usm allocations:
* add aligned functions (blocked by liboffload support) - to implement USM methods
* forward templated funcs to alignment methods (rewrite current impl)
* handle sub devices once they are implemented (blocked by liboffload support)
* ``event``: - `memcpy`: enable the host-to-host case (blocked by liboffload limitations)
* get_info, get_profiling_info (no liboffload support) are not implemented - to implement synchronization methods
* 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 - to implement submit & copy with accessors (low priority)
* general opens:
* define a way to report errors from object dtors - get_info & properties
* unittests: add functions to reset libsycl internal state completely (static variables)
- 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)
- `property_list`: to fully implement and integrate with existing SYCL runtime classes supporting it
- usm allocations:
- 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)
- `event`:
- 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
- general opens:
- define a way to report errors from object dtors
- unittests: add functions to reset libsycl internal state completely (static variables)

92
libunwind/docs/BuildingLibunwind.md
View file

@ -1,16 +1,14 @@
.. _BuildingLibunwind: (buildinglibunwind)=
================== # Building libunwind
Building libunwind
==================
.. contents:: :::{contents}
:local: :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. 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 However if you want to build tip-of-trunk from here (getting the bleeding
@ -18,116 +16,124 @@ edge), read on.
The basic steps needed to build libunwind are: 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`` - `cd where-you-want-llvm-to-live`
* ``git clone https://github.com/llvm/llvm-project.git`` - `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. CMake is the only supported configuration system.
Clang is the preferred compiler when building and using libunwind. Clang is the preferred compiler when building and using libunwind.
* ``cd where you want to build llvm`` - `cd where you want to build llvm`
* ``mkdir build`` - `mkdir build`
* ``cd build`` - `cd build`
* ``cmake -G <generator> -DLLVM_ENABLE_RUNTIMES=libunwind [options] <llvm-monorepo>/runtimes`` - `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 unwind` --- will build libunwind.
* ``make check-unwind`` --- will run the test suite. - `make check-unwind` --- will run the test suite.
Shared and static libraries for libunwind should now be present in llvm/build/lib. 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 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. 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 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 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 **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 Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio
the user sets the build type with the IDE settings. the user sets the build type with the IDE settings.
**CMAKE_INSTALL_PREFIX**:PATH **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. "INSTALL" target is built.
**CMAKE_CXX_COMPILER**:STRING **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
--------------------------
.. option:: LIBUNWIND_ENABLE_ASSERTIONS:BOOL :::{option} LIBUNWIND_ENABLE_ASSERTIONS:BOOL
**Default**: ``ON`` **Default**: ``ON``
Toggle assertions independent of the build mode. Toggle assertions independent of the build mode.
:::
.. option:: LIBUNWIND_ENABLE_PEDANTIC:BOOL :::{option} LIBUNWIND_ENABLE_PEDANTIC:BOOL
**Default**: ``ON`` **Default**: ``ON``
Compile with -Wpedantic. Compile with -Wpedantic.
:::
.. option:: LIBUNWIND_ENABLE_WERROR:BOOL :::{option} LIBUNWIND_ENABLE_WERROR:BOOL
**Default**: ``OFF`` **Default**: ``OFF``
Compile with -Werror Compile with -Werror
:::
.. option:: LIBUNWIND_ENABLE_SHARED:BOOL :::{option} LIBUNWIND_ENABLE_SHARED:BOOL
**Default**: ``ON`` **Default**: ``ON``
Build libunwind as a shared library. Build libunwind as a shared library.
:::
.. option:: LIBUNWIND_ENABLE_STATIC:BOOL :::{option} LIBUNWIND_ENABLE_STATIC:BOOL
**Default**: ``ON`` **Default**: ``ON``
Build libunwind as a static archive. Build libunwind as a static archive.
:::
.. option:: LIBUNWIND_ENABLE_CROSS_UNWINDING:BOOL :::{option} LIBUNWIND_ENABLE_CROSS_UNWINDING:BOOL
**Default**: ``OFF`` **Default**: ``OFF``
Enable cross-platform unwinding support. Enable cross-platform unwinding support.
:::
.. option:: LIBUNWIND_ENABLE_ARM_WMMX:BOOL :::{option} LIBUNWIND_ENABLE_ARM_WMMX:BOOL
**Default**: ``OFF`` **Default**: ``OFF``
Enable unwinding support for ARM WMMX registers. Enable unwinding support for ARM WMMX registers.
:::
.. option:: LIBUNWIND_ENABLE_THREADS:BOOL :::{option} LIBUNWIND_ENABLE_THREADS:BOOL
**Default**: ``ON`` **Default**: ``ON``
Build libunwind with threading support. Build libunwind with threading support.
:::
.. option:: LIBUNWIND_INSTALL_LIBRARY_DIR:PATH :::{option} LIBUNWIND_INSTALL_LIBRARY_DIR:PATH
**Default**: ``lib${LIBUNWIND_LIBDIR_SUFFIX}`` **Default**: ``lib${LIBUNWIND_LIBDIR_SUFFIX}``
Path where built libunwind libraries should be installed. If a relative path, Path where built libunwind libraries should be installed. If a relative path,
relative to ``CMAKE_INSTALL_PREFIX``. relative to ``CMAKE_INSTALL_PREFIX``.
:::

90
libunwind/docs/index.md
View file

@ -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 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 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 functions. The low level APIs are the `unw_*` functions which are an interface
defined by the old HP libunwind project. defined by the old HP libunwind project.
Getting Started with libunwind ### Getting Started with libunwind
------------------------------
.. toctree:: :::{toctree}
:maxdepth: 2 :maxdepth: 2
BuildingLibunwind BuildingLibunwind
:::
Current Status ### Current Status
--------------
libunwind is a production-quality unwinder, with platform support for DWARF libunwind is a production-quality unwinder, with platform support for DWARF
unwind info, SjLj, and ARM EHABI. 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 or to operate on another process (aka remote), but only the local path has been
implemented. Remote unwinding remains as future work. implemented. Remote unwinding remains as future work.
Platform and Compiler Support ### Platform and Compiler Support
-----------------------------
libunwind is known to work on the following platforms: libunwind is known to work on the following platforms:
============ ======================== ============ ======================== | OS | Arch | Compilers | Unwind Info |
OS Arch Compilers Unwind Info | ---------- | ------------------------ | ---------- | ----------- |
============ ======================== ============ ======================== | Any | i386, x86_64, ARM | Clang | SjLj |
Any i386, x86_64, ARM Clang SjLj | Bare Metal | ARM | Clang, GCC | EHABI |
Bare Metal ARM Clang, GCC EHABI | FreeBSD | i386, x86_64, ARM64 | Clang | DWARF CFI |
FreeBSD i386, x86_64, ARM64 Clang DWARF CFI | iOS | ARM | Clang | SjLj |
iOS ARM Clang SjLj | Linux | ARM | Clang, GCC | EHABI |
Linux ARM Clang, GCC EHABI | Linux | i386, x86_64, ARM64 | Clang, GCC | DWARF CFI |
Linux i386, x86_64, ARM64 Clang, GCC DWARF CFI | macOS | i386, x86_64 | Clang, GCC | DWARF CFI |
macOS i386, x86_64 Clang, GCC DWARF CFI | NetBSD | x86_64 | Clang, GCC | DWARF CFI |
NetBSD x86_64 Clang, GCC DWARF CFI | Windows | i386, x86_64, ARM, ARM64 | Clang | DWARF CFI |
Windows i386, x86_64, ARM, ARM64 Clang DWARF CFI
============ ======================== ============ ========================
The following minimum compiler versions are strongly recommended. The following minimum compiler versions are strongly recommended.
* Clang 3.5 and above - Clang 3.5 and above
* GCC 4.7 and above. - GCC 4.7 and above.
Anything older *may* work. 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** **Bug Reports**
If you think you've found a bug in libunwind, please report it using If you think you've found a bug in libunwind, please report it using
the `LLVM bug tracker`_. If you're not sure, you the [LLVM bug tracker]. If you're not sure, you
can ask for support on the `Runtimes forum`_ or on Discord. can ask for support on the [Runtimes forum] or on Discord.
Please use the tag "libunwind" for new threads. Please use the tag "libunwind" for new threads.
**Patches** **Patches**
If you want to contribute a patch to libunwind, please start by reading the LLVM 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** **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/>`_

35
lldb/source/Plugins/TraceExporter/docs/htr.md
View file

@ -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. 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:** 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. **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: **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, - **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 metadata is only stored for instructions that are of interest, not every instruction in the trace. HTR contains a
single instruction layer. 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 - **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 *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. 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. **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. 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) 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. 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** **Basic Super Block Reduction**
@ -36,13 +36,16 @@ 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 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:* *Procedure to find all super blocks:*
- For each block, compute the number of distinct predecessor and successor 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 - **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
- **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. - 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.

165
llvm-libgcc/docs/LLVMLibgcc.md
View file

@ -1,33 +1,29 @@
.. llvm-libgcc: # llvm-libgcc
=========== :::{contents}
llvm-libgcc :local: true
=========== :::
.. contents::
:local:
**Note that these instructions assume a Linux and bash-friendly environment. **Note that these instructions assume a Linux and bash-friendly environment.
YMMV if you’re on a non Linux-based platform.** 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 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 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 base][5]. Some software is transitively dependent on libgcc because glibc makes
hardcoded calls to functions in libgcc_s. For example, the function hardcoded calls to functions in libgcc_s. For example, the function
``__GI___backtrace`` eventually makes its way to a [hardcoded dlopen to libgcc_s' `__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 but different implementations, the two libraries end up [cross-talking, which
ultimately results in a segfault][2]. ultimately results in a segfault][2].
To solve this problem, libunwind needs libgcc "front" that is, link the To solve this problem, libunwind needs libgcc "front" that is, link the
necessary functions from compiler-rt and libunwind into an archive and shared necessary functions from compiler-rt and libunwind into an archive and shared
object that advertise themselves as ``libgcc.a``, ``libgcc_eh.a``, and 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 `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 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 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 level: no program source needs to be edited. Thus, the end result is for a
@ -37,22 +33,18 @@ 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 family, and then generate symlinks named for our "libgcc" that point to their
corresponding libunwind counterparts. corresponding libunwind counterparts.
.. _alternatives ## Alternatives
Alternatives
============
We alternatively considered patching glibc so that the source doesn't directly 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. 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 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 binaries that are built using libgcc will still end up having cross-talk between
the differing implementations. 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 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 managers who want to replace libgcc with compiler-rt and libunwind, but cannot
@ -60,85 +52,77 @@ 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 managers must have worked out their compatibility requirements ahead of using
llvm-libgcc. llvm-libgcc.
.. _cmake options: (cmake-options)=
CMake options ## CMake options
=============
.. option:: `LLVM_LIBGCC_EXPLICIT_OPT_IN` :::{option} `LLVM_LIBGCC_EXPLICIT_OPT_IN`
**Required** **Required**
Since llvm-libgcc is such a fundamental, low-level component, we have made it 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. difficult to accidentally build, by requiring you to set an opt-in flag.
:::
.. _Building llvm-libgcc ### Building llvm-libgcc
Building llvm-libgcc
--------------------
The first build tree is a mostly conventional build tree and gets you a Clang The first build tree is a mostly conventional build tree and gets you a Clang
build with these compiler-rt symbols exposed. build with these compiler-rt symbols exposed.
.. code-block:: bash ```bash
# Assumes $(PWD) is /path/to/llvm-project # Assumes $(PWD) is /path/to/llvm-project
$ cmake -GNinja -S llvm -B build-primary \ $ cmake -GNinja -S llvm -B build-primary \
-DCMAKE_BUILD_TYPE=Release \ -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_CROSSCOMPILING=On \ -DCMAKE_CROSSCOMPILING=On \
-DCMAKE_INSTALL_PREFIX=/tmp/aarch64-unknown-linux-gnu \ -DCMAKE_INSTALL_PREFIX=/tmp/aarch64-unknown-linux-gnu \
-DLLVM_ENABLE_PROJECTS='clang' \ -DLLVM_ENABLE_PROJECTS='clang' \
-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;llvm-libgcc" \ -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;llvm-libgcc" \
-DLLVM_TARGETS_TO_BUILD=AArch64 \ -DLLVM_TARGETS_TO_BUILD=AArch64 \
-DLLVM_DEFAULT_TARGET_TRIPLE=aarch64-unknown-linux-gnu \ -DLLVM_DEFAULT_TARGET_TRIPLE=aarch64-unknown-linux-gnu \
-DLLVM_LIBGCC_EXPLICIT_OPT_IN=Yes -DLLVM_LIBGCC_EXPLICIT_OPT_IN=Yes
$ ninja -C build-primary install $ ninja -C build-primary install
```
It's very important to notice that neither ``compiler-rt``, nor ``libunwind``, It's very important to notice that neither `compiler-rt`, nor `libunwind`,
are listed in ``LLVM_ENABLE_RUNTIMES``. llvm-libgcc makes these subprojects, and 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 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 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. 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 This gets you a copy of libunwind with the libgcc symbols. You can verify this
using ``readelf``. using `readelf`.
.. code-block:: bash ```bash
$ llvm-readelf -W --dyn-syms "${LLVM_LIBGCC_SYSROOT}/lib/libunwind.so" | grep FUNC | grep GCC_3.0
```
$ 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. 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: llvm-libgcc currently supports the following target triples:
* ``aarch64-*-*-*`` - `aarch64-*-*-*`
* ``armv7a-*-*-gnueabihf`` - `armv7a-*-*-gnueabihf`
* ``i386-*-*-*`` - `i386-*-*-*`
* ``x86_64-*-*-*`` - `x86_64-*-*-*`
If you would like to support another triple (e.g. ``powerpc64-*-*-*``), you'll 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``. 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
-------------------------------
To generate a new version script, we need to generate the list of symbols that 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 The prerequisites for generating a version script are a binaries for the three
aforementioned libraries targeting your architecture (without having built aforementioned libraries targeting your architecture (without having built
llvm-libgcc). llvm-libgcc).
@ -146,42 +130,39 @@ llvm-libgcc).
Once these libraries are in place, to generate a new version script, run the Once these libraries are in place, to generate a new version script, run the
following command. following command.
.. code-block:: bash ```bash
/path/to/llvm-project
/path/to/llvm-project $ export ARCH=powerpc64
$ export ARCH=powerpc64 $ llvm/tools/llvm-libgcc/generate_version_script.py \
$ llvm/tools/llvm-libgcc/generate_version_script.py \ --compiler_rt=/path/to/libclang_rt.builtins-${ARCH}.a \
--compiler_rt=/path/to/libclang_rt.builtins-${ARCH}.a \ --libunwind=/path/to/libunwind.a \
--libunwind=/path/to/libunwind.a \ --libgcc_s=/path/to/libgcc_s.so.1 \
--libgcc_s=/path/to/libgcc_s.so.1 \ --output=${ARCH}
--output=${ARCH} ```
This will generate a new version script a la 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. in the next section.
.. _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 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. 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 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 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, 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 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 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 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. the new version section, with the appropriate include guards.
There are a few macros that aim to improve readability. There are a few macros that aim to improve readability.
* ``ARM_GNUEABIHF``, which targets exactly ``arm-*-*-gnueabihf``. - `ARM_GNUEABIHF`, which targets exactly `arm-*-*-gnueabihf`.
* ``GLOBAL_X86``, which should be used to target both x86 and x86_64, regardless - `GLOBAL_X86`, which should be used to target both x86 and x86_64, regardless
of the triple. of the triple.
* ``GLOBAL_32BIT``, which is be used to target 32-bit platforms. - `GLOBAL_32BIT`, which is be used to target 32-bit platforms.
* ``GLOBAL_64BIT``, which is be used to target 64-bit platforms. - `GLOBAL_64BIT`, which is be used to target 64-bit platforms.

1
offload/docs/conf.py
View file

@ -18,6 +18,7 @@ source_suffix = {
".rst": "restructuredtext", ".rst": "restructuredtext",
".md": "markdown", ".md": "markdown",
} }
myst_enable_extensions = ["colon_fence"]
templates_path = ["_templates"] templates_path = ["_templates"]
exclude_patterns = [] exclude_patterns = []

29
offload/docs/index.md
View file

@ -1,21 +1,20 @@
.. Offload documentation master file, created by % Offload documentation master file, created by
sphinx-quickstart on Fri Jul 4 14:59:13 2025. % sphinx-quickstart on Fri Jul 4 14:59:13 2025.
You can adapt this file completely to your liking, but it should at least % You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive. % contain the root `toctree` directive.
Welcome to Offload's documentation! # Welcome to Offload's documentation!
===================================
.. toctree:: :::{toctree}
:maxdepth: 2 :caption: 'Contents:'
: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`