# The OS/K Team licenses this file to you under the MIT license.
# See the LICENSE file in the project root for more information.

#------------------------------------------------------------------------------#

1. STACK

Stack grows downward. 'rbp' and 'rsp' are both used.
There is no red zone. The lowest stack frame is marked by having 'rbp' = 0.

A function's assembly code looks like this:
    label:
        enter N
        ...
        ...
        ...
        leave
        ret
'N' is the number of local variables used by the function,
and is omitted if there are none ('enter' alone takes N=0).

The above code is equivalent to the following, but much faster:
    label:
        mov [rsp-8], rbp
        lea rbp, [rsp-8]
        sub rsp, (N+1)*8
        ...
        ...
        ...
        lea rsp, [rbp+8]
        mov rbp, [rbp]
        ret

Between the 'enter' and the 'leave', the stack looks like this:
        .               .
        .               .
        .   (caller's)  .
        |---------------|
        |   saved rip   |   rbp+8
        |   saved rbp   |   rbp+0
        |       .       |   rsp+(N*8)   \
        |       .       |   ...         |
        |       .       |   ...         |
        |       .       |   ...         |- Local variables
        |       .       |   rsp+16      |
        |       .       |   rsp+8       |
        |       .       |   rsp+0       /
        |---------------|
        .  (undefined)  .
        .               .
        .               .


'enter' and 'leave' can be omitted if ALL the following hold:
the function
    - uses no local variables (on the stack)
    - never uses any function that changes 'rbp' nor 'rsp',
      aside from 'call' and 'ret'
    - never calls a variadic function

You can never omit 'enter' without omitting 'leave', anc vice-versa.

#------------------------------------------------------------------------------#

2. CALLING CONVENTION

No matter whether 'enter' and 'leave' were ommited or not, the following must
hold true whenever a function is entered or exited from:
    - 'rbp' must be 8-bytes aligned
    - 'rsp' must be 8-bytes aligned
    - the DF flag must be cleared

Aside from the DF flag, a function cannot assume anything about the state
of the flags in the FLG register.

Passing parameters is done using the following registers, in that order:
    ax0-ax7, lx0-lx7

The stack is never used for argument passing. If you need to pass large
structures of data, pass their address in an appropriate register.

Return values are passed in 'rax'. If the return value does not fit
and require more registers, use the following registers, in that order:
    rax, rdx, lx0-lx7

The following registers are volatile; the calling function cannot assume
that they will be left unmodified by the called function:
    rax, rcx, rdx, rsi, rdi, lx0-lx7, ax0-ax7

The following registers are nonvolatile; the called function must preserve them:
    rbp, rsp, rbx, rsx, rbi, nx0-nx7

#------------------------------------------------------------------------------#

3. SPECIAL REGISTERS

The 'inv' register cannot be referenced by machine code except when specified
as an offset register in the [reg+reg(*/+...)] memory formats; in these case,
'inv' can be assumed to be always null.

The following registers can only be used by the supervisor; they are intended
to be used as fast global variables for the supervisor:
    sa0-sa7

The following registers cannot be referenced by machine code at all; they must
be manipulated through specific instructions, and manipulating their values
allow for controlling the machine in various ways:
    cr0-cr7

#------------------------------------------------------------------------------#