[llvm] [docs] Rename LangRef.{rst|md} (PR #201974)
Reid Kleckner via llvm-commits
llvm-commits at lists.llvm.org
Wed Jul 8 11:51:51 PDT 2026
https://github.com/rnk updated https://github.com/llvm/llvm-project/pull/201974
>From fa234cc5ab154d4297fd3aa087ddd144fa10d723 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Fri, 5 Jun 2026 22:52:34 +0000
Subject: [PATCH] [docs] Rename LangRef.{rst|md}
Tracking issue: #201242
This commit does not use valid markdown, so the docs will not build, but they will be fixed in an immediate follow-up commit that does the migration.
---
.github/new-prs-labeler.yml | 2 +-
llvm/docs/AddingConstrainedIntrinsics.rst | 2 +-
llvm/docs/{LangRef.rst => LangRef.md} | 89 +++++------------------
3 files changed, 20 insertions(+), 73 deletions(-)
rename llvm/docs/{LangRef.rst => LangRef.md} (99%)
diff --git a/.github/new-prs-labeler.yml b/.github/new-prs-labeler.yml
index bd508cc22951f..4aff050ea1997 100644
--- a/.github/new-prs-labeler.yml
+++ b/.github/new-prs-labeler.yml
@@ -832,7 +832,7 @@ llvm:ir:
- any-glob-to-any-file:
- llvm/lib/IR/**
- llvm/include/llvm/IR/**
- - llvm/docs/LangRef.rst
+ - llvm/docs/LangRef.md
- llvm/unittests/IR/**
llvm:SandboxIR:
diff --git a/llvm/docs/AddingConstrainedIntrinsics.rst b/llvm/docs/AddingConstrainedIntrinsics.rst
index 41e7dece6dd8b..4d1739ff11748 100644
--- a/llvm/docs/AddingConstrainedIntrinsics.rst
+++ b/llvm/docs/AddingConstrainedIntrinsics.rst
@@ -98,4 +98,4 @@ Add documentation and tests
::
- docs/LangRef.rst
+ docs/LangRef.md
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.md
similarity index 99%
rename from llvm/docs/LangRef.rst
rename to llvm/docs/LangRef.md
index 22d8467959c47..c7e5d6df0e0d4 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.md
@@ -1620,12 +1620,6 @@ Currently, only the following parameter attributes are defined:
otherwise it is undefined behavior. This means ``dereferenceable(<n>)``
implies ``noundef``.
- The ``dereferenceable`` attribute only implies dereferenceability at the
- point of the attribute (i.e. on function entry for arguments or at the
- point of the call for return values). The underlying object may still get
- freed after that point. Other attributes such as ``nofree`` can be used
- to exclude frees.
-
.. _attr_dereferenceable_or_null:
``dereferenceable_or_null(<n>)``
@@ -2302,9 +2296,8 @@ For example:
- ``errnomem``: This refers to accesses to the ``errno`` variable.
- ``target_mem#`` : These refer to target specific state that cannot be
accessed by any other means. # is a number between 0 and 1 inclusive.
- Note: The following target_mem locations are implemented in AArch64.
- target_mem0 represents SME ZT0 state, target_mem1 represents SME ZA
- state.
+ Note: The target_mem locations are experimental and intended for internal
+ testing only. They must not be used in production code.
- The default access kind (specified without a location prefix) applies to
all locations that haven't been specified explicitly, including those that
@@ -3358,34 +3351,19 @@ Module-Level Inline Assembly
----------------------------
Modules may contain "module-level inline asm" blocks, which corresponds
-to the GCC "file scope inline asm" blocks:
+to the GCC "file scope inline asm" blocks. These blocks are internally
+concatenated by LLVM and treated as a single unit, but may be separated
+in the ``.ll`` file if desired. The syntax is very simple:
.. code-block:: llvm
- module asm
- "inline asm code goes here"
- "more can go here"
+ module asm "inline asm code goes here"
+ module asm "more can go here"
-The sequence of string literals is internally concatenated using newlines as
-separators. The strings can contain any character by escaping non-printable
+The strings can contain any character by escaping non-printable
characters. The escape sequence used is simply "\\xx" where "xx" is the
two digit hex code for the number.
-Additionally, module-level inline assembly can specify an optional list of
-properties:
-
-.. code-block:: llvm
-
- module asm(target_features: "+foo", target_cpu: "bar")
- "inline asm code goes here"
- "more can go here"
-
-Currently, the only supported properties are ``target_features`` and
-``target_cpu``, with the same meaning as the ``"target-features"`` and
-``"target-cpu"`` function attributes.
-
-Consecutive blocks with identical properties will be concatenated into one.
-
Note that the assembly string *must* be parseable by LLVM's integrated assembler
(unless it is disabled), even when emitting a ``.s`` file.
@@ -7860,15 +7838,12 @@ it is attached to is completely unpredictable.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The existence of the ``!dereferenceable`` metadata on the instruction
-tells the optimizer that the value loaded is known to be dereferenceable
-at the current program point, otherwise the behavior is undefined.
+tells the optimizer that the value loaded is known to be dereferenceable,
+otherwise the behavior is undefined.
The number of bytes known to be dereferenceable is specified by the integer
value in the metadata node. This is analogous to the ''dereferenceable''
attribute on parameters and return values.
-The ``!deferenceable`` metadata can be combined with the ``!nofree`` metadata
-to indicate that the pointer will stay dereferenceable forever.
-
.. _md_dereferenceable_or_null:
'``dereferenceable_or_null``' Metadata
@@ -7876,8 +7851,7 @@ to indicate that the pointer will stay dereferenceable forever.
The existence of the ``!dereferenceable_or_null`` metadata on the
instruction tells the optimizer that the value loaded is known to be either
-dereferenceable at the current program point or null, otherwise the behavior is
-undefined.
+dereferenceable or null, otherwise the behavior is undefined.
The number of bytes known to be dereferenceable is specified by the integer
value in the metadata node. This is analogous to the ''dereferenceable_or_null''
attribute on parameters and return values.
@@ -8660,37 +8634,6 @@ the irreducible loop) of 100:
Irreducible loop header weights are typically based on profile data.
-.. _md_invariant.load:
-
-'``invariant.load``' Metadata
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The ``invariant.load`` metadata may be attached to load operations or to intrinsic
-calls that only read memory (though it is possible this may be extended in the future
-if the need arises).
-
-If an ``invariant.load``-tagged operation is executed, every memory location
-read by that operation must contain the same value at all points in the program
-where that memory is dereferenceable; otherwise, the behavior is undefined.
-
-An ``invariant.load`` tag may be placed on operations that read inaccessible
-memory or non-memory values (such as registers). These load-like operations must
-be invariant throughout the lifetime of the state being read.
-
-.. code-block:: llvm
-
- ;; Invariant load of a pointer.
- load i32, ptr %ptr, !invariant.load !0
-
- ;; Invariant masked vector load.
- call <4 x i32> @llvm.masked.load.v4i32.p0(ptr %p, <4 x i1> %mask, <4 x i32> zeroinitializer), !invariant.load !0
-
- ;; Invariant "load" from a register.
- call i32 @llvm.read_register.i32(metadata !1), !invariant.load !0
- !0 = !{}
- !1 = !{!"reg"}
-
-
.. _md_invariant.group:
'``invariant.group``' Metadata
@@ -8788,7 +8731,7 @@ computed as follows:
- Reinterpret the first 8 bytes of the hash as a little-endian 64-bit integer.
To avoid mismatched pointer types, generalizations are applied.
-Pointers in return and argument types are treated as equivalent as long as the qualifiers for the
+Pointers in return and argument types are treated as equivalent as long as the qualifiers for the
type they point to match. For example, ``char*``, ``char**``, and ``int*`` are considered equivalent
types. However, ``char*`` and ``const char*`` are considered distinct types.
@@ -12207,7 +12150,11 @@ as the ``MOVNT`` instruction on x86.
The optional ``!invariant.load`` metadata must reference a single
metadata name ``<empty_node>`` corresponding to a metadata node with no
-entries. See :ref:`invariant.load <md_invariant.load>` metadata.
+entries. If a load instruction tagged with the ``!invariant.load``
+metadata is executed, the memory location referenced by the load has
+to contain the same value at all points in the program where the
+memory location is dereferenceable; otherwise, the behavior is
+undefined.
The optional ``!invariant.group`` metadata must reference a single metadata name
``<empty_node>`` corresponding to a metadata node with no entries.
@@ -15787,7 +15734,7 @@ knows those logical layouts are lowered to the same physical layout:
- `{ i32, i32, i32, i32 }`
- `[ i32 x 4 ]`
-This means it is valid to lower the following code to either:
+This means is is valid to lower the following code to either:
.. code-block:: llvm
More information about the llvm-commits
mailing list