diff options
Diffstat (limited to 'llvm/docs')
| -rw-r--r-- | llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst | 62 | ||||
| -rw-r--r-- | llvm/docs/AMDGPUUsage.rst | 16 | ||||
| -rw-r--r-- | llvm/docs/CMakeLists.txt | 22 | ||||
| -rw-r--r-- | llvm/docs/CallGraphSection.md | 6 | ||||
| -rw-r--r-- | llvm/docs/GettingStartedVS.rst | 13 | ||||
| -rw-r--r-- | llvm/docs/LangRef.rst | 12 | ||||
| -rw-r--r-- | llvm/docs/ReleaseNotes.md | 12 |
7 files changed, 83 insertions, 60 deletions
diff --git a/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst index ba670d3..f472b862 100644 --- a/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst +++ b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst @@ -37,13 +37,13 @@ includes contributions to open source projects such as LLVM [:ref:`LLVM The LLVM compiler has upstream support for commercially available AMD GPU hardware (AMDGPU) [:ref:`AMDGPU-LLVM <amdgpu-dwarf-AMDGPU-LLVM>`]. The open -source ROCgdb [:ref:`AMD-ROCgdb <amdgpu-dwarf-AMD-ROCgdb>`] GDB based debugger +source ROCgdb [:ref:`AMD-ROCgdb <amdgpu-dwarf-AMD-ROCgdb>`] GDB-based debugger also has support for AMDGPU which is being upstreamed. Support for AMDGPU is also being added by third parties to the GCC [:ref:`GCC <amdgpu-dwarf-GCC>`] compiler and the Perforce TotalView HPC Debugger [:ref:`Perforce-TotalView <amdgpu-dwarf-Perforce-TotalView>`]. -To support debugging heterogeneous programs several features that are not +To support debugging heterogeneous programs, several features that are not provided by current DWARF Version 5 [:ref:`DWARF <amdgpu-dwarf-DWARF>`] have been identified. The :ref:`amdgpu-dwarf-extensions` section gives an overview of the extensions devised to address the missing features. The extensions seek to @@ -107,7 +107,7 @@ for each in terms of heterogeneous debugging. DWARF Version 5 does not allow location descriptions to be entries on the DWARF expression stack. They can only be the final result of the evaluation of a DWARF expression. However, by allowing a location description to be a first-class -entry on the DWARF expression stack it becomes possible to compose expressions +entry on the DWARF expression stack, it becomes possible to compose expressions containing both values and location descriptions naturally. It allows objects to be located in any kind of memory address space, in registers, be implicit values, be undefined, or a composite of any of these. @@ -123,20 +123,20 @@ non-default address spaces and generalizing the power of composite location descriptions to any kind of location description. For those familiar with the definition of location descriptions in DWARF Version -5, the definitions in these extensions are presented differently, but does in +5, the definitions in these extensions are presented differently, but do in fact define the same concept with the same fundamental semantics. However, it does so in a way that allows the concept to extend to support address spaces, bit addressing, the ability for composite location descriptions to be composed of any kind of location description, and the ability to support objects located at multiple places. Collectively these changes expand the set of architectures -that can be supported and improves support for optimized code. +that can be supported and improve support for optimized code. Several approaches were considered, and the one presented, together with the extensions it enables, appears to be the simplest and cleanest one that offers the greatest improvement of DWARF's ability to support debugging optimized GPU and non-GPU code. Examining the GDB debugger and LLVM compiler, it appears only to require modest changes as they both already have to support general use of -location descriptions. It is anticipated that will also be the case for other +location descriptions. It is anticipated that this will also be the case for other debuggers and compilers. GDB has been modified to evaluate DWARF Version 5 expressions with location @@ -156,7 +156,7 @@ DWARF Expression Stack* [:ref:`AMDGPU-DWARF-LOC 2.2 Generalize CFI to Allow Any Location Description Kind --------------------------------------------------------- -CFI describes restoring callee saved registers that are spilled. Currently CFI +CFI describes restoring callee saved registers that are spilled. Currently, CFI only allows a location description that is a register, memory address, or implicit location description. AMDGPU optimized code may spill scalar registers into portions of vector registers. This requires extending CFI to allow any @@ -223,7 +223,7 @@ infinite precision offsets to allow it to correctly track a series of positive and negative offsets that may transiently overflow or underflow, but end up in range. This is simple for the arithmetic operations as they are defined in terms of two's complement arithmetic on a base type of a fixed size. Therefore, the -offset operation define that integer overflow is ill-formed. This is in contrast +offset operation defines that integer overflow is ill-formed. This is in contrast to the ``DW_OP_plus``, ``DW_OP_plus_uconst``, and ``DW_OP_minus`` arithmetic operations which define that it causes wrap-around. @@ -359,7 +359,7 @@ address space at a fixed address. The ``DW_OP_LLVM_form_aspace_address`` (see :ref:`amdgpu-dwarf-memory-location-description-operations`) operation is defined -to create a memory location description from an address and address space. If +to create a memory location description from an address and address space. It can be used to specify the location of a variable that is allocated in a specific address space. This allows the size of addresses in an address space to be larger than the generic type. It also allows a consumer great implementation @@ -372,7 +372,7 @@ In contrast, if the ``DW_OP_LLVM_form_aspace_address`` operation had been defined to produce a value, and an implicit conversion to a memory location description was defined, then it would be limited to the size of the generic type (which matches the size of the default address space). An implementation -would likely have to use *reserved ranges* of value to represent different +would likely have to use *reserved ranges* of values to represent different address spaces. Such a value would likely not match any address value in the actual hardware. That would require the consumer to have special treatment for such values. @@ -528,7 +528,7 @@ active. To describe the conceptual location of non-active lanes requires an attribute that has an expression that computes the source location PC for each lane. -For efficiency, the expression calculates the source location the wavefront as a +For efficiency, the expression calculates the source location of the wavefront as a whole. This can be done using the ``DW_OP_LLVM_select_bit_piece`` (see :ref:`amdgpu-dwarf-operation-to-create-vector-composite-location-descriptions`) operation. @@ -564,7 +564,7 @@ information entry to indicate that there is additional target architecture specific information in the debugging information entries of that compilation unit. This allows a consumer to know what extensions are present in the debugger information entries as is possible with the augmentation string of other -sections. See . +sections. The format that should be used for an augmentation string is also recommended. This allows a consumer to parse the string when it contains information from @@ -581,7 +581,7 @@ See :ref:`amdgpu-dwarf-full-and-partial-compilation-unit-entries`, AMDGPU supports programming languages that include online compilation where the source text may be created at runtime. For example, the OpenCL and HIP language -runtimes support online compilation. To support is, a way to embed the source +runtimes support online compilation. To support this, a way to embed the source text in the debug information is provided. See :ref:`amdgpu-dwarf-line-number-information`. @@ -589,16 +589,16 @@ See :ref:`amdgpu-dwarf-line-number-information`. 2.17 Allow MD5 Checksums to be Optionally Present ------------------------------------------------- -In DWARF Version 5 the file timestamp and file size can be optional, but if the -MD5 checksum is present it must be valid for all files. This is a problem if +In DWARF Version 5, the file timestamp and file size can be optional, but if the +MD5 checksum is present, it must be valid for all files. This is a problem if using link time optimization to combine compilation units where some have MD5 -checksums and some do not. Therefore, sSupport to allow MD5 checksums to be -optionally present in the line table is added. +checksums, and others do not. Therefore, the line table is extended to allow MD5 +checksums to be optional. See :ref:`amdgpu-dwarf-line-number-information`. -2.18 Add the HIP Programing Language ------------------------------------- +2.18 Add the HIP Programming Language +------------------------------------- The HIP programming language [:ref:`HIP <amdgpu-dwarf-HIP>`], which is supported by the AMDGPU, is added. @@ -617,7 +617,7 @@ hardware to allow a single instruction to execute multiple iterations using vector registers. Note that although this is similar to SIMT execution, the way a client debugger -uses the information is fundamentally different. In SIMT execution the debugger +uses the information is fundamentally different. In SIMT execution, the debugger needs to present the concurrent execution as distinct source language threads that the user can list and switch focus between. With iteration concurrency optimizations, such as software pipelining and vectorized SIMD, the debugger @@ -648,7 +648,7 @@ language loop iterations are executing concurrently. See It is common in SIMD vectorization for the compiler to generate code that promotes portions of an array into vector registers. For example, if the hardware has vector registers with 8 elements, and 8 wide SIMD instructions, the -compiler may vectorize a loop so that is executes 8 iterations concurrently for +compiler may vectorize a loop so that it executes 8 iterations concurrently for each vectorized loop iteration. On the first iteration of the generated vectorized loop, iterations 0 to 7 of @@ -691,7 +691,7 @@ Inside the loop body, the machine code loads ``src[i]`` and ``dst[i]`` into registers, adds them, and stores the result back into ``dst[i]``. Considering the location of ``dst`` and ``src`` in the loop body, the elements -``dst[i]`` and ``src[i]`` would be located in registers, all other elements are +``dst[i]`` and ``src[i]`` would be located in registers; all other elements are located in memory. Let register ``R0`` contain the base address of ``dst``, register ``R1`` contain ``i``, and register ``R2`` contain the registerized ``dst[i]`` element. We can describe the location of ``dst`` as a memory location @@ -722,7 +722,7 @@ with a register location overlaid at a runtime offset involving ``i``: ---------------------------------------------- AMDGPU supports languages, such as OpenCL, that define source language memory -spaces. Support is added to define language specific memory spaces so they can +spaces. Support is added to define language-specific memory spaces so they can be used in a consistent way by consumers. See :ref:`amdgpu-dwarf-memory-spaces`. A new attribute ``DW_AT_LLVM_memory_space`` is added to support using memory @@ -738,9 +738,9 @@ accommodates only 32 unique operations. In practice, the lack of a central registry and a desire for backwards compatibility means vendor extensions are never retired, even when standard versions are accepted into DWARF proper. This has produced a situation where the effective encoding space available for new -vendor extensions is miniscule today. +vendor extensions is minuscule today. -To expand this encoding space a new DWARF operation ``DW_OP_LLVM_user`` is +To expand this encoding space, a new DWARF operation ``DW_OP_LLVM_user`` is added which acts as a "prefix" for vendor extensions. It is followed by a ULEB128 encoded vendor extension opcode, which is then followed by the operands of the corresponding vendor extension operation. @@ -776,7 +776,7 @@ A. Changes Relative to DWARF Version 5 .. note:: Notes are included to describe how the changes are to be applied to the - DWARF Version 5 standard. They also describe rational and issues that may + DWARF Version 5 standard. They also describe rationale and issues that may need further consideration. A.2 General Description @@ -898,7 +898,7 @@ elements that can be specified are: *A current lane* - The 0 based SIMT lane identifier to be used in evaluating a user presented + The 0-based SIMT lane identifier to be used in evaluating a user presented expression. This applies to source languages that are implemented for a target architecture using a SIMT execution model. These implementations map source language threads of execution to lanes of the target architecture threads. @@ -917,7 +917,7 @@ elements that can be specified are: *A current iteration* - The 0 based source language iteration instance to be used in evaluating a user + The 0-based source language iteration instance to be used in evaluating a user presented expression. This applies to target architectures that support optimizations that result in executing multiple source language loop iterations concurrently. @@ -1845,7 +1845,7 @@ There are these special value operations currently defined: interpreted as a value of T. If a conversion is wanted it can be done explicitly using a ``DW_OP_convert`` operation. - GDB has a per register hook that allows a target specific conversion on a + GDB has a per register hook that allows a target-specific conversion on a register by register basis. It defaults to truncation of bigger registers. Removing use of the target hook does not cause any test failures in common architectures. If the compiler for a target architecture did want some @@ -1855,7 +1855,7 @@ There are these special value operations currently defined: If T is a larger type than the register size, then the default GDB register hook reads bytes from the next register (or reads out of bounds for the last register!). Removing use of the target hook does not cause - any test failures in common architectures (except an illegal hand written + any test failures in common architectures (except an illegal hand-written assembly test). If a target architecture requires this behavior, these extensions allow a composite location description to be used to combine multiple registers. @@ -2283,7 +2283,7 @@ bit offset equal to V scaled by 8 (the byte size). The implicit conversion could also be defined as target architecture specific. For example, GDB checks if V is an integral type. If it is not it gives an error. Otherwise, GDB zero-extends V to 64 bits. If the GDB target defines a - hook function, then it is called. The target specific hook function can modify + hook function, then it is called. The target-specific hook function can modify the 64-bit value, possibly sign extending based on the original value type. Finally, GDB treats the 64-bit value V as a memory location address. diff --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst index a4d110f..402fd05 100644 --- a/llvm/docs/AMDGPUUsage.rst +++ b/llvm/docs/AMDGPUUsage.rst @@ -4172,7 +4172,7 @@ non-AMD key names should be prefixed by "*vendor-name*.". "Image", or "Pipe". This may be more restrictive than indicated by "AccQual" to reflect what the - kernel actual does. If not + kernel actually does. If not present then the runtime must assume what is implied by "AccQual" and "IsConst". Values @@ -5436,8 +5436,8 @@ The fields used by CP for code objects before V3 also match those specified in ``COMPUTE_PGM_RSRC1.PRIORITY``. 13:12 2 bits FLOAT_ROUND_MODE_32 Wavefront starts execution with specified rounding - mode for single (32 - bit) floating point + mode for single (32-bit) + floating point precision floating point operations. @@ -5769,7 +5769,7 @@ The fields used by CP for code objects before V3 also match those specified in Wavefront starts execution with memory violation - exceptions exceptions + exceptions enabled which are generated when a memory violation has occurred for this wavefront from @@ -6005,7 +6005,7 @@ The fields used by CP for code objects before V3 also match those specified in FLOAT_DENORM_MODE_FLUSH_NONE 3 No Flush ====================================== ===== ==================================== - Denormal flushing is sign respecting. i.e. the behavior expected by + Denormal flushing is sign respecting, i.e., the behavior expected by ``"denormal-fp-math"="preserve-sign"``. The behavior is undefined with ``"denormal-fp-math"="positive-zero"`` @@ -16831,7 +16831,7 @@ For GFX125x: * Some memory operations contain a ``nv`` bit, for "non-volatile", which indicates memory that is not expected to change during a kernel's execution. This information is propagated to the cache lines for that address - (refered to as ``$nv``). + (referred to as ``$nv``). * When ``nv=0`` reads hit dirty ``$nv=1`` data in cache, the hardware will writeback the data to the next level in the hierarchy and then subsequently read @@ -18970,7 +18970,7 @@ On entry to a function: #. All other registers are unspecified. #. Any necessary ``s_waitcnt`` has been performed to ensure memory is available to the function. -#. Use pass-by-reference (byref) in stead of pass-by-value (byval) for struct +#. Use pass-by-reference (byref) instead of pass-by-value (byval) for struct arguments in C ABI. Callee is responsible for allocating stack memory and copying the value of the struct if modified. Note that the backend still supports byval for struct arguments. @@ -20214,7 +20214,7 @@ from the value of the ``-mcpu`` option that is passed to the assembler. .amdgpu_hsa_kernel (name) +++++++++++++++++++++++++ -This directives specifies that the symbol with given name is a kernel entry +This directive specifies that the symbol with given name is a kernel entry point (label) and the object should contain corresponding symbol of type STT_AMDGPU_HSA_KERNEL. diff --git a/llvm/docs/CMakeLists.txt b/llvm/docs/CMakeLists.txt index b4522e3..fc37c6d 100644 --- a/llvm/docs/CMakeLists.txt +++ b/llvm/docs/CMakeLists.txt @@ -136,17 +136,23 @@ if( NOT uses_ocaml LESS 0 AND LLVM_ENABLE_OCAMLDOC ) list(APPEND odoc_files -load ${odoc_file}) endforeach() - add_custom_target(ocaml_doc - COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html - COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html - COMMAND ${OCAMLFIND} ocamldoc -d ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html - -sort -colorize-code -html ${odoc_files} - COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/_ocamldoc/style.css - ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html) + set(OCAML_DOC_ADD_TO_ALL "") + if(LLVM_BUILD_DOCS) + set(OCAML_DOC_ADD_TO_ALL ALL) + endif() + + add_custom_target(ocaml_doc ${OCAML_DOC_ADD_TO_ALL} + COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html + COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html + COMMAND ${OCAMLFIND} ocamldoc -d ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html + -sort -colorize-code -html ${odoc_files} + COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/_ocamldoc/style.css + ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html) add_dependencies(ocaml_doc ${doc_targets}) - if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY) + + if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY AND LLVM_BUILD_DOCS) # ./ suffix is needed to copy the contents of html directory without # appending html/ into LLVM_INSTALL_OCAMLDOC_HTML_DIR. install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/ocamldoc/html/. diff --git a/llvm/docs/CallGraphSection.md b/llvm/docs/CallGraphSection.md index 8b18727..84d6061 100644 --- a/llvm/docs/CallGraphSection.md +++ b/llvm/docs/CallGraphSection.md @@ -1,10 +1,10 @@ -# .callgraph Section Layout +# .llvm.callgraph Section Layout -The `.callgraph` section is used to store call graph information for each function. The section contains a series of records, with each record corresponding to a single function. +The `.llvm.callgraph` section is used to store call graph information for each function. The section contains a series of records, with each record corresponding to a single function. ## Per Function Record Layout -Each record in the `.callgraph` section has the following binary layout: +Each record in the `.llvm.callgraph` section has the following binary layout: | Field | Type | Size (bits) | Description | | -------------------------------------- | ------------- | ----------- | ------------------------------------------------------------------------------------------------------- | diff --git a/llvm/docs/GettingStartedVS.rst b/llvm/docs/GettingStartedVS.rst index bc5746d..e65fd8f 100644 --- a/llvm/docs/GettingStartedVS.rst +++ b/llvm/docs/GettingStartedVS.rst @@ -126,6 +126,15 @@ These instructions were tested with Visual Studio 2019 and Python 3.9.6: cmake -S llvm\llvm -B build -DLLVM_ENABLE_PROJECTS=clang -DLLVM_TARGETS_TO_BUILD=X86 -Thost=x64 exit + .. note:: + By default, the Visual Studio project files generated by CMake use the + 32-bit toolset. If you are developing on a 64-bit version of Windows and + want to use the 64-bit toolset, pass the ``-Thost=x64`` flag when + generating the Visual Studio solution. This requires CMake 3.8.0 or later. + + For Windows on Arm the equivalent is ``-Thost=ARM64``, but this the default + for those hosts, so you do not have to use this option. + ``LLVM_ENABLE_PROJECTS`` specifies any additional LLVM projects you want to build while ``LLVM_TARGETS_TO_BUILD`` selects the compiler targets. If ``LLVM_TARGETS_TO_BUILD`` is omitted by default all targets are built @@ -149,10 +158,6 @@ These instructions were tested with Visual Studio 2019 and Python 3.9.6: * CMake generates project files for all build types. To select a specific build type, use the Configuration manager from the VS IDE or the ``/property:Configuration`` command-line option when using MSBuild. - * By default, the Visual Studio project files generated by CMake use the - 32-bit toolset. If you are developing on a 64-bit version of Windows and - want to use the 64-bit toolset, pass the ``-Thost=x64`` flag when - generating the Visual Studio solution. This requires CMake 3.8.0 or later. 13. Start Visual Studio and select configuration: diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst index 4884e2d..0c54f57 100644 --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -7517,12 +7517,12 @@ sections that the user does not want removed after linking. '``unpredictable``' Metadata ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``unpredictable`` metadata may be attached to any branch or switch -instruction. It can be used to express the unpredictability of control -flow. Similar to the ``llvm.expect`` intrinsic, it may be used to alter -optimizations related to compare and branch instructions. The metadata -is treated as a boolean value; if it exists, it signals that the branch -or switch that it is attached to is completely unpredictable. +``unpredictable`` metadata may be attached to any branch, select, or switch +instruction. It can be used to express the unpredictability of control flow. +Similar to the ``llvm.expect`` intrinsic, it may be used to alter optimizations +related to compare and branch instructions. The metadata is treated as a +boolean value; if it exists, it signals that the branch, select, or switch that +it is attached to is completely unpredictable. .. _md_dereferenceable: diff --git a/llvm/docs/ReleaseNotes.md b/llvm/docs/ReleaseNotes.md index 30aeccd..c352cd6 100644 --- a/llvm/docs/ReleaseNotes.md +++ b/llvm/docs/ReleaseNotes.md @@ -134,9 +134,13 @@ Changes to the WebAssembly Backend Changes to the Windows Target ----------------------------- +* `-fpseudo-probe-for-profiling` is now supported for COFF. + Changes to the X86 Backend -------------------------- +* `-mcpu=wildcatlake` is now supported. + Changes to the OCaml bindings ----------------------------- @@ -161,6 +165,8 @@ Changes to the Debug Info Changes to the LLVM tools --------------------------------- +* `llvm-profgen` now supports decoding pseudo probe for COFF binaries. + * `llvm-readelf` now dumps all hex format values in lower-case mode. * Some code paths for supporting Python 2.7 in `llvm-lit` have been removed. * Support for `%T` in lit has been removed. @@ -170,6 +176,12 @@ Changes to LLDB * LLDB can now set breakpoints, show backtraces, and display variables when debugging Wasm with supported runtimes (WAMR and V8). +* LLDB no longer stops processes by default when receiving SIGWINCH signals + (window resize events) on Linux. This is the default on other Unix platforms. + You can re-enable it using `process handle --notify=true --stop=true SIGWINCH`. +* The `show-progress` setting, which became a NOOP with the introduction of the + statusline, now defaults to off and controls using OSC escape codes to show a + native progress bar in supporting terminals like Ghostty and ConEmu. Changes to BOLT --------------------------------- |