diff options
Diffstat (limited to 'llvm/docs')
| -rw-r--r-- | llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst | 62 | ||||
| -rw-r--r-- | llvm/docs/AMDGPUUsage.rst | 6 | ||||
| -rw-r--r-- | llvm/docs/CMakeLists.txt | 22 | ||||
| -rw-r--r-- | llvm/docs/CallGraphSection.md | 6 | ||||
| -rw-r--r-- | llvm/docs/DirectX/DXILResources.rst | 89 | ||||
| -rw-r--r-- | llvm/docs/HowToReleaseLLVM.rst | 82 | ||||
| -rw-r--r-- | llvm/docs/LangRef.rst | 12 | ||||
| -rw-r--r-- | llvm/docs/ReleaseNotes.md | 4 |
8 files changed, 191 insertions, 92 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 402fd05..8193adc 100644 --- a/llvm/docs/AMDGPUUsage.rst +++ b/llvm/docs/AMDGPUUsage.rst @@ -488,21 +488,21 @@ Every processor supports every OS ABI (see :ref:`amdgpu-os`) with the following **GCN GFX11 (RDNA 3.5)** [AMD-GCN-GFX11-RDNA3.5]_ ----------------------------------------------------------------------------------------------------------------------- - ``gfx1150`` ``amdgcn`` APU - cumode - Architected *TBA* + ``gfx1150`` ``amdgcn`` APU - cumode - Architected Radeon 890M - wavefrontsize64 flat scratch .. TODO:: - Packed work-item Add product IDs names. - ``gfx1151`` ``amdgcn`` APU - cumode - Architected *TBA* + ``gfx1151`` ``amdgcn`` APU - cumode - Architected Radeon 8060S - wavefrontsize64 flat scratch .. TODO:: - Packed work-item Add product IDs names. - ``gfx1152`` ``amdgcn`` APU - cumode - Architected *TBA* + ``gfx1152`` ``amdgcn`` APU - cumode - Architected Radeon 860M - wavefrontsize64 flat scratch .. TODO:: - Packed 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/DirectX/DXILResources.rst b/llvm/docs/DirectX/DXILResources.rst index 91dcd5c8..f253e02f 100644 --- a/llvm/docs/DirectX/DXILResources.rst +++ b/llvm/docs/DirectX/DXILResources.rst @@ -746,3 +746,92 @@ Examples: @llvm.dx.resource.load.cbufferrow.8( target("dx.CBuffer", target("dx.Layout", {i16}, 2, 0)) %buffer, i32 %index) + +Resource dimensions +------------------- + +*relevant types: Textures and Buffer* + +The `getDimensions`_ DXIL operation returns the dimensions of a texture or +buffer resource. It returns a `Dimensions`_ type, which is a struct +containing four ``i32`` values. The values in the struct represent the size +of each dimension of the resource, and when aplicable the number of array +elements or number of samples. The mapping is defined in the +`getDimensions`_ documentation. + +The LLVM IR representation of this operation has several forms +depending on the resource type and the specific ``getDimensions`` query. +The intrinsics return a scalar or anonymous struct with up to 4 `i32` +elements. The intrinsic names include suffixes to indicate the number of +elements in the return value. The suffix `.x` indicates a single `i32` +return value, `.xy` indicates a struct with two `i32` values, and `.xyz` +indicates a struct with three `i32` values. + +Intrinsics representing queries on multisampled texture resources include +`.ms.` in their name and their return value includes an additional `i32` for +the number of samples. + +Intrinsics with `mip_level` argument and `.levels.` in their name are used +for texture resources with multiple MIP levels. Their return +struct includes an additional `i32` for the number of levels the resource has. + +.. code-block:: llvm + + i32 @llvm.dx.resource.getdimensions.x( target("dx.*") handle ) + {i32, i32} @llvm.dx.resource.getdimensions.xy( target("dx.*") handle ) + {i32, i32, i32} @llvm.dx.resource.getdimensions.xyz( target("dx.*") handle ) + {i32, i32} @llvm.dx.resource.getdimensions.levels.x( target("dx.*") handle, i32 mip_level ) + {i32, i32, i32} @llvm.dx.resource.getdimensions.levels.xy( target("dx.*") handle, i32 mip_level ) + {i32, i32, i32, i32} @llvm.dx.resource.getdimensions.levels.xyz( target("dx.*") handle, i32 mip_level ) + {i32, i32, i32} @llvm.dx.resource.getdimensions.ms.xy( target("dx.*") handle ) + {i32, i32, i32, i32} @llvm.dx.resource.getdimensions.ms.xyz( target("dx.*") handle ) + +.. list-table:: ``@llvm.dx.resource.getdimensions.*`` + :header-rows: 1 + + * - Argument + - + - Type + - Description + * - Return value + - + - `i32`, `{i32, i32}`, `{i32, i32, i32}`, or `{i32, i32, i32, i32}` + - Width, height, and depth of the resource (based on the specific suffix), and a number of levels or samples where aplicable. + * - ``%handle`` + - 0 + - ``target(dx.*)`` + - Resource handle + * - ``%mip_level`` + - 1 + - ``i32`` + - MIP level for the requested dimensions. + +Examples: + +.. code-block:: llvm + + ; RWBuffer<float4> + %dim = call i32 @llvm.dx.resource.getdimensions.x(target("dx.TypedBuffer", <4 x float>, 1, 0, 0) %handle) + + ; Texture2D + %0 = call {i32, i32} @llvm.dx.resource.getdimensions.xy(target("dx.Texture", ...) %tex2d) + %tex2d_width = extractvalue {i32, i32} %0, 0 + %tex2d_height = extractvalue {i32, i32} %0, 1 + + ; Texture2DArray with levels + %1 = call {i32, i32, i32, i32} @llvm.dx.resource.getdimensions.levels.xyz( + target("dx.Texture", ...) %tex2darray, i32 1) + %tex2darray_width = extractvalue {i32, i32, i32, i32} %1, 0 + %tex2darray_height = extractvalue {i32, i32, i32, i32} %1, 1 + %tex2darray_elem_count = extractvalue {i32, i32, i32, i32} %1, 2 + %tex2darray_levels_count = extractvalue {i32, i32, i32, i32} %1, 3 + + ; Texture2DMS + %2 = call {i32, i32, i32} @llvm.dx.resource.getdimensions.ms.xy( + target("dx.Texture", ...) %tex2dms) + %tex2dms_width = extractvalue {i32, i32, i32} %2, 0 + %tex2dms_height = extractvalue {i32, i32, i32} %2, 1 + %tex2dms_samples_count = extractvalue {i32, i32, i32} %2, 2 + +.. _Dimensions: https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#resource-operation-return-types +.. _getDimensions: https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#getdimensions diff --git a/llvm/docs/HowToReleaseLLVM.rst b/llvm/docs/HowToReleaseLLVM.rst index 1795d3a..171bf88 100644 --- a/llvm/docs/HowToReleaseLLVM.rst +++ b/llvm/docs/HowToReleaseLLVM.rst @@ -18,11 +18,11 @@ create the binary packages, please refer to the :doc:`ReleaseProcess` instead. Release Timeline ================ -LLVM is released on a time based schedule --- with major releases roughly +LLVM is released on a time-based schedule --- with major releases roughly every 6 months. In between major releases there may be dot releases. The release manager will determine if and when to make a dot release based on feedback from the community. Typically, dot releases should be made if -there are large number of bug-fixes in the stable branch or a critical bug +there are a large number of bug fixes in the stable branch or a critical bug has been discovered that affects a large number of users. Unless otherwise stated, dot releases will follow the same procedure as @@ -73,7 +73,7 @@ Release Process Summary * Generate and send out the second release candidate sources. Only *critical* bugs found during this testing phase will be fixed. Any bugs introduced by - merged patches will be fixed. If so a third round of testing is needed. + merged patches will be fixed. If so, a third round of testing is needed. * The release notes are updated. @@ -107,15 +107,15 @@ Create Release Branch and Update LLVM Version Branch the Git trunk using the following procedure: #. Remind developers that the release branching is imminent and to refrain from - committing patches that might break the build. E.g., new features, large + committing patches that might break the build, e.g., new features, large patches for works in progress, an overhaul of the type system, an exciting new TableGen feature, etc. #. Verify that the current git trunk is in decent shape by examining nightly tester and buildbot results. -#. Bump the version in trunk to N.0.0git with the script in - ``llvm/utils/release/bump-version.py``, and tag the commit with llvmorg-N-init. +#. Bump the version in trunk to ``N.0.0git`` with the script in + ``llvm/utils/release/bump-version.py``, and tag the commit with ``llvmorg-N-init``. If ``X`` is the version to be released, then ``N`` is ``X + 1``. :: $ git tag -sa llvmorg-N-init @@ -124,14 +124,14 @@ Branch the Git trunk using the following procedure: ``llvm/utils/release/clear-release-notes.py``. #. Create the release branch from the last known good revision from before the - version bump. The branch's name is release/X.x where ``X`` is the major version + version bump. The branch's name is ``release/X.x`` where ``X`` is the major version number and ``x`` is just the letter ``x``. #. On the newly-created release branch, immediately bump the version - to X.1.0git (where ``X`` is the major version of the branch.) + to ``X.1.0git`` (where ``X`` is the major version of the branch.) -#. All tags and branches need to be created in both the llvm/llvm-project and - llvm/llvm-test-suite repos. +#. All tags and branches need to be created in both the ``llvm/llvm-project`` and + ``llvm/llvm-test-suite`` repos. Tagging the LLVM Release Candidates ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -157,7 +157,7 @@ the release page. $ for f in *.xz; do gh attestation verify --owner llvm $f && gpg -b $f; done Tarballs, release binaries, or any other release artifacts must be uploaded to -GitHub. This can be done using the github-upload-release.py script in utils/release. +GitHub. This can be done using the ``github-upload-release.py`` script in ``utils/release``. :: @@ -170,10 +170,10 @@ Build The Binary Distribution Creating the binary distribution requires following the instructions :doc:`here <ReleaseProcess>`. -That process will perform both Release+Asserts and Release builds but only -pack the Release build for upload. You should use the Release+Asserts sysroot, +That process performs both Release+Asserts and Release builds but only packs +the Release build for upload. You should use the Release+Asserts sysroot, normally under ``final/Phase3/Release+Asserts/llvmCore-3.8.1-RCn.install/``, -for test-suite and run-time benchmarks, to make sure nothing serious has +for test-suite and run-time benchmarks, to ensure nothing serious has passed through the net. For compile-time benchmarks, use the Release version. The minimum required version of the tools you'll need are :doc:`here <GettingStarted>` @@ -181,14 +181,14 @@ The minimum required version of the tools you'll need are :doc:`here <GettingSta Release Qualification Criteria ------------------------------ -There are no official release qualification criteria. It is up to the -the release manager to determine when a release is ready. The release manager +There are no official release qualification criteria. +The release manager determines when a release is ready. The release manager should pay attention to the results of community testing, the number of outstanding -bugs, and then number of regressions when determining whether or not to make a +bugs, and the number of regressions when determining whether or not to make a release. The community values time based releases, so releases should not be delayed for -too long unless there are critical issues remaining. In most cases, the only +too long unless critical issues remain. In most cases, the only kind of bugs that are critical enough to block a release would be a major regression from a previous release. @@ -199,33 +199,33 @@ A few developers in the community have dedicated time to validate the release candidates and volunteered to be the official release testers for each architecture. -These will be the ones testing, generating and uploading the official binaries +These will be the ones testing, generating, and uploading the official binaries to the server, and will be the minimum tests *necessary* for the release to proceed. This will obviously not cover all OSs and distributions, so additional community -validation is important. However, if community input is not reached before the -release is out, all bugs reported will have to go on the next stable release. +validation is important. However, if community input is not received before the +release, all reported bugs will be deferred to the next stable release. The official release managers are: * Even releases: Tom Stellard (tstellar@redhat.com) * Odd releases: Tobias Hieta (tobias@hieta.se) -The official release testers are volunteered from the community and have +The official release testers are volunteers from the community who have consistently validated and released binaries for their targets/OSs. To contact them, you should post on the `Discourse forums (Project Infrastructure - Release Testers). <https://discourse.llvm.org/c/infrastructure/release-testers/66>`_ -The official testers list is in the file `RELEASE_TESTERS.TXT +The official testers list is in the file ``RELEASE_TESTERS.TXT`` <https://github.com/llvm/llvm-project/blob/main/llvm/RELEASE_TESTERS.TXT>`_, in the LLVM repository. Community Testing ----------------- -Once all testing has been completed and appropriate bugs filed, the release -candidate tarballs are put on the website and the LLVM community is notified. +Once all testing is complete and appropriate bugs are filed, the release +candidate tarballs are put on the website, and the LLVM community is notified. We ask that all LLVM developers test the release in any the following ways: @@ -251,7 +251,7 @@ We ask that all LLVM developers test the release in any the following ways: architecture. We also ask that the OS distribution release managers test their packages with -the first candidate of every release, and report any *new* errors in GitHub. +the first candidate of every release and report any *new* errors in GitHub. If the bug can be reproduced with an unpatched upstream version of the release candidate (as opposed to the distribution's own build), the priority should be release blocker. @@ -268,10 +268,10 @@ next stage. Reporting Regressions --------------------- -Every regression that is found during the tests (as per the criteria above), +Every regression found during the tests (as per the criteria above) should be filled in a bug in GitHub and added to the release milestone. -If a bug can't be reproduced, or stops being a blocker, it should be removed +If a bug can't be reproduced or stops being a blocker, it should be removed from the Milestone. Debugging can continue, but on trunk. Backport Requests @@ -299,15 +299,15 @@ This section describes how to triage bug reports: to see the list of bugs that are being considered for the release. #. Review each bug and first check if it has been fixed in main. If it has, update - its status to "Needs Pull Request", and create a pull request for the fix - using the /cherry-pick or /branch comments if this has not been done already. + its status to "Needs Pull Request" and create a pull request for the fix + using the ``/cherry-pick`` or ``/branch`` comments if this has not been done already. #. If a bug has been fixed and has a pull request created for backporting it, then update its status to "Needs Review" and notify a knowledgeable reviewer. Usually you will want to notify the person who approved the patch, but you may use your best judgement on who a good reviewer would be. Once you have identified the reviewer(s), assign the issue to them and - mention them (i.e @username) in a comment and ask them if the patch is safe + mention them (i.e., ``@username``) in a comment and ask them if the patch is safe to backport. You should also review the bug yourself to ensure that it meets the requirements for committing to the release branch. @@ -323,11 +323,11 @@ Release Patch Rules Below are the rules regarding patching the release branch: #. Patches applied to the release branch may only be applied by the release - manager, the official release testers or the maintainers with approval from + manager, the official release testers, or the maintainers with approval from the release manager. #. Release managers are encouraged, but not required, to get approval from a - maintainer before approving patches. If there are no reachable maintainers + maintainer before approving patches. If there are no reachable maintainers, then release managers can ask approval from patch reviewers or other developers active in that area. @@ -336,7 +336,7 @@ Below are the rules regarding patching the release branch: was created. As with all phases, release managers and maintainers can reject patches that are deemed too invasive. -#. *Before RC2/RC3* Patches should be limited to bug fixes or backend specific +#. *Before RC2/RC3* Patches should be limited to bug fixes or backend-specific improvements that are determined to be very safe. #. *Before Final Major Release* Patches should be limited to critical @@ -349,7 +349,7 @@ Below are the rules regarding patching the release branch: Release Final Tasks ------------------- -The final stages of the release process involves tagging the "final" release +The final stages of the release process involve tagging the "final" release branch, updating documentation that refers to the release, and updating the demo page. @@ -394,11 +394,11 @@ is what to do: #. Update the ``releases/index.html`` with the new release and link to release documentation. -#. After you push the changes to the www-releases repo, someone with admin - access must login to prereleases-origin.llvm.org and manually pull the new - changes into /data/www-releases/. This is where the website is served from. +#. After you push the changes to the ``www-releases`` repo, someone with admin + access must log in to ``prereleases-origin.llvm.org`` and manually pull the new + changes into ``/data/www-releases/``. This is where the website is served from. -#. Finally checkout the llvm-www repo and update the main page +#. Finally, check out the ``llvm-www`` repo and update the main page (``index.html`` and sidebar) to point to the new release and release announcement. @@ -414,5 +414,5 @@ using this command and add it to the post. $ git log --format="- %aN: [%s (%h)](https://github.com/llvm/llvm-project/commit/%H)" llvmorg-X.1.N-1..llvmorg-X.1.N -Once the release has been announced add a link to the announcement on the llvm -homepage (from the llvm-www repo) in the "Release Emails" section. +Once the release has been announced, add a link to the announcement on the llvm +homepage (from the ``llvm-www`` repo) in the "Release Emails" section. 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 9ca08d6..9cdd983 100644 --- a/llvm/docs/ReleaseNotes.md +++ b/llvm/docs/ReleaseNotes.md @@ -140,6 +140,7 @@ Changes to the X86 Backend -------------------------- * `-mcpu=wildcatlake` is now supported. +* `-mcpu=novalake` is now supported. Changes to the OCaml bindings ----------------------------- @@ -176,6 +177,9 @@ 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. |