· 8 years ago · Jul 05, 2018, 06:02 PM
1.. _CallingConvention:
2
3The Swift Calling Convention
4****************************
5
6This whitepaper discusses the Swift calling convention, at least as we
7want it to be.
8
9It's a basic assumption in this paper that Swift shouldn't make an
10implicit promise to exactly match the default platform calling
11convention. That is, if a C or Objective-C programmer manages to derive the
12address of a Swift function, we don't have to promise that an obvious
13translation of the type of that function will be correctly callable
14from C. For example, this wouldn't be guaranteed to work::
15
16 // In Swift:
17 func foo(_ x: Int, y: Double) -> MyClass { ... }
18
19 // In Objective-C:
20 extern id _TF4main3fooFTSiSd_CS_7MyClass(intptr_t x, double y);
21
22We do sometimes need to be able to match C conventions, both to use
23them and to generate implementations of them, but that level of
24compatibility should be opt-in and site-specific. If Swift would
25benefit from internally using a better convention than C/Objective-C uses,
26and switching to that convention doesn't damage the dynamic abilities
27of our target platforms (debugging, dtrace, stack traces, unwinding,
28etc.), there should be nothing preventing us from doing so. (If we
29did want to guarantee compatibility on this level, this paper would be
30a lot shorter!)
31
32Function call rules in high-level languages have three major
33components, each operating on a different abstraction level:
34
35* the high-level semantics of the call (pass-by-reference
36 vs. pass-by-value),
37
38* the ownership and validity conventions about argument and result
39 values ("+0" vs. "+1", etc.), and
40
41* the "physical" representation conventions of how values are actually
42 communicated between functions (in registers, on the stack, etc.).
43
44We'll tackle each of these in turn, then conclude with a detailed
45discussion of function signature lowering.
46
47High-level semantic conventions
48===============================
49
50The major division in argument passing conventions between languages
51is between pass-by-reference and pass-by-value languages. It's a
52distinction that only really makes sense in languages with the concept
53of an l-value, but Swift does, so it's pertinent.
54
55In general, the terms "pass-by-X" and "call-by-X" are used
56interchangeably. It's unfortunate, because these conventions are
57argument specific, and functions can be passed multiple arguments
58that are each handled in a different way. As such, we'll prefer
59"pass-by-X" for consistency and to emphasize that these conventions
60are argument-specific.
61
62Pass-by-reference
63-----------------
64
65In pass-by-reference (also called pass-by-name or pass-by-address), if
66`A` is an l-value expression, `foo(A)` is passed some sort of opaque
67reference through which the original l-value can be modified. If `A`
68is not an l-value, the language may prohibit this, or (if
69pass-by-reference is the default convention) it may pass a temporary
70variable containing the result of `A`.
71
72Don't confuse pass-by-reference with the concept of a *reference
73type*. A reference type is a type whose value is a reference to a
74different object; for example, a pointer type in C, or a class type in
75Java or Swift. A variable of reference type can be passed by value
76(copying the reference itself) or by reference (passing the variable
77itself, allowing it to be changed to refer to a different object).
78Note that references in C++ are a generalization of pass-by-reference,
79not really a reference type; in C++, a variable of reference type
80behaves completely unlike any other variable in the language.
81
82Also, don't confuse pass-by-reference with the physical convention of
83passing an argument value indirectly. In pass-by-reference, what's
84logically being passed is a reference to a tangible, user-accessible
85object; changes to the original object will be visible in the
86reference, and changes to the reference will be reflected in the
87original object. In an indirect physical convention, the argument is
88still logically an independent value, no longer associated with the
89original object (if there was one).
90
91If every object in the language is stored in addressable memory,
92pass-by-reference can be easily implemented by simply passing the
93address of the object. If an l-value can have more structure than
94just a single, independently-addressable object, more information may
95be required from the caller. For example, an array argument in
96FORTRAN can be a row or column vector from a matrix, and so arrays are
97generally passed as both an address and a stride. C and C++ do have
98unaddressable l-values because of bitfields, but they forbid passing
99bitfields by reference (in C++) or taking their address (in either
100language), which greatly simplifies pointer and reference types in
101those languages.
102
103FORTRAN is the last remaining example of a language that defaults to
104pass-by-reference. Early FORTRAN implementations famously passed
105constants by passing the address of mutable global memory initialized
106to the constant; if the callee modified its parameter (illegal under
107the standard, but...), it literally changed the constant for future
108uses. FORTRAN now allows procedures to explicitly take arguments by
109value and explicitly declare that arguments must be l-values.
110
111However, many languages do allow parameters to be explicitly marked as
112pass-by-reference. As mentioned for C++, sometimes only certain kinds
113of l-values are allowed.
114
115Swift allows parameters to be marked as pass-by-reference with
116`inout`. Arbitrary l-values can be passed. The Swift convention is
117to always pass an address; if the parameter is not addressable, it
118must be materialized into a temporary and then written back. See the
119accessors proposal for more details about the high-level semantics of
120`inout` arguments.
121
122Pass-by-value
123-------------
124
125In pass-by-value, if `A` is an l-value expression, `foo(A)` copies the
126current value there. Any modifications `foo` makes to its parameter
127are made to this copy, not to the original l-value.
128
129Most modern languages are pass-by-value, with specific functions able
130to opt in to pass-by-reference semantics. This is exactly what Swift
131does.
132
133There's not much room for variation in the high-level semantics of
134passing arguments by value; all the variation is in the ownership and
135physical conventions.
136
137Ownership transfer conventions
138==============================
139
140Arguments and results that require cleanup, like an Objective-C object
141reference or a non-POD C++ object, raise two questions about
142responsibility: who is responsible for cleaning it up, and when?
143
144These questions arise even when the cleanup is explicit in code. C's
145`strdup` function returns newly-allocated memory which the caller is
146responsible for freeing, but `strtok` does not. Objective-C has
147standard naming conventions that describe which functions return
148objects that the caller is responsible for releasing, and outside of
149ARC these must be followed manually. Of course, conventions designed
150to be implemented by programmers are often designed around the
151simplicity of that implementation, rather than necessarily being more
152efficient.
153
154Pass-by-reference arguments
155---------------------------
156
157Pass-by-reference arguments generally don't involve a *transfer* of
158ownership. It's assumed that the caller will ensure that the referent
159is valid at the time of the call, and that the callee will ensure that
160the referent is still valid at the time of return.
161
162FORTRAN does actually allow parameters to be tagged as out-parameters,
163where the caller doesn't guarantee the validity of the argument before
164the call. Objective-C has something similar, where an indirect method
165argument can be marked `out`; ARC takes advantage of this with
166autoreleasing parameters to avoid a copy into the writeback temporary.
167Neither of these are something we semantically care about supporting
168in Swift.
169
170There is one other theoretically interesting convention question here:
171the argument has to be valid before the call and after the call, but
172does it have to valid during the call? Swift's answer to this is
173generally "yes". Swift does have `inout` aliasing rules that allow a
174certain amount of optimization, but the compiler is forbidden from
175exploiting these rules in any way that could cause memory corruption
176(at least in the absence of race conditions). So Swift has to ensure
177that an `inout` argument is valid whenever it does something
178(including calling an opaque function) that could potentially access
179the original l-value.
180
181If Swift allowed local variables to be captured through `inout`
182parameters, and therefore needed to pass an implicit owner parameter
183along with an address, this owner parameter would behave like a
184pass-by-value argument and could use any of the conventions listed
185below. However, the optimal convention for this is obvious: it should
186be `guaranteed`, since captures are very unlikely and callers are
187almost always expected to use the value of an `inout` variable
188afterwards.
189
190Pass-by-value arguments
191-----------------------
192
193All conventions for this have performance trade-offs.
194
195We're only going to discuss *static* conventions, where the transfer
196is picked at compile time. It's possible to have a *dynamic*
197convention, where the caller passes a flag indicating whether it's
198okay to directly take responsibility for the value, and the callee can
199(conceptually) return a flag indicating whether it actually did take
200responsibility for it. If copying is extremely expensive, that can be
201worthwhile; otherwise, the code cost may overwhelm any other benefits.
202
203This discussion will ignore one particular impact of these conventions
204on code size. If a function has many callers, conventions that
205require more code in the caller are worse, all else aside. If a
206single call site has many possible targets, conventions that require
207more code in the callee are worse, all else aside. It's not really
208reasonable to decide this in advance for unknown code; we could maybe
209make rules about code calling system APIs, except that system APIs are
210by definition locked down, and we can't change them. It's a
211reasonable thing to consider changing with PGO, though.
212
213Responsibility
214~~~~~~~~~~~~~~
215
216A common refrain in this performance analysis will be whether a
217function has responsibility for a value. A function has to get a
218value from *somewhere*:
219
220* A caller is usually responsible for the return values it receives:
221 the callee generated the value and the caller is responsible for
222 destroying it. Any other convention has to rely on heavily
223 restricting what kind of value can be returned. (If you're thinking
224 about Objective-C autoreleased results, just accept this for now;
225 we'll talk about that later.)
226
227* A function isn't necessarily responsible for a value it loads from
228 memory. Ignoring race conditions, the function may be able to
229 immediately use the value without taking any specific action to keep
230 it valid.
231
232* A callee may or may not be responsible for a value passed as a
233 parameter, depending on the convention it was passed with.
234
235* A function might come from a source that doesn't necessarily make
236 the function responsible, but if the function takes an action which
237 invalidates the source before using the value, the function has to
238 take action to keep the value valid. At that point, the function
239 has responsibility for the value despite its original source.
240
241 For example, a function `foo()` might load a reference `r` from a
242 global variable `x`, call an unknown function `bar()`, and then use
243 `r` in some way. If `bar()` can't possibly overwrite `x`, `foo()`
244 doesn't have to do anything to keep `r` alive across the call;
245 otherwise it does (e.g. by retaining it in a refcounted
246 environment). This is a situation where humans are often much
247 smarter than compilers. Of course, it's also a situation where
248 humans are sometimes insufficiently conservative.
249
250A function may also require responsibility for a value as part of its
251operation:
252
253* Since a variable is always responsible for the current value it
254 stores, a function which stores a value into memory must first gain
255 responsibility for that value.
256
257* A callee normally transfers responsibility for its return value to
258 its caller; therefore it must gain responsibility for its return
259 value before returning it.
260
261* A caller may need to gain responsibility for a value before passing
262 it as an argument, depending on the parameter's ownership-transfer
263 convention.
264
265Known conventions
266~~~~~~~~~~~~~~~~~
267
268There are three static parameter conventions for ownership worth
269considering here:
270
271* The caller may transfer responsibility for the value to the callee.
272 In SIL, we call this an **owned** parameter.
273
274 This is optimal if the caller has responsibility for the value and
275 doesn't need it after the call. This is an extremely common
276 situation; for example, it comes up whenever a call result is
277 immediately used as an argument. By giving the callee responsibility
278 for the value, this convention allows the callee to use the value at
279 a later point without taking any extra action to keep it alive.
280
281 The flip side is that this convention requires a lot of extra work
282 when a single value is used multiple times in the caller. For
283 example, a value passed in every iteration of a loop will need to be
284 copied/retained/whatever each time.
285
286* The caller may provide the value without any responsibility on
287 either side. In SIL, we call this an **unowned** parameter. The
288 value is guaranteed to be valid at the moment of the call, and in
289 the absence of race conditions, that guarantee can be assumed to
290 continue unless the callee does something that might invalidate it.
291 As discussed above, humans are often much smarter than computers
292 about knowing when that's possible.
293
294 This is optimal if the caller can acquire the value without
295 responsibility and the callee doesn't require responsibility of it.
296 In very simple code --- e.g., loading values from an array and
297 passing them to a comparator function which just reads a few fields
298 from each and returns --- this can be extremely efficient.
299
300 Unfortunately, this convention is completely undermined if either
301 side has to do anything that forces it to take action to keep the
302 value alive. Also, if that happens on the caller side, the
303 convention can keep values alive longer than is necessary. It's
304 very easy for both sides of the convention to end up doing extra
305 work because of this.
306
307* The caller may assert responsibility for the value. In SIL, we call
308 this a **guaranteed** parameter. The callee can rely on the value
309 staying valid for the duration of the call.
310
311 This is optimal if the caller needs to use the value after the call
312 and either has responsibility for it or has a guarantee like this
313 for it. Therefore, this convention is particularly nice when a
314 value is likely to be forwarded by value a great deal.
315
316 However, this convention does generally keep values alive longer
317 than is necessary, since the outermost function which passed it as
318 an argument will generally be forced to hold a reference for the
319 duration. By the same mechanism, in refcounted systems, this
320 convention tends to cause values to have multiple retains active at
321 once; for example, if a copy-on-write array is created in one
322 function, passed to another, stored in a mutable variable, and then
323 modified, the callee will see a reference count of 2 and be forced
324 to do a structural copy. This can occur even if the caller
325 literally constructed the array for the sole and immediate purpose
326 of passing it to the callee.
327
328Analysis
329~~~~~~~~
330
331Objective-C generally uses the unowned convention for object-pointer
332parameters. It is possible to mark a parameter as being consumed,
333which is basically the owned convention. As a special case, in ARC we
334assume that callers are responsible for keeping `self` values alive
335(including in blocks), which is effectively the `guaranteed`
336convention.
337
338`unowned` causes a lot of problems without really solving any, in my
339experience looking at ARC-generated code and optimizer output. A
340human can take advantage of it, but the compiler is so frequently
341blocked. There are many common idioms (like chains of functions that
342just add default arguments at each step) have really awful performance
343because the compiler is adding retains and releases at every single
344level. It's just not a good convention to adopt by default. However,
345we might want to consider allowing specific function parameters to opt
346into it; sort comparators are a particularly interesting candidate
347for this. `unowned` is very similar to C++'s `const &` for things
348like that.
349
350`guaranteed` is good for some things, but it causes a lot of silly
351code bloat when values are really only used in one place, which is
352quite common. The liveness / refcounting issues are also pretty
353problematic. But there is one example that's very nice for
354`guaranteed`: `self`. It's quite common for clients of a type to call
355multiple methods on a single value, or for methods to dispatch to
356multiple other methods, which are exactly the situations where
357`guaranteed` excels. And it's relatively uncommon (but not
358unimaginable) for a non-mutating method on a copy-on-write struct to
359suddenly store `self` aside and start mutating that copy.
360
361`owned` is a good default for other parameters. It has some minor
362performance disadvantages (unnecessary retains if you have an
363unoptimizable call in a loop) and some minor code size benefits (in
364common straight-line code), but frankly, both of those points pale in
365importance to the ability to transfer copy-on-write structures around
366without spuriously increasing reference counts. It doesn't take too
367many unnecessary structural copies before any amount of
368reference-counting traffic (especially the Swift-native
369reference-counting used in copy-on-write structures) is basically
370irrelevant in comparison.
371
372Result values
373-------------
374
375There's no major semantic split in result conventions like that
376between pass-by-reference and pass-by-value. In most languages, a
377function has to return a value (or nothing). There are languages like
378C++ where functions can return references, but that's inherently
379limited, because the reference has to refer to something that exists
380outside the function. If Swift ever adds a similar language
381mechanism, it'll have to be memory-safe and extremely opaque, and
382it'll be easy to just think of that as a kind of weird value result.
383So we'll just consider value results here.
384
385Value results raise some of the same ownership-transfer questions as
386value arguments. There's one major limitation: just like a
387by-reference result, an actual `unowned` convention is inherently
388limited, because something else other than the result value must be
389keeping it valid. So that's off the table for Swift.
390
391What Objective-C does is something more dynamic. Most APIs in
392Objective-C give you a very ephemeral guarantee about the validity of
393the result: it's valid now, but you shouldn't count on it being valid
394indefinitely later. This might be because the result is actually
395owned by some other object somewhere, or it might be because the
396result has been placed in the autorelease pool, a thread-local data
397structure which will (when explicitly drained by something up the call
398chain) eventually release that's been put into it. This autorelease
399pool can be a major source of spurious memory growth, and in classic
400manual reference-counting it was important to drain it fairly
401frequently. ARC's response to this convention was to add an
402optimization which attempts to prevent things from ending up in the
403autorelease pool; the net effect of this optimization is that ARC ends
404up with an owned reference regardless of whether the value was
405autoreleased. So in effect, from ARC's perspective, these APIs still
406return an owned reference, mediated through some extra runtime calls
407to undo the damage of the convention.
408
409So there's really no compelling alternative to an owned return
410convention as the default in Swift.
411
412Physical conventions
413====================
414
415The lowest abstraction level for a calling convention is the actual
416"physical" rules for the call:
417
418* where the caller should place argument values in registers and
419 memory before the call,
420
421* how the callee should pass back the return values in registers
422 and/or memory after the call, and
423
424* what invariants hold about registers and memory over the call.
425
426In theory, all of these could be changed in the Swift ABI. In
427practice, it's best to avoid changes to the invariant rules, because
428those rules could complicate Swift-to-C interoperation:
429
430* Assuming a higher stack alignment would require dynamic realignment
431 whenever Swift code is called from C.
432
433* Assuming a different set of callee-saved registers would require
434 additional saves and restores when either Swift code calls C or is
435 called from C, depending on the exact change. That would then
436 inhibit some kinds of tail call.
437
438So we will limit ourselves to considering the rules for allocating
439parameters and results to registers. Our platform C ABIs are usually
440quite good at this, and it's fair to ask why Swift shouldn't just use
441C's rules. There are three general answers:
442
443* Platform C ABIs are specified in terms of the C type system, and the
444 Swift type system allows things to be expressed which don't have
445 direct analogues in C (for example, enums with payloads).
446
447* The layout of structures in Swift does not necessarily match their
448 layout in C, which means that the C rules don't necessarily cover
449 all the cases in Swift.
450
451* Swift places a larger emphasis on first-class structs than C does.
452 C ABIs often fail to allocate even small structs to registers, or
453 use inefficient registers for them, and we would like to be somewhat
454 more aggressive than that.
455
456Accordingly, the Swift ABI is defined largely in terms of lowering: a
457Swift function signature is translated to a C function signature with
458all the aggregate arguments and results eliminated (possibly by
459deciding to pass them indirectly). This lowering will be described in
460detail in the final section of this whitepaper.
461
462However, there are some specific circumstances where we'd like to
463deviate from the platform ABI:
464
465Aggregate results
466-----------------
467
468As mentioned above, Swift puts a lot of focus on first-class value
469types. As part of this, it's very valuable to be able to return
470common value types fully in registers instead of indirectly. The
471magic number here is three: it's very common for copy-on-write value
472types to want about three pointers' worth of data, because that's just
473enough for some sort of owner pointer plus a begin/end pair.
474
475Unfortunately, many common C ABIs fall slightly short of that. Even
476those ABIs that do allow small structs to be returned in registers
477tend to only allow two pointers' worth. So in general, Swift would
478benefit from a very slightly-tweaked calling convention that allocates
479one or two more registers to the result.
480
481Implicit parameters
482-------------------
483
484There are several language features in Swift which require implicit
485parameters:
486
487Closures
488~~~~~~~~
489
490Swift's function types are "thick" by default, meaning that a function
491value carries an optional context object which is implicitly passed to
492the function when it is called. This context object is
493reference-counted, and it should be passed `guaranteed` for
494straightforward reasons:
495
496* It's not uncommon for closures to be called many times, in which
497 case an `owned` convention would be unnecessarily expensive.
498
499* While it's easy to imagine a closure which would want to take
500 responsibility for its captured values, giving it responsibility for
501 a retain of the context object doesn't generally allow that. The
502 closure would only be able to take ownership of the captured values
503 if it had responsibility for a *unique* reference to the context.
504 So the closure would have to be written to do different things based
505 on the uniqueness of the reference, and it would have to be able to
506 tear down and deallocate the context object after stealing values
507 from it. The optimization just isn't worth it.
508
509* It's usually straightforward for the caller to guarantee the
510 validity of the context reference; worst case, a single extra
511 Swift-native retain/release is pretty cheap. Meanwhile, not having
512 that guarantee would force many closure functions to retain their
513 contexts, since many closures do multiple things with values from
514 the context object. So `unowned` would not be a good convention.
515
516Many functions don't actually need a context, however; they are
517naturally "thin". It would be best if it were possible to construct a
518thick function directly from a thin function without having to
519introduce a thunk just to move parameters around the missing context
520parameter. In the worst case, a thunk would actually require the
521allocation of a context object just to store the original function
522pointer; but that's only necessary when converting from a completely
523opaque function value. When the source function is known statically,
524which is far more likely, the thunk can just be a global function
525which immediately calls the target with the correctly shuffled
526arguments. Still, it'd be better to be able to avoid creating such
527thunks entirely.
528
529In order to reliably avoid creating thunks, it must be possible for
530code invoking an opaque thick function to pass the context pointer in
531a way that can be safely and implicitly ignored if the function
532happens to actually be thin. There are two ways to achieve this:
533
534* The context can be passed as the final parameter. In most C calling
535 conventions, extra arguments can be safely ignored; this is because
536 most C calling conventions support variadic arguments, and such
537 conventions inherently can't rely on the callee knowing the extent
538 of the arguments.
539
540 However, this is sub-optimal because the context is often used
541 repeatedly in a closure, especially at the beginning, and putting it
542 at the end of the argument list makes it more likely to be passed on
543 the stack.
544
545* The context can be passed in a register outside of the normal
546 argument sequence. Some ABIs actually even reserve a register for
547 this purpose; for example, on x86-64 it's `%r10`. Neither of the
548 ARM ABIs do, however.
549
550Having an out-of-band register would be the best solution.
551
552(Surprisingly, the ownership transfer convention for the context
553doesn't actually matter here. You might think that an `owned`
554convention would be prohibited, since the callee would fail to release
555the context and would therefore leak it. However, a thin function
556should always have a `nil` context, so this would be harmless.)
557
558Either solution works acceptably with curried partial application,
559since the inner parameters can be left in place while transforming the
560context into the outer parameters. However, an `owned` convention
561would either prevent the uncurrying forwarder from tail-calling the
562main function or force all the arguments to be spilled. Neither is
563really acceptable; one more argument against an `owned` convention.
564(This is another example where `guaranteed` works quite nicely, since
565the guarantees are straightforward to extend to the main function.)
566
567`self`
568~~~~~~
569
570Methods (both static and instance) require a `self` parameter. In all
571of these cases, it's reasonable to expect that `self` will used
572frequently, so it's best to pass it in a register. Also, many methods
573call other methods on the same object, so it's also best if the
574register storing `self` is stable across different method signatures.
575
576In static methods on value types, `self` doesn't require any dynamic
577information: there's only one value of the metatype, and there's
578usually no point in passing it.
579
580In static methods on class types, `self` is a reference to the class
581metadata, a single pointer. This is necessary because it could
582actually be the class object of a subclass.
583
584In instance methods on class types, `self` is a reference to the
585instance, again a single pointer.
586
587In mutating instance methods on value types, `self` is the address of
588an object.
589
590In non-mutating instance methods on value types, `self` is a value; it
591may require multiple registers, or none, or it may need to be passed
592indirectly.
593
594All of these cases except mutating instance methods on value types can
595be partially applied to create a function closure whose type is the
596formal type of the method. That is, if class `A` has a method
597declared `func foo(_ x: Int) -> Double`, then `A.foo` yields a function
598of type `(Int) -> Double`. Assuming that we continue to feel that
599this is a useful language feature, it's worth considered how we could
600support it efficiently. The expenses associated with a partial
601application are (1) the allocation of a context object and (2) needing
602to introduce a thunk to forward to the original function. All else
603aside, we can avoid the allocation if the representation of `self` is
604compatible with the representation of a context object reference; this
605is essentially true only if `self` is a class instance using Swift
606reference counting. Avoiding the thunk is possible only if we
607successfully avoided the allocation (since otherwise a thunk is
608required in order to extract the correct `self` value from the
609allocated context object) and `self` is passed in exactly the same
610manner as a closure context would be.
611
612It's unclear whether making this more efficient would really be
613worthwhile on its own, but if we do support an out-of-band context
614parameter, taking advantage of it for methods is essentially trivial.
615
616Error handling
617--------------
618
619The calling convention implications of Swift's error handling design
620aren't yet settled. It may involve extra parameters; it may involve
621extra return values. Considerations:
622
623* Callers will generally need to immediately check for an error.
624 Being able to quickly check a register would be extremely
625 convenient.
626
627* If the error is returned as a component of the result value, it
628 shouldn't be physically combined with the normal result. If the
629 normal result is returned in registers, it would be unfortunate to
630 have to do complicated logic to test for error. If the normal
631 result is returned indirectly, contorting the indirect result with
632 the error would likely prevent the caller from evaluating the call
633 in-place.
634
635* It would be very convenient to be able to trivially turn a function
636 which can't produce an error into a function which can. This is an
637 operation that we expect higher-order code to have do frequently, if
638 it isn't completely inlined away. For example::
639
640 // foo() expects its argument to follow the conventions of a
641 // function that's capable of throwing.
642 func foo(_ fn: () throws -> ()) throwsIf(fn)
643
644 // Here we're passing foo() a function that can't throw; this is
645 // allowed by the subtyping rules of the language. We'd like to be
646 // able to do this without having to introduce a thunk that maps
647 // between the conventions.
648 func bar(_ fn: () -> ()) {
649 foo(fn)
650 }
651
652We'll consider two ways to satisfy this.
653
654The first is to pass a pointer argument that doesn't interfere with
655the normal argument sequence. The caller would initialize the memory
656to a zero value. If the callee is a throwing function, it would be
657expected to write the error value into this argument; otherwise, it
658would naturally ignore it. Of course, the caller then has to load
659from memory to see whether there's an error. This would also either
660consume yet another register not in the normal argument sequence or
661have to be placed at the end of the argument list, making it more
662likely to be passed on the stack.
663
664The second is basically the same idea, but using a register that's
665otherwise callee-save. The caller would initialize the register to a
666zero value. A throwing function would write the error into it; a
667non-throwing function would consider it callee-save and naturally
668preserve it. It would then be extremely easy to check it for an
669error. Of course, this would take away a callee-save register in the
670caller when calling throwing functions. Also, if the caller itself
671isn't throwing, it would have to save and restore that register.
672
673Both solutions would allow tail calls, and the zero store could be
674eliminated for direct calls to known functions that can throw. The
675second is the clearly superior solution, but definitely requires more
676work in the backend.
677
678Default argument generators
679---------------------------
680
681By default, Swift is resilient about default arguments and treats them
682as essentially one part of the implementation of the function. This
683means that, in general, a caller using a default argument must call a
684function to emit the argument, instead of simply inlining that
685emission directly into the call.
686
687These default argument generation functions are unlike any other
688because they have very precise information about how their result will
689be used: it will be placed into a specific position in specific
690argument list. The only reason the caller would ever want to do
691anything else with the result is if it needs to spill the value before
692emitting the call.
693
694Therefore, in principle, it would be really nice if it were possible
695to tell these functions to return in a very specific way, e.g. to
696return two values in the second and third argument registers, or to
697return a value at a specific location relative to the stack pointer
698(although this might be excessively constraining; it would be
699reasonable to simply opt into an indirect return instead). The
700function should also preserve earlier argument registers (although
701this could be tricky if the default argument generator is in a generic
702context and therefore needs to be passed type-argument information).
703
704This enhancement is very easy to postpone because it doesn't affect
705any basic language mechanics. The generators are always called
706directly, and they're inherently attached to a declaration, so it's
707quite easy to take any particular generator and compatibly enhance it
708with a better convention.
709
710ARM32
711-----
712
713Most of the platforms we support have pretty good C calling
714conventions. The exceptions are i386 (for the iOS simulator) and
715ARM32 (for iOS). We really, really don't care about i386, but iOS on
716ARM32 is still an important platform. Switching to a better physical
717calling convention (only for calls from Swift to Swift, of course)
718would be a major improvement.
719
720It would be great if this were as simple as flipping a switch, but
721unfortunately the obvious convention to switch to (AAPCS-VFP) has a
722slightly different set of callee-save registers: iOS treats `r9` as a
723scratch register. So we'd really want a variant of AAPCS-VFP that did
724the same. We'd also need to make sure that SJ/LJ exceptions weren't
725disturbed by this calling convention; we aren't really *supporting*
726exception propagation through Swift frames, but completely breaking
727propagation would be unfortunate, and we may need to be able to
728*catch* exceptions.
729
730So this would also require some amount of additional support from the
731backend.
732
733Function signature lowering
734===========================
735
736Function signatures in Swift are lowered in two phases.
737
738Semantic lowering
739-----------------
740
741The first phase is a high-level semantic lowering, which does a number
742of things:
743
744* It determines a high-level calling convention: specifically, whether
745 the function must match the C calling convention or the Swift
746 calling convention.
747
748* It decides the types of the parameters:
749
750 * Functions exported for the purposes of C or Objective-C may need
751 to use bridged types rather than Swift's native types. For
752 example, a function that formally returns Swift's `String` type
753 may be bridged to return an `NSString` reference instead.
754
755 * Functions which are values, not simply immediately called, may
756 need their types lowered to follow to match a specific generic
757 abstraction pattern. This applies to functions that are
758 parameters or results of the outer function signature.
759
760* It identifies specific arguments and results which *must* be passed
761 indirectly:
762
763 * Some types are inherently address-only:
764
765 * The address of a weak reference must be registered with the
766 runtime at all times; therefore, any `struct` with a weak field
767 must always be passed indirectly.
768
769 * An existential type (if not class-bounded) may contain an
770 inherently address-only value, or its layout may be sensitive to
771 its current address.
772
773 * A value type containing an inherently address-only type as a
774 field or case payload becomes itself inherently address-only.
775
776 * Some types must be treated as address-only because their layout is
777 not known statically:
778
779 * The layout of a resilient value type may change in a later
780 release; the type may even become inherently address-only by
781 adding a weak reference.
782
783 * In a generic context, the layout of a type may be dependent on a
784 type parameter. The type parameter might even be inherently
785 address-only at runtime.
786
787 * A value type containing a type whose layout isn't known
788 statically itself generally will not have a layout that can be
789 known statically.
790
791 * Other types must be passed or returned indirectly because the
792 function type uses an abstraction pattern that requires it. For
793 example, a generic `map` function expects a function that takes a
794 `T` and returns a `U`; the generic implementation of `map` will
795 expect these values to be passed indirectly because their layout
796 isn't statically known. Therefore, the signature of a function
797 intended to be passed as this argument must pass them indirectly,
798 even if they are actually known statically to be non-address-only
799 types like (e.g.) `Int` and `Float`.
800
801* It expands tuples in the parameter and result types. This is done
802 at this level both because it is affected by abstraction patterns
803 and because different tuple elements may use different ownership
804 conventions. (This is most likely for imported APIs, where it's the
805 tuple elements that correspond to specific C or Objective-C parameters.)
806
807 This completely eliminates top-level tuple types from the function
808 signature except when they are a target of abstraction and thus are
809 passed indirectly. (A function with type `(Float, Int) -> Float`
810 can be abstracted as `(T) -> U`, where `T == (Float, Int)`.)
811
812* It determines ownership conventions for all parameters and results.
813
814After this phase, a function type consists of an abstract calling
815convention, a list of parameters, and a list of results. A parameter
816is a type, a flag for indirectness, and an ownership convention. A
817result is a type, a flag for indirectness, and an ownership
818convention. (Results need ownership conventions only for non-Swift
819calling conventions.) Types will not be tuples unless they are
820indirect.
821
822Semantic lowering may also need to mark certain parameters and results
823as special, for the purposes of the special-case physical treatments
824of `self`, closure contexts, and error results.
825
826Physical lowering
827-----------------
828
829The second phase of lowering translates a function type produced by
830semantic lowering into a C function signature. If the function
831involves a parameter or result with special physical treatment,
832physical lowering initially ignores this value, then adds in the
833special treatment as agreed upon with the backend.
834
835General expansion algorithm
836~~~~~~~~~~~~~~~~~~~~~~~~~~~
837
838Central to the operation of the physical-lowering algorithm is the
839**generic expansion algorithm**. This algorithm turns any
840non-address-only Swift type in a sequence of zero or more **legal
841type**, where a legal type is either:
842
843* an integer type, with a power-of-two size no larger than the maximum
844 integer size supported by C on the target,
845
846* a floating-point type supported by the target, or
847
848* a vector type supported by the target.
849
850Obviously, this is target-specific. The target also specifies a
851maximum voluntary integer size. The legal type sequence only contains
852vector types or integer types larger than the maximum voluntary size
853when the type was explicit in the input.
854
855Pointers are represented as integers in the legal type sequence. We
856assume there's never a reason to differentiate them in the ABI as long
857as the effect of address spaces on pointer size is taken into account.
858If that's not true, this algorithm should be adjusted.
859
860The result of the algorithm also associates each legal type with an
861offset. This information is sufficient to reconstruct an object in
862memory from a series of values and vice-versa.
863
864The algorithm proceeds in two steps.
865
866Typed layouts
867^^^^^^^^^^^^^
868
869First, the type is recursively analyzed to produce a **typed layout**.
870A typed layout associates ranges of bytes with either (1) a legal type
871(whose storage size must match the size of the associated byte
872range), (2) the special type **opaque**, or (3) the special type
873**empty**. Adjacent ranges mapped to **opaque** or **empty** can be
874combined.
875
876For most of the types in Swift, this process is obvious: they either
877correspond to an obvious legal type (e.g. thick metatypes are
878pointer-sized integers), or to an obvious sequence of scalars
879(e.g. class existentials are a sequence of pointer-sized integers).
880Only a few cases remain:
881
882* Integer types that are not legal types should be mapped as opaque.
883
884* Vector types that are not legal types should be broken into smaller
885 vectors, if their size is an even multiple of a legal vector type,
886 or else broken into their components. (This rule may need some
887 tinkering.)
888
889* Tuples and structs are mapped by merging the typed layouts of the
890 fields, as padded out to the extents of the aggregate with
891 empty-mapped ranges. Note that, if fields do not overlap, this is
892 equivalent to concatenating the typed layouts of the fields, in
893 address order, mapping internal padding to empty. Bit-fields should
894 map the bits they occupy to opaque.
895
896 For example, given the following struct type::
897
898 struct FlaggedPair {
899 var flag: Bool
900 var pair: (MyClass, Float)
901 }
902
903 If Swift performs naive, C-like layout of this structure, and this
904 is a 64-bit platform, typed layout is mapped as follows::
905
906 FlaggedPair.flag := [0: i1, ]
907 FlaggedPair.pair := [ 8-15: i64, 16-19: float]
908 FlaggedPair := [0: i1, 8-15: i64, 16-19: float]
909
910 If Swift instead allocates `flag` into the spare (little-endian) low
911 bits of `pair.0`, the typed layout map would be::
912
913 FlaggedPair.flag := [0: i1 ]
914 FlaggedPair.pair := [0-7: i64, 8-11: float]
915 FlaggedPair := [0-7: opaque, 8-11: float]
916
917* Unions (imported from C) are mapped by merging the typed layouts of
918 the fields, as padded out to the extents of the aggregate with
919 empty-mapped ranges. This will often result in a fully-opaque
920 mapping.
921
922* Enums are mapped by merging the typed layouts of the cases, as
923 padded out to the extents of the aggregate with empty-mapped ranges.
924 A case's typed layout consists of the typed layout of the case's
925 directly-stored payload (if any), merged with the typed layout for
926 its discriminator. We assume that checking for a discriminator
927 involves a series of comparisons of bits extracted from
928 non-overlapping ranges of the value; the typed layout of a
929 discriminator maps all these bits to opaque and the rest to empty.
930
931 For example, given the following enum type::
932
933 enum Sum {
934 case Yes(MyClass)
935 case No(Float)
936 case Maybe
937 }
938
939 If Swift, in its infinite wisdom, decided to lay this out
940 sequentially, and to use invalid pointer values the class to
941 indicate that the other cases are present, the layout would look as
942 follows::
943
944 Sum.Yes.payload := [0-7: i64 ]
945 Sum.Yes.discriminator := [0-7: opaque ]
946 Sum.Yes := [0-7: opaque ]
947 Sum.No.payload := [ 8-11: float]
948 Sum.No.discriminator := [0-7: opaque ]
949 Sum.No := [0-7: opaque, 8-11: float]
950 Sum.Maybe := [0-7: opaque ]
951 Sum := [0-7: opaque, 8-11: float]
952
953 If Swift instead chose to just use a discriminator byte, the layout
954 would look as follows::
955
956 Sum.Yes.payload := [0-7: i64 ]
957 Sum.Yes.discriminator := [ 8: opaque]
958 Sum.Yes := [0-7: i64, 8: opaque]
959 Sum.No.payload := [0-3: float ]
960 Sum.No.discriminator := [ 8: opaque]
961 Sum.No := [0-3: float, 8: opaque]
962 Sum.Maybe := [ 8: opaque]
963 Sum := [0-8: opaque ]
964
965 If Swift chose to use spare low (little-endian) bits in the class
966 pointer, and to offset the float to make this possible, the layout
967 would look as follows::
968
969 Sum.Yes.payload := [0-7: i64 ]
970 Sum.Yes.discriminator := [0: opaque ]
971 Sum.Yes := [0-7: opaque ]
972 Sum.No.payload := [ 4-7: float]
973 Sum.No.discriminator := [0: opaque ]
974 Sum.No := [0: opaque, 4-7: float]
975 Sum.Maybe := [0: opaque ]
976 Sum := [0-7: opaque ]
977
978The merge algorithm for typed layouts is as follows. Consider two
979typed layouts `L` and `R`. A range from `L` is said to *conflict*
980with a range from `R` if they intersect and they are mapped as
981different non-empty types. If two ranges conflict, and either range
982is mapped to a vector, replace it with mapped ranges for the vector
983elements. If two ranges conflict, and neither range is mapped to a
984vector, map them both to opaque, combining them with adjacent opaque
985ranges as necessary. If a range is mapped to a non-empty type, and
986the bytes in the range are all mapped as empty in the other map, add
987that range-mapping to the other map. `L` and `R` should now match
988perfectly; this is the result of the merge. Note that this algorithm
989is both associative and commutative.
990
991Forming a legal type sequence
992^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
993
994Once the typed layout is constructed, it can be turned into a legal
995type sequence.
996
997Note that this transformation is sensitive to the offsets of ranges in
998the complete type. It's possible that the simplifications described
999here could be integrated directly into the construction of the typed
1000layout without changing the results, but that's not yet proven.
1001
1002In all of these examples, the maximum voluntary integer size is 4
1003(`i32`) unless otherwise specified.
1004
1005If any range is mapped as a non-empty, non-opaque type, but its start
1006offset is not a multiple of its natural alignment, remap it as opaque.
1007For these purposes, the natural alignment of an integer type is the
1008minimum of its size and the maximum voluntary integer size; the
1009natural alignment of any other type is its C ABI type. Combine
1010adjacent opaque ranges.
1011
1012For example::
1013
1014 [1-2: i16, 4: i8, 6-7: i16] ==> [1-2: opaque, 4: i8, 6-7: i16]
1015
1016If any range is mapped as an integer type that is not larger than the
1017maximum voluntary size, remap it as opaque. Combine adjacent opaque
1018ranges.
1019
1020For example::
1021
1022 [1-2: opaque, 4: i8, 6-7: i16] ==> [1-2: opaque, 4: opaque, 6-7: opaque]
1023 [0-3: i32, 4-11: i64, 12-13: i16] ==> [0-3: opaque, 4-11: i64, 12-13: opaque]
1024
1025An *aligned storage unit* is an N-byte-aligned range of N bytes, where
1026N is a power of 2 no greater than the maximum voluntary integer size.
1027A *maximal* aligned storage unit has a size equal to the maximum
1028voluntary integer size.
1029
1030Note that any remaining ranges mapped as integers must fully occupy
1031multiple maximal aligned storage units.
1032
1033Split all opaque ranges at the boundaries of maximal aligned storage
1034units. From this point on, never combine adjacent opaque ranges
1035across these boundaries.
1036
1037For example::
1038
1039 [1-6: opaque] ==> [1-3: opaque, 4-6: opaque]
1040
1041Within each maximal aligned storage unit, find the smallest aligned
1042storage unit which contains all the opaque ranges. Replace the first
1043opaque range in the maximal aligned storage unit with a mapping from
1044that aligned storage unit to an integer of the aligned storage unit's
1045size. Remove any other opaque ranges in the maximal aligned storage
1046unit. Note that this can create overlapping ranges in some cases.
1047For this purposes of this calculation, the last maximal aligned
1048storage unit should be considered "full", as if the type had an
1049infinite amount of empty tail-padding.
1050
1051For example::
1052
1053 [1-2: opaque] ==> [0-3: i32]
1054 [0-1: opaque] ==> [0-1: i16]
1055 [0: opaque, 2: opaque] ==> [0-3: i32]
1056 [0-9: fp80, 10: opaque] ==> [0-9: fp80, 10: i8]
1057
1058 // If maximum voluntary size is 8 (i64):
1059 [0-9: fp80, 11: opaque, 13: opaque] ==> [0-9: fp80, 8-15: i64]
1060
1061(This assumes that `fp80` is a legal type for illustrative purposes.
1062It would probably be a better policy for the actual x86-64 target to
1063consider it illegal and treat it as opaque from the start, at least
1064when lowering for the Swift calling convention; for C, it is important
1065to produce an `fp80` mapping for ABI interoperation with C functions
1066that take or return `long double` by value.)
1067
1068The final legal type sequence is the sequence of types for the
1069non-empty ranges in the map. The associated offset for each type is
1070the offset of the start of the corresponding range.
1071
1072Only the final step can introduce overlapping ranges, and this is only
1073possible if there's a non-integer legal type which:
1074
1075* has a natural alignment less than half of the size of the maximum
1076 voluntary integer size or
1077
1078* has a store size is not a multiple of half the size of the maximum
1079 voluntary integer size.
1080
1081On our supported platforms, these conditions are only true on x86-64,
1082and only of `long double`.
1083
1084Deconstruction and Reconstruction
1085~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1086
1087Given the address of an object and a legal type sequence for its type,
1088it's straightforward to load a valid sequence or store the sequence
1089back into memory. For the most part, it's sufficient to simply load
1090or store each value at its appropriate offset. There are two
1091subtleties:
1092
1093* If the legal type sequence had any overlapping ranges, the integer
1094 values should be stored first to prevent overwriting parts of the
1095 other values they overlap.
1096
1097* Care must be taken with the final values in the sequence; integer
1098 values may extend slightly beyond the ordinary storage size of the
1099 argument type. This is usually easy to compensate for.
1100
1101The value sequence essentially has the same semantics that the value
1102in memory would have: any bits that aren't part of the actual
1103representation of the original type have a completely unspecified
1104value.
1105
1106Forming a C function signature
1107~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1108
1109As mentioned before, in principle the process of physical lowering
1110turns a semantically-lowered Swift function type (in implementation
1111terms, a SILFunctionType) into a C function signature, which can then
1112be lowered according to the usual rules for the ABI. This is, in
1113fact, what we do when trying to match a C calling convention.
1114However, for the native Swift calling convention, because we actively
1115want to use more aggressive rules for results, we instead build an
1116LLVM function type directly. We first construct a direct result type
1117that we're certain the backend knows how to interpret according to our
1118more aggressive desired rules, and then we use the expansion algorithm
1119to construct a parameter sequence consisting solely of types with
1120obvious ABI lowering that the backend can reliably handle. This
1121bypasses the need to consult Clang for our own native calling
1122convention.
1123
1124We have this generic expansion algorithm, but it's important to
1125understand that the physical lowering process does not just naively
1126use the results of this algorithm. The expansion algorithm will
1127happily expand an arbitrary structure; if that structure is very
1128large, the algorithm might turn it into hundreds of values. It would
1129be foolish to pass it as an argument that way; it would use up all the
1130argument registers and basically turn into a very inefficient memcpy,
1131and if the caller wanted it all in one place, they'd have to very
1132painstakingly reassemble. It's much better to pass large structures
1133indirectly. And with result values, we really just don't have a
1134choice; there's only so many registers you can use before you have to
1135give up and return indirectly. Therefore, even in the Swift native
1136convention, the expansion algorithm is basically used as a first pass.
1137A second pass then decides whether the expanded sequence is actually
1138reasonable to pass directly.
1139
1140Recall that one aspect of the semantically-lowered Swift function type
1141is whether we should be matching the C calling convention or not. The
1142following algorithm here assumes that the importer and semantic
1143lowering have conspired in a very particular way to make that
1144possible. Specifically, we assume is that an imported C function
1145type, lowered semantically by Swift, will follow some simple
1146structural rules:
1147
1148* If there was a by-value `struct` or `union` parameter or result in
1149 the imported C type, it will correspond to a by-value direct
1150 parameter or return type in Swift, and the Swift type will be a
1151 nominal type whose declaration links back to the original C
1152 declaration.
1153
1154* Any other parameter or result will be transformed by the importer
1155 and semantic lowering to a type that the generic expansion algorithm
1156 will expand to a single legal type whose representation is
1157 ABI-compatible with the original parameter. For example, an
1158 imported pointer type will eventually expand to an integer of
1159 pointer size.
1160
1161* There will be at most one result in the lowered Swift type, and it
1162 will be direct.
1163
1164Given this, we go about lowering the function type as follows. Recall
1165that, when matching the C calling convention, we're building a C
1166function type; but that when matching the Swift native calling
1167convention, we're building an LLVM function type directly.
1168
1169Results
1170^^^^^^^
1171
1172The first step is to consider the results of the function.
1173
1174There's a different set of rules here when we're matching the C
1175calling convention. If there's a single direct result type, and it's
1176a nominal type imported from Clang, then the result type of the C
1177function type is that imported Clang type. Otherwise, concatenate the
1178legal type sequences from the direct results. If this yields an empty
1179sequence, the result type is `void`. If it yields a single legal
1180type, the result type is the corresponding Clang type. No other could
1181actually have come from an imported C declaration, so we don't have
1182any real compatibility requirements; for the convenience of
1183interoperation, this is handled by constructing a new C struct which
1184contains the corresponding Clang types for the legal type sequence as
1185its fields.
1186
1187Otherwise, we are matching the Swift calling convention. Concatenate
1188the legal type sequences from all the direct results. If
1189target-specific logic decides that this is an acceptable collection to
1190return directly, construct the appropriate IR result type to convince
1191the backend to handle it. Otherwise, use the `void` IR result type
1192and return the "direct" results indirectly by passing the address of a
1193tuple combining the original direct results (*not* the types from the
1194legal type sequence).
1195
1196Finally, any indirect results from the semantically-lowered function
1197type are simply added as pointer parameters.
1198
1199Parameters
1200^^^^^^^^^^
1201
1202After all the results are collected, it's time to collect the
1203parameters. This is done one at the time, from left to right, adding
1204parameters to our physically-lowered type.
1205
1206If semantic lowering has decided that we have to pass the parameter
1207indirectly, we simply add a pointer to the type. This covers both
1208mandatory-indirect pass-by-value parameters and pass-by-reference
1209parameters. The latter can arise even in C and Objective-C.
1210
1211Otherwise, the rules are somewhat different if we're matching the C
1212calling convention. If the parameter is a nominal type imported from
1213Clang, then we just add the imported Clang type to the Clang function
1214type as a parameter. Otherwise, we derive the legal type sequence for
1215the parameter type. Again, we should only have compatibility
1216requirements if the legal type sequence has a single element, but for
1217the convenience of interoperation, we collect the corresponding Clang
1218types for all of the elements of the sequence.
1219
1220Finally, if we're matching the Swift calling convention, derive the
1221legal type sequence. If the result appears to be a reasonably small
1222and efficient set of parameters, add their corresponding IR types to
1223the function type we're building; otherwise, ignore the legal type
1224sequence and pass the address of the original type indirectly.
1225
1226Considerations for whether a legal type sequence is reasonable to pass
1227directly:
1228
1229* There probably ought to be a maximum size. Unless it's a single
1230 256-bit vector, it's hard to imagine wanting to pass more than, say,
1231 32 bytes of data as individual values. The callee may decide that
1232 it needs to reconstruct the value for some reason, and the larger
1233 the type gets, the more expensive this is. It may also be
1234 reasonable for this cap to be lower on 32-bit targets, but that
1235 might be dealt with better by the next restriction.
1236
1237* There should also be a cap on the number of values. A 32-byte limit
1238 might be reasonable for passing 4 doubles. It's probably not
1239 reasonable for passing 8 pointers. That many values will exhaust
1240 all the parameter registers for just a single value. 4 is probably
1241 a reasonable cap here.
1242
1243* There's no reason to require the data to be homogeneous. If a
1244 struct contains three floats and a pointer, why force it to be
1245 passed in memory?
1246
1247When all of the parameters have been processed in this manner,
1248the function type is complete.