llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-lldb Author: Reid Kleckner (rnk) <details> <summary>Changes</summary> 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. --- Patch is 57.55 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/210209.diff 12 Files Affected: - (modified) compiler-rt/docs/ASanABI.md (+29-31) - (modified) compiler-rt/docs/BuildingCompilerRT.md (+34-27) - (modified) compiler-rt/docs/TestingGuide.md (+34-36) - (modified) flang/docs/CommandGuide/index.md (+43-39) - (modified) libsycl/docs/CodingGuidelines.md (+18-24) - (modified) libsycl/docs/index.md (+109-102) - (modified) libunwind/docs/BuildingLibunwind.md (+49-43) - (modified) libunwind/docs/index.md (+40-50) - (modified) lldb/source/Plugins/TraceExporter/docs/htr.md (+19-17) - (modified) llvm-libgcc/docs/LLVMLibgcc.md (+74-93) - (modified) offload/docs/conf.py (+1) - (modified) offload/docs/index.md (+14-15) ``````````diff diff --git a/compiler-rt/docs/ASanABI.md b/compiler-rt/docs/ASanABI.md index 6fc2594f91ae9..5d2f701f44331 100644 --- a/compiler-rt/docs/ASanABI.md +++ b/compiler-rt/docs/ASanABI.md @@ -1,51 +1,49 @@ -.. _BuildingCompilerRT: +(buildingcompilerrt)= -============================ -Darwin Sanitizers Stable ABI -============================ +# Darwin Sanitizers Stable ABI Some OSes like Darwin want to include the AddressSanitizer runtime by establishing a stable ASan ABI. lib/asan_abi contains a secondary stable ABI for Darwin use and potentially others. The Stable ABI has minimal impact on the community, prioritizing stability over performance. -The Stable ABI is isolated by a “shim” layer which maps the unstable ABI to the stable ABI. It consists of a static library (libclang_rt.asan_abi_osx.a) that contains simple mappings of the existing ASan ABI to the smaller Stable ABI. After linking with the static shim library, only calls to the Stable ABI remain. +The Stable ABI is isolated by a “shim” layer which maps the unstable ABI to the stable ABI. It consists of a static library (libclang_rt.asan_abi_osx.a) that contains simple mappings of the existing ASan ABI to the smaller Stable ABI. After linking with the static shim library, only calls to the Stable ABI remain. - Sample content of the shim: +Sample content of the shim: - .. 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: - - * An existing ABI function is changed to return the input parameter on success or NULL on failure. In this scenario, a reasonable change to the shim would be to modify the function signature appropriately and to simply guess at a common-sense implementation. - - .. code-block:: c - - uptr __asan_load1(uptr p) { __asan_abi_loadn(p, 1, true); return p; } +Following are some examples of reasonable responses to such changes: - * 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 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; } + ``` - void __asan_load128(uptr p) { __asan_abi_loadn(p, 128, true); } +- 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 entry point is added to the existing ABI for which there is no obvious stable ABI implementation: In this case, doing nothing in a no-op stub would be acceptable, assuming existing features of ASan can still work without an actual implementation of this new function. + ```c + void __asan_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_prefetch(uptr p) { } + ```c + void __asan_prefetch(uptr p) { } + ``` - * An entrypoint in the existing ABI is deprecated and/or deleted: +- An entrypoint in the existing ABI is deprecated and/or deleted: - .. code-block:: c + ```c + (Delete the entrypoint from the shim.) + ``` - (Delete the entrypoint from the shim.) diff --git a/compiler-rt/docs/BuildingCompilerRT.md b/compiler-rt/docs/BuildingCompilerRT.md index 98f54ae444123..eec7574dcea34 100644 --- a/compiler-rt/docs/BuildingCompilerRT.md +++ b/compiler-rt/docs/BuildingCompilerRT.md @@ -1,13 +1,12 @@ -.. _BuildingCompilerRT: +(buildingcompilerrt)= -=============== -Building Compiler-RT -=============== +# Building Compiler-RT -.. contents:: - :local: +:::{contents} +:local: true +::: -.. _build instructions: +(build-instructions)= The instructions on this page are aimed at vendors who ship Compiler-RT as part of an operating system distribution, a toolchain or similar shipping vehicles. If you @@ -15,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``. +::: + diff --git a/compiler-rt/docs/TestingGuide.md b/compiler-rt/docs/TestingGuide.md index a1419ede02fed..a94ed6d65f9b8 100644 --- a/compiler-rt/docs/TestingGuide.md +++ b/compiler-rt/docs/TestingGuide.md @@ -1,67 +1,65 @@ -======================================== -Compiler-rt Testing Infrastructure Guide -======================================== +# Compiler-rt Testing Infrastructure Guide -.. contents:: - :local: +:::{contents} +:local: true +::: -Overview -======== +## Overview This document is the reference manual for the compiler-rt modifications to the testing infrastructure. Documentation for the infrastructure itself can be found at -:ref:`llvm_testing_guide`. +{ref}`llvm_testing_guide`. -LLVM testing infrastructure organization -======================================== +## LLVM testing infrastructure organization The compiler-rt testing infrastructure contains regression tests which are run -as part of the usual ``make check-all`` and are expected to always pass -- they +as part of the usual `make check-all` and are expected to always pass -- they should be run before every commit. -Quick start -=========== +## Quick start The regressions tests are in the "compiler-rt" module and are normally checked -out in the directory ``llvm/projects/compiler-rt/test``. Use ``make check-all`` +out in the directory `llvm/projects/compiler-rt/test`. Use `make check-all` to run the regression tests after building compiler-rt. -REQUIRES, XFAIL, etc. ---------------------- +### REQUIRES, XFAIL, etc. Sometimes it is necessary to restrict a test to a specific target or mark it as -an "expected fail" or XFAIL. This is normally achieved using ``REQUIRES:`` or -``XFAIL:`` and the ``target=<target-triple>`` feature, typically with a regular +an "expected fail" or XFAIL. This is normally achieved using `REQUIRES:` or +`XFAIL:` and the `target=<target-triple>` feature, typically with a regular expression matching an appropriate substring of the triple. Unfortunately, the behaviour of this is somewhat quirky in compiler-rt. There are two main pitfalls to avoid. The first pitfall is that these regular expressions may inadvertently match -more triples than expected. For example, ``XFAIL: target=mips{{.*}}`` matches -``mips-linux-gnu``, ``mipsel-linux-gnu``, ``mips64-linux-gnu``, and -``mips64el-linux-gnu``. Including a trailing ``-`` such as in -``XFAIL: target=mips-{{.*}}`` can help to mitigate this quirk but even that has +more triples than expected. For example, `XFAIL: target=mips{{.*}}` matches +`mips-linux-gnu`, `mipsel-linux-gnu`, `mips64-linux-gnu`, and +`mips64el-linux-gnu`. Including a trailing `-` such as in +`XFAIL: target=mips-{{.*}}` can help to mitigate this quirk but even that has issues as described below. The second pitfall is that the default target triple is often inappropriate for compiler-rt tests since compiler-rt tests may be compiled for multiple targets. -For example, a typical build on an ``x86_64-linux-gnu`` host will often run the -tests for both x86_64 and i386. In this situation ``XFAIL: target=x86_64{{{.*}}`` -will mark both the x86_64 and i386 tests as an expected failure while -``XFAIL: target=i386{{.*}}`` will have no effect at all. +For example, a typical build on an `x86_64-linux-gnu` host will often run the +tests for both x86_64 and i386. In this situation `XFAIL: target=x86_64{{{.*}}` +will mark both the x86_64 and i386 tests as an expected failure while +`XFAIL: target=i386{{.*}}` will have no effect at all. To remedy both pitfalls, compiler-rt tests provide a feature string which can be used to specify a single target. This string is of the form -``target-is-${arch}`` where ``${arch}}`` is one of the values from the -following lines of the CMake output:: +`target-is-${arch}` where `${arch}}` is one of the values from the +following lines of the CMake output: - -- Compiler-RT supported architectures: x86_64;i386 - -- Builtin supported architectures: i386;x86_64 +``` +-- Compiler-RT supported architectures: x86_64;i386 +-- Builtin supported architectures: i386;x86_64 +``` -So for example ``XFAIL: target-is-x86_64`` will mark a test as expected to fail -on x86_64 without also affecting the i386 test and ``XFAIL: target-is-i386`` +So for example `XFAIL: target-is-x86_64` will mark a test as expected to fail +on x86_64 without also affecting the i386 test and `XFAIL: target-is-i386` will mark a test as expected to fail on i386 even if the default target triple -is ``x86_64-linux-gnu``. Directives that use these ``target-is-${arch}`` string -require exact matches so ``XFAIL: target-is-mips``, -``XFAIL: target-is-mipsel``, ``XFAIL: target-is-mips64``, and -``XFAIL: target-is-mips64el`` all refer to different MIPS targets. +is `x86_64-linux-gnu`. Directives that use these `target-is-${arch}` string +require exact matches so `XFAIL: target-is-mips`, +`XFAIL: target-is-mipsel`, `XFAIL: target-is-mips64`, and +`XFAIL: target-is-mips64el` all refer to different MIPS targets. + diff --git a/flang/docs/CommandGuide/index.md b/flang/docs/CommandGuide/index.md index 1ba97464242e4..93473b7a9fc9e 100644 --- a/flang/docs/CommandGuide/index.md +++ b/flang/docs/CommandGuide/index.md @@ -1,63 +1,67 @@ -flang - the Flang Fortran compiler -================================== +# flang - the Flang Fortran compiler -SYNOPSIS --------- +## SYNOPSIS -:program:`flang` [*options*] *filename ...* +{program}`flang` \[*options*\] *filename ...* -DESCRIPTION ------------ +## DESCRIPTION -:program:`flang` is a Fortran compiler which supports all of the Fortran 95 and +{program}`flang` is a Fortran compiler which supports all of the Fortran 95 and many newer language features. Flang supports OpenMP and has some support for OpenACC and CUDA. It encompasses preprocessing, parsing, optimization, code -generation, assembly, and linking. Depending on the options passed in, Flang +generation, assembly, and linking. Depending on the options passed in, Flang will perform only some, or all, of these actions. While Flang is highly integrated, it is important to understand the stages of compilation in order to -understand how to invoke it. These stages are: +understand how to invoke it. These stages are: Driver - The flang executable is actually a small driver that orchestrates the - execution of other tools such as the compiler, assembler and linker. - Typically you do not need to interact with the driver, but you - transparently use it to run the other tools. + +: The flang executable is actually a small driver that orchestrates the + execution of other tools such as the compiler, assembler and linker. + Typically you do not need to interact with the driver, but you + transparently use it to run the other tools. Preprocessing - This stage performs tokenization of the input source file, macro expansion, - #include expansion and handles other preprocessor directives. + +: This stage performs tokenization of the input source file, macro expansion, + #include expansion and handles other preprocessor directives. Parsing and Semantic Analysis - This stage parses the input file, translating preprocessor tokens into a - parse tree. Once in the form of a parse tree, it applies semantic - analysis to compute types for expressions and determine whether - the code is well formed. Parse errors and most compiler warnings - are generated by this stage. + +: This stage parses the input file, translating preprocessor tokens into a + parse tree. Once in the form of a parse tree, it applies semantic + analysis to compute types for expressions and determine whether + the code is well formed. Parse errors and most compiler warnings + are generated by this stage. Code Generation and Optimization - This stage translates the parse tree into intermediate code (known as - "LLVM IR") and, ultimately, machine code. It also optimizes this - intermediate code and handles target-specific code generation. The output - of this stage is typically a ".s" file, referred to as an "assembly" file. - Flang also supports the use of an integrated assembler, in which the code - generator produces object files directly. This avoids the overhead of - generating the ".s" file and calling the target assembler explicitly. +: This stage translates the parse tree into intermediate code (known as + "LLVM IR") and, ultimately, machine code. It also optimizes this + intermediate code and handles target-specific code generation. The output + of this stage is typically a ".s" file, referred to as an "assembly" file. + + Flang also supports the use of an integrated assembler, in which the code + generator produces object files directly. This avoids the overhead of + generating the ".s" file and calling the target assembler explicitly. Assembler - This stage runs the target assembler to translate the output of the - compiler into a target object file. The output of this stage is typically - a ".o" file, referred to as an "object" file. + +: This stage runs the target assembler to translate the output of the + compiler into a target object file. The output of this stage is typically + a ".o" file, referred to as an "object" file. Linker - This stage runs the target linker to merge multiple object files into an - executable or dynamic library. The output of this stage is typically - an "a.out", ".dylib" or ".so" file. -OPTIONS -------- +: This stage runs the target linker to merge multiple object files into an + executable or dynamic library. The output of this stage is typically + an "a.out", ".dylib" or ".so" file. + +## OPTIONS + +:::{toctree} +:maxdepth: 1 -.. toctree:: - :maxdepth: 1 +FlangCommandLineOptions +::: - FlangCommandLineOptions diff --git a/libsycl/docs/CodingGuidelines.md b/libsycl/docs/CodingGuidelines.md index 7aece05a3e50b..0709c556d78fa 100644 --- a/libsycl/docs/CodingGuidelines.md +++ b/libsycl/docs/CodingGuidelines.md @@ -1,39 +1,33 @@ -======================== -Libsycl Coding Standards -======================== +# Libsycl Coding Standards -.. contents:: - :local: +:::{contents} +:local: true +::: -Introduction -============ +## Introduction -The ``libsycl`` project follows the -`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_ with +The `libsycl` project follows the +[LLVM Coding Standards](https://llvm.org/docs/CodingStandards.html) with exceptions as described in this document. -Naming ------- +### Naming -Names of Macros, Types, Functions, Variables, and Enumerators -^^^^^^^^^^^... [truncated] `````````` </details> https://github.com/llvm/llvm-project/pull/210209 _______________________________________________ llvm-branch-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-branch-commits
