interrupt.h

Go to the documentation of this file.

#pragma once
 
#ifndef __ASSEMBLER__
#include <kernel/cpu/idt.h>
 
#include <stdbool.h>
#include <stdint.h>
 
typedef struct cpu cpu_t;
#endif
 
/**
 * @brief Interrupt Handling
 * @defgroup kernel_cpu_interrupt Interrupts
 * @ingroup kernel_cpu
 *
 * Interrupts are a way to allow the CPU or external devices to stop the currently executing code and instead to execute
 * a handler function specified in the Interrupt Descriptor Table (IDT).
 *
 * ## Interrupt Frames
 *
 * An interrupt frame (`interrupt_frame_t`) is a structure that lets us access data pushed onto the stack by the CPU and
 * in the assembly interrupt stubs when an interrupt occurs.
 *
 * First, when an interrupt occurs, the CPU automatically pushes some data onto the stack, such as the instruction
 * pointer and code/data segments, this data is stored in the higher addresses of the `interrupt_frame_t` (since the
 * stack grows downwards).
 *
 * After that, depending on the type of interrupt, the CPU might push an error code, if not the stub will push a `0` as
 * a dummy, all stubs will also push the interrupt vector number onto the stack.
 *
 * Finally, the `vector_common` assembly function pushes all general-purpose registers onto the stack, completing the
 * `interrupt_frame_t`.
 *
 * After the interrupt handler is done executing, the interrupt frame is popped off the stack allowing the CPU to
 * restore its previous state or, if the interrupt handler modified the registers, it may return to a different state,
 * for example, a different thread. This is how context switching is implemented.
 *
 * ## Interrupt Numbers
 *
 * Interrupts are identified by their vector number, which is an 8-bit value ranging from `0x00` to `0xFF`. Usually,
 * each vector number would be associated with a specific handler function, but this is quite inconvenient for the OS as
 * a whole, it's more practical to have one single `interrupt_handler()` function which can then more easily group and
 * dispatch the interrupts as needed, it also lets us write interrupt handling code in C instead of assembly.
 *
 * This is done by, as mentioned above, having each vector's handler push its vector number onto the stack before
 * jumping to the common `interrupt_handler()`, which can then read the vector number from the `interrupt_frame_t`.
 *
 * @{
 */
 
/**
 * @brief Macro to be used in ASM to define the size of an interrupt frame.
 */
#define INTERRUPT_FRAME_SIZE (8 * 22)
 
/**
 * @brief Macro to be used in ASM to push general-purpose registers onto the stack.
 */
#define INTERRUPT_FRAME_REGS_PUSH \
    pushq % rax; \
    pushq % rbx; \
    pushq % rcx; \
    pushq % rdx; \
    pushq % rsi; \
    pushq % rdi; \
    pushq % rbp; \
    pushq % r8; \
    pushq % r9; \
    pushq % r10; \
    pushq % r11; \
    pushq % r12; \
    pushq % r13; \
    pushq % r14; \
    pushq % r15;
 
/**
 * @brief Macro to be used in ASM to pop general-purpose registers from the stack.
 */
#define INTERRUPT_FRAME_REGS_POP \
    popq % r15; \
    popq % r14; \
    popq % r13; \
    popq % r12; \
    popq % r11; \
    popq % r10; \
    popq % r9; \
    popq % r8; \
    popq % rbp; \
    popq % rdi; \
    popq % rsi; \
    popq % rdx; \
    popq % rcx; \
    popq % rbx; \
    popq % rax;
 
#ifndef __ASSEMBLER__
 
/**
 * @brief Page Fault Error Codes.
 * @enum page_fault_errors_t
 *
 * Will be stored in the error code of the interrupt frame on a page fault.
 */
typedef enum
{
    PAGE_FAULT_PRESENT = 1 << 0,
    PAGE_FAULT_WRITE = 1 << 1,
    PAGE_FAULT_USER = 1 << 2,
    PAGE_FAULT_RESERVED = 1 << 3,
    PAGE_FAULT_INSTRUCTION = 1 << 4,
    PAGE_FAULT_PROTECTION_KEY = 1 << 5,
    PAGE_FAULT_SHADOW_STACK = 1 << 6,
    PAGE_FAULT_SOFTWARE_GUARD_EXT = 1 << 7,
} page_fault_errors_t;
 
/**
 * @brief Interrupt Vectors.
 * @enum interrupt_vector_t
 *
 * Lists all interrupt vectors, divided into exceptions, external interrupts and internal interrupts.
 *
 * ## Exceptions
 *
 * Exceptions are interrupts generated by the CPU itself in response to, usually, unexpected conditions such as a divide
 * by zero. Sometimes exceptions can be intentional, such as the use of page faults for dynamic stack growth.
 *
 * ## External Interrupts
 *
 * External interrupts are reserved for the IRQ system.
 *
 * See @ref kernel_cpu_irq.
 *
 * ## Internal Interrupts
 *
 * Internal interrupts are, as the name suggests, used internally by the kernel for things such as timer interrupts and
 * inter-processor interrupts (IPIs).
 *
 * See @ref kernel_cpu_ipi and @ref kernel_timer.
 *
 */
typedef enum
{
    VECTOR_EXCEPTION_START = 0x0, ///< Inclusive start of exceptions.
    VECTOR_DIVIDE_ERROR = 0x0,
    VECTOR_DEBUG = 0x1,
    VECTOR_NMI = 0x2,
    VECTOR_BREAKPOINT = 0x3,
    VECTOR_OVERFLOW = 0x4,
    VECTOR_BOUND_RANGE_EXCEEDED = 0x5,
    VECTOR_INVALID_OPCODE = 0x6,
    VECTOR_DEVICE_NOT_AVAILABLE = 0x7,
    VECTOR_DOUBLE_FAULT = 0x8,
    VECTOR_COPROCESSOR_SEGMENT_OVERRUN = 0x9,
    VECTOR_INVALID_TSS = 0xA,
    VECTOR_SEGMENT_NOT_PRESENT = 0xB,
    VECTOR_STACK_SEGMENT_FAULT = 0xC,
    VECTOR_GENERAL_PROTECTION_FAULT = 0xD,
    VECTOR_PAGE_FAULT = 0xE,
    VECTOR_RESERVED = 0xF,
    VECTOR_X87_FLOATING_POINT_EXCEPTION = 0x10,
    VECTOR_ALIGNMENT_CHECK = 0x11,
    VECTOR_MACHINE_CHECK = 0x12,
    VECTOR_SIMD_FLOATING_POINT_EXCEPTION = 0x13,
    VECTOR_VIRTUALIZATION_EXCEPTION = 0x14,
    VECTOR_CONTROL_PROTECTION_EXCEPTION = 0x15,
    VECTOR_HYPERVISOR_INJECTION_EXCEPTION = 0x1C,
    VECTOR_VMM_COMMUNICATION_EXCEPTION = 0x1D,
    VECTOR_SECURITY_EXCEPTION = 0x1E,
    VECTOR_EXCEPTION_END = 0x20, ///< Exclusive end of exceptions.
 
    VECTOR_EXTERNAL_START = 0x20, ///< Inclusive start of external interrupts (handled by the IRQ system).
    VECTOR_EXTERNAL_END = 0xF0,   ///< Exclusive end of external interrupts.
 
    VECTOR_EXTERNAL_AMOUNT = VECTOR_EXTERNAL_END - VECTOR_EXTERNAL_START,
 
    VECTOR_INTERNAL_START = 0xF0, ///< Inclusive start of internal interrupts.
    VECTOR_FAKE = 0xFC,           ///< Used to implement `interrupt_fake()`.
    VECTOR_IPI = 0xFD,            ///< See @ref kernel_cpu_ipi for more information.
    VECTOR_TIMER = 0xFE,          ///< See @ref kernel_timer for more information.
    VECTOR_SPURIOUS = 0xFF,       ///< Made available for any component to use as a sink for spurious interrupts.
    VECTOR_INTERNAL_END = 0x100,  ///< Exclusive end of internal interrupts.
 
    VECTOR_TOTAL_AMOUNT = 0x100,
} interrupt_vector_t;
 
/**
 * @brief Trap Frame Structure.
 * @struct interrupt_frame_t
 *
 * Stores the CPU state at the time of a interrupt, usefull for context switching as we can modify the
 * registers before returning from the interrupt.
 */
typedef struct interrupt_frame
{
    uint64_t r15;
    uint64_t r14;
    uint64_t r13;
    uint64_t r12;
    uint64_t r11;
    uint64_t r10;
    uint64_t r9;
    uint64_t r8;
    uint64_t rbp;
    uint64_t rdi;
    uint64_t rsi;
    uint64_t rdx;
    uint64_t rcx;
    uint64_t rbx;
    uint64_t rax;
 
    uint64_t vector;
    uint64_t errorCode;
 
    uint64_t rip;
    uint64_t cs;
    uint64_t rflags;
    uint64_t rsp;
    uint64_t ss;
} interrupt_frame_t;
 
/**
 * @brief Checks if a interrupt frame is from user space.
 * @def INTERRUPT_FRAME_IN_USER_SPACE
 *
 * @param frame The interrupt frame to check.
 * @return true if the interrupt frame is from user space, false otherwise.
 */
#define INTERRUPT_FRAME_IN_USER_SPACE(frame) ((frame)->ss == (GDT_SS_RING3) && (frame)->cs == (GDT_CS_RING3))
 
/**
 * @brief Pointers to functions to handle each vector.
 */
extern void* vectorTable[IDT_GATE_AMOUNT];
 
/**
 * @brief Handles CPU interrupts.
 *
 * This will be called from `vector_common` in `vectors.S`.
 *
 * @param frame The interrupt frame containing the CPU state at the time of the exception.
 */
void interrupt_handler(interrupt_frame_t* frame);
 
/**
 * @brief Enter a fake interrupt context as if an interrupt had occurred at the given frame.
 *
 * Provides a way to schedule and handle notes outside of a real interrupt context.
 *
 * @warning Must only be called when interrupts are disabled.
 *
 * @param frame The interrupt frame representing the state at the time of the fake interrupt.
 * @return Will not return, instead will load and jump to the given interrupt frame, unless the thread gets scheduled or
 * the frame is modified.
 */
_NORETURN extern void interrupt_fake(interrupt_frame_t* frame);
 
#endif
 
/** @} */