interrupt.h

Go to the documentation of this file.

#pragma once
 
#include <kernel/cpu/idt.h>
 
#include <stdbool.h>
#include <stdint.h>
 
/**
 * @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 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_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 Per-CPU Interrupt Context.
 * @struct interrupt_ctx_t
 *
 * Used to manage nested CLI (Clear Interrupt Flag) calls and track interrupt depth.
 */
typedef struct
{
    bool inInterrupt;
    uint64_t oldRflags;
    uint32_t disableDepth;
} interrupt_ctx_t;
 
/**
 * @brief Pointers to functions to handle each vector.
 */
extern void* vectorTable[IDT_GATE_AMOUNT];
 
/**
 * @brief Initializes the interrupt context.
 *
 * @param ctx The interrupt context to initialize.
 */
void interrupt_ctx_init(interrupt_ctx_t* ctx);
 
/**
 * @brief Disable interrupts and increment the disableDepth.
 *
 * Must have a matching `interrupt_enable()` call to re-enable interrupts when depth reaches zero.
 */
void interrupt_disable(void);
 
/**
 * @brief Decrement the CLI depth and enable interrupts if depth reaches zero and interrupts were previously enabled.
 */
void interrupt_enable(void);
 
/**
 * @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);
 
/** @} */