# 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.
The lowest stack frame is marked by having 'rbp' = 0.
There is a 128-bytes red zone below 'rsp'.

A function's assembly code looks like this:
    label:
        enter N
        ...
        ...
        ...
        leave
        ret
'N' is the number of local variables used by the function.

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', and 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, except for variadic functions,
cf the next section. 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, rsx, lx0-lx7, ax0-ax7

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

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

3. VARIADIC FUNCTIONS

To call a variadic function, do this:
        sub rsp, nargs * 8
        mov [rsp], arg0
        ...
        ...
        ...
        mov [rsp+(N*8)], argN
        call variadic_func
        add rsp, nargs * 8

To the variadic function, argN can be accessed the following way:
        mov reg, [rbp + N*8 + 16]

For instance:
        mov rax, [rbp + 16]     ; arg1
        mov rdx, [rbp + 24]     ; arg2

It is recommended to use the reg+reg*imm16+imm16 memory format:
        mov rax, [rbp + rcx * 8 + 16]       ; accesses arg#rcx

The 'va_list' type can be regarded as a pointer to the
variadic function's rbp+16

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

4. 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

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