Device Drivers

# What a driver actually implements: a table of function pointers the
# kernel dispatches through. It never knows what hardware is underneath.

class NvmeDriver:
    BLOCK = 512

    def read(self, offset, count):
        lba, blocks = offset // self.BLOCK, count // self.BLOCK
        cmd = self.build_read_cmd(lba, blocks)   # generic -> device command
        self.ring_doorbell(cmd)                  # an MMIO write IS the command
        self.wait_for_irq()                      # sleep; the CPU runs other work
        return self.dma_bytes(count)             # hardware wrote memory directly

    def build_read_cmd(self, lba, blocks):
        return {"opcode": "read", "lba": lba, "blocks": blocks}

    def ring_doorbell(self, cmd):
        self.last = cmd                          # a store to a mapped register

    def wait_for_irq(self):
        pass                                     # top half acks, bottom half works

    def dma_bytes(self, count):
        return bytes(count)                      # no CPU cycles spent copying

d = NvmeDriver()
data = d.read(offset=0, count=4096)
print("command issued:", d.last)
print("bytes returned:", len(data))
print("1 interrupt, 0 CPU copies -- DMA moved every byte")

// A block driver in outline. Real kernel headers cannot compile in
// userspace, so the same structure is shown with the kernel types stubbed:
// what matters is the SHAPE -- a table of operations the kernel calls.
#include <iostream>
#include <cstdint>
#include <cstddef>
#include <vector>
struct Command {
    const char* opcode;
    std::uint64_t lba;
    int blocks;
};
class NvmeDriver {
    static constexpr int BLOCK = 512;
    Command last {
    };
    std::vector<char> dma; // memory the device writes
    public:
    // The kernel calls this through a function-pointer table. It never
    // knows whether the device is NVMe, SATA, or a USB stick.
    std::size_t read(std::uint64_t offset, std::size_t count) {
        last = {"read", offset / BLOCK, int(count / BLOCK)};
        ringDoorbell(); // an MMIO store IS the command
        waitForIrq(); // sleep; the CPU runs elsewhere
        dma.assign(count, 0); // hardware wrote this, not us
        return dma.size();
    }
    const Command& issued() const {
        return last;
    }
    private:
    void ringDoorbell() {
    }
    // a store to a mapped register, not to RAM
    void waitForIrq() {
    }
    // top half acks; bottom half does the work
};
int main() {
    NvmeDriver d;
    std::size_t n = d.read(0, 4096);
    std::cout << "lba " << d.issued().lba << " blocks " << d.issued().blocks
    << " -> " << n << " bytes, 1 interrupt, 0 CPU copies\n";
}

// Drivers are not written in Java, but the dispatch pattern is the point:
// the kernel holds an interface reference and never knows the concrete type.
interface BlockDevice {
    int read(byte[] buf, long offset, int count);
    void open();
    void close();
}
class NvmeDevice implements BlockDevice {
    private final Mmio regs; // memory-mapped registers
    private final DmaPool pool; // memory the controller can reach
    public int read(byte[] buf, long offset, int count) {
        long lba = offset >> 9; // bytes -> logical block
        DmaBuffer dma = pool.alloc(count); // device-visible memory
        Command cmd = Command.read(lba, count >> 9, dma.busAddress());
        submissionQueue.push(cmd);
        regs.write(DOORBELL, submissionQueue.tail()); // MMIO write starts it
        completion.await(); // thread sleeps here
        dma.syncForCpu(); // invalidate stale cache
        dma.copyTo(buf, count);
        return count;
    }
}
// The VFS layer holds BlockDevice, not NvmeDevice -- swap the hardware,
// swap the implementation, the caller is unchanged.