From bad10eebbe00e6fd72fb4f34daecf28dac6791e6 Mon Sep 17 00:00:00 2001 From: Chris Lattner Date: Fri, 6 May 2005 22:57:40 +0000 Subject: [PATCH] document calling convention extensions git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@21753 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/BytecodeFormat.html | 6 +- docs/LangRef.html | 179 ++++++++++++++++++++++++++++++--------- 2 files changed, 143 insertions(+), 42 deletions(-) diff --git a/docs/BytecodeFormat.html b/docs/BytecodeFormat.html index a7726c16447..5d5d55fec29 100644 --- a/docs/BytecodeFormat.html +++ b/docs/BytecodeFormat.html @@ -1059,7 +1059,11 @@ href="#uint32_vbr">uint32_vbr that describes the function.

bit(0-3) - Reserved for future use. Currently set to 0001. + + Encodes the calling convention number of the function. If this number is + zero, this field is followed by a vbr indicating the CC#. Otherwise, the + CC number of the function is the value of this field minus one. + bit(4) diff --git a/docs/LangRef.html b/docs/LangRef.html index df5cd9f9af2..71faede993a 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -21,6 +21,7 @@
  1. Module Structure
  2. Linkage Types
    3. +
  3. Calling Conventions
  4. Global Variables
  5. Function Structure
@@ -426,6 +427,62 @@ to have any linkage type other than "externally visible".

+ +
+ Calling Conventions +
+ +
+ +

LLVM functions, calls +and invokes can all have an optional calling convention +specified for the call. The calling convention of any pair of dynamic +caller/callee must match, or the behavior of the program is undefined. The +following calling conventions are supported by LLVM, and more may be added in +the future:

+ +
+
"ccc" - The C calling convention:
+ +
This calling convention (the default if no other calling convention is + specified) matches the target C calling conventions. This calling convention + supports varargs function calls, and tolerates some mismatch in the declared + prototype and implemented declaration of the function (as does normal C). +
+ +
"fastcc" - The fast calling convention:
+ +
This calling convention attempts to make calls as fast as possible + (e.g. by passing things in registers). This calling convention allows the + target to use whatever tricks it wants to produce fast code for the target, + without having to conform to an externally specified ABI. This calling + convention does not support varargs and requires the prototype of all callees + to exactly match the prototype of the function definition. +
+ +
"coldcc" - The cold calling convention:
+ +
This calling convention attempts to make code in the caller as efficient + as possible under the assumption that the call is not commonly executed. As + such, these calls often preserve all registers so that the call does not break + any live ranges in the caller side. This calling convention does not support + varargs and requires the prototype of all callees to exactly match the + prototype of the function definition. +
+ +
"cc <n>" - Numbered convention:
+ +
Any calling convention may be specified by number, allowing + target-specific calling conventions to be used. Target specific calling + conventions start at 64. +
+ +

More calling conventions can be added/defined on an as-needed basis, to +support pascal conventions or any other well-known target-independent +convention.

+ +
+
Global Variables @@ -466,10 +523,13 @@ accessed through pointers.

-

LLVM function definitions are composed of a (possibly empty) argument list, -an opening curly brace, a list of basic blocks, and a closing curly brace. LLVM -function declarations are defined with the "declare" keyword, a -function name, and a function signature.

+

LLVM function definitions consist of an optional linkage +type, an optional calling convention, a return +type, a function name, a (possibly empty) argument list, an opening curly brace, +a list of basic blocks, and a closing curly brace. LLVM function declarations +are defined with the "declare" keyword, an optional calling convention, a return type, a function name, and +a possibly empty list of arguments.

A function definition contains a list of basic blocks, forming the CFG for the function. Each basic block may optionally start with a label (giving the @@ -1154,51 +1214,82 @@ branches or with a lookup table.

uint 2, label %ontwo ]
+ -
'invoke' -Instruction
+
+ 'invoke' Instruction +
+
+
Syntax:
-
  <result> = invoke <ptr to function ty> %<function ptr val>(<function args>)
                 to label <normal label> except label <exception label>
+ +
+  <result> = invoke [cconv] <ptr to function ty> %<function ptr val>(<function args>) 
+                to label <normal label> except label <exception label>
+
+
Overview:
-

The 'invoke' instruction causes control to transfer to a -specified function, with the possibility of control flow transfer to -either the 'normal' label label or the 'exception'label. -If the callee function returns with the "ret" -instruction, control flow will return to the "normal" label. If the -callee (or any indirect callees) returns with the "unwind" -instruction, control is interrupted, and continued at the dynamically -nearest "except" label.

+ +

The 'invoke' instruction causes control to transfer to a specified +function, with the possibility of control flow transfer to either the +'normal' label label or the +'exception'label. If the callee function returns with the +"ret" instruction, control flow will return to the +"normal" label. If the callee (or any indirect callees) returns with the "unwind" instruction, control is interrupted, and +continued at the dynamically nearest "except" label.

+
Arguments:
+

This instruction requires several arguments:

+
    -
  1. 'ptr to function ty': shall be the signature of the -pointer to function value being invoked. In most cases, this is a -direct function invocation, but indirect invokes are just as -possible, branching off an arbitrary pointer to function value.
    2. -
  2. 'function ptr val': An LLVM value containing a pointer -to a function to be invoked.
    3. -
  3. 'function args': argument list whose types match the -function signature argument types. If the function signature indicates -the function accepts a variable number of arguments, the extra -arguments can be specified.
    4. -
  4. 'normal label': the label reached when the called -function executes a 'ret' instruction.
    5. -
  5. 'exception label': the label reached when a callee -returns with the unwind instruction.
    6. +
  6. +

    The optional "cconv" marker indicates which calling + convention the call should use. If none is specified, the call defaults + to using C calling conventions. +

    7. +
  7. 'ptr to function ty': shall be the signature of the pointer to + function value being invoked. In most cases, this is a direct function + invocation, but indirect invokes are just as possible, branching off + an arbitrary pointer to function value. +
    8. + +
  8. 'function ptr val': An LLVM value containing a pointer to a + function to be invoked.
    9. + +
  9. 'function args': argument list whose types match the function + signature argument types. If the function signature indicates the function + accepts a variable number of arguments, the extra arguments can be + specified.
    10. + +
  10. 'normal label': the label reached when the called function + executes a 'ret' instruction.
    11. + +
  11. 'exception label': the label reached when a callee returns with + the unwind instruction.
    12. +
+
Semantics:
+

This instruction is designed to operate as a standard 'call' instruction in most regards. The -primary difference is that it establishes an association with a label, -which is used by the runtime library to unwind the stack.

-

This instruction is used in languages with destructors to ensure -that proper cleanup is performed in the case of either a longjmp -or a thrown exception. Additionally, this is important for -implementation of 'catch' clauses in high-level languages that -support them.

+href="#i_call">call' instruction in most regards. The primary +difference is that it establishes an association with a label, which is used by +the runtime library to unwind the stack.

+ +

This instruction is used in languages with destructors to ensure that proper +cleanup is performed in the case of either a longjmp or a thrown +exception. Additionally, this is important for implementation of +'catch' clauses in high-level languages that support them.

+
Example:
-
  %retval = invoke int %Test(int 15)
              to label %Continue
              except label %TestCleanup     ; {int}:retval set
+
+  %retval = invoke int %Test(int 15)             to label %Continue
+              except label %TestCleanup     ; {int}:retval set
+  %retval = invoke coldcc int %Test(int 15)             to label %Continue
+              except label %TestCleanup     ; {int}:retval set
@@ -2049,7 +2140,7 @@ value argument, otherwise it returns the second value argument.
Syntax:
-  <result> = [tail] call <ty>* <fnptrval>(<param list>)
+  <result> = [tail] call [cconv] <ty>* <fnptrval>(<param list>)
Overview:
@@ -2062,12 +2153,17 @@ value argument, otherwise it returns the second value argument.
  1. -

    The "tail" marker indicates whether the callee function accesses any - allocas or varargs in the caller. If the "tail" marker is present, the +

    The optional "tail" marker indicates whether the callee function accesses + any allocas or varargs in the caller. If the "tail" marker is present, the function call is eligible for tail call optimization. Note that calls may be marked "tail" even if they do not occur before a ret instruction.

    2. +
  2. +

    The optional "cconv" marker indicates which calling + convention the call should use. If none is specified, the call defaults + to using C calling conventions. +

  3. 'ty': shall be the signature of the pointer to function value being invoked. The argument types must match the types implied by this @@ -2104,6 +2200,7 @@ the invoke instruction.

    %retval = call int %test(int %argc) call int(sbyte*, ...) *%printf(sbyte* %msg, int 12, sbyte 42); %X = tail call int %foo() + %Y = tail call fastcc int %foo()
-- 2.34.1