@node Calling Convention
@comment  node-name,  next,  previous,  up
@chapter Calling Convention

@menu
* Assembly Routines::           
* Local Calls::                 
* Full Calls::                  
* Unknown-Values Returns::      
* IR2 Conversion::              
* Additional Notes::            
@end menu

The calling convention used within Lisp code on SBCL/x86 was,
for the longest time, really bad. If it weren't for the fact
that it predates modern x86 CPUs, one might almost believe it to
have been designed explicitly to defeat the branch-prediction
hardware therein. This chapter is somewhat of a brain-dump of
information that might be useful when attempting to improve the
situation further, mostly written immediately after having made
a dent in the problem.

Assumptions about the calling convention are embedded throughout
the system. The runtime knows how to call in to Lisp and receive
a value from Lisp, the assembly-routines have intimate knowledge
of what registers are involved in a call situation,
@file{src/compiler/target/call.lisp} contains the VOPs involved in
implementing function call/return, and @file{src/compiler/ir2tran.lisp} has
assumptions about frame allocation and argument/return-value
passing locations.

The current round of changes has been limited to VOPs, assembly-routines,
related support functions, and the required support in the runtime.

Note that most of this documentation also applies to other CPUs,
modulo the actual registers involved, the displacement used
in the single-value return convention, and the fact that they
use the ``old'' convention anywhere it is mentioned.


@node Assembly Routines
@comment  node-name,  next,  previous,  up
@section Assembly Routines

@example
;;; The :full-call assembly-routines must use the same full-call
;;; unknown-values return convention as a normal call, as some
;;; of the routines will tail-chain to a static-function. The
;;; routines themselves, however, take all of their arguments
;;; in registers (this will typically be one or two arguments,
;;; and is one of the lower bounds on the number of argument-
;;; passing registers), and thus don't need a call frame, which
;;; simplifies things for the normal call/return case. When it
;;; is neccessary for one of the assembly-functions to call a
;;; static-function it will construct the required call frame.
;;; Also, none of the assembly-routines return other than one
;;; value, which again simplifies the return path.
;;;    -- AB, 2006/Feb/05.
@end example

There are a couple of assembly-routines that implement parts of
the process of returning or tail-calling with a variable number
of values. These are @code{return-multiple} and @code{tail-call-variable} in
@file{src/assembly/x86/assem-rtns.lisp}. They have their own calling
convention for invocation from a VOP, but implement various
block-move operations on the stack contents followed by a return
or tail-call operation.

That's about all I have to say about the assembly-routines.


@node Local Calls
@comment  node-name,  next,  previous,  up
@section Local Calls

Calls within a block, whatever a block is, can use a local
calling convention in which the compiler knows where all of the
values are to be stored, and thus can elide the check for number
of return values, stack-pointer restoration, etc. Alternately,
they can use the full unknown-values return convention while
trying to short-circuit the call convention. There is probably
some low-hanging fruit here in terms of CPU branch-prediction.

The local (known-values) calling convention is implemented by
the @code{known-call-local} and @code{known-return} VOPs.

Local unknown-values calls are handled at the call site by the
@code{call-local} and @code{mutiple-call-local} VOPs. The main difference
between the full call and local call protocols here is that
local calls use a different frame setup protocol, and will tend
to not use the normal frame layout for the old frame-pointer and
return-address.


@node Full Calls
@comment  node-name,  next,  previous,  up
@section Full Calls

@example
;;; There is something of a cross-product effect with full calls.
;;; Different versions are used depending on whether we know the
;;; number of arguments or the name of the called function, and
;;; whether we want fixed values, unknown values, or a tail call.
;;;
;;; In full call, the arguments are passed creating a partial frame on
;;; the stack top and storing stack arguments into that frame. On
;;; entry to the callee, this partial frame is pointed to by FP.
@end example

Basically, we use caller-allocated frames, pass an fdefinition,
function, or closure in @code{EAX},
argcount in @code{ECX}, and first three args in @code{EDX}, @code{EDI},
and @code{ESI}. @code{EBP} points to just past the start of the frame
(the first frame slot is at @code{[EBP-4]}, not the traditional @code{[EBP]},
due in part to how the frame allocation works). The caller stores the
link for the old frame at @code{[EBP-4]} and reserved space for a
return address at @code{[EBP-8]}. @code{[EBP-12]} appears to be an
empty slot available to the compiler within a function, it
may-or-may-not be used by some of the call/return junk. The first stack
argument is at @code{[EBP-16]}. The callee then reallocates the
frame to include sufficient space for its local variables, after
possibly converting any @code{&rest} arguments to a proper list.


@node Unknown-Values Returns
@comment  node-name,  next,  previous,  up
@section Unknown-Values Returns

The unknown-values return convention consists of two parts. The
first part is that of returning a single value. The second is
that of returning a different number of values. We also changed
the convention here recently, so we should describe both the old
and new versions. The three interesting VOPs here are @code{return-single},
@code{return}, and @code{return-multiple}.

For a single-value return, we load the return value in the first
argument-passing register (@code{A0}, or @code{EDI}), reload the old frame
pointer, burn the stack frame, and return. The old convention
was to increment the return address by two before returning,
typically via a @code{JMP}, which was guaranteed to screw up branch-
prediction hardware. The new convention is to return with the
carry flag clear.

For a multiple-value return, we pass the first three values in
the argument-passing registers, and the remainder on the stack.
@code{ECX} contains the total number of values as a fixnum, @code{EBX} points
to where the callee frame was, @code{EBP} has been restored to point to
the caller frame, and the first of the values on the stack (the
fourth overall) is at @code{[EBP-16]}. The old convention was just to
jump to the return address at this point. The newer one has us
setting the carry flag first.

The code at the call site for accepting some number of unknown-
values is fairly well boilerplated. If we are expecting zero or
one values, then we need to reset the stack pointer if we are in
a multiple-value return. In the old convention we just encoded a
@code{MOV ESP, EBX} instruction, which neatly fit in the two byte gap
that was skipped by a single-value return. In the new convention
we have to explicitly check the carry flag with a conditional
jump around the @code{MOV ESP, EBX} instruction. When expecting more
than one value, we need to arrange to set up default values when
a single-value return happens, so we encode a jump around a
stub of code which fakes up the register use convention of a
multiple-value return. Again, in the old convention this was a
two-byte unconditionl jump, and in the new convention this is
a conditional jump based on the carry flag.


@node IR2 Conversion
@comment  node-name,  next,  previous,  up
@section IR2 Conversion

The actual selection of VOPs for implementing call/return for a
given function is handled in ir2tran.lisp. Returns are handled
by @code{ir2-convert-return}, calls are handled by @code{ir2-convert-local-call},
@code{ir2-convert-full-call}, and @code{ir2-convert-mv-call}, and
function prologues are handled by @code{ir2-convert-bind} (which calls
@code{init-xep-environment} for the case of an entry point for a full
call).


@node Additional Notes
@comment  node-name,  next,  previous,  up
@section Additional Notes

The low-hanging fruit here is going to be changing every call
and return to use @code{CALL} and @code{RETURN} instructions
instead of @code{JMP} instructions.

A more involved change would be to reduce the number of argument
passing registers from three to two, which may be beneficial in
terms of our quest to free up a GPR for use on Win32 boxes for a
thread structure.

Another possible win could be to store multiple return-values
somewhere other than the stack, such as a dedicated area of the
thread structure. The main concern here in terms of clobbering
would be to make sure that interrupts (and presumably the
internal-error machinery) know to save the area and that the
compiler knows that the area cannot be live across a function
call. Actually implementing this would involve hacking the IR2
conversion, since as it stands now the same argument conventions
are used for both call and return value storage (same TNs).
