[flang-commits] [flang] [llvm] [flang][docs] Update runtime trampoline documentation (PR #215233)

[Sairudra More via flang-commits]

================
@@ -259,136 +266,84 @@ trampoline1:
 ...
 ```
 
-The `TDATA` memory is writeable and contains *<static chain address, function address>*
-for each of the trampolines.
-
-A runtime support library may provide APIs for initializing/accessing/deallocating
-the trampolines that can be used by `BoxedProcedure` pass.
-
-### Implementation considerations
-
-* The static chain address still has to be passed in fixed target-specific register,
-  and the implementations that rely on LLVM back-ends can use `nest` attribute for this.
-
-* The trampoline area must be able to grow, because there can be a trampoline
-  for each internal procedure per host invocation, and an internal procedure can call
-  the host recursively. This means that the amount of trampolines in one thread
-  may grow pretty quickly.
-
-  ```fortran
-  recursive subroutine host(local)
-    use other
-    integer :: local
-    call foo(callee)
-    return
-
-    contains
-
-    function callee()
-      integer :: callee
-      if (local .le. CONST_N) then
-         call host(local + 1)
-      endif
-    end function callee
-  end subroutine host
-  ```
+Each `TDATA` entry stores the callee and static-chain addresses for one
+trampoline. The generated stub loads both values, places the static-chain
+address in the target-specific register, and jumps to the callee.
 
-* On the other hand, putting a hard limit on the number of trampolines live at the same time
-  allows putting the trampolines into the static code segment.
+### Implementation characteristics
 
-* Each thread may have its own dynamic trampoline area to reduce the number
-  of required locks.
+* The pool contains 1024 slots by default. `FLANG_TRAMPOLINE_POOL_SIZE` can set
+  a different capacity, as described in the
+  [runtime environment documentation](RuntimeEnvironment.md).
+* Allocation from a full pool terminates the program with a diagnostic. The
+  pool does not grow dynamically.
+* `TrampolineFree` returns a slot to the synchronized global pool for reuse.
+  The implementation does not use a dynamic trampoline area per thread.
+* Each trampoline invocation loads the static chain and callee addresses from
+  its paired data entry.
 
-* Some support is required for the offload devices.
----------------
Saieiei wrote:

Yeah. It was describing future/offload work rather than the current runtime-pool behavior, so I removed it while updating the document to reflect the implemented behavior.

https://github.com/llvm/llvm-project/pull/215233