@@ -1958,3 +1958,147 @@ hardware design, touch the red zone.
19581958 The system will crash if the wrong handler is used.
19591959 }];
19601960}
1961+
1962+ def SwiftCallDocs : Documentation {
1963+ let Category = DocCatVariable;
1964+ let Content = [{
1965+ The ``swiftcall`` attribute indicates that a function should be called
1966+ using the Swift calling convention for a function or function pointer.
1967+
1968+ The lowering for the Swift calling convention, as described by the Swift
1969+ ABI documentation, occurs in multiple phases. The first, "high-level"
1970+ phase breaks down the formal parameters and results into innately direct
1971+ and indirect components, adds implicit paraameters for the generic
1972+ signature, and assigns the context and error ABI treatments to parameters
1973+ where applicable. The second phase breaks down the direct parameters
1974+ and results from the first phase and assigns them to registers or the
1975+ stack. The ``swiftcall`` convention only handles this second phase of
1976+ lowering; the C function type must accurately reflect the results
1977+ of the first phase, as follows:
1978+
1979+ - Results classified as indirect by high-level lowering should be
1980+ represented as parameters with the ``swift_indirect_result`` attribute.
1981+
1982+ - Results classified as direct by high-level lowering should be represented
1983+ as follows:
1984+
1985+ - First, remove any empty direct results.
1986+
1987+ - If there are no direct results, the C result type should be ``void``.
1988+
1989+ - If there is one direct result, the C result type should be a type with
1990+ the exact layout of that result type.
1991+
1992+ - If there are a multiple direct results, the C result type should be
1993+ a struct type with the exact layout of a tuple of those results.
1994+
1995+ - Parameters classified as indirect by high-level lowering should be
1996+ represented as parameters of pointer type.
1997+
1998+ - Parameters classified as direct by high-level lowering should be
1999+ omitted if they are empty types; otherwise, they should be represented
2000+ as a parameter type with a layout exactly matching the layout of the
2001+ Swift parameter type.
2002+
2003+ - The context parameter, if present, should be represented as a trailing
2004+ parameter with the ``swift_context`` attribute.
2005+
2006+ - The error result parameter, if present, should be represented as a
2007+ trailing parameter (always following a context parameter) with the
2008+ ``swift_error_result`` attribute.
2009+
2010+ ``swiftcall`` does not support variadic arguments or unprototyped functions.
2011+
2012+ The parameter ABI treatment attributes are aspects of the function type.
2013+ A function type which which applies an ABI treatment attribute to a
2014+ parameter is a different type from an otherwise-identical function type
2015+ that does not. A single parameter may not have multiple ABI treatment
2016+ attributes.
2017+
2018+ Support for this feature is target-dependent, although it should be
2019+ supported on every target that Swift supports. Query for this support
2020+ with ``__has_attribute(swiftcall)``. This implies support for the
2021+ ``swift_context``, ``swift_error_result``, and ``swift_indirect_result``
2022+ attributes.
2023+ }];
2024+ }
2025+
2026+ def SwiftContextDocs : Documentation {
2027+ let Category = DocCatVariable;
2028+ let Content = [{
2029+ The ``swift_context`` attribute marks a parameter of a ``swiftcall``
2030+ function as having the special context-parameter ABI treatment.
2031+
2032+ This treatment generally passes the context value in a special register
2033+ which is normally callee-preserved.
2034+
2035+ A ``swift_context`` parameter must either be the last parameter or must be
2036+ followed by a ``swift_error_result`` parameter (which itself must always be
2037+ the last parameter).
2038+
2039+ A context parameter must have pointer or reference type.
2040+ }];
2041+ }
2042+
2043+ def SwiftErrorResultDocs : Documentation {
2044+ let Category = DocCatVariable;
2045+ let Content = [{
2046+ The ``swift_error_result`` attribute marks a parameter of a ``swiftcall``
2047+ function as having the special error-result ABI treatment.
2048+
2049+ This treatment generally passes the underlying error value in and out of
2050+ the function through a special register which is normally callee-preserved.
2051+ This is modeled in C by pretending that the register is addressable memory:
2052+
2053+ - The caller appears to pass the address of a variable of pointer type.
2054+ The current value of this variable is copied into the register before
2055+ the call; if the call returns normally, the value is copied back into the
2056+ variable.
2057+
2058+ - The callee appears to receive the address of a variable. This address
2059+ is actually a hidden location in its own stack, initialized with the
2060+ value of the register upon entry. When the function returns normally,
2061+ the value in that hidden location is written back to the register.
2062+
2063+ A ``swift_error_result`` parameter must be the last parameter, and it must be
2064+ preceded by a ``swift_context`` parameter.
2065+
2066+ A ``swift_error_result`` parameter must have type ``T**`` or ``T*&`` for some
2067+ type T. Note that no qualifiers are permitted on the intermediate level.
2068+
2069+ It is undefined behavior if the caller does not pass a pointer or
2070+ reference to a valid object.
2071+
2072+ The standard convention is that the error value itself (that is, the
2073+ value stored in the apparent argument) will be null upon function entry,
2074+ but this is not enforced by the ABI.
2075+ }];
2076+ }
2077+
2078+ def SwiftIndirectResultDocs : Documentation {
2079+ let Category = DocCatVariable;
2080+ let Content = [{
2081+ The ``swift_indirect_result`` attribute marks a parameter of a ``swiftcall``
2082+ function as having the special indirect-result ABI treatmenet.
2083+
2084+ This treatment gives the parameter the target's normal indirect-result
2085+ ABI treatment, which may involve passing it differently from an ordinary
2086+ parameter. However, only the first indirect result will receive this
2087+ treatment. Furthermore, low-level lowering may decide that a direct result
2088+ must be returned indirectly; if so, this will take priority over the
2089+ ``swift_indirect_result`` parameters.
2090+
2091+ A ``swift_indirect_result`` parameter must either be the first parameter or
2092+ follow another ``swift_indirect_result`` parameter.
2093+
2094+ A ``swift_indirect_result`` parameter must have type ``T*`` or ``T&`` for
2095+ some object type ``T``. If ``T`` is a complete type at the point of
2096+ definition of a function, it is undefined behavior if the argument
2097+ value does not point to storage of adequate size and alignment for a
2098+ value of type ``T``.
2099+
2100+ Making indirect results explicit in the signature allows C functions to
2101+ directly construct objects into them without relying on language
2102+ optimizations like C++'s named return value optimization (NRVO).
2103+ }];
2104+ }
0 commit comments