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

CPU device function slots:

   slot    ax0 ax1 ax2 thr  name            desc
   0-15     -   -   -   -   (reserved)      (reserved)
    16      -   -   -   -   getmaxidx       rax = maximal index for a register frame
    17      -   -   -   -   getrfusage      rax = number of register frames active
    18      -   -   -   -   getcuridx       rax = index of the current register frame
    19      -   -   -   -   leastavail      rax = least index among inactive frames, -1 if none
    20      i   -   -   -   isactive        rax = is register frame #ax0 active?
    21      i   -   -   y   activate        activates register frame #ax0 (filling it with 0's)
    22      i   -   -   y   deactivate      deactivates register frame #ax0 (losing all its contents!)
    23      i   i   -   y   copyframe       copy contents of frame #ax1 into (active) frame #ax0
    24      i   i   -   y   moveframe       move frame #ax1 to (inactive) frame index #ax0
    25      i   -   -   -   switchrf        switch to register frame #ax0
   26-31    -   -   -   -   (reserved)      (reserved)
    32      i   -   -   -   loadargs        load registers ax0-ax7 from frame #ax0
    33      i   r   -   -   loadreg         rax = register #ax1 from frame #ax0
   34-47    -   -   -   -   (reserved)      (reserved)
    48      i   r   i   y   storereg        store ax2 into register #ax1 from frame #ax0
   49-63    -   -   -   -   (reserved)      (reserved)
    64      i   i   -   y   idtadd          mark E/I #ax0 as handled by register frame #ax1
    65      i   -   -   y   idtdel          mark E/I #ax0 as unhandled
    66      i   -   -   -   idtquery        rax = E/I #ax0 has handler? rdx = index of handling frame
    67      i   -   -   -   idtdone         signals that handler for E/I #ax0 is done handling
    68+     -   -   -   -   (reserved)      (reserved)

Arguments:
    i       immediate
    r       register index (0=inv, 1=rip, etc...)

Terminology:
    interrupt:  asynchronous transfer of control to another RFRAME due to some device
    exception:  general term for synchronous transfer of control to another RFRAME
    fault:      hardware exception (slots 1-255)
    trap:       software exception (slots 256-511)

IDT slots:
    0           a handler at this slot will receive all exceptions
    1-255       hardware exceptions (see vm/except.h), OVERRIDES slot 0
  256-511       software exceptions (TRAP instruction), OVERRIDES slot 0

    512         a handler at this slot will receive all maskable hardware interrupts
  513-767       maskable hardware interrupts (see ...), OVERRIDES slot 512

    768         a handler in this slot will receive all non-maskable hardware interrupts
  769-1022      non-maskable hardware interrupts (see ...), OVERRIDES slot 768

    1023        Uncatchable exception, guarantees shutdown. Only throwable by supervisor
                via the CRASH instruction, or by the machine in case of irrecoverable failure

A handler for some E/I must use the 'idtdone' iocall to show that it is done dealing with
a certain E/I. If that same E/I happens again before that, the following happens:
    - if this E/I is a fault (hardware exception), but not #DBF, then a #DBF exception is thrown
    - if this E/I is #DBF (double fault), the system crashes ("triple fault")
    - if this E/I is a hardware interrupt, it is queued (*** XXX ***)

When called, a handler will receive the number of the E/I it is handling in R10,
and its own RFRAME ID in R11. (in particular, if exception #25 happens and there are no
handler for it, the handler #0 that will be called will receive '25' in R10, and '0' in R11).
R11 is the value that must be passed to the 'initdone' iocall.
The handler will also receive the previous RFRAME ID in R12.
R13 is also modified but its value is meaningful only to the processor.

To return from an E/I, *after* having called 'idtdone' (using the value originally in R11),
the handler must simply restore R12's and R13's values to what they were when the handler
started executing, and then use the 'IRET' instruction.

Clearing the interrupt flag prevents (and queues) maskable hardware interrupts

Note: RFRAME #0 *cannot* handle interrupts, as a value of 0 in an IDT slot
indicates than there are no handler for the corresponding exception/interrupt