[docs] Finish misc MyST migration (#210209)
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
+29
-31
@@ -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:
|
||||
|
||||
.. 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); }
|
||||
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.
|
||||
|
||||
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:
|
||||
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.)
|
||||
|
||||
@@ -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,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
|
||||
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
|
||||
|
||||
.. option:: COMPILER_RT_INSTALL_PATH:PATH
|
||||
:::{option} COMPILER_RT_INSTALL_PATH:PATH
|
||||
|
||||
**Default**: ```` (empty relative path)
|
||||
|
||||
@@ -51,57 +50,65 @@ Compiler-RT specific options
|
||||
``-DCOMPILER_RT_INSTALL_PATH:PATH=...`` not
|
||||
``-DCOMPILER_RT_INSTALL_PATH=...``, otherwise CMake will convert the
|
||||
path to an absolute path.
|
||||
:::
|
||||
|
||||
.. 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``.
|
||||
:::
|
||||
|
||||
.. 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``.
|
||||
:::
|
||||
|
||||
.. 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``.
|
||||
:::
|
||||
|
||||
.. 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``.
|
||||
:::
|
||||
|
||||
.. 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.
|
||||
:::
|
||||
|
||||
.. 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-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
|
||||
installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
|
||||
to install libraries to ``/usr/lib64``.
|
||||
:::
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
## OPTIONS
|
||||
|
||||
:::{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
FlangCommandLineOptions
|
||||
:::
|
||||
|
||||
FlangCommandLineOptions
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
+108
-101
@@ -1,140 +1,147 @@
|
||||
===========================
|
||||
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++
|
||||
```c++
|
||||
#include <sycl/sycl.hpp>
|
||||
|
||||
#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;
|
||||
}
|
||||
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
|
||||
```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
|
||||
installprefix=`pwd`/install
|
||||
llvm=`pwd`
|
||||
mkdir -p $build_llvm
|
||||
mkdir -p $installprefix
|
||||
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
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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``:
|
||||
- `exception`: methods with context are not implemented, to add once context is ready
|
||||
|
||||
* ``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``
|
||||
- `platform`: deprecated info descriptor is not implemented (`info::platform::extensions`), to implement on RT level with `device::get_info<info::device::aspects>()`
|
||||
|
||||
* 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``:
|
||||
- `device`:
|
||||
|
||||
* 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
|
||||
* 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)
|
||||
- `context`: to implement get_info, properties & public constructors once context support is added to liboffload
|
||||
|
||||
* ``property_list``: to fully implement and integrate with existing SYCL runtime classes supporting it
|
||||
* usm allocations:
|
||||
- `queue`:
|
||||
|
||||
* 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)
|
||||
- to implement USM methods
|
||||
|
||||
* ``event``:
|
||||
- `memcpy`: enable the host-to-host case (blocked by liboffload limitations)
|
||||
|
||||
* 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
|
||||
- to implement synchronization methods
|
||||
|
||||
* ``range``, ``id`` - __SYCL_DISABLE_ID_TO_INT_CONV__ and __SYCL_ASSUME_ID_RANGE optimizations are not implemented
|
||||
* general opens:
|
||||
- to implement submit & copy with accessors (low priority)
|
||||
|
||||
* define a way to report errors from object dtors
|
||||
* unittests: add functions to reset libsycl internal state completely (static variables)
|
||||
- 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
|
||||
|
||||
- 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)
|
||||
|
||||
@@ -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,124 @@ 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 [CMake Options](#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
|
||||
|
||||
.. option:: LIBUNWIND_ENABLE_ASSERTIONS:BOOL
|
||||
:::{option} LIBUNWIND_ENABLE_ASSERTIONS:BOOL
|
||||
|
||||
**Default**: ``ON``
|
||||
|
||||
Toggle assertions independent of the build mode.
|
||||
:::
|
||||
|
||||
.. option:: LIBUNWIND_ENABLE_PEDANTIC:BOOL
|
||||
:::{option} LIBUNWIND_ENABLE_PEDANTIC:BOOL
|
||||
|
||||
**Default**: ``ON``
|
||||
|
||||
Compile with -Wpedantic.
|
||||
:::
|
||||
|
||||
.. option:: LIBUNWIND_ENABLE_WERROR:BOOL
|
||||
:::{option} LIBUNWIND_ENABLE_WERROR:BOOL
|
||||
|
||||
**Default**: ``OFF``
|
||||
|
||||
Compile with -Werror
|
||||
:::
|
||||
|
||||
.. option:: LIBUNWIND_ENABLE_SHARED:BOOL
|
||||
:::{option} LIBUNWIND_ENABLE_SHARED:BOOL
|
||||
|
||||
**Default**: ``ON``
|
||||
|
||||
Build libunwind as a shared library.
|
||||
:::
|
||||
|
||||
.. option:: LIBUNWIND_ENABLE_STATIC:BOOL
|
||||
:::{option} LIBUNWIND_ENABLE_STATIC:BOOL
|
||||
|
||||
**Default**: ``ON``
|
||||
|
||||
Build libunwind as a static archive.
|
||||
:::
|
||||
|
||||
.. option:: LIBUNWIND_ENABLE_CROSS_UNWINDING:BOOL
|
||||
:::{option} LIBUNWIND_ENABLE_CROSS_UNWINDING:BOOL
|
||||
|
||||
**Default**: ``OFF``
|
||||
|
||||
Enable cross-platform unwinding support.
|
||||
:::
|
||||
|
||||
.. option:: LIBUNWIND_ENABLE_ARM_WMMX:BOOL
|
||||
:::{option} LIBUNWIND_ENABLE_ARM_WMMX:BOOL
|
||||
|
||||
**Default**: ``OFF``
|
||||
|
||||
Enable unwinding support for ARM WMMX registers.
|
||||
:::
|
||||
|
||||
.. option:: LIBUNWIND_ENABLE_THREADS:BOOL
|
||||
:::{option} LIBUNWIND_ENABLE_THREADS:BOOL
|
||||
|
||||
**Default**: ``ON``
|
||||
|
||||
Build libunwind with threading support.
|
||||
:::
|
||||
|
||||
.. 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``.
|
||||
:::
|
||||
|
||||
+40
-50
@@ -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/>`_
|
||||
|
||||
@@ -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.
|
||||
- **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.
|
||||
- **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,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
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
@@ -1,33 +1,29 @@
|
||||
.. 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 +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
|
||||
corresponding libunwind counterparts.
|
||||
|
||||
.. _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 +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
|
||||
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
|
||||
difficult to accidentally build, by requiring you to set an opt-in flag.
|
||||
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
|
||||
|
||||
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
|
||||
```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
|
||||
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``.
|
||||
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.
|
||||
|
||||
(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
|
||||
|
||||
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 +130,39 @@ 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`
|
||||
|
||||
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.
|
||||
|
||||
@@ -18,6 +18,7 @@ source_suffix = {
|
||||
".rst": "restructuredtext",
|
||||
".md": "markdown",
|
||||
}
|
||||
myst_enable_extensions = ["colon_fence"]
|
||||
|
||||
templates_path = ["_templates"]
|
||||
exclude_patterns = []
|
||||
|
||||
+14
-15
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user