[PATCH] D134648: [LangRef] Update text for vscale to be more flexible but maintain original intent.

[Paul Walker via Phabricator via llvm-commits]

paulwalker-arm created this revision.
Herald added subscribers: jdoerfert, kristof.beyls.
Herald added a project: All.
paulwalker-arm requested review of this revision.
Herald added a project: LLVM.
Herald added a subscriber: llvm-commits.

llvm/docs/AArch64SME.rst contains a set of design decisions that
include controlled ways for an AArch64 binary to support multiple
values of vscale during program execution albeit not at the same time.

However, the LangRef prohibits this by requiring vscale to be constant
throughout the whole execution of a binary. This is overly restrictive
as limiting to function call boundaries should be sufficient.

Such a change does not affect existing code because changes of vscale
must be well defined within the IR (e.g. function attributes) of which
nothing exists prior to LLVM16 and so original behaviour is maintained.
For example, traditional function inlining can continue because while
the new definition allows the caller and callee to have different
vscales, neither function contain any decoration that allows such a
transition and thus it's safe to assume there is none. Essentially,
all complexity is pushed onto the implementors of vscale changing
behaviour


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D134648

Files:
  llvm/docs/LangRef.rst


Index: llvm/docs/LangRef.rst
===================================================================
--- llvm/docs/LangRef.rst
+++ llvm/docs/LangRef.rst
@@ -3683,11 +3683,19 @@
 The number of elements is a constant integer value larger than 0;
 elementtype may be any integer, floating-point or pointer type. Vectors
 of size zero are not allowed. For scalable vectors, the total number of
-elements is a constant multiple (called vscale) of the specified number
-of elements; vscale is a positive integer that is unknown at compile time
-and the same hardware-dependent constant for all scalable vectors at run
-time. The size of a specific scalable vector type is thus constant within
-IR, even if the exact size in bytes cannot be determined until run time.
+elements is a multiple (called ``vscale``) of the specified number of elements;
+
+.. _vscale
+
+``vscale`` is a positive integer that is unknown at compile time but has the
+same hardware-dependent value for all scalable vectors in a function. ``vscale``
+can change at function call boundaries but such a change is tightly controlled
+by function attributes and should not be observable to the calling function.
+
+The size of a specific scalable vector type is thus constant within a function,
+even if the exact size in bytes cannot be determined until run time. However,
+care must be taken to limit cross function optimisations if ``vscale`` might
+change.
 
 :Examples:
 
@@ -24745,11 +24753,9 @@
 Semantics:
 """"""""""
 
-``vscale`` is a positive value that is constant throughout program
-execution, but is unknown at compile time.
-If the result value does not fit in the result type, then the result is
-a :ref:`poison value <poisonvalues>`.
-
+:ref:`vscale <vscale>` is a positive value that is constant throughout the
+calling function. If the result value does not fit in the result type, then the
+result is a :ref:`poison value <poisonvalues>`.
 
 Stack Map Intrinsics
 --------------------


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D134648.462917.patch
Type: text/x-patch
Size: 1966 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20220926/b65c0479/attachment.bin>