[llvm] [docs] Rewrite 19 LLVM docs from reST to markdown (PR #208798)
Scott Linder via llvm-commits
llvm-commits at lists.llvm.org
Mon Aug 3 13:05:50 PDT 2026
================
@@ -78,82 +82,73 @@ these restrictions when generating LLVM IR.
Even though the runtime SVE vector length may change, for the purpose of LLVM IR
and almost all parts of CodeGen we can assume that the runtime value for
-``vscale`` does not. If we let the compiler insert the appropriate ``smstart``
-and ``smstop`` instructions around call boundaries, then the effects on SVE
+`vscale` does not. If we let the compiler insert the appropriate `smstart`
+and `smstop` instructions around call boundaries, then the effects on SVE
state can be mitigated. By limiting the state changes to a very brief window
around the call, we can control how the operations are scheduled and how live
values remain preserved between state transitions.
In order to control PSTATE.SM at this level of granularity, we use function and
callsite attributes rather than intrinsics.
+### Restrictions on attributes
-Restrictions on attributes
---------------------------
-
-* It is undefined behaviour to pass or return (pointers to) scalable vector
+- It is undefined behaviour to pass or return (pointers to) scalable vector
objects to/from functions which may use a different SVE vector length.
This includes functions with a non-streaming interface but marked with
- ``aarch64_pstate_sm_body``.
-
-* It is not allowed for a function to be decorated with both
- ``aarch64_pstate_sm_compatible`` and ``aarch64_pstate_sm_enabled``.
-
-* It is not allowed for a function to be decorated with more than one of the
+ `aarch64_pstate_sm_body`.
+- It is not allowed for a function to be decorated with both
+ `aarch64_pstate_sm_compatible` and `aarch64_pstate_sm_enabled`.
+- It is not allowed for a function to be decorated with more than one of the
following attributes:
- ``aarch64_new_za``, ``aarch64_in_za``, ``aarch64_out_za``, ``aarch64_inout_za``,
- ``aarch64_preserves_za``.
+ `aarch64_new_za`, `aarch64_in_za`, `aarch64_out_za`, `aarch64_inout_za`,
+ `aarch64_preserves_za`.
These restrictions also apply in the higher-level SME ACLE, which means we can
emit diagnostics in Clang to signal users about incorrect behaviour.
-
-Compiler inserted streaming-mode changes
-----------------------------------------
+### Compiler inserted streaming-mode changes
The table below describes the transitions in PSTATE.SM the compiler has to
account for when doing calls between functions with different attributes.
In this table, we use the following abbreviations:
-``N``
- functions with a normal interface (PSTATE.SM=0 on entry, PSTATE.SM=0 on
+`N`
+
+: functions with a normal interface (PSTATE.SM=0 on entry, PSTATE.SM=0 on
return)
-``S``
- functions with a Streaming interface (PSTATE.SM=1 on entry, PSTATE.SM=1
+`S`
+
+: functions with a Streaming interface (PSTATE.SM=1 on entry, PSTATE.SM=1
on return)
-``SC``
- functions with a Streaming-Compatible interface (PSTATE.SM can be
+`SC`
+
+: functions with a Streaming-Compatible interface (PSTATE.SM can be
either 0 or 1 on entry, and is unchanged on return).
-Functions with ``__attribute__((arm_locally_streaming))`` are excluded from this
+Functions with `__attribute__((arm_locally_streaming))` are excluded from this
table because for the caller the attribute is synonymous with 'streaming', and
for the callee it is merely an implementation detail that is explicitly not
exposed to the caller.
-.. table:: Combinations of calls for functions with different attributes
-
- ==== ==== =============================== ============================== ==============================
- From To Before call After call After exception
- ==== ==== =============================== ============================== ==============================
- N N
- N S SMSTART SMSTOP
- N SC
- S N SMSTOP SMSTART SMSTART
- S S SMSTART
- S SC SMSTART
- SC N If PSTATE.SM before call is 1, If PSTATE.SM before call is 1, If PSTATE.SM before call is 1,
- then SMSTOP then SMSTART then SMSTART
- SC S If PSTATE.SM before call is 0, If PSTATE.SM before call is 0, If PSTATE.SM before call is 1,
- then SMSTART then SMSTOP then SMSTART
- SC SC If PSTATE.SM before call is 1,
- then SMSTART
- ==== ==== =============================== ============================== ==============================
+**Combinations of calls for functions with different attributes**
+| From | To | Before call | After call | After exception |
----------------
slinder1 wrote:
the table formatting in the source leaves a bit to be desired here
https://github.com/llvm/llvm-project/pull/208798
More information about the llvm-commits
mailing list