DEV Community: Václav Hajšman

Mastering interrupt handling in your kernel

Václav Hajšman — Wed, 24 Dec 2025 01:02:14 +0000

Building a kernel from scratch is one thing. Mastering its interrupt system is another. In this article, We'll talk about how I designed, implemented, and fine-tuned a full-featured interrupt handling system in my custom kernel, complete with queues, priorities, and statistics collection, all without relying on external multitasking frameworks.

The primary goals for the new interrupt handling system were:

Immediate execution of critical ISRs for devices that just can not wait (for example PIT)
Flexible queue and prioritization for non-critical ISRs
Interrupt-related statistics such as processing time, trigger frequency and drop count.
Simple and maintainable interface for registering and handling ISRs.

The ISR Parameter Block

At the core of the system is the isrpb_t structure - a parameter block for every handler. It stores the statistics, configuration, flags, pointer to handler itself and optional additional context resolution.

struct kernel_isrpb {
    ISR handler;

    unsigned int avgTimeElapsed;
    unsigned int avgTrigPerSecond;
    unsigned int maxTimeElapsed;
    unsigned int minTimeElapsed;

    unsigned int trigCount;
    unsigned int trigCountTmp;
    unsigned int completeCount;
    unsigned int trigTimestamp;
    unsigned int droppedCount;

    unsigned int flags;

    void* (*additionalContextResolv) (struct kernel_isrpb* param);
} __attribute__((packed));

Using the unified block allows to manage interrupts consistently and extend its capabilities.

Queues and priorities

Non-critical ISRs are enqueued using a FIFO circular buffer keeping the system responsive while respecting priorities. The queue supports 3 priority levels determined based on ISR Parameter Block flags (IsrPriorityHigh and IsrPriorityCrit).

if(isr->flags & IsrPriorityCrit) return 0;
return isr->flags & IsrPriorityHigh ? 1 : 2;

I also designed a small function that based on queue takes the ISR with the greatest priority.

isrpb_t* isr_queue_autotake() {
    for(unsigned int priority = 0; priority < 3; priority++) {
        isrpb_t* isr = isr_queue_pop(priority);
        if(isr) return isr;
    }
    return NULL;
}

Dispatching and execution

The dispatch function handles executing ISRs while updating their statistics, such as average execution time and trigger counts, but more on statistics later.

Critical ISRs bypass the queue and are executed immediately, this also happens when the queue is empty, so the routine is as short as possible.

The system also tracks whether an ISR is currently active by setting IsrActive flag LOW and HIGH and checking it's value to prevent reentrant execution unless explicitly allowed using the IsrReenterant flag.

isr->trigCount++; isr->trigCountTmp++;
isr->trigTimestamp = pit_get();

if((isr->flags & IsrActive) && !(isr->flags & IsrReentrant))
    return;

isr->flags |= IsrActive;
u32 start = 0;

// do stats only if IsrDoStats and not IsrPriorityCrit
int doStats = (isr->flags & IsrDoStats) && !(isr->flags & IsrPriorityCrit);
if(doStats) start = isr->trigTimestamp;

ISR handler = isr->handler;
handler(reg);

if(doStats) isr_doStats(isr, start);

isr->flags &= ~IsrActive;
isr->completeCount++;

The dispatch logic executes scheduled when the system iterates to the next ISR through the queue or immediately when an interrupt is fired and the queue is empty. Since PIT (Programmable Interrupt Timer) is active, there's always an interrupt.

void isr_processQueue() {
    isrpb_t* isr = isr_queue_autotake();
    if(isr) isr_dispatch(isr, NULL, 1);
}

void isr_irqHandler(REGISTERS *reg) {
    // ...
    // run immediatelly if critical or queue empty
    unsigned int priority = isr_getPriority(isr);
    if(isr_canRunNow(priority)) goto skip;
    isr_queue_push(isr);
    return;
skip:
    isr_dispatch(isr, reg, 1);
    isr_processQueue();
    return;
}

Statistics observation

The next important part was measuring how interrupts actually behave in real-time. For each ISR, the system tracks following statistics (stored in ISR Parameter Block):

Average, Minimum and Maximum Execution time - the moving average of processing time in ticks (avgTimeElapsed) and min/max time extremes observed for the ISR (minTimeElapsed, maxTimeElapsed).

if(isr->completeCount > 0) {
    isr->avgTimeElapsed = ((isr->avgTimeElapsed * isr->completeCount) + elapsed) / (isr->completeCount + 1);
    if(elapsed > isr->maxTimeElapsed) isr->maxTimeElapsed = elapsed;
    if(elapsed < isr->minTimeElapsed) isr->minTimeElapsed = elapsed;
    return;
}
isr->avgTimeElapsed = elapsed; isr->minTimeElapsed = elapsed; isr->maxTimeElapsed = elapsed;

Trigger count - how many times the ISR was invoked (trigCount).
Completion count - how many times the ISR actually finished the execution (completeCount).
Drop count - how many times the ISR execution was dropped (droppedCount). The ISR drop actually happens when the system is overloaded and the space in queue is no longer sufficient. This statistic is even logged independently on IsrDoStats flag and is being done in isr_queue_push function.

if(next == queue->head) {
    // system is overloaded and not capable of any new ISR at the moment.
    isr->droppedCount++;
    return;
}

Average trigger frequency - how many times the ISR was invoked per second in average (avgTrigPerSecond). The trigCountTmp and trigTimestamp fields (parameters) are used for calculation of this statistic.

if(elapsed == 0) elapsed = 1;
u32 tdiff = now - isr->trigTimestamp;
if(tdiff >= PIT_FREQUENCY) {
    isr->avgTrigPerSecond = (isr->trigCountTmp * PIT_FREQUENCY) / tdiff;
    isr->trigCountTmp = 0;
}

These statistics (except the droppedCount) are updated only for non-critical ISRs to avoid skewing by high-frequency timer interrupts, and only if the IsrDoStats flag is set. Critical ISRs (like the PIT), bypass statistics to prevent counter overflow and measurement noise and to allow even better latency.

This data provides deep insight into system behavior. You can see which interrupt dominate the CPU time, how often they are triggered, and how effeciently each handler executes.

Putting it all together

Once the queue, dispatch and registration mechanisms were in place, the system ran smoothly. Even althrough i've not implemented the multitasking yet, this design allows the kernel to maintain predictable and measurable behavior and allows easier debugging of device drivers.

IRQ Lookup: an utility for interrupt handling related diagnosis

To better understand and debug interrupt behavior, I implemented an IRQ Lookup utility in the kernel.

ISR listing

Executing the command with no arguments makes the utility iterate through all registered interrupt handlers and prints key information about each ISR in the following format:

IRQ_BASE+<IRQ no.> -> (Handler address (Base16)) (Handler function symbol name):
 -> avgTps=X avgTE=X minTE=X maxTE=X, lastTrig=X cc=X tc=X dc=X flags=X

Detailed summary for ISR specified

Executing the command with --show-irq <IRQ no.> argument generates a detailed summary of what is contained in ISR Parameter Block, that includes:

IRQ. no, handler address and symbol name
Additional context resolution function address and symbol name
Stats
- IRQ acknowledge count, ISR complete count, ISR drop count
- Last timestamp
- Averge, minimal and maximal time elapsed
- Total time elapsed - this is calculated in time by multiplying an average time (avgTimeElapsed) with acknowledge count (trigCount), giving u64 time_tot
- Average frequency - how many times the interrupt was invoked per second in average
- Parameter block flags - written using their names as strings.

const char* flagName(unsigned int bit) {
    switch (bit) {
        case IsrActive:         return "IsrActive";
        // ...
        case IsrWakeup:         return "IsrWakeup";
        default:                return "Unknown";
    }
}

u64 time_tot = ((p->flags & IsrDoStats) && !(p->flags & IsrPriorityCrit) && p->avgTimeElapsed != 0) 
    ? (p->completeCount * p->avgTimeElapsed) : 0;

int first = 1;
for(unsigned int bit = 1; bit != 0; bit <<= 1) {
    if(p->flags & bit) {
        if(!first) callback_stdout("\n                         ");
        callback_stdout((char*) flagName(bit));
        first = 0;
    }
}

Parameter block flags decode

Executing the command with --decode-flags <Flags integer> argument decodes the flags and outputs them as string in human readable format.

Conclusion

Mastering interrupt handling in kernel is not just about making ISRs run, but it's also about observing, controlling and prioritizing them effectively. Implementing a queue-based priority system ensures that critical interrupts are serviced immediately while less critical ones wait for their turn, maintaining system stability and predictability.

The IRQ Lookup utility complement this design by providing real-time visibility into the interrupt subsystem. With these, I cam:

Inspect which ISRs are registered and active.
Monitor execution statistics.
Verify flags and handler states to ensure correct behavior.

This combination provides both robustness and transparency.

Moving forward on stack trace and symbols

Václav Hajšman — Mon, 07 Jul 2025 18:59:56 +0000

In the last post, we talked about stack, stack trace and symbols, and how to make use of these. I've mentioned that in future i would like to focus on replacing GCC __builtin_return_address() with frame-pointer unwinding and improving symbol lookup performance with binary search. So, lets begin.

What even is frame pointer unwinding

Frame pointer unwinding is a method which can be used to get backtrace (iterate through stack trace). It assumes that every function has stored the frame of previously called function using frame pointer (in our case ebp register, because we're on x86 - or for example rbp on x86_64, fp (aka x29) on AArch64, etc.).

This creates a linked list of frames, where each frame points to the one below it (i.e., the caller's frame). That allows us to traverse the call stack in a straightforward way — just by following the chain of saved frame pointers.

To prevent compiler from doing optimization, make sure to pass these as CFLAGS: -fno-omit-frame-pointer -fno-optimize-sibling-calls -mno-omit-leaf-frame-pointer. This ensures ebp is kept for each function, including the most optimized ones.

Implementing unwinder

On x86 architecture, the structure of stack frame looks like this

+-------------------+
| address on return | ← saved on `call`
+-------------------+
| previous `EBP`    | ← stored by function when start
+-------------------+ ← `EBP` points here

So implementing the structure in C is not even much hard

typedef struct kernel_stack_frame {
    struct kernel_stack_frame* ebp;
    void* ret_addr;
} kernel_stack_frame_t;

As long as the compiler doesn't optimize this away (using -fomit-frame-pointer), each function:

saves previous value of ebp on stack,
sets new value setting value of ebp to current value of esp - this creates the frame,
when the function ends, ebp and esp restores to unwind back to the caller.

So now, lets actually code the unwinder.
First, you set frame pointer address from ebp

kernel_stack_frame_t* frame;
asm volatile("movl %%ebp, %0" : "=r" (frame));

Then, you simply just iterate through these frames, copy current frame's return address and set frame to the next one

for(unsigned int i = 0; i < maxFrames; i++) {
    if(frame == NULL || frame->ebp == NULL)
        break;

    buffer[i] = frame->ret_addr;
    frame = frame->ebp;
}

And yeah, that's all. The final function should look somehow like this. Easy, right?

void debug_captureStackTrace(void** buffer, unsigned int maxFrames) {
    if(maxFrames == 0 || buffer == NULL) {
        debug_message("debug_captureStackTrace(): invalid parameters", "debug", KERNEL_ERROR);
        return;
    }

    kernel_stack_frame_t* frame;

    // get EBP register value
    asm volatile("movl %%ebp, %0" : "=r" (frame));

    for(unsigned int i = 0; i < maxFrames; i++) {
        if(frame == NULL || frame->ebp == NULL)
            break;

        buffer[i] = frame->ret_addr;
        frame = frame->ebp;
    }
}

Using in debug_dumpStackTrace()

Remember that ugly, goofy, switch based "iterator"? No more of that. In debug_dumpStackTrace(), capture the stack trace to the preallocated buffer and just dump the buffer instead.

void debug_dumpStackTrace(u8 depth, void (*_fn_print)(unsigned char*)) {
    // ...

    void* trace[depth];
    memset(trace, 0x00, sizeof(trace));

    debug_captureStackTrace(trace, depth);

    for(unsigned int i = 0; i < depth; i++) {
        void* addr = trace[i];
        if(!addr || (uintptr_t) addr < 0x10000)
            break;

        // ...
    }
}

Now we can finally remove the get_return_address() function.

Future plans

Allow mapping source file + line using DWARF or ELF debug info

Implementing stack traces and symbol lookup in my kernel: debugging without GDB

Václav Hajšman — Sun, 06 Jul 2025 22:52:17 +0000

In this post, i describe how I implemented stack tracing in my hobby operating system kernel — including symbolic address resolution without GDB. Includes code snippets, explanation of pitfalls with __builtin_return_address, and a simple symbol map generator.

What even is stack, stack tracing and symbols?

Stack

In many programming languages (including C, the one i used), stack is used to store function return addresses, local variables and context used when calling functions. It works based on LIFO (last-in, first-out) principle, when last called function is the first one to be thrown away.

In the context of operating system (hobby kernels especially), you are the one fully responsible for this stack and you need to implement one at your own. When something fails, the stack is often a thing which tells you where that happened.

Stack trace

Stack trace (or call trace, backtrace) is a list of symbols and memory addresses. These addresses tells the developer, how the program (kernel) ended up on the location where it crashed.

Typically stack trace is shown while crash, kernel panic - it might be on the screen, in the runtime logs, debug outputs, etc.

DEBUG: [ FATAL   ][Kernel panic] Kernel panic.
...
DEBUG: [ FATAL   ][Kernel panic] kernel stack trace
  [trace frame 0x0] 0x1078457: debug_dumpStackTrace
  [trace frame 0x1] 0x1074140: kernel_panic
  [trace frame 0x2] 0x1079080: kernel_exit
  [trace frame 0x3] 0x1061516: _start

It is often also present in GNU/Linux kernel panic info:

Symbols

In translated binary executable (for example kernel.elf - in my case, krnl.tmp.elf), a memory address is assigned for each function. The problem is, the address itself (0x1074140) does not tell you much - this is when symbols take place. They help mapping memory addresses to function names.

It is common to throw away symbols while binary optimization or stripping, but it is still possible to generate them during build process and use them later in order to translate memory addresses to function names even without the debugger. But more on that later.

How i implemented stacktrace

In early kernel, you have no GDB, no debug symbols in runtime, no backtrace or libunwind. If stacktrace is needed, you need to pull it out bare hands, using GCC builting function __builtin_return_address().

/*
#define __wrap_return_address(x)    \
    ((x) >= 0 && (x) < 16 ? __builtin_return_address(x) : NULL)

As you can see, i wrapped the function call in the wrapper, because:

i can always replace __builtin_result_address with something else, if needed (and possible),
the macro i used is designed to prevent overflows while passing the x parameter

But how do you dump it?

Reading stack trace is useless if you can't use it somehow. And the way you can use the most of it (and probably the most understandable way and only way you want to) is to dump it somehow in order to debug your kernel.

There is simple way to do it, just iterate through it until you reach the end or the maximum depth you wanted to, right?

for(int i = 0; i > depth; i++) {
    void* addr = __wrap_return_address(i);
    if(!addr) return;

    / ...
}

It makes sense, but the problem is the __builtin_return_address is actually not a function, but a macros on the compiler level (intrinsics) and the values of their call parameters are needed to be known at the time of compilation, so:

GCC can replace their result statically (this is called "constant folding")
GCC can optimize the code
GCC can eliminate branches and decide the data type

The way you can overcome the intrinsics is probably using the switch statement and checking for every number from zero to maximum. I know, it looks goofy and bad, and no one wants that in their code - because of this, i plan replacing it with Frame pointer-based unwinding sometime in the future.

void* get_return_address(int i) {
    switch(i) {
        case 0: return __builtin_return_address(0);
        case 1: return __builtin_return_address(1);
        // ...
        case 15: return __builtin_return_address(15);
        default: return NULL;
    }
}

/**
 * @brief Dumps stack trace
 * 
 * @param depth how many addresses to dump
 * @param _fn_print pointer to function that is used as print
 */
void debug_dumpStackTrace(u8 depth, void (*_fn_print)(unsigned char*)) {
    // ...

    for(int i = 0; i < depth; i++) {
        void* addr = get_return_address(i);
        if(!addr || (uintptr_t) addr < 0x10000)
            break;

        // ...
    }
}

Update your linker script

When trying to build, i have experienced an linkage error saying something like the program can't reach __builtin_return_address function, or is not executable. To fix this, i needed to add this to the end of SECTIONS list of my linker script:

.note.GNU-stack : {
        KEEP(*(.note.GNU-stack))
    }

Symbols, converting addresses to names

As mentioned, without symbols, 0x1074140 in dump does not make much sense. This is why i decided to generate custom symbol map from linker outputs and use it in runtime.

Converting the addresses

After kernel compilation, i generate symbol map using nm:

ld -T config/linker.ld -o build/bin/krnl.tmp.elf $(find build/obj -name "*.o" -type f) \
    -m elf_i386 -nostdlib

nm -n build/bin/krnl.tmp.elf > build/kernel.map

Then, i use awk, cat, and echo to convert this symbol map to an array in C.

cat build/kernel.map | awk '$2 == "T" { printf("    { 0x%s, \"%s\" },\n", $1, $3); }' > src/kernel/core/kernel.sym.entries

echo '#include "kernel/core/symbols.h"' > src/kernel/core/kernel.sym.c
echo 'symbol_t kernel_symbols[] = {' >> src/kernel/core/kernel.sym.c
cat src/kernel/core/kernel.sym.entries >> src/kernel/core/kernel.sym.c
echo '};' >> src/kernel/core/kernel.sym.c
echo 'size_t kernel_symbol_count = sizeof(kernel_symbols) / sizeof(kernel_symbols[0]);' >> src/kernel/core/kernel.sym.c

gcc -I src -m32 -std=gnu99 -ffreestanding -c src/kernel/core/kernel.sym.c -o build/obj/kernel/core/kernel.sym.c.o

This results in C code which is pasted into the kernel using the script above.

typedef struct {
    uintptr_t addr;
    const char* name;
} symbol_t;

#include "kernel/core/symbols.h"
symbol_t kernel_symbols[] = {
    { 0x00100000, "__code" },
    { 0x00100000, "_code" },
    { 0x00100000, "code" },
    { 0x00100000, "__kernel_text_section_start" },
    // ...
};

size_t kernel_symbol_count = sizeof(kernel_symbols) / sizeof(kernel_symbols[0]);

After this, i can proceed to generate the image the way i always used to.

Symbol lookup

After building a symbol map and translating it into C array, making of debug_lookup function is quite easy.

const char* debug_lookup(uintptr_t addr) {
    const char* best_match = "??";
    uintptr_t best_addr = 0x00000000;

    for(size_t i = 0; i < kernel_symbol_count; i++) {
        if(kernel_symbols[i].addr <= addr && kernel_symbols[i].addr >= best_addr) {
            best_addr = kernel_symbols[i].addr;
            best_match = kernel_symbols[i].name;
        }
    }

    return best_match;
}

This function takes an address of a function, looks up to the symbol map and returns function name, or ?? if nothing is found.

Lets make some use of it. Remember me saying that stack trace dump is useless if we don't know what the functions are, but addresses? Lets update the debug_dumpStackTrace() function to dump not only the addresses, but function names next to them.

void debug_dumpStackTrace(u8 depth, void (*_fn_print)(unsigned char*)) {
    // ...

    for(int i = 0; i < depth; i++) {
        // ...

        _fn_print((unsigned char*) "  [trace frame 0x");
        _fn_print((unsigned char*) i_string);
        _fn_print((unsigned char*) "] 0x");
        _fn_print((unsigned char*) addr_string);
        _fn_print(": ");
        _fn_print((unsigned char*) debug_lookup((uintptr_t) addr));
        _fn_print((unsigned char*) "\n");
    }
}

Enhacing the kernel panic dump with stack trace dump with function names

I already had kernel panic callback implemented, so the only thing to worry about was calling a function to dump stack trace

#ifndef __KERNEL_PANIC_STACK_TRACE_DEPTH
#define __KERNEL_PANIC_STACK_TRACE_DEPTH 10
#endif

void kernel_panic(REGISTERS* reg, signed int exception) {
    // ...

    // --- stack trace ---
    debug_message("kernel stack trace\n", "Kernel panic", KERNEL_FATAL);
    void _print(unsigned char* data) {
        puts(data);
        debug_append(data);
    }

    puts("\nKERNEL STACK TRACE:\n");
    debug_dumpStackTrace(__KERNEL_PANIC_STACK_TRACE_DEPTH, &_print);

    // ...
}

Now we have beautiful and useful info dump.

DEBUG: [ FATAL   ][Kernel panic] Kernel panic.
...
DEBUG: [ FATAL   ][Kernel panic] kernel stack trace
  [trace frame 0x0] 0x1078457: debug_dumpStackTrace
  [trace frame 0x1] 0x1074140: kernel_panic
  [trace frame 0x2] 0x1079080: kernel_exit
  [trace frame 0x3] 0x1061516: _start

Future plans

Replace __builtin_return_address() with frame pointer unwinding
Improve symbol lookup performance using binary search
Allow mapping source file + line using DWARF or ELF debug info

kmalloc() bugfix

Václav Hajšman — Sun, 06 Jul 2025 19:06:30 +0000

Yesterday, after a huge amount of time, after a lot of trying, i was able to finally fix a bug in kmalloc function of my kernel.

The kmalloc function in kernel is a function responsible for locating a block of size specified, marking it as used and returning it's address.

What caused the bug and how the bug was fixed

The bug was that the address was stored in a result variable and instead of its value, its address was returned In a summary: A classic beginner mistake - when instead of addr, the function returns &addr.

This caused the function to not only return an invalid address, but always the same value, which i simply did not notice for a long amount of time.

Also a refactor has been done, removing the potentionaly useless functions, separating a long functions into separate files and focusing a bit more on safe code.

The proof of bug fix

As seen in debug logs, attempting of allocation of 8 memory blocks of size 8 bytes results in success and returns different address each time.

./qemu.sh
cat serial.log | grep "malloc(8)"
DEBUG: [   ***   ][kmalloc] malloc(8) = 0x1323024
DEBUG: [   ***   ][kmalloc] malloc(8) = 0x1318928
 ...
DEBUG: [   ***   ][kmalloc] malloc(8) = 0x1294352