[llvm] [LangRef] Update the semantic of `experimental.get.vector.length` (PR #104475)

[Min-Yih Hsu via llvm-commits]

https://github.com/mshockwave updated https://github.com/llvm/llvm-project/pull/104475

>From 2cd78f259d74f287d1edeafb75a59e4fa3efbf60 Mon Sep 17 00:00:00 2001
From: Min Hsu <min.hsu at sifive.com>
Date: Mon, 15 Jul 2024 14:29:32 -0700
Subject: [PATCH 1/4] [doc] Update the semantic of
 `experimental.get.vector.length` in LangRef

The previous semantics of `llvm.experimental.get.vector.length` was too
permissive such that it gave optimizers a hard time on anything related
to the number of iterations of VP-vectorized loops.

This patch tries to address this by assigning it a set of stricter
semantics similar to that of RVV's VSETVLI instructions, while being not
too RISC-V specific and leaving room for other (future) targets.

Co-authored-by: Craig Topper <craig.topper at sifive.com>
---
 llvm/docs/LangRef.rst | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 5e5e9b9e8a93b1..22fd805a4685b1 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -19644,13 +19644,19 @@ in order to get the number of elements to process on each loop iteration. The
 result should be used to decrease the count for the next iteration until the
 count reaches zero.
 
-If the count is larger than the number of lanes in the type described by the
-last 2 arguments, this intrinsic may return a value less than the number of
-lanes implied by the type. The result will be at least as large as the result
-will be on any later loop iteration.
-
-This intrinsic will only return 0 if the input count is also 0. A non-zero input
-count will produce a non-zero result.
+Let ``%max_lanes`` be the number of lanes in the type described by ``%vf`` and
+``%scalable``, here are the constraints on the returned value:
+- If ``%cnt`` equals to 0, returns 0.
+- The returned value is always less or equal to ``%max_lanes``.
+- The returned value is always larger or equal to
+  ``ceil(%cnt / ceil(%cnt / %max_lanes))``.
+  - This implies that if ``%cnt`` is non-zero, the result should be non-zero
+    as well.
+  - This also implies that if ``%cnt`` is less than ``%max_lanes``, it has to
+    return ``%cnt``.
+- The returned values decrease monotonically in each loop iteration. That is,
+  the returned value of a iteration is at least as large as that of any later
+  iterations.
 
 '``llvm.experimental.vector.partial.reduce.add.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

>From 7f74ada4f2f90c8e1ca21d17f1a2cc16738ff28d Mon Sep 17 00:00:00 2001
From: Min Hsu <min.hsu at sifive.com>
Date: Fri, 16 Aug 2024 10:03:43 -0700
Subject: [PATCH 2/4] Fix formatting issues reported by sphinx buildbot

---
 llvm/docs/LangRef.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 22fd805a4685b1..a245715a8c8d0e 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -19648,8 +19648,7 @@ Let ``%max_lanes`` be the number of lanes in the type described by ``%vf`` and
 ``%scalable``, here are the constraints on the returned value:
 - If ``%cnt`` equals to 0, returns 0.
 - The returned value is always less or equal to ``%max_lanes``.
-- The returned value is always larger or equal to
-  ``ceil(%cnt / ceil(%cnt / %max_lanes))``.
+- The returned value is always larger or equal to ``ceil(%cnt / ceil(%cnt / %max_lanes))``.
   - This implies that if ``%cnt`` is non-zero, the result should be non-zero
     as well.
   - This also implies that if ``%cnt`` is less than ``%max_lanes``, it has to

>From 911fdcdedae40e92a4e0a3fcfed6c819b7db0212 Mon Sep 17 00:00:00 2001
From: Min Hsu <min.hsu at sifive.com>
Date: Mon, 19 Aug 2024 13:50:40 -0700
Subject: [PATCH 3/4] Address reviewers' comments

---
 llvm/docs/LangRef.rst | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index a245715a8c8d0e..dcd0f38fd8cd39 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -19634,7 +19634,7 @@ vectorization factor should be multiplied by vscale.
 Semantics:
 """"""""""
 
-Returns a positive i32 value (explicit vector length) that is unknown at compile
+Returns a non-negative i32 value (explicit vector length) that is unknown at compile
 time and depends on the hardware specification.
 If the result value does not fit in the result type, then the result is
 a :ref:`poison value <poisonvalues>`.
@@ -19646,16 +19646,18 @@ count reaches zero.
 
 Let ``%max_lanes`` be the number of lanes in the type described by ``%vf`` and
 ``%scalable``, here are the constraints on the returned value:
-- If ``%cnt`` equals to 0, returns 0.
-- The returned value is always less or equal to ``%max_lanes``.
-- The returned value is always larger or equal to ``ceil(%cnt / ceil(%cnt / %max_lanes))``.
-  - This implies that if ``%cnt`` is non-zero, the result should be non-zero
-    as well.
-  - This also implies that if ``%cnt`` is less than ``%max_lanes``, it has to
-    return ``%cnt``.
-- The returned values decrease monotonically in each loop iteration. That is,
-  the returned value of a iteration is at least as large as that of any later
-  iterations.
+
+-  If ``%cnt`` equals to 0, returns 0.
+-  The returned value is always less than or equal to ``%max_lanes``.
+-  The returned value is always greater than or equal to ``ceil(%cnt / ceil(%cnt / %max_lanes))``.
+-  The returned values decrease monotonically in each loop iteration. That is,
+   the returned value of a iteration is at least as large as that of any later
+   iterations.
+
+Note that it has the following implications:
+
+-  If ``%cnt`` is non-zero, the result should be non-zero as well.
+-  If ``%cnt`` is less than ``%max_lanes``, it has to return ``%cnt``.
 
 '``llvm.experimental.vector.partial.reduce.add.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

>From 70fc039967e160972e840251ab1a05b48753e968 Mon Sep 17 00:00:00 2001
From: Min Hsu <min.hsu at sifive.com>
Date: Thu, 22 Aug 2024 17:00:34 -0700
Subject: [PATCH 4/4] fixup! Address reviewers' comments

---
 llvm/docs/LangRef.rst | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index dcd0f38fd8cd39..81394bf2a60430 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -19649,15 +19649,18 @@ Let ``%max_lanes`` be the number of lanes in the type described by ``%vf`` and
 
 -  If ``%cnt`` equals to 0, returns 0.
 -  The returned value is always less than or equal to ``%max_lanes``.
--  The returned value is always greater than or equal to ``ceil(%cnt / ceil(%cnt / %max_lanes))``.
--  The returned values decrease monotonically in each loop iteration. That is,
-   the returned value of a iteration is at least as large as that of any later
-   iterations.
+-  The returned value is always greater than or equal to ``ceil(%cnt / ceil(%cnt / %max_lanes))``,
+   if ``%cnt`` is non-zero.
+-  The returned values are monotonically non-increasing in each loop iteration. That is,
+   the returned value of an iteration is at least as large as that of any later
+   iteration.
 
 Note that it has the following implications:
 
--  If ``%cnt`` is non-zero, the result should be non-zero as well.
--  If ``%cnt`` is less than ``%max_lanes``, it has to return ``%cnt``.
+-  For a loop that uses this intrinsic, the number of iterations is equal to
+   ``ceil(%C / %max_lanes)`` where ``%C`` is the initial ``%cnt`` value.
+-  If ``%cnt`` is non-zero, the return value is non-zero as well.
+-  If ``%cnt`` is less than or equal to ``%max_lanes``, the return value is equal to ``%cnt``.
 
 '``llvm.experimental.vector.partial.reduce.add.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^