IRQ pseudocode compiler

[Jiri Svoboda]

Devise a programmer-friendly language for describing HelenOS IRQ pseudocode and then implement its compiler and make HelenOS use it.

Details

Level-sensitive interrupts are tricky to handle especially in a microkernel-based operating system in which the device drivers run as userspace processes. The condition which triggered the interrupt must be cleared before the system is ready to receive another interrupt of the same kind (or the device immediately interrupts the system again), but only the userspace driver knows how to do it. This kind of a chicken-and-egg problem must be solved somehow. HelenOS achieves this in a portable way by letting the userspace driver inject a specialized byte code into the kernel. When an interrupt comes, the kernel uses the pseudocode to figure out whether the driver wants to accept the interrupt and also to clear the condition.

IRQ pseudocode in drivers is typically written as a C initializer (array of structs with designated members). This is not very concise/elegant. What's worse, often we need to substitute constants representing various physical addresses into the code, which is done by patching the individual pseudocode instructions at run time by hand.

It would be much more elegant to define a text-based language for expressing this symbolic instruction code. Thus the driver could express the pseudocode as a simple string literal that would be then converted to the binary form. The language could allow for named constants, which would make the code much more readable.

What Gains and Benefits will this bring?

It will be easier and more comfortable to write the interrupt-handling part of each driver. The pseudocode will be much more readable and there will be fewer programming errors.

Difficulty

Depending on the devised language, the difficulty will range from easy for an assembly-like language to medium and difficult for a more C-like language, such as the one suggested here or in ​this master thesis.

Required skills

A successful applicant will have good skills of programming in the C language and the ability to use both the current and the devised language for writing HelenOS IRQ pseudocode. In case of a more sophisticated language, the candidate shall also have an understanding of grammars and various compiler construction techniques.

Documentation

• Example of the current IRQ pseudocode in the NE2000 driver​
• Example of possible IRQ pseduocode description language
• Writing Device Drivers for HelenOS
• ​Linux kernel userspace modules (master thesis)

Possible mentors

HelenOS Core Team, Jiri Svoboda, Jakub Jermar, Martin Decky

[Jakub Jermář]

I can imagine, the text-based language could look something like this:

//
// This IRQ pseudocode assumes the address of what will later be defined as my_device on its input during compile-time.
//
code(device my_device) {
    // named constant
    const MY_DEVICE_DATA_READY 0x1

    // definition of the layout of the device's registers
    device my_device {
        ioport32 status;
        ioport8 data;
    }

    // definition of the used PIO ranges
    range mydevice_pio_range_1 {
        base = my_device;
        size = sizeof(my_device);
    }

    //
    // The IRQ claim routine, executed to determine whether the interrupt is for
    // our device and possibly to do some necessary work.
    //
    claim {
        uint8 data;  // limited number of variables as user-friendly names for the underlying irq->notif_cfg.scratch

        //
        // Read/write accesses into the device translate into CMD_PIO_READ/WRITE_n.
        // The if-construct combined with the bitwise AND translates into CMD_BTEST and CMD_PREDICATE.
        //
        if (my_device.status & MY_DEVICE_DATA_READY) {
            data = my_device.data;
            accept(data);  // accept the IRQ and send an IPC message with data as ARG1
        }
    }
}

This pseudocode source can be stored somewhere on the file system. The driver would then use a library code to compile it into a byte code, which would then be uploaded into the kernel. The compilation in the driver-runtime could look something like this:

        char *codesrc;
        irq_code_t irq_code;
        ioport8_t *reg_base;

        ...

        ret = compile_interrupt_code(&irq_code, codesrc, reg_base);
        if (ret != EOK) {
        }

[Martin Decky]

Due to the general proliferation of eBPF, I believe it would be reasonable to switch from our in-house pseudocode to (a subset of) eBPF. This would enable to leverage all the existing eBPF tooling support instead of implementing a very limited custom compiler.

[Jiri Svoboda]

At the time when I filed this ER I thought that complex IRQ pseudocode would be needed for some devices. But the reality has proven otherwise. Given how little and how simple IRQ pseudocode is needed for all our devices, I don't think it would be worth the cost of implementing a compiler, nor worth the cost of pulling in an existing one. eBPF is also much more complex than our pseudocode, it's just an overkill. We implemented a bunch of device drivers and really this hasn't been an issue.