|
221
|
1 <!--===- docs/Calls.md
|
|
|
2
|
|
|
3 Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
|
|
|
4 See https://llvm.org/LICENSE.txt for license information.
|
|
|
5 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
|
|
6
|
|
|
7 -->
|
|
|
8
|
|
|
9 # Representation of Fortran function calls
|
|
|
10
|
|
|
11 ```eval_rst
|
|
|
12 .. contents::
|
|
|
13 :local:
|
|
|
14 ```
|
|
|
15
|
|
|
16 ## Procedure reference implementation protocol
|
|
|
17
|
|
|
18 Fortran function and subroutine references are complicated.
|
|
|
19 This document attempts to collect the requirements imposed by the 2018
|
|
|
20 standard (and legacy extensions) on programs and implementations, work
|
|
|
21 through the implications of the various features, and propose both a
|
|
|
22 runtime model and a compiler design.
|
|
|
23
|
|
|
24 All section, requirement, and constraint numbers herein pertain to
|
|
|
25 the Fortran 2018 standard.
|
|
|
26
|
|
|
27 This note does not consider calls to intrinsic procedures, statement
|
|
|
28 functions, or calls to internal runtime support library routines.
|
|
|
29
|
|
|
30 ## Quick review of terminology
|
|
|
31
|
|
|
32 * A *dummy argument* is a function or subroutine parameter.
|
|
|
33 It is *associated* with an *effective argument* at each call
|
|
|
34 to the procedure.
|
|
|
35 * The *shape* of an array is a vector containing its extent (size)
|
|
|
36 on each dimension; the *rank* of an array is the number of its
|
|
|
37 dimensions (i.e., the shape of its shape).
|
|
|
38 The absolute values of the lower and upper bounds of the dimensions
|
|
|
39 of an array are not part of its shape, just their difference (plus 1).
|
|
|
40 * An *explicit-shape* array has all of its bounds specified; lower
|
|
|
41 bounds default to 1. These can be passed by with a single address
|
|
|
42 and their contents are contiguous.
|
|
|
43 * An *assumed-size* array is an explicit-shape array with `*` as its
|
|
|
44 final dimension, which is the most-significant one in Fortran
|
|
|
45 and whose value does not affect indexed address calculations.
|
|
|
46 * A *deferred-shape* array (`DIMENSION::A(:)`) is a `POINTER` or `ALLOCATABLE`.
|
|
|
47 `POINTER` target data might not be contiguous.
|
|
|
48 * An *assumed-shape* (not size!) array (`DIMENSION::A(:)`) is a dummy argument
|
|
|
49 that is neither `POINTER` nor `ALLOCATABLE`; its lower bounds can be set
|
|
|
50 by the procedure that receives them (defaulting to 1), and its
|
|
|
51 upper bounds are functions of the lower bounds and the extents of
|
|
|
52 dimensions in the *shape* of the effective argument.
|
|
|
53 * An *assumed-length* `CHARACTER(*)` dummy argument
|
|
|
54 takes its length from the effective argument.
|
|
|
55 * An *assumed-length* `CHARACTER(*)` *result* of an external function (C721)
|
|
|
56 has its length determined by its eventual declaration in a calling scope.
|
|
|
57 * An *assumed-rank* `DIMENSION::A(..)` dummy argument array has an unknown
|
|
|
58 number of dimensions.
|
|
|
59 * A *polymorphic* `CLASS(t)` dummy argument, `ALLOCATABLE`, or `POINTER`
|
|
|
60 has a specific derived type or some extension of that type.
|
|
|
61 An *unlimited polymorphic* `CLASS(*)` object can have any
|
|
|
62 intrinsic or derived type.
|
|
|
63 * *Interoperable* `BIND(C)` procedures are written in C or callable from C.
|
|
|
64
|
|
|
65 ## Interfaces
|
|
|
66
|
|
|
67 Referenced procedures may or may not have declared interfaces
|
|
|
68 available to their call sites.
|
|
|
69
|
|
|
70 Procedures with some post-Fortran '77 features *require* an
|
|
|
71 explicit interface to be called (15.4.2.2) or even passed (4.3.4(5)):
|
|
|
72
|
|
|
73 * use of argument keywords in a call
|
|
|
74 * procedures that are `ELEMENTAL` or `BIND(C)`
|
|
|
75 * procedures that are required to be `PURE` due to the context of the call
|
|
|
76 (specification expression, `DO CONCURRENT`, `FORALL`)
|
|
|
77 * dummy arguments with these attributes: `ALLOCATABLE`, `POINTER`,
|
|
|
78 `VALUE`, `TARGET`, `OPTIONAL`, `ASYNCHRONOUS`, `VOLATILE`,
|
|
|
79 and, as a consequence of limitations on its use, `CONTIGUOUS`;
|
|
|
80 `INTENT()`, however, does *not* require an explicit interface
|
|
|
81 * dummy arguments that are coarrays
|
|
|
82 * dummy arguments that are assumed-shape or assumed-rank arrays
|
|
|
83 * dummy arguments with parameterized derived types
|
|
|
84 * dummy arguments that are polymorphic
|
|
|
85 * function result that is an array
|
|
|
86 * function result that is `ALLOCATABLE` or `POINTER`
|
|
|
87 * `CHARACTER` function result whose length is neither constant
|
|
|
88 nor assumed
|
|
|
89 * derived type function result with `LEN` type parameter value that is
|
|
|
90 not constant
|
|
|
91 (note that result derived type parameters cannot be assumed (C795))
|
|
|
92
|
|
|
93 Module procedures, internal procedures, procedure pointers,
|
|
|
94 type-bound procedures, and recursive references by a procedure to itself
|
|
|
95 always have explicit interfaces.
|
|
|
96 (Consequently, they cannot be assumed-length `CHARACTER(*)` functions;
|
|
|
97 conveniently, assumed-length `CHARACTER(*)` functions are prohibited from
|
|
|
98 recursion (15.6.2.1(3))).
|
|
|
99
|
|
|
100 Other uses of procedures besides calls may also require explicit interfaces,
|
|
|
101 such as procedure pointer assignment, type-bound procedure bindings, &c.
|
|
|
102
|
|
|
103 Note that non-parameterized monomorphic derived type arguments do
|
|
|
104 *not* by themselves require the use of an explicit interface.
|
|
|
105 However, dummy arguments with any derived type parameters *do*
|
|
|
106 require an explicit interface, even if they are all `KIND` type
|
|
|
107 parameters.
|
|
|
108
|
|
|
109 15.5.2.9(2) explicitly allows an assumed-length `CHARACTER(*)` function
|
|
|
110 to be passed as an actual argument to an explicit-length dummy;
|
|
|
111 this has implications for calls to character-valued dummy functions
|
|
|
112 and function pointers.
|
|
|
113 (In the scopes that reference `CHARACTER` functions, they must have
|
|
|
114 visible definitions with explicit result lengths.)
|
|
|
115
|
|
|
116 ### Implicit interfaces
|
|
|
117
|
|
|
118 In the absence of any characteristic or context that *requires* an
|
|
|
119 explicit interface (see above), an external function or subroutine (R503)
|
|
|
120 or `ENTRY` (R1541) can be called directly or indirectly via its implicit interface.
|
|
|
121 Each of the arguments can be passed as a simple address, including
|
|
|
122 dummy procedures.
|
|
|
123 Procedures that *can* be called via an implicit interface can
|
|
|
124 undergo more thorough checking
|
|
|
125 by semantics when an explicit interface for them exists, but they must be
|
|
|
126 compiled as if all calls to them were through the implicit interface.
|
|
|
127 This note will mention special handling for procedures that are exposed
|
|
|
128 to the possibility of being called with an implicit interface as *F77ish* procedures
|
|
|
129 below; this is of course not standard terminology.
|
|
|
130
|
|
|
131 Internal and module subprograms that are ever passed as arguments &/or
|
|
|
132 assigned as targets of procedure pointers may be F77ish.
|
|
|
133
|
|
|
134 Every F77ish procedure can and must be distinguished at compilation time.
|
|
|
135 Such procedures should respect the external naming conventions (when external)
|
|
|
136 and any legacy ABI used for Fortran '77 programs on the target architecture,
|
|
|
137 so that portable libraries can be compiled
|
|
|
138 and used by distinct implementations (and their versions)
|
|
|
139 of Fortran.
|
|
|
140
|
|
|
141 Note that F77ish functions still have known result types, possibly by means
|
|
|
142 of implicit typing of their names.
|
|
|
143 They can also be `CHARACTER(*)` assumed-length character functions.
|
|
|
144
|
|
|
145 In other words: these F77sh procedures that do not require the use of an explicit
|
|
|
146 interface and that can possibly be referenced, directly or indirectly,
|
|
|
147 with implicit interfaces are limited to argument lists that comprise
|
|
|
148 only the addresses of effective arguments and the length of a `CHARACTER` function result
|
|
|
149 (when there is one), and they can return only scalar values with constant
|
|
|
150 type parameter values.
|
|
|
151 None of their arguments or results need be (or can be) implemented
|
|
|
152 with descriptors,
|
|
|
153 and any internal procedures passed to them as arguments must be
|
|
|
154 simple addresses of non-internal subprograms or trampolines for
|
|
|
155 internal procedures.
|
|
|
156
|
|
|
157 Note that the `INTENT` attribute does not, by itself,
|
|
|
158 require the use of explicit interface; neither does the use of a dummy
|
|
|
159 procedure (implicit or explicit in their interfaces).
|
|
|
160 So the analysis of calls to F77ish procedures must allow for the
|
|
|
161 invisible use of `INTENT(OUT)`.
|
|
|
162
|
|
|
163 ## Protocol overview
|
|
|
164
|
|
|
165 Here is a summary script of all of the actions that may need to be taken
|
|
|
166 by the calling procedure and its referenced procedure to effect
|
|
|
167 the call, entry, exit, and return steps of the procedure reference
|
|
|
168 protocol.
|
|
|
169 The order of these steps is not particularly strict, and we have
|
|
|
170 some design alternatives that are explored further below.
|
|
|
171
|
|
|
172 ### Before the call:
|
|
|
173
|
|
|
174 1. Compute &/or copy into temporary storage the values of
|
|
|
175 some effective argument expressions and designators (see below).
|
|
|
176 1. Create and populate descriptors for arguments that use them
|
|
|
177 (see below).
|
|
|
178 1. Possibly allocate function result storage,
|
|
|
179 when its size can be known by all callers; function results that are
|
|
|
180 neither `POINTER` nor `ALLOCATABLE` must have explicit shapes (C816).
|
|
|
181 1. Create and populate a descriptor for the function result, if it
|
|
|
182 needs one (deferred-shape/-length `POINTER`, any `ALLOCATABLE`,
|
|
|
183 derived type with non-constant length parameters, &c.).
|
|
|
184 1. Capture the values of host-escaping local objects in memory;
|
|
|
185 package them into single address (for calls to internal procedures &
|
|
|
186 for calls that pass internal procedures as arguments).
|
|
|
187 1. Resolve the target procedure's polymorphic binding, if any.
|
|
|
188 1. Marshal effective argument addresses (or values for `%VAL()` and some
|
|
|
189 discretionary `VALUE` arguments) into registers.
|
|
|
190 1. Marshal `CHARACTER` argument lengths in additional value arguments for
|
|
|
191 `CHARACTER` effective arguments not passed via descriptors.
|
|
|
192 These lengths must be 64-bit integers.
|
|
|
193 1. Marshal an extra argument for the length of a `CHARACTER` function
|
|
|
194 result if the function is F77ish.
|
|
|
195 1. Marshal an extra argument for the function result's descriptor,
|
|
|
196 if it needs one.
|
|
|
197 1. Set the "host instance" (static link) register when calling an internal
|
|
|
198 procedure from its host or another internal procedure, a procedure pointer,
|
|
|
199 or dummy procedure (when it has a descriptor).
|
|
|
200 1. Jump.
|
|
|
201
|
|
|
202 ### On entry:
|
|
|
203 1. For subprograms with alternate `ENTRY` points: shuffle `ENTRY` dummy arguments
|
|
|
204 set a compiler-generated variable to identify the alternate entry point,
|
|
|
205 and jump to the common entry point for common processing and a `switch()`
|
|
|
206 to the statement after the `ENTRY`.
|
|
|
207 1. Capture `CHARACTER` argument &/or assumed-length result length values.
|
|
|
208 1. Complete `VALUE` copying if this step will not always be done
|
|
|
209 by the caller (as I think it should be).
|
|
|
210 1. Finalize &/or re-initialize `INTENT(OUT)` non-pointer
|
|
|
211 effective arguments (see below).
|
|
|
212 1. For interoperable procedures called from C: compact discontiguous
|
|
|
213 dummy argument values when necessary (`CONTIGUOUS` &/or
|
|
|
214 explicit-shape/assumed-size arrays of assumed-length `CHARACTER(*)`).
|
|
|
215 1. Optionally compact assumed-shape arguments for contiguity on one
|
|
|
216 or more leading dimensions to improve SIMD vectorization, if not
|
|
|
217 `TARGET` and not already sufficiently contiguous.
|
|
|
218 (PGI does this in the caller, whether the callee needs it or not.)
|
|
|
219 1. Complete allocation of function result storage, if that has
|
|
|
220 not been done by the caller.
|
|
|
221 1. Initialize components of derived type local variables,
|
|
|
222 including the function result.
|
|
|
223
|
|
|
224 Execute the callee, populating the function result or selecting
|
|
|
225 the subroutine's alternate return.
|
|
|
226
|
|
|
227 ### On exit:
|
|
|
228 1. Clean up local scope (finalization, deallocation)
|
|
|
229 1. Deallocate `VALUE` argument temporaries.
|
|
|
230 (But don't finalize them; see 7.5.6.3(3)).
|
|
|
231 1. Replace any assumed-shape argument data that were compacted on
|
|
|
232 entry for contiguity when the data were possibly
|
|
|
233 modified across the call (never when `INTENT(IN)` or `VALUE`).
|
|
|
234 1. Identify alternate `RETURN` to caller.
|
|
|
235 1. Marshal results.
|
|
|
236 1. Jump
|
|
|
237
|
|
|
238 ### On return to the caller:
|
|
|
239 1. Save the result registers, if any.
|
|
|
240 1. Copy effective argument array designator data that was copied into
|
|
|
241 a temporary back into its original storage (see below).
|
|
|
242 1. Complete deallocation of effective argument temporaries (not `VALUE`).
|
|
|
243 1. Reload definable host-escaping local objects from memory, if they
|
|
|
244 were saved to memory by the host before the call.
|
|
|
245 1. `GO TO` alternate return, if any.
|
|
|
246 1. Use the function result in an expression.
|
|
|
247 1. Eventually, finalize &/or deallocate the function result.
|
|
|
248
|
|
|
249 (I've omitted some obvious steps, like preserving/restoring callee-saved
|
|
|
250 registers on entry/exit, dealing with caller-saved registers before/after
|
|
|
251 calls, and architecture-dependent ABI requirements.)
|
|
|
252
|
|
|
253 ## The messy details
|
|
|
254
|
|
|
255 ### Copying effective argument values into temporary storage
|
|
|
256
|
|
|
257 There are several conditions that require the compiler to generate
|
|
|
258 code that allocates and populates temporary storage for an actual
|
|
|
259 argument.
|
|
|
260
|
|
|
261 First, effective arguments that are expressions, not designators, obviously
|
|
|
262 need to be computed and captured into memory in order to be passed
|
|
|
263 by reference.
|
|
|
264 This includes parenthesized designators like `(X)`, which are
|
|
|
265 expressions in Fortran, as an important special case.
|
|
|
266 (This case also technically includes unparenthesized constants,
|
|
|
267 but those are better implemented by passing addresses in read-only
|
|
|
268 memory.)
|
|
|
269 The dummy argument cannot be known to have `INTENT(OUT)` or
|
|
|
270 `INTENT(IN OUT)`.
|
|
|
271
|
|
|
272 Small scalar or elemental `VALUE` arguments may be passed in registers,
|
|
|
273 as should arguments wrapped in the legacy VMS `%VAL()` notation.
|
|
|
274 Multiple elemental `VALUE` arguments might be packed into SIMD registers.
|
|
|
275
|
|
|
276 Effective arguments that are designators, not expressions, must also
|
|
|
277 be copied into temporaries in the following situations.
|
|
|
278
|
|
|
279 1. Coindexed objects need to be copied into the local image.
|
|
|
280 This can get very involved if they contain `ALLOCATABLE`
|
|
|
281 components, which also need to be copied, along with their
|
|
|
282 `ALLOCATABLE` components, and may be best implemented with a runtime
|
|
|
283 library routine working off a description of the type.
|
|
|
284 1. Effective arguments associated with dummies with the `VALUE`
|
|
|
285 attribute need to be copied; this can be done on either
|
|
|
286 side of the call, but there are optimization opportunities
|
|
|
287 available when the caller's side bears the responsibility.
|
|
|
288 1. In non-elemental calls, the values of array sections with
|
|
|
289 vector-valued subscripts need to be gathered into temporaries.
|
|
|
290 These effective arguments are not definable, and they are not allowed to
|
|
|
291 be associated with non-`VALUE` dummy arguments with the attributes
|
|
|
292 `INTENT(OUT)`, `INTENT(IN OUT)`, `ASYNCHRONOUS`, or `VOLATILE`
|
|
|
293 (15.5.2.4(21)); `INTENT()` can't always be checked.
|
|
|
294 1. Non-simply-contiguous (9.5.4) arrays being passed to non-`POINTER`
|
|
|
295 dummy arguments that must be contiguous (due to a `CONTIGUOUS`
|
|
|
296 attribute, or not being assumed-shape or assumed-rank; this
|
|
|
297 is always the case for F77ish procedures).
|
|
|
298 This should be a runtime decision, so that effective arguments
|
|
|
299 that turn out to be contiguous can be passed cheaply.
|
|
|
300 This rule does not apply to coarray dummies, whose effective arguments
|
|
|
301 are required to be simply contiguous when this rule would otherwise
|
|
|
302 force the use of a temporary (15.5.2.8); neither does it apply
|
|
|
303 to `ASYNCHRONOUS` and `VOLATILE` effective arguments, which are
|
|
|
304 disallowed when copies would be necessary (C1538 - C1540).
|
|
|
305 *Only temporaries created by this contiguity requirement are
|
|
|
306 candidates for being copied back to the original variable after
|
|
|
307 the call* (see below).
|
|
|
308
|
|
|
309 Fortran requires (18.3.6(5)) that calls to interoperable procedures
|
|
|
310 with dummy argument arrays with contiguity requirements
|
|
|
311 handle the compaction of discontiguous data *in the Fortran callee*,
|
|
|
312 at least when called from C.
|
|
|
313 And discontiguous data must be compacted on the *caller's* side
|
|
|
314 when passed from Fortran to C (18.3.6(6)).
|
|
|
315
|
|
|
316 We could perform all argument compaction (discretionary or
|
|
|
317 required) in the callee, but there are many cases where the
|
|
|
318 compiler knows that the effective argument data are contiguous
|
|
|
319 when compiling the caller (a temporary is needed for other reasons,
|
|
|
320 or the effective argument is simply contiguous) and a run-time test for
|
|
|
321 discontiguity in the callee can be avoided by using a caller-compaction
|
|
|
322 convention when we have the freedom to choose.
|
|
|
323
|
|
|
324 While we are unlikely to want to _needlessly_ use a temporary for
|
|
|
325 an effective argument that does not require one for any of these
|
|
|
326 reasons above, we are specifically disallowed from doing so
|
|
|
327 by the standard in cases where pointers to the original target
|
|
|
328 data are required to be valid across the call (15.5.2.4(9-10)).
|
|
|
329 In particular, compaction of assumed-shape arrays for discretionary
|
|
|
330 contiguity on the leading dimension to ease SIMD vectorization
|
|
|
331 cannot be done safely for `TARGET` dummies without `VALUE`.
|
|
|
332
|
|
|
333 Effective arguments associated with known `INTENT(OUT)` dummies that
|
|
|
334 require allocation of a temporary -- and this can only be for reasons of
|
|
|
335 contiguity -- don't have to populate it, but they do have to perform
|
|
|
336 minimal initialization of any `ALLOCATABLE` components so that
|
|
|
337 the runtime doesn't crash when the callee finalizes and deallocates
|
|
|
338 them.
|
|
|
339 `ALLOCATABLE` coarrays are prohibited from being affected by `INTENT(OUT)`
|
|
|
340 (see C846).
|
|
|
341 Note that calls to implicit interfaces must conservatively allow
|
|
|
342 for the use of `INTENT(OUT)` by the callee.
|
|
|
343
|
|
|
344 Except for `VALUE` and known `INTENT(IN)` dummy arguments, the original
|
|
|
345 contents of local designators that have been compacted into temporaries
|
|
|
346 could optionally have their `ALLOCATABLE` components invalidated
|
|
|
347 across the call as an aid to debugging.
|
|
|
348
|
|
|
349 Except for `VALUE` and known `INTENT(IN)` dummy arguments, the contents of
|
|
|
350 the temporary storage will be copied back into the effective argument
|
|
|
351 designator after control returns from the procedure, and it may be necessary
|
|
|
352 to preserve addresses (or the values of subscripts and cosubscripts
|
|
|
353 needed to recalculate them) of the effective argument designator, or its
|
|
|
354 elements, in additional temporary storage if they can't be safely or
|
|
|
355 quickly recomputed after the call.
|
|
|
356
|
|
|
357 ### `INTENT(OUT)` preparation
|
|
|
358
|
|
|
359 Effective arguments that are associated with `INTENT(OUT)`
|
|
|
360 dummy arguments are required to be definable.
|
|
|
361 This cannot always be checked, as the use of `INTENT(OUT)`
|
|
|
362 does not by itself mandate the use of an explicit interface.
|
|
|
363
|
|
|
364 `INTENT(OUT)` arguments are finalized (as if) on entry to the called
|
|
|
365 procedure. In particular, in calls to elemental procedures,
|
|
|
366 the elements of an array are finalized by a scalar or elemental
|
|
|
367 `FINAL` procedure (7.5.6.3(7)).
|
|
|
368
|
|
|
369 Derived type components that are `ALLOCATABLE` are finalized
|
|
|
370 and deallocated; they are prohibited from being coarrays.
|
|
|
371 Components with initializers are (re)initialized.
|
|
|
372
|
|
|
373 The preparation of effective arguments for `INTENT(OUT)` could be
|
|
|
374 done on either side of the call. If the preparation is
|
|
|
375 done by the caller, there is an optimization opportunity
|
|
|
376 in situations where unmodified incoming `INTENT(OUT)` dummy
|
|
|
377 arguments whose types lack `FINAL` procedures are being passed
|
|
|
378 onward as outgoing `INTENT(OUT)` arguments.
|
|
|
379
|
|
|
380 ### Arguments and function results requiring descriptors
|
|
|
381
|
|
|
382 Dummy arguments are represented with the addresses of new descriptors
|
|
|
383 when they have any of the following characteristics:
|
|
|
384
|
|
|
385 1. assumed-shape array (`DIMENSION::A(:)`)
|
|
|
386 1. assumed-rank array (`DIMENSION::A(..)`)
|
|
|
387 1. parameterized derived type with assumed `LEN` parameters
|
|
|
388 1. polymorphic (`CLASS(T)`, `CLASS(*)`)
|
|
|
389 1. assumed-type (`TYPE(*)`)
|
|
|
390 1. coarray dummy argument
|
|
|
391 1. `INTENT(IN) POINTER` argument (15.5.2.7, C.10.4)
|
|
|
392
|
|
|
393 `ALLOCATABLE` and other `POINTER` arguments can be passed by simple
|
|
|
394 address.
|
|
|
395
|
|
|
396 Non-F77ish procedures use descriptors to represent two further
|
|
|
397 kinds of dummy arguments:
|
|
|
398
|
|
|
399 1. assumed-length `CHARACTER(*)`
|
|
|
400 1. dummy procedures
|
|
|
401
|
|
|
402 F77ish procedures use other means to convey character length and host instance
|
|
|
403 links (respectively) for these arguments.
|
|
|
404
|
|
|
405 Function results are described by the caller & callee in
|
|
|
406 a caller-supplied descriptor when they have any of the following
|
|
|
407 characteristics, some which necessitate an explicit interface:
|
|
|
408
|
|
|
409 1. deferred-shape array (so `ALLOCATABLE` or `POINTER`)
|
|
|
410 1. derived type with any non-constant `LEN` parameter
|
|
|
411 (C795 prohibit assumed lengths)
|
|
|
412 1. procedure pointer result (when the interface must be explicit)
|
|
|
413
|
|
|
414 Storage for a function call's result is allocated by the caller when
|
|
|
415 possible: the result is neither `ALLOCATABLE` nor `POINTER`,
|
|
|
416 the shape is scalar or explicit, and the type has `LEN` parameters
|
|
|
417 that are constant expressions.
|
|
|
418 In other words, the result doesn't require the use of a descriptor
|
|
|
419 but can't be returned in registers.
|
|
|
420 This allows a function result to be written directly into a local
|
|
|
421 variable or temporary when it is safe to treat the variable as if
|
|
|
422 it were an additional `INTENT(OUT)` argument.
|
|
|
423 (Storage for `CHARACTER` results, assumed or explicit, is always
|
|
|
424 allocated by the caller, and the length is always passed so that
|
|
|
425 an assumed-length external function will work when eventually
|
|
|
426 called from a scope that declares the length that it will use
|
|
|
427 (15.5.2.9 (2)).)
|
|
|
428
|
|
|
429 Note that the lower bounds of the dimensions of non-`POINTER`
|
|
|
430 non-`ALLOCATABLE` dummy argument arrays are determined by the
|
|
|
431 callee, not the caller.
|
|
|
432 (A Fortran pitfall: declaring `A(0:9)`, passing it to a dummy
|
|
|
433 array `D(:)`, and assuming that `LBOUND(D,1)` will be zero
|
|
|
434 in the callee.)
|
|
|
435 If the declaration of an assumed-shape dummy argument array
|
|
|
436 contains an explicit lower bound expression (R819), its value
|
|
|
437 needs to be computed by the callee;
|
|
|
438 it may be captured and saved in the incoming descriptor
|
|
|
439 as long as we assume that argument descriptors can be modified
|
|
|
440 by callees.
|
|
|
441 Callers should fill in all of the fields of outgoing
|
|
|
442 non-`POINTER` non-`ALLOCATABLE` argument
|
|
|
443 descriptors with the assumption that the callee will use 1 for
|
|
|
444 lower bound values, and callees can rely on them being 1 if
|
|
|
445 not modified.
|
|
|
446
|
|
|
447 ### Copying temporary storage back into argument designators
|
|
|
448
|
|
|
449 Except for `VALUE` and known `INTENT(IN)` dummy arguments and array sections
|
|
|
450 with vector-valued subscripts (15.5.2.4(21)), temporary storage into
|
|
|
451 which effective argument data were compacted for contiguity before the call
|
|
|
452 must be redistributed back to its original storage by the caller after
|
|
|
453 the return.
|
|
|
454
|
|
|
455 In conjunction with saved cosubscript values, a standard descriptor
|
|
|
456 would suffice to represent a pointer to the original storage into which the
|
|
|
457 temporary data should be redistributed;
|
|
|
458 the descriptor need not be fully populated with type information.
|
|
|
459
|
|
|
460 Note that coindexed objects with `ALLOCATABLE` ultimate components
|
|
|
461 are required to be associated only with dummy arguments with the
|
|
|
462 `VALUE` &/or `INTENT(IN)` attributes (15.6.2.4(6)), so there is no
|
|
|
463 requirement that the local image somehow reallocate remote storage
|
|
|
464 when copying the data back.
|
|
|
465
|
|
|
466 ### Polymorphic bindings
|
|
|
467
|
|
|
468 Calls to the type-bound procedures of monomorphic types are
|
|
|
469 resolved at compilation time, as are calls to `NON_OVERRIDABLE`
|
|
|
470 type-bound procedures.
|
|
|
471 The resolution of calls to overridable type-bound procedures of
|
|
|
472 polymorphic types must be completed at execution (generic resolution
|
|
|
473 of type-bound procedure bindings from effective argument types, kinds,
|
|
|
474 and ranks is always a compilation-time task (15.5.6, C.10.6)).
|
|
|
475
|
|
|
476 Each derived type that declares or inherits any overridable
|
|
|
477 type-bound procedure bindings must correspond to a static constant
|
|
|
478 table of code addresses (or, more likely, a static constant type
|
|
|
479 description containing or pointing to such a table, along with
|
|
|
480 information used by the runtime support library for initialization,
|
|
|
481 copying, finalization, and I/O of type instances). Each overridable
|
|
|
482 type-bound procedure in the type corresponds to an index into this table.
|
|
|
483
|
|
|
484 ### Host instance linkage
|
|
|
485
|
|
|
486 Calls to dummy procedures and procedure pointers that resolve to
|
|
|
487 internal procedures need to pass an additional "host instance" argument that
|
|
|
488 addresses a block of storage in the stack frame of their
|
|
|
489 host subprogram that was active at the time they were passed as an
|
|
|
490 effective argument or associated with a procedure pointer.
|
|
|
491 This is similar to a static link in implementations of programming
|
|
|
492 languages with nested subprograms, although Fortran only allows
|
|
|
493 one level of nesting.
|
|
|
494 The 64-bit x86 and little-endian OpenPower ABIs reserve registers
|
|
|
495 for this purpose (`%r10` & `R11`); 64-bit ARM has a reserved register
|
|
|
496 that can be used (`x18`).
|
|
|
497
|
|
|
498 The host subprogram objects that are visible to any of their internal
|
|
|
499 subprograms need to be resident in memory across any calls to them
|
|
|
500 (direct or not). Any host subprogram object that might be defined
|
|
|
501 during a call to an internal subprogram needs to be reloaded after
|
|
|
502 a call or reside permanently in memory.
|
|
|
503 A simple conservative analysis of the internal subprograms can
|
|
|
504 identify all of these escaping objects and their definable subset.
|
|
|
505
|
|
|
506 The address of the host subprogram storage used to hold the escaping
|
|
|
507 objects needs to be saved alongside the code address(es) that
|
|
|
508 represent a procedure pointer.
|
|
|
509 It also needs to be conveyed alongside the text address for a
|
|
|
510 dummy procedure.
|
|
|
511
|
|
|
512 For F77ish procedures, we cannot use a "procedure pointer descriptor"
|
|
|
513 to pass a procedure argument -- they expect to receive a single
|
|
|
514 address argument.
|
|
|
515 We will need to package the host instance link in a trampoline
|
|
|
516 that loads its address into the designated register.
|
|
|
517
|
|
|
518 GNU Fortran and Intel Fortran construct trampolines by writing
|
|
|
519 a sequence of machine instructions to a block of storage in the
|
|
|
520 host's stack frame, which requires the stack to be executable,
|
|
|
521 which seems inadvisable for security reasons;
|
|
|
522 XLF manages trampolines in its runtime support library, which adds some overhead
|
|
|
523 to their construction and a reclamation obligation;
|
|
|
524 NAG Fortran manages a static fixed-sized stack of trampolines
|
|
|
525 per call site, imposing a hidden limit on recursion and foregoing
|
|
|
526 reentrancy;
|
|
|
527 PGI passes host instance links in descriptors in additional arguments
|
|
|
528 that are not always successfully forwarded across implicit interfaces,
|
|
|
529 sometimes leading to crashes when they turn out to be needed.
|
|
|
530
|
|
|
531 F18 will manage a pool of trampolines in its runtime support library
|
|
|
532 that can be used to pass internal procedures as effective arguments
|
|
|
533 to F77ish procedures, so that
|
|
|
534 a bare code address can serve to represent the effective argument.
|
|
|
535 But targets that can only be called with an explicit interface
|
|
|
536 have the option of using a "fat pointer" (or additional argument)
|
|
|
537 to represent a dummy procedure closure so as
|
|
|
538 to avoid the overhead of constructing and reclaiming a trampoline.
|
|
|
539 Procedure descriptors can also support multiple code addresses.
|
|
|
540
|
|
|
541 ### Naming
|
|
|
542
|
|
|
543 External subroutines and functions (R503) and `ENTRY` points (R1541)
|
|
|
544 with `BIND(C)` (R808) have linker-visible names that are either explicitly
|
|
|
545 specified in the program or determined by straightforward rules.
|
|
|
546 The names of other F77ish external procedures should respect the conventions
|
|
|
547 of the target architecture for legacy Fortran '77 programs; this is typically
|
|
|
548 something like `foo_`.
|
|
|
549
|
|
|
550 In other cases, however, we have fewer constraints on external naming,
|
|
|
551 as well as some additional requirements and goals.
|
|
|
552
|
|
|
553 Module procedures need to be distinguished by the name of their module
|
|
|
554 and (when they have one) the submodule where their interface was
|
|
|
555 defined.
|
|
|
556 Note that submodule names are distinct in their modules, not hierarchical,
|
|
|
557 so at most two levels of qualification are needed.
|
|
|
558
|
|
|
559 Pure `ELEMENTAL` functions (15.8) must use distinct names for any alternate
|
|
|
560 entry points used for packed SIMD arguments of various widths if we support
|
|
|
561 calls to these functions in SIMD parallel contexts.
|
|
|
562 There are already conventions for these names in `libpgmath`.
|
|
|
563
|
|
|
564 The names of non-F77ish external procedures
|
|
|
565 should be distinguished as such so that incorrect attempts to call or pass
|
|
|
566 them with an implicit interface will fail to resolve at link time.
|
|
|
567 Fortran 2018 explicitly enables us to do this with a correction to Fortran
|
|
|
568 2003 in 4.3.4(5).
|
|
|
569
|
|
|
570 Last, there must be reasonably permanent naming conventions used
|
|
|
571 by the F18 runtime library for those unrestricted specific intrinsic
|
|
|
572 functions (table 16.2 in 16.8) and extensions that can be passed as
|
|
|
573 arguments.
|
|
|
574
|
|
|
575 In these cases where external naming is at the discretion
|
|
|
576 of the implementation, we should use names that are not in the C language
|
|
|
577 user namespace, begin with something that identifies
|
|
|
578 the current incompatible version of F18, the module, the submodule, and
|
|
|
579 elemental SIMD width, and are followed by the external name.
|
|
|
580 The parts of the external name can be separated by some character that
|
|
|
581 is acceptable for use in LLVM IR and assembly language but not in user
|
|
|
582 Fortran or C code, or by switching case
|
|
|
583 (so long as there's a way to cope with extension names that don't begin
|
|
|
584 with letters).
|
|
|
585
|
|
|
586 In particular, the period (`.`) seems safe to use as a separator character,
|
|
|
587 so a `Fa.` prefix can serve to isolate these discretionary names from
|
|
|
588 other uses and to identify the earliest link-compatible version.
|
|
|
589 For examples: `Fa.mod.foo`, `Fa.mod.submod.foo`, and (for an external
|
|
|
590 subprogram that requires an explicit interface) `Fa.foo`.
|
|
|
591 When the ABI changes in the future in an incompatible way, the
|
|
|
592 initial prefix becomes `Fb.`, `Fc.`, &c.
|
|
|
593
|
|
|
594 ## Summary of checks to be enforced in semantics analysis
|
|
|
595
|
|
|
596 8.5.10 `INTENT` attributes
|
|
|
597 * (C846) An `INTENT(OUT)` argument shall not be associated with an
|
|
|
598 object that is or has an allocatable coarray.
|
|
|
599 * (C847) An `INTENT(OUT)` argument shall not have `LOCK_TYPE` or `EVENT_TYPE`.
|
|
|
600
|
|
|
601 8.5.18 `VALUE` attribute
|
|
|
602 * (C863) The argument cannot be assumed-size, a coarray, or have a coarray
|
|
|
603 ultimate component.
|
|
|
604 * (C864) The argument cannot be `ALLOCATABLE`, `POINTER`, `INTENT(OUT)`,
|
|
|
605 `INTENT(IN OUT)`, or `VOLATILE`.
|
|
|
606 * (C865) If the procedure is `BIND(C)`, the argument cannot be `OPTIONAL`.
|
|
|
607
|
|
|
608 15.5.1 procedure references:
|
|
|
609 * (C1533) can't pass non-intrinsic `ELEMENTAL` as argument
|
|
|
610 * (C1536) alternate return labels must be in the inclusive scope
|
|
|
611 * (C1537) coindexed argument cannot have a `POINTER` ultimate component
|
|
|
612
|
|
|
613 15.5.2.4 requirements for non-`POINTER` non-`ALLOCATABLE` dummies:
|
|
|
614 * (2) dummy must be monomorphic for coindexed polymorphic actual
|
|
|
615 * (2) dummy must be polymorphic for assumed-size polymorphic actual
|
|
|
616 * (2) dummy cannot be `TYPE(*)` if effective is PDT or has TBPs or `FINAL`
|
|
|
617 * (4) character length of effective cannot be less than dummy
|
|
|
618 * (6) coindexed effective with `ALLOCATABLE` ultimate component requires
|
|
|
619 `INTENT(IN)` &/or `VALUE` dummy
|
|
|
620 * (13) a coindexed scalar effective requires a scalar dummy
|
|
|
621 * (14) a non-conindexed scalar effective usually requires a scalar dummy,
|
|
|
622 but there are some exceptions that allow elements of storage sequences
|
|
|
623 to be passed and treated like explicit-shape or assumed-size arrays
|
|
|
624 (see 15.5.2.11)
|
|
|
625 * (16) array rank agreement
|
|
|
626 * (20) `INTENT(OUT)` & `INTENT(IN OUT)` dummies require definable actuals
|
|
|
627 * (21) array sections with vector subscripts can't be passed to definable dummies
|
|
|
628 (`INTENT(OUT)`, `INTENT(IN OUT)`, `ASYNCHRONOUS`, `VOLATILE`)
|
|
|
629 * (22) `VOLATILE` attributes must match when dummy has a coarray ultimate component
|
|
|
630 * (C1538 - C1540) checks for `ASYNCHRONOUS` and `VOLATILE`
|
|
|
631
|
|
|
632 15.5.2.5 requirements for `ALLOCATABLE` & `POINTER` arguments when both
|
|
|
633 the dummy and effective arguments have the same attributes:
|
|
|
634 * (2) both or neither can be polymorphic
|
|
|
635 * (2) both are unlimited polymorphic or both have the same declared type
|
|
|
636 * (3) rank compatibility
|
|
|
637 * (4) effective argument must have deferred the same type parameters as the dummy
|
|
|
638
|
|
|
639 15.5.2.6 `ALLOCATABLE` dummy arguments:
|
|
|
640 * (2) effective must be `ALLOCATABLE`
|
|
|
641 * (3) corank must match
|
|
|
642 * (4) coindexed effective requires `INTENT(IN)` dummy
|
|
|
643 * (7) `INTENT(OUT)` & `INTENT(IN OUT)` dummies require definable actuals
|
|
|
644
|
|
|
645 15.5.2.7 `POINTER` dummy arguments:
|
|
|
646 * (C1541) `CONTIGUOUS` dummy requires simply contiguous actual
|
|
|
647 * (C1542) effective argument cannot be coindexed unless procedure is intrinsic
|
|
|
648 * (2) effective argument must be `POINTER` unless dummy is `INTENT(IN)` and
|
|
|
649 effective could be the right-hand side of a pointer assignment statement
|
|
|
650
|
|
|
651 15.5.2.8 corray dummy arguments:
|
|
|
652 * (1) effective argument must be coarray
|
|
|
653 * (1) `VOLATILE` attributes must match
|
|
|
654 * (2) explicitly or implicitly contiguous dummy array requires a simply contiguous actual
|
|
|
655
|
|
|
656 15.5.2.9 dummy procedures:
|
|
|
657 * (1) explicit dummy procedure interface must have same characteristics as actual
|
|
|
658 * (5) dummy procedure `POINTER` requirements on effective arguments
|
|
|
659
|
|
|
660 15.6.2.1 procedure definitions:
|
|
|
661 * `NON_RECURSIVE` procedures cannot recurse.
|
|
|
662 * Assumed-length `CHARACTER(*)` functions cannot be declared as `RECURSIVE`, array-valued,
|
|
|
663 `POINTER`, `ELEMENTAL`, or `PURE' (C723), and cannot be called recursively (15.6.2.1(3)).
|
|
|
664 * (C823) A function result cannot be a coarray or contain a coarray ultimate component.
|
|
|
665
|
|
|
666 `PURE` requirements (15.7): C1583 - C1599.
|
|
|
667 These also apply to `ELEMENTAL` procedures that are not `IMPURE`.
|
|
|
668
|
|
|
669 `ELEMENTAL` requirements (15.8.1): C15100-C15103,
|
|
|
670 and C1533 (can't pass as effective argument unless intrinsic)
|
|
|
671
|
|
|
672 For interoperable procedures and interfaces (18.3.6):
|
|
|
673 * C1552 - C1559
|
|
|
674 * function result is scalar and of interoperable type (C1553, 18.3.1-3)
|
|
|
675 * `VALUE` arguments are scalar and of interoperable type
|
|
|
676 * `POINTER` dummies cannot be `CONTIGUOUS` (18.3.6 paragraph 2(5))
|
|
|
677 * assumed-type dummies cannot be `ALLOCATABLE`, `POINTER`, assumed-shape, or assumed-rank (18.3.6 paragraph 2 (5))
|
|
|
678 * `CHARACTER` dummies that are `ALLOCATABLE` or `POINTER` must be deferred-length
|
|
|
679
|
|
|
680 ## Further topics to document
|
|
|
681
|
|
|
682 * Alternate return specifiers
|
|
|
683 * `%VAL()`, `%REF()`, and `%DESCR()` legacy VMS interoperability extensions
|
|
|
684 * Unrestricted specific intrinsic functions as effective arguments
|
|
|
685 * SIMD variants of `ELEMENTAL` procedures (& unrestricted specific intrinsics)
|
|
|
686 * Elemental subroutine calls with array arguments
|
