Merge pull request swiftlang#81747 from gottesmm/pr-021007354c4c9e191bcb63c8573c668dc20a40fd

[sil][docs] Add documentation about sil_implicit_leading_param.

Author: rjmansfield

docs/SIL/SIL.md

@@ -457,9 +457,10 @@ The ownership kind of a value is statically determined:
       ...
 ```
 
-- The ownership of most instruction results is statically defined. For example
-  `copy_value` always produces an owned value, whereas `begin_borrow` always
-  produces a guaranteed value.
+- The ownership of most instruction results can be statically determined from
+  the instruction's kind and the offset of the value in the result tuple. For
+  example `copy_value` has only one result and that result is always an owned
+  value, whereas `begin_borrow` always produces a guaranteed value.
 
 - Forwarding instructions: some instructions work with both, owned and
   guaranteed ownership, and "forward" the ownership from their operand(s) to

docs/SIL/Types.md

@@ -431,6 +431,44 @@ in the callee.
     `@sil_isolated` since a function cannot be isolated to multiple
     actors at the same time.
 
+-   SIL functions may optionally mark a function parameter as
+    `@sil_implicit_leading_param`. A SIL generator places this on a parameter
+    that is used to represent a parameter that is implicitly generated by the
+    generator at a full call site. Since they can only appear at the full call
+    site, a `@sil_implicit_leading_param` can only appear in between the
+    indirect result parameters and the direct parameters. For example the
+    following swift code that uses `nonisolated(nonsending)`:
+
+    ```
+    nonisolated(nonsending)
+    func f(_ x: DirectParam) -> IndirectResult {
+      ...
+    }
+    ```
+
+    would translate to the following SIL:
+
+    ```
+      sil [ossa] @f : $@convention(thin) @async (
+         @sil_isolated @sil_implicit_leading_param @guaranteed Optional<any Actor>,
+         @guaranteed DirectParam
+      ) -> @out IndirectResult {
+      bb0(%0 : $*IndirectResult, %1 : @guaranteed $Optional<Actor>, %2 : @guaranteed $DirectParam):
+        ... use %0 ...
+      }
+    ```
+
+    Notice how there is an `@sil_isolated` `@sil_implicit_leading_param`
+    parameter that was inserted by SILGen to implicitly take in the caller's
+    actor of f.
+
+    NOTE: By design SILOptimizer passes should ignore
+    `@sil_implicit_leading_param`. Instead, it should only be analyzed as a
+    normal parameter. So as an example, in f above the implicit parameter should
+    be treated by the optimizer just as any other isolated parameter. This is
+    solely SILGen using SIL as a data structure. TODO: Can this be removed by
+    SILGen so SILOptimizer passes cannot even see it?
+
 ### Async Functions
 
 SIL function types may be `@async`. `@async` functions run inside async