[llvm] [GlobalISel] Expand IRTranslator docs. NFC (PR #89186)

[Diana Picus via llvm-commits]

https://github.com/rovka updated https://github.com/llvm/llvm-project/pull/89186

>From 03a7f3e8953819be794f9575d54f4b4cc47cc773 Mon Sep 17 00:00:00 2001
From: Diana Picus <Diana-Magda.Picus at amd.com>
Date: Thu, 18 Apr 2024 10:24:57 +0200
Subject: [PATCH 1/4] [GlobalISel] Expand IRTranslator docs. NFC

Add some more details about how calls are lowered and what APIs are
available.
---
 llvm/docs/GlobalISel/IRTranslator.rst | 35 ++++++++++++++++++++++++---
 llvm/docs/WritingAnLLVMBackend.rst    |  2 ++
 2 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/llvm/docs/GlobalISel/IRTranslator.rst b/llvm/docs/GlobalISel/IRTranslator.rst
index 6268ebb4f4a1d7..5d0add89fbcd51 100644
--- a/llvm/docs/GlobalISel/IRTranslator.rst
+++ b/llvm/docs/GlobalISel/IRTranslator.rst
@@ -6,7 +6,7 @@ IRTranslator
 .. contents::
   :local:
 
-This pass translates the input LLVM-IR ``Function`` to a GMIR
+This pass translates the input LLVM-IR ``Function`` to a :doc:`GMIR`
 ``MachineFunction``. This is typically a direct translation but does
 occasionally get a bit more involved. For example:
 
@@ -51,8 +51,37 @@ Translating Function Calls
 
 The ``IRTranslator`` also implements the ABI's calling convention by lowering
 calls, returns, and arguments to the appropriate physical register usage and
-instruction sequences. This is achieved using the ``CallLowering``
-implementation,
+instruction sequences. This is achieved using the ``CallLowering`` interface,
+which provides several hooks that targets should implement:
+``lowerFormalArguments``, ``lowerReturn``, ``lowerCall`` etc.
+
+In essence, all of these hooks need to find a way to move the argument/return
+values between the virtual registers used in the rest of the function and either
+physical registers or the stack, as dictated by the ABI. This may involve
+splitting large types into smaller ones, introducing sign/zero extensions etc.
+In order to share as much of this code as possible between the different
+backends, ``CallLowering`` makes available a few helpers and interfaces:
+
+* ``ArgInfo`` - used for formal arguments, but also return values, call
+  parameters and call returns; contains info such as the IR type, the virtual
+  registers etc; large values will likely have to be split into several
+  ``ArgInfo`` objects (``CallLowering::splitToValueTypes`` can help with that)
+
+* ``ValueAssigner`` - uses a ``CCAssignFn``, usually generated by TableGen (see
+  :ref:`backend-calling-convs`), to decide where to put each
+  ``ArgInfo`` (physical register or stack); backends can use the provided
+  ``IncomingValueAssigner`` (for formal arguments and call results) and
+  ``OutgoingValueAssigner`` (for call paramters and function returns), but it's
+  also possible to subclass them
+
+* ``ValueHandler`` - inserts the necessary instructions for putting each value
+  where it belongs; it has pure virtual methods for assigning values to
+  registers or to addresses, and a host of other helpers
+
+* ``determineAndHandleAssignments`` (or for more fine grained control,
+  ``determineAssignments`` and ``handleAssignments``) contains some boilerplate
+  for invoking a given ``ValueAssigner`` and ``ValueHandler`` on a series of
+  ``ArgInfo`` objects
 
 .. _irtranslator-aggregates:
 
diff --git a/llvm/docs/WritingAnLLVMBackend.rst b/llvm/docs/WritingAnLLVMBackend.rst
index 31ebc6204c98fa..f1f07e4681d509 100644
--- a/llvm/docs/WritingAnLLVMBackend.rst
+++ b/llvm/docs/WritingAnLLVMBackend.rst
@@ -1503,6 +1503,8 @@ non-v9 SPARC implementations.
   if (TM.getSubtarget<SparcSubtarget>().isV9())
     setOperationAction(ISD::CTPOP, MVT::i32, Legal);
 
+.. _backend-calling-convs:
+
 Calling Conventions
 -------------------
 

>From 05569d81393db0fc3ba49220c4323d5c53206962 Mon Sep 17 00:00:00 2001
From: Diana Picus <Diana-Magda.Picus at amd.com>
Date: Thu, 18 Apr 2024 10:35:24 +0200
Subject: [PATCH 2/4] Fixups

---
 llvm/docs/GlobalISel/IRTranslator.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/llvm/docs/GlobalISel/IRTranslator.rst b/llvm/docs/GlobalISel/IRTranslator.rst
index 5d0add89fbcd51..3e15d4ba1df312 100644
--- a/llvm/docs/GlobalISel/IRTranslator.rst
+++ b/llvm/docs/GlobalISel/IRTranslator.rst
@@ -65,23 +65,23 @@ backends, ``CallLowering`` makes available a few helpers and interfaces:
 * ``ArgInfo`` - used for formal arguments, but also return values, call
   parameters and call returns; contains info such as the IR type, the virtual
   registers etc; large values will likely have to be split into several
-  ``ArgInfo`` objects (``CallLowering::splitToValueTypes`` can help with that)
+  ``ArgInfo`` objects (``CallLowering::splitToValueTypes`` can help with that);
 
 * ``ValueAssigner`` - uses a ``CCAssignFn``, usually generated by TableGen (see
   :ref:`backend-calling-convs`), to decide where to put each
   ``ArgInfo`` (physical register or stack); backends can use the provided
   ``IncomingValueAssigner`` (for formal arguments and call results) and
   ``OutgoingValueAssigner`` (for call paramters and function returns), but it's
-  also possible to subclass them
+  also possible to subclass them;
 
 * ``ValueHandler`` - inserts the necessary instructions for putting each value
   where it belongs; it has pure virtual methods for assigning values to
-  registers or to addresses, and a host of other helpers
+  registers or to addresses, and a host of other helpers;
 
 * ``determineAndHandleAssignments`` (or for more fine grained control,
-  ``determineAssignments`` and ``handleAssignments``) contains some boilerplate
+  ``determineAssignments`` and ``handleAssignments``) - contains some boilerplate
   for invoking a given ``ValueAssigner`` and ``ValueHandler`` on a series of
-  ``ArgInfo`` objects
+  ``ArgInfo`` objects.
 
 .. _irtranslator-aggregates:
 

>From dea6f3225887162dee975f0934f72b8b6751318d Mon Sep 17 00:00:00 2001
From: Diana Picus <Diana-Magda.Picus at amd.com>
Date: Thu, 18 Apr 2024 11:32:16 +0200
Subject: [PATCH 3/4] Typo

---
 llvm/docs/GlobalISel/IRTranslator.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/llvm/docs/GlobalISel/IRTranslator.rst b/llvm/docs/GlobalISel/IRTranslator.rst
index 3e15d4ba1df312..bf44137bdfa8e8 100644
--- a/llvm/docs/GlobalISel/IRTranslator.rst
+++ b/llvm/docs/GlobalISel/IRTranslator.rst
@@ -71,7 +71,7 @@ backends, ``CallLowering`` makes available a few helpers and interfaces:
   :ref:`backend-calling-convs`), to decide where to put each
   ``ArgInfo`` (physical register or stack); backends can use the provided
   ``IncomingValueAssigner`` (for formal arguments and call results) and
-  ``OutgoingValueAssigner`` (for call paramters and function returns), but it's
+  ``OutgoingValueAssigner`` (for call parameters and function returns), but it's
   also possible to subclass them;
 
 * ``ValueHandler`` - inserts the necessary instructions for putting each value

>From e801101e42f495487ad89fe0345863040c05fdfd Mon Sep 17 00:00:00 2001
From: Diana Picus <Diana-Magda.Picus at amd.com>
Date: Mon, 22 Apr 2024 13:53:36 +0200
Subject: [PATCH 4/4] s/call parameters/actual arguments/

---
 llvm/docs/GlobalISel/IRTranslator.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/llvm/docs/GlobalISel/IRTranslator.rst b/llvm/docs/GlobalISel/IRTranslator.rst
index bf44137bdfa8e8..0cb596c516e2fc 100644
--- a/llvm/docs/GlobalISel/IRTranslator.rst
+++ b/llvm/docs/GlobalISel/IRTranslator.rst
@@ -62,8 +62,8 @@ splitting large types into smaller ones, introducing sign/zero extensions etc.
 In order to share as much of this code as possible between the different
 backends, ``CallLowering`` makes available a few helpers and interfaces:
 
-* ``ArgInfo`` - used for formal arguments, but also return values, call
-  parameters and call returns; contains info such as the IR type, the virtual
+* ``ArgInfo`` - used for formal arguments, but also return values, actual
+  arguments and call results; contains info such as the IR type, the virtual
   registers etc; large values will likely have to be split into several
   ``ArgInfo`` objects (``CallLowering::splitToValueTypes`` can help with that);
 
@@ -71,8 +71,8 @@ backends, ``CallLowering`` makes available a few helpers and interfaces:
   :ref:`backend-calling-convs`), to decide where to put each
   ``ArgInfo`` (physical register or stack); backends can use the provided
   ``IncomingValueAssigner`` (for formal arguments and call results) and
-  ``OutgoingValueAssigner`` (for call parameters and function returns), but it's
-  also possible to subclass them;
+  ``OutgoingValueAssigner`` (for actual arguments and function returns), but
+  it's also possible to subclass them;
 
 * ``ValueHandler`` - inserts the necessary instructions for putting each value
   where it belongs; it has pure virtual methods for assigning values to