Tag: Linux kernel module

  • Complete Linux Block Device Driver Project: Kernel Driver + Userspace Access Program

    Complete Linux Block Device Driver Project tutorial covering kernel module development and userspace access program. Learn how to build, register, and test a block device driver in Linux with step-by-step code examples, real-world concepts, and performance insights for beginners and advanced developers.

    This is a complete, working project. By the end of this guide you will have a Linux block device driver running as a kernel module, a userspace C program that opens the device and performs raw read/write operations on it, a working Makefile that builds both, and a clear understanding of every line of code.

    No hand-waving. No “left as an exercise.” Every file is here, complete and ready to compile.

    This is the kind of project that actually belongs in a portfolio if you are looking for embedded Linux or Linux kernel driver roles. It touches kernel module development, block layer internals, device node access from userspace, raw sector I/O, and ioctl communication all in one project.

    Before diving into implementation, it’s important to understand the fundamentals of how block device drivers work in Linux. If you’re new to this topic, check out this Linux Block Device Drivers: The Complete Beginner’s Guide, which explains core concepts like request queues, buffering, and kernel interactions in a simple and beginner-friendly way.

    Linux Block Device Driver Project

    1. Project Overview and Architecture

    Here is what we are building and how the pieces connect:

    
    +---------------------------+
    |     Userspace Program     |  userapp.c
    |  open() / read() / write()|
    |  ioctl() / lseek()        |
    +------------+--------------+
                 |
                 | /dev/myblkdev  (block device node)
                 |
    +------------+--------------+
    |      Linux Block Layer    |  Kernel block layer
    |  bio, request queue,      |
    |  blk-mq, scheduler        |
    +------------+--------------+
                 |
    +------------+--------------+
    |   myblkdev.ko             |  Our kernel module
    |   RAM-backed block driver |
    |   16MB virtual disk       |
    |   ioctl for device info   |
    +---------------------------+
                 |
         vmalloc'd RAM buffer
         (simulates disk storage)
    

    The kernel module registers a block device backed by a 16MB chunk of kernel RAM. It handles read and write requests through the blk-mq interface. It also exposes an ioctl command so userspace can query device information like size and sector count.

    The userspace program opens the device node directly using open(), writes a pattern to specific sectors using write(), reads it back and verifies it, and calls ioctl() to print device info.

    This is exactly how tools like dd, hdparm, and storage benchmark tools work at the lowest level.

    2. Prerequisites and Environment Setup

    Before you start, make sure your system has everything needed:

    # Install kernel headers for your running kernel
    sudo apt-get update
    sudo apt-get install linux-headers-$(uname -r) build-essential
    
    # Verify kernel headers are present
    ls /lib/modules/$(uname -r)/build
    # Should show a directory, not an error
    
    # Check your kernel version
    uname -r
    # This project is tested on 5.15+ and 6.x kernels

    You also need to run the load and test steps as root or with sudo. Block devices require root access for raw sector I/O from userspace.

    If you are on a VM (recommended for kernel development), make sure you can do sudo insmod and that your VM has at least 256MB of RAM free for the driver’s buffer plus kernel overhead.

    3. Project Directory Structure

    Create this layout on your machine:

    myblkdev/
    ├── myblkdev.c       # Kernel block device driver
    ├── myblkdev.h      # Shared header (kernel + userspace)
    ├── userapp.c         # Userspace test and access program
    └── Makefile           # Builds both kernel module and userapp
    mkdir myblkdev
    cd myblkdev

    All four files go in this single directory. The Makefile handles building the kernel module (which goes through the kernel build system) and the userspace binary (which is just a normal gcc compile) in one make command.

    4. Shared Header File : myblkdev.h

    This header is included by both the kernel driver and the userspace program. It defines the ioctl command numbers and the data structure used to exchange device information. Sharing this header between kernel and userspace is the standard kernel pattern — it ensures both sides agree on the exact binary layout of ioctl structures.

    /* myblkdev.h
     * Shared header between kernel driver and userspace program.
     * Defines ioctl interface for myblkdev block device driver.
     */
    
    #ifndef MYBLKDEV_H
    #define MYBLKDEV_H
    
    #include <linux/ioctl.h>
    
    /* Magic number for our driver's ioctl commands.
     * Pick something unlikely to conflict. Check Documentation/userspace-api/ioctl/ioctl-number.rst
     */
    #define MYBLKDEV_MAGIC  0xBD
    
    /* Device info structure returned by MYBLKDEV_GET_INFO ioctl */
    struct myblkdev_info {
        unsigned long total_bytes;    /* total device size in bytes */
        unsigned long sector_count;   /* total number of 512-byte sectors */
        unsigned int  sector_size;    /* sector size in bytes (always 512 here) */
        unsigned int  major;          /* device major number */
        unsigned int  minor;          /* device minor number */
    };
    
    /* ioctl command: get device info
     * Direction: kernel -> userspace (IOR = read from kernel's perspective)
     * Type: MYBLKDEV_MAGIC
     * Number: 1
     * Size: sizeof(struct myblkdev_info)
     */
    #define MYBLKDEV_GET_INFO  _IOR(MYBLKDEV_MAGIC, 1, struct myblkdev_info)
    
    /* ioctl command: reset device (zero all storage)
     * Direction: no data transfer
     * Type: MYBLKDEV_MAGIC
     * Number: 2
     */
    #define MYBLKDEV_RESET     _IO(MYBLKDEV_MAGIC, 2)
    
    #endif /* MYBLKDEV_H */

    The _IOR and _IO macros encode the direction, magic number, command number, and data size into a single 32-bit integer. This encoding prevents different drivers from accidentally sharing the same ioctl number, which would cause the wrong driver to handle the command.

    5. The Kernel Block Device Driver : myblkdev.c

    This is the full kernel driver. Read through it section by section — every part is commented to explain what it does and why.

    /* myblkdev.c
     * A RAM-backed Linux block device driver with ioctl support.
     * Registers /dev/myblkdev as a 16MB block device.
     *
     * Tested on Linux 5.15 - 6.x
     * License: GPL v2
     */
    
    #include <linux/module.h>
    #include <linux/kernel.h>
    #include <linux/init.h>
    #include <linux/fs.h>
    #include <linux/blkdev.h>
    #include <linux/blk-mq.h>
    #include <linux/genhd.h>
    #include <linux/hdreg.h>
    #include <linux/vmalloc.h>
    #include <linux/uaccess.h>
    #include "myblkdev.h"
    
    MODULE_LICENSE("GPL");
    MODULE_AUTHOR("myblkdev project");
    MODULE_DESCRIPTION("RAM-backed block device driver with ioctl");
    MODULE_VERSION("1.0");
    
    /* ===== Configuration ===== */
    #define MYBLKDEV_MAJOR       240        /* static major; 240-254 are for local use */
    #define MYBLKDEV_NAME        "myblkdev"
    #define MYBLKDEV_MINORS      1          /* 1 = no partitions; use 16 to allow partitions */
    #define DISK_SIZE_MB         16
    #define KERNEL_SECTOR_SIZE   512
    
    /* ===== Device State ===== */
    struct myblkdev_state {
        unsigned long    size;          /* device size in bytes */
        u8              *data;          /* vmalloc'd storage buffer */
        spinlock_t       lock;          /* protects data access */
        struct blk_mq_tag_set  tag_set;
        struct request_queue  *queue;
        struct gendisk        *gd;
        int              major;
        int              minor;
    };
    
    /* Single global device instance for this example */
    static struct myblkdev_state *mydev;
    
    /* ===== Request Handler ===== */
    /*
     * This is the core of the driver. The block layer calls this function
     * for every I/O request. We iterate over each segment of the request,
     * copy data to/from our RAM buffer, and signal completion.
     */
    static blk_status_t myblkdev_queue_rq(struct blk_mq_hw_ctx *hctx,
                                           const struct blk_mq_queue_data *bd)
    {
        struct request        *req  = bd->rq;
        struct myblkdev_state *dev  = req->q->queuedata;
        struct bio_vec         bvec;
        struct req_iterator    iter;
        loff_t                 pos;
        unsigned long          flags;
    
        /* Mark request as started — required by blk-mq before any processing */
        blk_mq_start_request(req);
    
        /* Reject non-filesystem requests (SCSI passthrough, etc.) */
        if (blk_rq_is_passthrough(req)) {
            pr_notice(MYBLKDEV_NAME ": skip passthrough request\n");
            blk_mq_end_request(req, BLK_STS_IOERR);
            return BLK_STS_OK;
        }
    
        /* Convert starting sector to byte offset.
         * blk_rq_pos() returns offset in 512-byte units always. */
        pos = (loff_t)blk_rq_pos(req) * KERNEL_SECTOR_SIZE;
    
        spin_lock_irqsave(&dev->lock, flags);
    
        /* Iterate over each scatter-gather segment in the request */
        rq_for_each_segment(bvec, req, iter) {
            void   *buf = page_address(bvec.bv_page) + bvec.bv_offset;
            size_t  len = bvec.bv_len;
    
            /* Bounds check — never go past our buffer */
            if (pos + len > dev->size) {
                pr_err(MYBLKDEV_NAME ": I/O beyond device size "
                       "(pos=%lld len=%zu size=%lu)\n",
                       pos, len, dev->size);
                spin_unlock_irqrestore(&dev->lock, flags);
                blk_mq_end_request(req, BLK_STS_IOERR);
                return BLK_STS_OK;
            }
    
            if (rq_data_dir(req) == WRITE) {
                /* WRITE: copy from bio page into our RAM buffer */
                memcpy(dev->data + pos, buf, len);
            } else {
                /* READ: copy from our RAM buffer into bio page */
                memcpy(buf, dev->data + pos, len);
            }
    
            pos += len;
        }
    
        spin_unlock_irqrestore(&dev->lock, flags);
    
        /* Signal successful completion to the block layer */
        blk_mq_end_request(req, BLK_STS_OK);
        return BLK_STS_OK;
    }
    
    /* blk-mq operations table — only queue_rq is mandatory */
    static const struct blk_mq_ops myblkdev_mq_ops = {
        .queue_rq = myblkdev_queue_rq,
    };
    
    /* ===== ioctl Handler ===== */
    /*
     * Userspace programs can call ioctl() on the block device fd to
     * get device info or trigger a reset. We handle our custom commands
     * here and return -ENOTTY for anything we don't recognize.
     */
    static int myblkdev_ioctl(struct block_device *bdev, fmode_t mode,
                               unsigned int cmd, unsigned long arg)
    {
        struct myblkdev_state *dev = bdev->bd_disk->private_data;
        struct myblkdev_info   info;
        unsigned long          flags;
    
        switch (cmd) {
    
        case MYBLKDEV_GET_INFO:
            /* Fill info structure and copy to userspace */
            info.total_bytes  = dev->size;
            info.sector_count = dev->size / KERNEL_SECTOR_SIZE;
            info.sector_size  = KERNEL_SECTOR_SIZE;
            info.major        = dev->major;
            info.minor        = dev->minor;
    
            if (copy_to_user((void __user *)arg, &info, sizeof(info)))
                return -EFAULT;
            return 0;
    
        case MYBLKDEV_RESET:
            /* Zero the entire storage buffer */
            spin_lock_irqsave(&dev->lock, flags);
            memset(dev->data, 0, dev->size);
            spin_unlock_irqrestore(&dev->lock, flags);
            pr_info(MYBLKDEV_NAME ": device reset (zeroed)\n");
            return 0;
    
        default:
            /* Unknown command — return standard "not a typewriter" error */
            return -ENOTTY;
        }
    }
    
    /* ===== Block Device Operations Table ===== */
    static const struct block_device_operations myblkdev_fops = {
        .owner          = THIS_MODULE,
        .ioctl          = myblkdev_ioctl,
    };
    
    /* ===== Module Init ===== */
    static int __init myblkdev_init(void)
    {
        int ret;
    
        pr_info(MYBLKDEV_NAME ": initializing %d MB RAM block device\n",
                DISK_SIZE_MB);
    
        /* Allocate our device state structure */
        mydev = kzalloc(sizeof(*mydev), GFP_KERNEL);
        if (!mydev) {
            pr_err(MYBLKDEV_NAME ": failed to allocate device state\n");
            return -ENOMEM;
        }
    
        mydev->size  = DISK_SIZE_MB * 1024 * 1024;
        mydev->major = MYBLKDEV_MAJOR;
        mydev->minor = 0;
        spin_lock_init(&mydev->lock);
    
        /* Allocate the RAM storage buffer using vmalloc.
         * We use vmalloc (not kmalloc) because we need a large contiguous
         * virtual mapping but don't need physically contiguous memory. */
        mydev->data = vmalloc(mydev->size);
        if (!mydev->data) {
            pr_err(MYBLKDEV_NAME ": failed to allocate %d MB storage\n",
                   DISK_SIZE_MB);
            ret = -ENOMEM;
            goto err_free_dev;
        }
        memset(mydev->data, 0, mydev->size);
    
        /* Register the block device major number */
        ret = register_blkdev(MYBLKDEV_MAJOR, MYBLKDEV_NAME);
        if (ret < 0) {
            pr_err(MYBLKDEV_NAME ": register_blkdev failed (%d)\n", ret);
            goto err_free_data;
        }
    
        /* Configure blk-mq tag set.
         * nr_hw_queues=1: single hardware queue (fine for RAM, no real HW)
         * queue_depth=128: up to 128 in-flight requests at once */
        mydev->tag_set.ops          = &myblkdev_mq_ops;
        mydev->tag_set.nr_hw_queues = 1;
        mydev->tag_set.queue_depth  = 128;
        mydev->tag_set.numa_node    = NUMA_NO_NODE;
        mydev->tag_set.cmd_size     = 0;
        mydev->tag_set.flags        = BLK_MQ_F_SHOULD_MERGE;
    
        ret = blk_mq_alloc_tag_set(&mydev->tag_set);
        if (ret) {
            pr_err(MYBLKDEV_NAME ": blk_mq_alloc_tag_set failed (%d)\n", ret);
            goto err_unreg_blkdev;
        }
    
        /* Create the request queue linked to our tag set */
        mydev->queue = blk_mq_init_queue(&mydev->tag_set);
        if (IS_ERR(mydev->queue)) {
            ret = PTR_ERR(mydev->queue);
            pr_err(MYBLKDEV_NAME ": blk_mq_init_queue failed (%d)\n", ret);
            goto err_free_tag_set;
        }
    
        /* Store device pointer in queue for access from request handler */
        mydev->queue->queuedata = mydev;
    
        /* Set queue limits — tell the block layer what our "hardware" supports */
        blk_queue_logical_block_size(mydev->queue, KERNEL_SECTOR_SIZE);
        blk_queue_max_hw_sectors(mydev->queue, 256); /* max 128KB per request */
    
        /* Allocate the gendisk structure.
         * MYBLKDEV_MINORS=1 means no partition support.
         * Use 16 if you want to allow up to 15 partitions. */
        mydev->gd = alloc_disk(MYBLKDEV_MINORS);
        if (!mydev->gd) {
            pr_err(MYBLKDEV_NAME ": alloc_disk failed\n");
            ret = -ENOMEM;
            goto err_free_queue;
        }
    
        /* Fill in gendisk fields */
        mydev->gd->major        = MYBLKDEV_MAJOR;
        mydev->gd->first_minor  = 0;
        mydev->gd->fops         = &myblkdev_fops;
        mydev->gd->queue        = mydev->queue;
        mydev->gd->private_data = mydev;
        snprintf(mydev->gd->disk_name, sizeof(mydev->gd->disk_name),
                 MYBLKDEV_NAME);
    
        /* Set disk capacity in 512-byte sectors */
        set_capacity(mydev->gd, mydev->size / KERNEL_SECTOR_SIZE);
    
        /* add_disk() makes the device visible — /dev/myblkdev appears after this */
        add_disk(mydev->gd);
    
        pr_info(MYBLKDEV_NAME ": ready — /dev/%s, major=%d, size=%lu MB\n",
                mydev->gd->disk_name, MYBLKDEV_MAJOR,
                mydev->size / (1024 * 1024));
        return 0;
    
    /* Error cleanup — reverse order of initialization */
    err_free_queue:
        blk_cleanup_queue(mydev->queue);
    err_free_tag_set:
        blk_mq_free_tag_set(&mydev->tag_set);
    err_unreg_blkdev:
        unregister_blkdev(MYBLKDEV_MAJOR, MYBLKDEV_NAME);
    err_free_data:
        vfree(mydev->data);
    err_free_dev:
        kfree(mydev);
        return ret;
    }
    
    /* ===== Module Exit ===== */
    static void __exit myblkdev_exit(void)
    {
        /* Cleanup in strict reverse order of init */
        del_gendisk(mydev->gd);          /* remove from block layer */
        put_disk(mydev->gd);             /* release gendisk reference */
        blk_cleanup_queue(mydev->queue); /* destroy request queue */
        blk_mq_free_tag_set(&mydev->tag_set);
        unregister_blkdev(MYBLKDEV_MAJOR, MYBLKDEV_NAME);
        vfree(mydev->data);              /* free RAM storage */
        kfree(mydev);                    /* free device state */
    
        pr_info(MYBLKDEV_NAME ": unloaded\n");
    }
    
    module_init(myblkdev_init);
    module_exit(myblkdev_exit);
    

    6. The Makefile

    This single Makefile builds both the kernel module and the userspace program. Run make once and you get both.

    # Makefile for myblkdev project
    # Builds kernel module (myblkdev.ko) and userspace program (userapp)
    
    # Kernel build directory — uses headers for currently running kernel
    KDIR ?= /lib/modules/$(shell uname -r)/build
    
    # Kernel module object
    obj-m += myblkdev.o
    
    # Default target: build kernel module then userspace app
    all: module userapp
    
    module:
    	$(MAKE) -C $(KDIR) M=$(PWD) modules
    
    # Userspace app: plain gcc, no kernel headers needed
    # _GNU_SOURCE for pread/pwrite, O_DIRECT etc.
    userapp: userapp.c myblkdev.h
    	gcc -Wall -Wextra -O2 -D_GNU_SOURCE -o userapp userapp.c
    
    clean:
    	$(MAKE) -C $(KDIR) M=$(PWD) clean
    	rm -f userapp
    
    .PHONY: all module userapp clean

    The kernel module build goes through the kernel’s own build system (make -C $(KDIR)). The userspace binary is just a normal gcc compile. The shared myblkdev.h header is included by both — that dependency is declared on the userapp line so it rebuilds if the header changes.

    7. The Userspace Access Program : userapp.c

    This program demonstrates every way a userspace application can interact with a raw block device. It opens the device node directly, queries info via ioctl, writes test patterns to specific sectors, reads them back, and verifies the data.

    /* userapp.c
     * Userspace program to test and demonstrate myblkdev block driver access.
     * Performs: ioctl info query, raw sector write, raw sector read, verify.
     *
     * Run as root: sudo ./userapp /dev/myblkdev
     */
    
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <unistd.h>
    #include <fcntl.h>
    #include <errno.h>
    #include <sys/ioctl.h>
    #include <sys/types.h>
    
    /* Include our shared header.
     * For userspace, linux/ioctl.h is included via sys/ioctl.h already.
     * We redefine to use userspace-safe types. */
    #include "myblkdev.h"
    
    #define SECTOR_SIZE     512
    #define TEST_SECTORS    8       /* write/read 8 sectors = 4KB at a time */
    #define TEST_PATTERN    0xAB    /* byte pattern to write for verification */
    
    /* ===== Helper: print device info from ioctl ===== */
    static void print_device_info(int fd)
    {
        struct myblkdev_info info;
    
        printf("\n--- Device Info (via ioctl) ---\n");
    
        if (ioctl(fd, MYBLKDEV_GET_INFO, &info) < 0) {
            perror("ioctl MYBLKDEV_GET_INFO failed");
            return;
        }
    
        printf("  Total Size   : %lu bytes (%lu MB)\n",
               info.total_bytes, info.total_bytes / (1024 * 1024));
        printf("  Sector Count : %lu sectors\n", info.sector_count);
        printf("  Sector Size  : %u bytes\n", info.sector_size);
        printf("  Major Number : %u\n", info.major);
        printf("  Minor Number : %u\n", info.minor);
        printf("-------------------------------\n\n");
    }
    
    /* ===== Helper: write pattern to a sector range ===== */
    static int write_sectors(int fd, off_t start_sector,
                              int num_sectors, unsigned char pattern)
    {
        size_t   buf_size = num_sectors * SECTOR_SIZE;
        unsigned char *buf;
        ssize_t  written;
        off_t    offset = start_sector * SECTOR_SIZE;
    
        buf = malloc(buf_size);
        if (!buf) {
            fprintf(stderr, "malloc failed\n");
            return -1;
        }
    
        /* Fill buffer with test pattern */
        memset(buf, pattern, buf_size);
    
        /* Seek to the correct byte offset on the block device */
        if (lseek(fd, offset, SEEK_SET) < 0) {
            perror("lseek failed");
            free(buf);
            return -1;
        }
    
        /* Write the buffer — this goes through VFS -> block layer -> our driver */
        written = write(fd, buf, buf_size);
        if (written != (ssize_t)buf_size) {
            fprintf(stderr, "write: expected %zu bytes, got %zd (%s)\n",
                    buf_size, written, strerror(errno));
            free(buf);
            return -1;
        }
    
        printf("[WRITE] Sector %ld - %ld: wrote %zu bytes, pattern=0x%02X\n",
               (long)start_sector, (long)(start_sector + num_sectors - 1),
               buf_size, pattern);
    
        free(buf);
        return 0;
    }
    
    /* ===== Helper: read from sector range and verify pattern ===== */
    static int read_and_verify(int fd, off_t start_sector,
                                int num_sectors, unsigned char expected_pattern)
    {
        size_t    buf_size = num_sectors * SECTOR_SIZE;
        unsigned char *buf;
        ssize_t   bytes_read;
        off_t     offset = start_sector * SECTOR_SIZE;
        int       errors = 0;
        size_t    i;
    
        buf = malloc(buf_size);
        if (!buf) {
            fprintf(stderr, "malloc failed\n");
            return -1;
        }
    
        /* Seek to sector offset */
        if (lseek(fd, offset, SEEK_SET) < 0) {
            perror("lseek failed");
            free(buf);
            return -1;
        }
    
        /* Read back the data */
        bytes_read = read(fd, buf, buf_size);
        if (bytes_read != (ssize_t)buf_size) {
            fprintf(stderr, "read: expected %zu bytes, got %zd (%s)\n",
                    buf_size, bytes_read, strerror(errno));
            free(buf);
            return -1;
        }
    
        /* Verify every byte matches the expected pattern */
        for (i = 0; i < buf_size; i++) {
            if (buf[i] != expected_pattern) {
                fprintf(stderr, "[VERIFY] Mismatch at byte %zu: "
                        "got 0x%02X, expected 0x%02X\n",
                        i, buf[i], expected_pattern);
                errors++;
                if (errors > 5) {
                    fprintf(stderr, "[VERIFY] Too many errors, stopping\n");
                    break;
                }
            }
        }
    
        if (errors == 0) {
            printf("[READ]  Sector %ld - %ld: read %zu bytes — VERIFIED OK "
                   "(pattern=0x%02X)\n",
                   (long)start_sector,
                   (long)(start_sector + num_sectors - 1),
                   buf_size, expected_pattern);
        } else {
            printf("[READ]  Sector %ld - %ld: VERIFICATION FAILED "
                   "(%d errors)\n",
                   (long)start_sector,
                   (long)(start_sector + num_sectors - 1),
                   errors);
        }
    
        free(buf);
        return errors ? -1 : 0;
    }
    
    /* ===== Helper: dump first 64 bytes of a sector as hex ===== */
    static void hexdump_sector(int fd, off_t sector)
    {
        unsigned char buf[64];
        ssize_t       n;
        size_t        i;
    
        lseek(fd, sector * SECTOR_SIZE, SEEK_SET);
        n = read(fd, buf, sizeof(buf));
        if (n <= 0) {
            perror("hexdump read failed");
            return;
        }
    
        printf("\n[HEXDUMP] First 64 bytes of sector %ld:\n", (long)sector);
        for (i = 0; i < (size_t)n; i++) {
            if (i % 16 == 0) printf("  %04zx: ", i);
            printf("%02x ", buf[i]);
            if (i % 16 == 15) printf("\n");
        }
        printf("\n");
    }
    
    /* ===== Helper: reset device via ioctl ===== */
    static void reset_device(int fd)
    {
        printf("[RESET] Sending MYBLKDEV_RESET ioctl...\n");
        if (ioctl(fd, MYBLKDEV_RESET) < 0) {
            perror("ioctl MYBLKDEV_RESET failed");
            return;
        }
        printf("[RESET] Device zeroed successfully\n");
    }
    
    /* ===== Main ===== */
    int main(int argc, char *argv[])
    {
        const char *devpath;
        int         fd;
        int         ret = 0;
    
        if (argc < 2) {
            fprintf(stderr, "Usage: %s \n", argv[0]);
            fprintf(stderr, "Example: sudo %s /dev/myblkdev\n", argv[0]);
            return EXIT_FAILURE;
        }
    
        devpath = argv[1];
    
        printf("===========================================\n");
        printf("  myblkdev Userspace Test Program\n");
        printf("  Device: %s\n", devpath);
        printf("===========================================\n");
    
        /* Open the block device.
         * O_RDWR: we need both read and write access.
         * O_SYNC: write() calls wait for I/O completion before returning.
         *         Important for testing — without this, writes may be
         *         cached by the page cache and not reach the driver immediately. */
        fd = open(devpath, O_RDWR | O_SYNC);
        if (fd < 0) {
            fprintf(stderr, "open(%s) failed: %s\n", devpath, strerror(errno));
            fprintf(stderr, "Did you load the module? Are you running as root?\n");
            return EXIT_FAILURE;
        }
    
        printf("[OPEN]  Opened %s successfully (fd=%d)\n\n", devpath, fd);
    
        /* Step 1: Query device info via ioctl */
        print_device_info(fd);
    
        /* Step 2: Write pattern 0xAB to sectors 0-7 (first 4KB) */
        printf("--- Test 1: Write and Read First 4KB ---\n");
        if (write_sectors(fd, 0, TEST_SECTORS, TEST_PATTERN) < 0) {
            ret = 1;
            goto out;
        }
    
        /* Step 3: Read back and verify */
        if (read_and_verify(fd, 0, TEST_SECTORS, TEST_PATTERN) < 0) {
            ret = 1;
            goto out;
        }
    
        /* Step 4: Hexdump sector 0 to visually confirm */
        hexdump_sector(fd, 0);
    
        /* Step 5: Write different pattern to a sector in the middle of the disk */
        printf("\n--- Test 2: Write and Read Middle of Disk ---\n");
        {
            off_t mid_sector = (DISK_SIZE_MB * 1024 * 1024 / SECTOR_SIZE) / 2;
            printf("[INFO]  Mid-disk sector: %ld\n", (long)mid_sector);
    
            if (write_sectors(fd, mid_sector, TEST_SECTORS, 0xCD) < 0) {
                ret = 1;
                goto out;
            }
            if (read_and_verify(fd, mid_sector, TEST_SECTORS, 0xCD) < 0) {
                ret = 1;
                goto out;
            }
            hexdump_sector(fd, mid_sector);
        }
    
        /* Step 6: Verify sector 0 still has original pattern
         * (mid-disk write must not have corrupted sector 0) */
        printf("\n--- Test 3: Re-verify Sector 0 (Isolation Check) ---\n");
        if (read_and_verify(fd, 0, TEST_SECTORS, TEST_PATTERN) < 0) {
            ret = 1;
            goto out;
        }
    
        /* Step 7: Reset device and verify sector 0 is now zeroed */
        printf("\n--- Test 4: Reset Device and Verify Zeroed ---\n");
        reset_device(fd);
        if (read_and_verify(fd, 0, TEST_SECTORS, 0x00) < 0) {
            ret = 1;
            goto out;
        }
    
        printf("\n===========================================\n");
        if (ret == 0)
            printf("  ALL TESTS PASSED\n");
        else
            printf("  SOME TESTS FAILED — check output above\n");
        printf("===========================================\n");
    
    out:
        close(fd);
        return ret ? EXIT_FAILURE : EXIT_SUCCESS;
    }
    

    8. How the ioctl Interface Works

    The ioctl path is worth understanding clearly because it is the standard way userspace programs communicate non-I/O control information to block and character drivers.

    When userspace calls:

    ioctl(fd, MYBLKDEV_GET_INFO, &info);

    The kernel routes this through VFS to blkdev_ioctl() in the block layer, which checks if it is a standard block ioctl (like BLKGETSIZE, BLKRRPART). If not recognized, it calls your driver’s .ioctl function pointer — which is myblkdev_ioctl() in our driver.

    Inside the driver, copy_to_user() safely copies data from kernel space to the userspace buffer pointer that was passed in as the third argument. You must always use copy_to_user and copy_from_user for this — never dereference a userspace pointer directly in kernel code. It will either fault or silently access wrong memory.

    The _IOR, _IOW, _IOWR, and _IO macros encode direction and size into the command number so the kernel’s ioctl dispatch can do basic sanity checking on the argument size before even calling your handler.

    9. Build, Load, and Run : Step by Step

    # Step 1: Build everything
    cd myblkdev
    make
    
    # You should see:
    # CC [M] /path/to/myblkdev/myblkdev.o
    # LD [M] /path/to/myblkdev/myblkdev.ko
    # gcc -Wall -Wextra -O2 -D_GNU_SOURCE -o userapp userapp.c
    
    # Step 2: Load the kernel module
    sudo insmod myblkdev.ko
    
    # Step 3: Verify it loaded and device node exists
    dmesg | tail -5
    # Expected: myblkdev: ready — /dev/myblkdev, major=240, size=16 MB
    
    ls -la /dev/myblkdev
    # Expected: brw-rw---- 1 root disk 240, 0 ... /dev/myblkdev
    
    cat /proc/devices | grep myblkdev
    # Expected: 240 myblkdev
    
    # Step 4: Run the userspace test program
    sudo ./userapp /dev/myblkdev
    
    # Step 5: When done, unload the module
    sudo rmmod myblkdev
    dmesg | tail -3
    # Expected: myblkdev: unloaded

    10. Expected Output

    When you run sudo ./userapp /dev/myblkdev you should see exactly this:

    ===========================================
      myblkdev Userspace Test Program
      Device: /dev/myblkdev
    ===========================================
    [OPEN]  Opened /dev/myblkdev successfully (fd=3)
    
    --- Device Info (via ioctl) ---
      Total Size   : 16777216 bytes (16 MB)
      Sector Count : 32768 sectors
      Sector Size  : 512 bytes
      Major Number : 240
      Minor Number : 0
    -------------------------------
    
    --- Test 1: Write and Read First 4KB ---
    [WRITE] Sector 0 - 7: wrote 4096 bytes, pattern=0xAB
    [READ]  Sector 0 - 7: read 4096 bytes — VERIFIED OK (pattern=0xAB)
    
    [HEXDUMP] First 64 bytes of sector 0:
      0000: ab ab ab ab ab ab ab ab ab ab ab ab ab ab ab ab
      0010: ab ab ab ab ab ab ab ab ab ab ab ab ab ab ab ab
      0020: ab ab ab ab ab ab ab ab ab ab ab ab ab ab ab ab
      0030: ab ab ab ab ab ab ab ab ab ab ab ab ab ab ab ab
    
    --- Test 2: Write and Read Middle of Disk ---
    [INFO]  Mid-disk sector: 16384
    [WRITE] Sector 16384 - 16391: wrote 4096 bytes, pattern=0xCD
    [READ]  Sector 16384 - 16391: read 4096 bytes — VERIFIED OK (pattern=0xCD)
    
    [HEXDUMP] First 64 bytes of sector 16384:
      0000: cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd cd
      ...
    
    --- Test 3: Re-verify Sector 0 (Isolation Check) ---
    [READ]  Sector 0 - 7: read 4096 bytes — VERIFIED OK (pattern=0xAB)
    
    --- Test 4: Reset Device and Verify Zeroed ---
    [RESET] Sending MYBLKDEV_RESET ioctl...
    [RESET] Device zeroed successfully
    [READ]  Sector 0 - 7: read 4096 bytes — VERIFIED OK (pattern=0x00)
    
    ===========================================
      ALL TESTS PASSED
    ===========================================

    11. How Userspace Actually Talks to the Block Driver

    This is worth tracing through the full kernel call path for both the write and ioctl cases, because understanding this path is what separates someone who just ran the code from someone who actually understands it.

    write() Call Path

    userapp: write(fd, buf, 4096)
      |
      v
    syscall: sys_write()
      |
      v
    VFS: vfs_write() -> block_write_iter()
      |
      v
    Page Cache: data written to page cache first
      |
      v (O_SYNC forces immediate flush)
    Block Layer: submit_bio()
      -> bio created with our data pages
      -> bio submitted to request queue
      -> blk-mq merges/dispatches
      |
      v
    myblkdev_queue_rq()  <-- OUR DRIVER
      -> rq_for_each_segment loops over bio_vec segments
      -> memcpy(dev->data + pos, buf, len)  for WRITE
      -> blk_mq_end_request(req, BLK_STS_OK)
      |
      v
    Block layer signals completion
      -> page cache marks page clean (O_SYNC path)
      |
      v
    write() returns 4096 to userspace

    ioctl() Call Path

    userapp: ioctl(fd, MYBLKDEV_GET_INFO, &info)
      |
      v
    syscall: sys_ioctl()
      |
      v
    VFS: vfs_ioctl() -> blkdev_ioctl()
      |
      v (not a standard block ioctl)
    myblkdev_ioctl()  <-- OUR DRIVER
      -> copy_to_user(&info, kernel_info, sizeof(info))
      -> return 0
      |
      v
    ioctl() returns 0 to userspace
    userspace info struct now has device data

    The key thing to notice: userspace never directly accesses the driver’s memory. Everything goes through the kernel’s VFS and block layer. The copy_to_user() in the driver is the only point where kernel-owned data crosses into user-owned memory, and it does so safely through kernel-controlled copy routines that check permissions.

    12. Extending the Project

    Here are four concrete things you can add to this project to take it further:

    Add Partition Support

    Change MYBLKDEV_MINORS from 1 to 16. Then after loading, run fdisk /dev/myblkdev to create partitions. The kernel will automatically create /dev/myblkdev1, /dev/myblkdev2, etc. Your driver handles them with zero additional code because the block layer translates offsets for you.

    Add a Module Parameter for Disk Size

    static int disk_size_mb = DISK_SIZE_MB;
    module_param(disk_size_mb, int, 0444);
    MODULE_PARM_DESC(disk_size_mb, "Disk size in MB (default 16)");

    Then load with: sudo insmod myblkdev.ko disk_size_mb=64

    Add Multiple Device Instances

    Change the single global device to an array and support creating multiple devices at load time, like the real brd driver does with /dev/ram0, /dev/ram1, etc.

    Format and Mount It

    sudo mkfs.ext4 /dev/myblkdev
    sudo mkdir /mnt/myblkdev
    sudo mount /dev/myblkdev /mnt/myblkdev
    echo "data survives in RAM until rmmod" | sudo tee /mnt/myblkdev/note.txt
    cat /mnt/myblkdev/note.txt
    sudo umount /mnt/myblkdev

    13. Troubleshooting Common Errors

    insmod: ERROR: could not insert module myblkdev.ko: Invalid module format

    Your kernel headers do not match your running kernel. Run uname -r and verify that /lib/modules/$(uname -r)/build exists and matches. On Ubuntu after a kernel update, run sudo apt-get install linux-headers-$(uname -r) again.

    open(/dev/myblkdev) failed: No such file or directory

    The module is not loaded or load failed. Run dmesg | tail -20 to see the error. Also check lsmod | grep myblkdev.

    open(/dev/myblkdev) failed: Permission denied

    Run with sudo. Block devices require root for raw access. Alternatively: sudo chmod 666 /dev/myblkdev for testing only.

    ioctl MYBLKDEV_GET_INFO failed: Inappropriate ioctl for device

    This means the ioctl command number does not match between userapp and the loaded driver. Make sure you rebuilt both after any header change. Run make clean && make, then sudo rmmod myblkdev && sudo insmod myblkdev.ko.

    Kernel panic on rmmod

    Almost always caused by a cleanup order bug. The most common one: calling put_disk() before del_gendisk(), or calling unregister_blkdev() while requests are still in flight. Make sure your exit function matches the exact order in the code above.

    VERIFICATION FAILED in userapp output

    Check dmesg for any error messages from the driver. The most common causes are wrong sector arithmetic (off-by-one in byte offset calculation) or a missing spinlock that lets two requests race on the same buffer region.

    Project File Summary

    FilePurposeLines
    myblkdev.hShared ioctl definitions, magic numbers, info struct~50
    myblkdev.cKernel block device driver — full blk-mq + ioctl~220
    userapp.cUserspace test program — open, write, read, ioctl, verify~230
    MakefileBuilds kernel module and userspace binary together~15

    Final Thoughts

    This project gives you a working end-to-end example of how the Linux block I/O stack operates from the userspace open() call all the way down to your driver’s request handler. Every layer in between VFS, page cache, block layer, blk-mq scheduler, bio structure, scatter-gather segments is exercised by running this code.

    The most important habit to build from here: whenever something does not work, start with dmesg. The kernel logs everything your driver prints and every oops or warning. It is your primary debugging window and it will tell you exactly where something went wrong almost every time.

    From this foundation, the next logical project is adding DMA support to talk to real hardware, or building a stacked driver using the Device Mapper framework that encrypts data before passing it to this RAM disk. Both use exactly the same block layer interfaces you just learned.

    For detailed understanding of Platform Devices and Drivers on Linux, refer to the Linux documentation on Platform Devices and Drivers .

  • Linux Character Driver from Scratch (Beginner to Pro)

    Learn how to build a Linux Character Driver from scratch with this beginner-friendly guide. Step-by-step tutorial covering kernel modules, file operations, device files, and real-world driver examples.

    If you’ve ever wanted to understand how Linux actually talks to hardware, learning a Linux Character Driver is one of the best places to start.

    This guide is not just theory. We’ll go step by step, from zero to a working driver, and explain things like you’re sitting next to me with a coffee asking real questions.

    By the end, you’ll:

    • Understand what a Linux Character Driver is
    • Know where it’s used in real systems (UART, GPIO, etc.)
    • Build a complete driver from scratch
    • Write a user-space program to interact with it
    • Learn how real production drivers are structured

    What is a Linux Character Driver?

    A Linux Character Driver is a type of device driver that communicates with hardware one byte (character) at a time.

    Think of it like reading a book letter by letter instead of jumping pages.

    Examples:

    • UART (serial communication)
    • Keyboard input
    • GPIO pins
    • Sensors

    These are all handled using character device drivers in Linux.

    Character vs Block Drivers

    Let’s make this super simple.

    Imagine you’re reading data like you read content in real life.

    Character Driver (One by One Data)

    A Linux Character Driver works like reading a message letter by letter.

    You don’t jump around. You go in order.

    Example:

    Think of:

    • Typing on keyboard
    • Reading from a serial port
    • Getting sensor data

    All of these send data continuously and sequentially.

    That’s why they use a character device driver in Linux

    Real Devices:

    • /dev/ttyS0 (UART)
    • /dev/input/event0 (keyboard/mouse)
    • /dev/gpiochip0 (GPIO)

    Block Driver (Data in Chunks)

    A Block Driver works like reading a book where you can:

    • Jump to page 10
    • Then page 50
    • Then page 2

    No need to go in order.

    Example:

    Think of:

    • Hard disk
    • SSD
    • USB storage

    You can directly access any part of data.

    That’s why they use block device drivers

    Real Devices:

    • /dev/sda (hard disk)
    • /dev/mmcblk0 (SD card)

    Simple Comparison

    FeatureCharacter DriverBlock Driver
    Data AccessSequentialRandom
    Data TypeStream (byte-by-byte)Blocks (chunks)
    ExampleUART, GPIOHard disk
    SpeedUsually slowerFaster (optimized)
    BufferingMinimalHeavy buffering

    Easy Analogy (Best Way to Remember)

    • Character Driver → Like listening to a song live 🎧
      You hear it as it plays (no jumping)
    • Block Driver → Like YouTube video 📺
      You can skip anywhere

    Golden Rule

    Ask this question:

    👉 “Do I need to access data randomly or sequentially?”

    • Sequential → Linux Character Driver
    • Random → Block Driver

    In real linux driver development beginner journey:

    • First drivers you learn → Character Drivers
    • Advanced storage systems → Block Drivers

    Because character drivers are:

    • Easier to write
    • Closer to hardware
    • Great for learning linux kernel programming basics

    If data flows like a stream → Character Driver
    If data is accessed like storage → Block Driver

    Where Are Character Drivers Used?

    A Linux Character Driver isn’t just a textbook concept. It’s used everywhere Linux needs to handle stream-based, byte-by-byte communication with hardware.

    Think of any device where data flows continuously rather than in chunks. That’s your signal that a character device driver in Linux is probably involved.

    Let’s break down the most common real-world use cases.

    UART Driver

    Used for serial communication between devices.

    GPIO Driver

    Used to control pins (LED, buttons).

    Sensors

    Temperature, pressure sensors send data continuously.

    So yes — when you asked earlier:

    “Is UART, GPIO implemented using character driver?”

    ==> Yes, most of the time : absolutely.

    Basic Architecture of Linux Character Driver

    High-Level Architecture

    Here’s the overall flow:

    User Space Application
            │
            ▼
    System Calls (open, read, write, close)
            │
            ▼
    VFS (Virtual File System)
            │
            ▼
    Character Driver (Your Code)
            │
            ▼
    Hardware Device
    

    Key Components Explained

    1. User Space

    This is where your application runs.

    Example:

    int fd = open("/dev/my_device", O_RDWR);
    write(fd, "Hello", 5);
    read(fd, buffer, 5);
    close(fd);
    

    These are system calls, not direct hardware access.

    2. System Calls Interface

    Linux provides standard APIs:

    • open()
    • read()
    • write()
    • close()

    These calls go through the kernel and reach your driver.

    3. VFS (Virtual File System)

    VFS acts as a bridge between system calls and drivers.

    It ensures:

    • Everything in Linux is treated as a file
    • Your driver is accessed via /dev/my_device

    4. Device File (/dev)

    Example:

    /dev/my_device

    Created using:

    • mknod (manual)
    • udev (automatic)

    It connects user space to your driver.

    5. Character Driver Core Structure

    Your driver mainly consists of:

    a) File Operations Structure

    This is the heart of the driver.

    struct file_operations fops = {
        .open = my_open,
        .read = my_read,
        .write = my_write,
        .release = my_close,
    };

    It tells the kernel:

    “When user calls read(), call my_read()”

    b) Major & Minor Number

    • Major Number → Identifies driver
    • Minor Number → Identifies device

    Example:

    Major: 240 → my driver
    Minor: 0   → device instance

    c) Device Registration

    alloc_chrdev_region(&dev, 0, 1, "my_device");
    

    Registers device with kernel

    d) cdev Structure

    struct cdev my_cdev;
    cdev_init(&my_cdev, &fops);
    cdev_add(&my_cdev, dev, 1);
    

    Links file operations with device

    e) Class & Device Creation

    class_create(THIS_MODULE, "my_class");
    device_create(my_class, NULL, dev, NULL, "my_device");
    

    Creates /dev/my_device

    Driver Entry & Exit

    Init Function

    static int __init my_init(void)
    {
        // register device
        return 0;
    }
    

    Exit Function

    static void __exit my_exit(void)
    {
        // cleanup
    }
    

    Registered using:

    module_init(my_init);
    module_exit(my_exit);

    Complete Flow (Step-by-Step)

    1. User runs program
    2. Calls open("/dev/my_device")
    3. VFS finds your driver
    4. Calls my_open()
    5. User calls write()
    6. Kernel calls my_write()
    7. Driver interacts with hardware
    8. Data flows back via read()

    Pro Tip

    “Character drivers are synchronous, stream-oriented, and accessed via file operations.”

    Linux Kernel Module Basics

    Before writing a driver, we need a kernel module.

    Simple Hello World Module

    #include <linux/module.h>
    #include <linux/kernel.h>
    
    static int __init hello_init(void) {
        printk(KERN_INFO "Hello Driver Loaded\n");
        return 0;
    }
    
    static void __exit hello_exit(void) {
        printk(KERN_INFO "Driver Removed\n");
    }
    
    module_init(hello_init);
    module_exit(hello_exit);
    
    MODULE_LICENSE("GPL");
    

    Compile

    make
    

    Insert Module

    sudo insmod hello.ko

    Remove Module

    sudo rmmod hello

    What is #include?

    #include <linux/module.h>
    #include <linux/kernel.h>
    

    In C, #include means:

    “Bring definitions and declarations from another file so I can use them.”

    1. #include <linux/module.h>

    What it is:

    This header is used for loadable kernel modules (LKM).

    A Linux character driver is actually a kernel module, so this is mandatory.

    What it provides:

    Module Macros

    module_init(my_init);
    module_exit(my_exit);
    

    These tell the kernel:

    • Which function to run when module is loaded
    • Which function to run when module is removed

    License Declaration

    MODULE_LICENSE("GPL");
    

    Important because:

    • Avoids kernel warnings
    • Enables access to some kernel features

    Author & Description

    MODULE_AUTHOR("Raj");
    MODULE_DESCRIPTION("Simple Character Driver");

    Simple Meaning:

    This header makes your C file behave like a kernel module

    2. #include <linux/kernel.h>

    What it is:

    This header provides kernel-level utilities and logging functions

    What it provides:

    printk() (Very Important)

    printk(KERN_INFO "Hello Kernel\n");
    

    This is like printf() but for the kernel.

    Log Levels

    KERN_INFO
    KERN_WARNING
    KERN_ERR
    

    Example:

    printk(KERN_ERR "Something went wrong\n");

    Difference Between Them

    Feature<linux/module.h><linux/kernel.h>
    PurposeModule handlingKernel utilities
    Needed forDriver lifecycleDebugging/logging
    Key Featuremodule_init()printk()

    static int __init hello_init(void) function

    static int __init hello_init(void) {
        printk(KERN_INFO "Hello Driver Loaded\n");
        return 0;
    }
    

    What is this function?

    This is the initialization function (entry point) of your kernel module (driver).

    It runs when you load the driver using:

    insmod driver.ko
    

    Line-by-Line Explanation

    1. static

    Meaning:

    • Limits the scope of this function only to this file

    Other files in the kernel cannot access it

    Why use it?

    • Avoid name conflicts
    • Good coding practice in kernel development

    2. int

    Meaning:

    • Function returns an integer value

    Important:

    • 0 → Success
    • Negative value → Failure

    Example:

    return -ENOMEM;  // Memory allocation failed
    

    3. __init

    What is this?

    A special kernel macro

    What it does:

    • Marks this function as initialization-only code
    • After driver loads → memory is freed automatically

    Saves kernel memory

    Important Rule:

    ❌ Never call an __init function after initialization
    (its memory is gone!)

    4. hello_init

    Function Name:

    • You can name it anything
    • Convention: drivername_init

    5. (void)

    Meaning:

    • Function takes no arguments

    6. { ... } (Function Body)

    a) printk(KERN_INFO "Hello Driver Loaded\n");

    This prints a message inside the kernel log

    • printk → Kernel version of printf
    • KERN_INFO → Log level (informational message)

    Where to see output?

    dmesg
    

    Example output:

    Hello Driver Loaded
    

    b) return 0;

    Tells kernel:

    “Driver loaded successfully”

    Full Flow

    1. You run:insmod driver.ko
    2. Kernel calls:hello_init()
    3. Message printed:Hello Driver Loaded
    4. Kernel accepts module (since return = 0)

    What if it fails?

    If you return:

    return -1;
    

    Then:

    • Driver will NOT load
    • Kernel shows error

    Real-World Use of hello_init

    In real drivers, this function is used to:

    • Register device (alloc_chrdev_region)
    • Initialize cdev
    • Create device file (/dev/...)
    • Allocate memory
    • Setup hardware

    static void __exit hello_exit(void) function

    static void __exit hello_exit(void) {
        printk(KERN_INFO "Driver Removed\n");
    }
    

    What is this function?

    This function runs when you remove/unload the driver:

    rmmod driver
    

    So:

    hello_init() = when driver loads
    hello_exit() = when driver unloads

    Line-by-Line Explanation

    1. static

    Meaning:

    • Function is only visible inside this file

    Prevents conflicts with other kernel code

    2. void

    Meaning:

    • Function does not return anything

    Unlike init, kernel doesn’t expect success/failure here
    (you must clean up properly no matter what)

    3. __exit

    What it is:

    A kernel macro similar to __init

    What it does:

    • Marks function as exit/cleanup code
    • Used only when module is removed
    • If driver is built into kernel (not module) → this code is ignored

    Important:

    If built-in:

    Exit function may never run

    4. hello_exit

    Function name (can be anything)

    Convention:

    drivername_exit

    5. (void)

    No parameters

    6. Function Body

    printk(KERN_INFO "Driver Removed\n");

    Prints message to kernel log

    Check using:

    dmesg

    Output:

    Driver Removed

    Full Flow

    1. You run:rmmod driver
    2. Kernel calls:hello_exit()
    3. Cleanup happens
    4. Message printed:Driver Removed

    Real-World Importance

    In real drivers, this function is critical

    You must clean everything you created in init():

    Example Cleanup Tasks:

    device_destroy(...)
    class_destroy(...)
    cdev_del(...)
    unregister_chrdev_region(...)
    kfree(...)
    

    If you don’t clean properly:

    • Memory leaks
    • Device conflicts
    • Kernel crash (serious bug)

    Analogy

    Think of it like:

    “Shutdown procedure of your driver”

    If you turned ON things in init(),
    you MUST turn them OFF here.

    How It Connects

    You register it using:

    module_exit(hello_exit);
    

    This tells kernel:

    “Call this function when module is removed”

    Pro Tip (Interview Level)

    Always say:

    “Whatever is allocated in init must be freed in exit”

    What is a Device File in Linux?

    In Linux, everything is a file.

    Your driver becomes usable through:

    /dev/my_device

    This is called a device file in Linux.

    Core Components of a Linux Character Driver

    Now we move into real Linux driver development for beginners.

    Key parts:

    • dev_t → device number
    • cdev → character device structure
    • file_operations → driver functions

    File Operations Structure (Very Important)

    This is the heart of your driver.

    struct file_operations fops = {
        .open = my_open,
        .read = my_read,
        .write = my_write,
        .release = my_close,
    };
    

    This connects user-space calls to kernel functions.

    What is struct file_operations?

    It is a structure of function pointers defined by the kernel.

    It tells the kernel:
    “When a user performs a file operation, call these functions.”

    Big Picture

    When user runs:

    fd = open("/dev/my_device", O_RDWR);
    write(fd, "Hi", 2);
    read(fd, buf, 2);
    close(fd);
    

    Kernel maps them like this:

    User CallDriver Function
    open()my_open()
    read()my_read()
    write()my_write()
    close()my_close()

    Line-by-Line Breakdown

    struct file_operations fops

    Declares a variable fops of type file_operations

    This structure is defined in:

    #include <linux/fs.h>
    

    .open = my_open

    When user calls open() → kernel calls:

    my_open()
    

    Typical use:

    • Initialize device
    • Allocate resources
    • Check permissions

    .read = my_read

    When user calls read() → kernel calls:

    my_read()
    

    Typical use:

    • Send data from kernel → user
    • Use copy_to_user()

    .write = my_write

    When user calls write() → kernel calls:

    my_write()
    

    Typical use:

    • Receive data from user → kernel
    • Use copy_from_user()

    .release = my_close

    Called when user runs close()

    my_close()
    

    Note:

    • release = close (kernel naming)

    How It Works Internally

    1. You register your driver (cdev_add)
    2. Kernel stores pointer to fops
    3. When user performs operations:
      • Kernel looks into fops
      • Calls the corresponding function

    Example Function Prototypes

    int my_open(struct inode *inode, struct file *file);
    
    ssize_t my_read(struct file *file, char __user *buf, size_t len, loff_t *offset);
    
    ssize_t my_write(struct file *file, const char __user *buf, size_t len, loff_t *offset);
    
    int my_close(struct inode *inode, struct file *file);
    

    Simple Analogy

    Think of file_operations like:

    📞 A contact list for the kernel

    • open → call this number
    • read → call this number
    • write → call this number

    Important Notes

    You don’t need to implement all functions

    Example:

    struct file_operations fops = {
        .read = my_read,
    };
    

    Only read is supported

    If function is missing

    • Kernel may return error (-ENOSYS)
    • Operation fails

    Must Register This

    cdev_init(&my_cdev, &fops);
    

    This connects your driver with fops

    Real Driver Flow

    User → open() → my_open()
    User → write() → my_write()
    User → read() → my_read()
    User → close() → my_close()

    Full Linux Character Driver Example

    Now let’s build a complete character driver example in Linux.

    #include <linux/module.h>
    #include <linux/fs.h>
    #include <linux/cdev.h>
    #include <linux/uaccess.h>
    
    #define DEVICE_NAME "my_char_dev"
    
    static dev_t dev_num;
    static struct cdev my_cdev;
    
    char kernel_buffer[1024];
    
    static int my_open(struct inode *inode, struct file *file) {
        printk("Device Opened\n");
        return 0;
    }
    
    static int my_close(struct inode *inode, struct file *file) {
        printk("Device Closed\n");
        return 0;
    }
    
    static ssize_t my_read(struct file *file, char __user *buf, size_t len, loff_t *off) {
        copy_to_user(buf, kernel_buffer, len);
        return len;
    }
    
    static ssize_t my_write(struct file *file, const char __user *buf, size_t len, loff_t *off) {
        copy_from_user(kernel_buffer, buf, len);
        return len;
    }
    
    static struct file_operations fops = {
        .owner = THIS_MODULE,
        .open = my_open,
        .read = my_read,
        .write = my_write,
        .release = my_close,
    };
    
    static int __init driver_init(void) {
        alloc_chrdev_region(&dev_num, 0, 1, DEVICE_NAME);
        cdev_init(&my_cdev, &fops);
        cdev_add(&my_cdev, dev_num, 1);
    
        printk("Driver Loaded\n");
        return 0;
    }
    
    static void __exit driver_exit(void) {
        cdev_del(&my_cdev);
        unregister_chrdev_region(dev_num, 1);
    
        printk("Driver Unloaded\n");
    }
    
    module_init(driver_init);
    module_exit(driver_exit);
    
    MODULE_LICENSE("GPL");
    

    Create Device File

    sudo mknod /dev/my_char_dev c <major> <minor>
    

    User Space Program

    Now let’s interact with the driver.

    #include <stdio.h>
    #include <fcntl.h>
    #include <unistd.h>
    
    int main() {
        int fd = open("/dev/my_char_dev", O_RDWR);
    
        write(fd, "Hello Driver", 12);
    
        char buf[100];
        read(fd, buf, 12);
    
        printf("Data: %s\n", buf);
    
        close(fd);
        return 0;
    }
    

    How It Works End-to-End

    1. User program calls write()
    2. Kernel calls my_write()
    3. Data stored in kernel buffer
    4. read() fetches it back

    This is a complete Linux device driver examples

    Why Exit Function is Important?

    You asked earlier:

    Why do we need exit function?

    Because kernel modules must clean up resources.

    Without cleanup:

    • Memory leaks
    • Device conflicts
    • System instability

    So always use:

    module_exit(driver_exit);

    Real Production Driver Structure

    In real embedded Linux driver development, drivers are more complex:

    • Use platform_driver
    • Device Tree (DTS)
    • Interrupt handling
    • DMA
    • Hardware registers

    Debugging Linux Drivers

    Essential for real work.

    Use:

    dmesg

    Add logs:

    printk(KERN_INFO "Debug Message\n");

    Advanced:

    • ftrace
    • kgdb

    Common Mistakes Beginners Make

    • Forgetting copy_to_user
    • Not checking return values
    • Memory leaks
    • Wrong device permissions

    Linux Driver Interview Questions

    You’ll definitely face these:

    Q1: What is character driver?

    Ans : Sequential data transfer driver

    Q2: What is file_operations?

    Ans : Structure linking user calls to kernel

    Q3: Difference between user and kernel space?

    Ans : Security and access level separation

    Best Practices

    • Always validate user input
    • Use snprintf instead of sprintf
    • Follow kernel coding style
    • Keep driver modular

    Advanced Topics (Next Step)

    Once you’re comfortable:

    • Interrupt handling
    • Platform drivers + DTS
    • SPI/I2C drivers
    • Kernel synchronization

    Final Thoughts

    Learning a Linux Character Driver is like opening the door to kernel-level programming.

    At first, it feels confusing:

    • Kernel space
    • File operations
    • Device numbers

    But once you build one working driver, everything clicks

    FAQ : Linux Character Driver

    1.What is a Linux Character Driver?

    A Linux Character Driver is a type of device driver that allows communication between user space and hardware devices one byte at a time (stream-based data transfer). These drivers are commonly used for devices like UART, keyboards, GPIO, and sensors.

    2.How does a Linux Character Driver work?

    A Linux Character Driver works through a layered architecture:

    • User application calls open(), read(), write()
    • System calls reach the kernel via VFS (Virtual File System)
    • Kernel invokes driver functions defined in file_operations
    • Driver interacts with hardware

    3.What is file_operations in a character driver?

    file_operations is a structure that maps user-space system calls to driver functions.

    Example:

    • open() → my_open()
    • read() → my_read()
    • write() → my_write()

    It acts as the core interface between user space and kernel space.

    4.What is the difference between Character Driver and Block Driver?

    FeatureCharacter DriverBlock Driver
    Data AccessByte-by-byteBlock (chunks)
    ExampleUART, GPIOHard Disk
    BufferingMinimalUses cache
    Access TypeSequentialRandom

    5.What are major and minor numbers?

    • Major Number → Identifies the driver
    • Minor Number → Identifies the device instance

    These numbers help the kernel route operations to the correct driver.

    6.What is /dev in Linux Character Drivers?

    /dev is a directory where device files are created.

    Example:

    /dev/my_device
    

    This file acts as the entry point for user applications to interact with the driver.

    7.What is printk() in Linux drivers?

    printk() is used for kernel-level logging, similar to printf() in user space.

    Example:

    printk(KERN_INFO "Driver Loaded\n");
    

    You can view logs using:

    dmesg
    

    8.What is __init and __exit in Linux drivers?

    • __init → Marks initialization function (freed after loading)
    • __exit → Marks cleanup function (used during module removal)

    These help optimize memory usage in the kernel.

    9.How do you load and unload a character driver?

    Load driver:

    sudo insmod driver.ko
    

    Unload driver:

    sudo rmmod driver
    

    Check logs:

    dmesg
    

    10.What is a kernel module in Linux?

    A kernel module is a piece of code that can be loaded/unloaded into the kernel dynamically. A Linux Character Driver is typically implemented as a kernel module.

    11.Where are Linux Character Drivers used?

    They are used in real-world scenarios like:

    • UART communication
    • GPIO control
    • Sensor interfacing
    • Embedded systems
    • Serial devices

    12.Do I need hardware to learn character drivers?

    No. You can start with a virtual character driver (dummy driver) and simulate read/write operations without real hardware.

    13.What are common mistakes beginners make?

    • Forgetting cleanup in __exit
    • Not handling copy_to_user() properly
    • Incorrect major/minor number handling
    • Missing error checks in init function

    14.Is Linux Character Driver development hard?

    Initially, it may feel complex, but with step-by-step practice:

    • Start with a simple module
    • Learn file_operations
    • Build a dummy driver

    It becomes much easier over time.

    15.What is the difference between read() and write() in drivers?

    • read() → Kernel → User space (sending data)
    • write() → User space → Kernel (receiving data)

    16.Can I build a production-level driver with character drivers?

    Yes. Many real-world drivers (UART, I2C user interfaces, debug interfaces) are built using character drivers.

    For detailed understanding of Platform Devices and Drivers on Linux, refer to the official Linux documentation on Platform Devices and Drivers .

  • Master How to Write Platform Devices and Drivers (2026)

    Learn how to write Platform Devices and Drivers from scratch using Device Tree, I2C, interrupts, and testing, explained clearly for beginners.

    If you are stepping into Linux device driver development, sooner or later you will hear one phrase again and again: Platform Devices and Drivers.
    They sound complex at first, but once you understand the flow, they are actually one of the cleanest and most structured ways to write Linux drivers for embedded systems.

    In this article, we will go from zero to a working platform driver.
    We will start with the basic idea, then move step by step through implementation, device tree integration, I2C communication, interrupt handling, and finally testing and debugging.

    What Is Platform Devices and Drivers?

    Platform Devices and Drivers are a Linux kernel mechanism used to describe and manage on-board hardware that is not discoverable dynamically.

    Unlike USB or PCI devices, platform devices do not announce themselves.
    They are usually fixed on the board, soldered directly to the SoC or connected via internal buses like I2C or SPI.

    Examples include:

    • GPIO controllers
    • I2C sensors
    • RTC chips
    • Watchdog timers
    • Custom hardware blocks

    Linux needs a way to:

    1. Describe this hardware
    2. Match it with the correct driver
    3. Initialize it safely during boot

    That is exactly what platform devices and drivers do.

    Why Platform Devices and Drivers Matter in Embedded Linux

    If you work with embedded boards, you will almost always use Platform Devices and Drivers because:

    • Hardware is board-specific
    • There is no auto-detection
    • Device Tree is used to describe hardware
    • Drivers must bind cleanly during boot

    This model separates hardware description (Device Tree) from driver logic (kernel module), which makes systems easier to maintain and port.

    High-Level Architecture

    Before writing any code, let’s understand the flow:

    1. You buy an I2C chip (for example, a temperature sensor)
    2. You connect it to your board
    3. You describe it in the Device Tree
    4. Linux creates a platform device
    5. Your platform driver registers itself
    6. Kernel matches device and driver
    7. probe() function runs
    8. Driver initializes hardware
    9. Device becomes usable from user space

    Once you understand this flow, everything else fits naturally.

    From Purchase to Product: Real-World Scenario

    Let’s make this real.

    Imagine you purchased an I2C temperature sensor that:

    • Works over I2C
    • Has an interrupt pin
    • Is connected to your SoC

    Your goal:

    • Write a Linux driver
    • Handle I2C communication
    • Handle interrupts
    • Expose data to user space

    We will build this using Platform Devices and Drivers.

    Step 1: Understand the Hardware

    Before touching the kernel:

    • Read the datasheet
    • Note the I2C address
    • Register map
    • Interrupt behavior
    • Voltage levels

    Example details:

    • I2C address: 0x48
    • Interrupt active low
    • Data register at 0x00

    Never skip this step. Drivers written without understanding hardware always fail.

    Step 2: Device Tree Basics

    In modern Linux, Device Tree describes platform devices.

    The Device Tree tells the kernel:

    • Where the device is
    • How it is connected
    • What driver should bind to it

    Example Device Tree Node

    i2c1 {
        status = "okay";
    
        temp_sensor@48 {
            compatible = "vendor,temp-sensor";
            reg = <0x48>;
            interrupt-parent = <&gpio1>;
            interrupts = <12 IRQ_TYPE_EDGE_FALLING>;
        };
    };
    

    Important properties:

    • compatible → used for driver matching
    • reg → I2C address
    • interrupts → interrupt configuration

    This node becomes a platform device internally.

    Step 3: Platform Driver Structure

    A platform driver is a kernel module that registers itself using platform_driver.

    Basic Skeleton

    static int temp_probe(struct platform_device *pdev)
    {
        return 0;
    }
    
    static int temp_remove(struct platform_device *pdev)
    {
        return 0;
    }
    
    static const struct of_device_id temp_of_match[] = {
        { .compatible = "vendor,temp-sensor" },
        { }
    };
    MODULE_DEVICE_TABLE(of, temp_of_match);
    
    static struct platform_driver temp_driver = {
        .probe = temp_probe,
        .remove = temp_remove,
        .driver = {
            .name = "temp_sensor",
            .of_match_table = temp_of_match,
        },
    };
    
    module_platform_driver(temp_driver);
    

    This is the heart of Platform Devices and Drivers.

    Step 4: Driver and Device Matching

    Matching happens using the compatible string.

    • Device Tree provides compatible = "vendor,temp-sensor"
    • Driver declares the same string
    • Kernel binds them automatically

    If probe() is not called:

    • Check compatible string
    • Check Device Tree compilation
    • Check kernel logs

    Step 5: Accessing Device Tree Data

    Inside probe(), you can read properties from Device Tree.

    struct device *dev = &pdev->dev;
    struct device_node *np = dev->of_node;
    

    This lets you:

    • Read GPIO numbers
    • Read custom properties
    • Configure behavior per board

    This is why platform drivers are flexible.

    Step 6: Integrating I2C in Platform Drivers

    Many beginners get confused here.

    Yes, the device is on I2C, but the binding still happens via platform devices when using Device Tree.

    You usually:

    • Get the I2C adapter
    • Create an I2C client
    • Communicate using I2C APIs

    Example

    struct i2c_client *client;
    
    client = i2c_new_dummy_device(adapter, 0x48);
    

    Now you can read registers:

    i2c_smbus_read_byte_data(client, 0x00);
    

    This approach keeps hardware description separate from communication logic.

    Step 7: Interrupt Handling

    Interrupts are critical for real devices.

    Get IRQ Number

    int irq = platform_get_irq(pdev, 0);
    

    Register Interrupt Handler

    request_irq(irq, temp_irq_handler,
                IRQF_TRIGGER_FALLING,
                "temp_irq", dev);
    

    Interrupt Handler

    static irqreturn_t temp_irq_handler(int irq, void *dev_id)
    {
        // Read status register
        return IRQ_HANDLED;
    }
    

    Always keep interrupt handlers short and fast.

    Step 8: Exposing Data to User Space

    A driver is useless if user space cannot talk to it.

    Common approaches:

    • sysfs
    • character device
    • IIO subsystem (for sensors)

    Simple sysfs Example

    static ssize_t temp_show(struct device *dev,
                             struct device_attribute *attr,
                             char *buf)
    {
        return sprintf(buf, "25\n");
    }
    
    DEVICE_ATTR_RO(temp);
    

    This creates:

    /sys/devices/.../temp
    

    Step 9: Error Handling and Cleanup

    Good platform drivers always clean up.

    In remove():

    • Free IRQ
    • Unregister I2C client
    • Free memory
    free_irq(irq, dev);
    

    Never assume probe() always succeeds.

    Step 10: Building and Testing

    Compile the Driver

    • Add to kernel tree or as module
    • Enable in menuconfig

    Load Module

    insmod temp_driver.ko
    

    Check Logs

    dmesg | grep temp
    

    Verify Device Tree

    ls /proc/device-tree
    

    Testing is where most learning happens.

    Common Mistakes Beginners Make

    • Wrong compatible string
    • Forgetting to enable I2C bus
    • Interrupt polarity mismatch
    • Blocking code in IRQ handler
    • Ignoring return values

    Every one of these will cost you hours if you ignore basics.

    How to Write Platform Devices and Drivers

    // SPDX-License-Identifier: GPL-2.0
    /*
     * Production-ready Platform Driver example
     * - Device Tree based
     * - I2C sensor
     * - Interrupt handling
     * - sysfs interface
     */
    
    #include <linux/module.h>
    #include <linux/kernel.h>
    #include <linux/platform_device.h>
    #include <linux/of.h>
    #include <linux/of_irq.h>
    #include <linux/i2c.h>
    #include <linux/interrupt.h>
    #include <linux/slab.h>
    #include <linux/mutex.h>
    #include <linux/pm.h>
    #include <linux/sysfs.h>
    
    /* ---------- Driver Private Data ---------- */
    struct temp_dev {
    	struct device       *dev;
    	struct i2c_client   *client;
    	int                  irq;
    	int                  temperature;
    	struct mutex         lock;
    };
    
    /* ---------- I2C Read Helper ---------- */
    static int temp_sensor_read(struct temp_dev *tdev)
    {
    	int ret;
    
    	ret = i2c_smbus_read_byte_data(tdev->client, 0x00);
    	if (ret < 0)
    		dev_err(tdev->dev, "I2C read failed\n");
    
    	return ret;
    }
    
    /* ---------- Interrupt Handler ---------- */
    static irqreturn_t temp_irq_handler(int irq, void *data)
    {
    	struct temp_dev *tdev = data;
    	int temp;
    
    	mutex_lock(&tdev->lock);
    
    	temp = temp_sensor_read(tdev);
    	if (temp >= 0)
    		tdev->temperature = temp;
    
    	mutex_unlock(&tdev->lock);
    
    	dev_info(tdev->dev, "Interrupt: temperature=%d\n",
    		 tdev->temperature);
    
    	return IRQ_HANDLED;
    }
    
    /* ---------- sysfs Interface ---------- */
    static ssize_t temperature_show(struct device *dev,
    				struct device_attribute *attr,
    				char *buf)
    {
    	struct temp_dev *tdev = dev_get_drvdata(dev);
    	int temp;
    
    	mutex_lock(&tdev->lock);
    	temp = tdev->temperature;
    	mutex_unlock(&tdev->lock);
    
    	return sysfs_emit(buf, "%d\n", temp);
    }
    
    static DEVICE_ATTR_RO(temperature);
    
    static struct attribute *temp_attrs[] = {
    	&dev_attr_temperature.attr,
    	NULL,
    };
    
    static const struct attribute_group temp_attr_group = {
    	.attrs = temp_attrs,
    };
    
    /* ---------- Probe Function ---------- */
    static int temp_probe(struct platform_device *pdev)
    {
    	struct temp_dev *tdev;
    	struct i2c_adapter *adapter;
    	struct device *dev = &pdev->dev;
    	int ret;
    
    	dev_info(dev, "Probing temperature sensor\n");
    
    	tdev = devm_kzalloc(dev, sizeof(*tdev), GFP_KERNEL);
    	if (!tdev)
    		return -ENOMEM;
    
    	tdev->dev = dev;
    	mutex_init(&tdev->lock);
    	platform_set_drvdata(pdev, tdev);
    
    	/* Get I2C adapter (from DT bus number) */
    	adapter = i2c_get_adapter(1);
    	if (!adapter) {
    		dev_err(dev, "Failed to get I2C adapter\n");
    		return -ENODEV;
    	}
    
    	/* Create I2C client */
    	tdev->client = i2c_new_dummy_device(adapter, 0x48);
    	i2c_put_adapter(adapter);
    
    	if (IS_ERR(tdev->client)) {
    		dev_err(dev, "Failed to create I2C client\n");
    		return PTR_ERR(tdev->client);
    	}
    
    	/* Read initial value */
    	ret = temp_sensor_read(tdev);
    	if (ret >= 0)
    		tdev->temperature = ret;
    
    	/* Get IRQ from Device Tree */
    	tdev->irq = platform_get_irq(pdev, 0);
    	if (tdev->irq < 0) {
    		dev_err(dev, "Failed to get IRQ\n");
    		return tdev->irq;
    	}
    
    	ret = devm_request_irq(dev,
    			       tdev->irq,
    			       temp_irq_handler,
    			       IRQF_TRIGGER_FALLING,
    			       dev_name(dev),
    			       tdev);
    	if (ret) {
    		dev_err(dev, "Failed to request IRQ\n");
    		return ret;
    	}
    
    	/* Create sysfs group */
    	ret = sysfs_create_group(&dev->kobj, &temp_attr_group);
    	if (ret) {
    		dev_err(dev, "Failed to create sysfs group\n");
    		return ret;
    	}
    
    	dev_info(dev, "Temperature sensor driver loaded\n");
    	return 0;
    }
    
    /* ---------- Remove Function ---------- */
    static int temp_remove(struct platform_device *pdev)
    {
    	struct temp_dev *tdev = platform_get_drvdata(pdev);
    
    	sysfs_remove_group(&pdev->dev.kobj, &temp_attr_group);
    
    	if (tdev->client)
    		i2c_unregister_device(tdev->client);
    
    	dev_info(&pdev->dev, "Temperature sensor removed\n");
    	return 0;
    }
    
    /* ---------- Power Management ---------- */
    #ifdef CONFIG_PM_SLEEP
    static int temp_suspend(struct device *dev)
    {
    	dev_info(dev, "Suspending temperature sensor\n");
    	return 0;
    }
    
    static int temp_resume(struct device *dev)
    {
    	dev_info(dev, "Resuming temperature sensor\n");
    	return 0;
    }
    #endif
    
    static SIMPLE_DEV_PM_OPS(temp_pm_ops,
    			 temp_suspend,
    			 temp_resume);
    
    /* ---------- Device Tree Match ---------- */
    static const struct of_device_id temp_of_match[] = {
    	{ .compatible = "demo,temp-sensor" },
    	{ }
    };
    MODULE_DEVICE_TABLE(of, temp_of_match);
    
    /* ---------- Platform Driver ---------- */
    static struct platform_driver temp_driver = {
    	.probe  = temp_probe,
    	.remove = temp_remove,
    	.driver = {
    		.name           = "temp_sensor",
    		.of_match_table = temp_of_match,
    		.pm             = &temp_pm_ops,
    	},
    };
    
    module_platform_driver(temp_driver);
    
    MODULE_LICENSE("GPL");
    MODULE_AUTHOR("Nishant Singh");
    MODULE_DESCRIPTION("Production-ready Platform Driver with I2C and Interrupt");
    

    Device Tree

    &i2c1 {
    	status = "okay";
    
    	temp_sensor@48 {
    		compatible = "demo,temp-sensor";
    		reg = <0x48>;
    		interrupt-parent = <&gpio1>;
    		interrupts = <12 IRQ_TYPE_EDGE_FALLING>;
    	};
    };
    

    User Space Test

    cat /sys/devices/platform/temp_sensor/temperature
    

    Why Platform Devices and Drivers Scale Well

    Once you master Platform Devices and Drivers, you can:

    • Port drivers across boards
    • Reuse Device Tree files
    • Support multiple variants
    • Keep drivers clean and readable

    This is why the Linux kernel strongly encourages this model.

    FAQs : Platform Devices and Drivers.

    1. What are Platform Devices and Drivers in Linux?

    Platform Devices and Drivers are a Linux kernel mechanism used for non-discoverable hardware. These are devices that are permanently attached to the board, like I2C sensors, GPIO controllers, RTCs, and on-chip peripherals. Since such hardware cannot announce itself, Linux relies on the Device Tree to describe it and platform drivers to manage it.

    2. Why do we need Platform Drivers when using Device Tree?

    Device Tree only describes hardware.
    Platform drivers contain the actual code that talks to the hardware. The kernel uses the compatible string in the Device Tree to match a platform device with the correct platform driver and then calls the driver’s probe() function.

    3. What is the role of the probe() function?

    The probe() function is where everything starts. It is called when the kernel successfully matches a platform device with its driver. In probe(), you:

    • Allocate memory
    • Read Device Tree properties
    • Initialize hardware
    • Register interrupts
    • Create sysfs or character devices

    If probe() fails, the device will not work.

    4. How does Device Tree match a Platform Driver?

    Matching is done using the compatible string.
    The Device Tree node provides a compatible property, and the platform driver provides an of_device_id table with the same string. If they match exactly, the kernel binds them together.

    5. Can Platform Drivers be used for I2C or SPI devices?

    Yes. This is very common.
    Even though the device communicates over I2C or SPI, the binding still happens through Platform Devices and Drivers when using Device Tree. Inside the platform driver, you create or access an I2C or SPI client to communicate with the hardware.

    6. What is the difference between a Platform Driver and an I2C Driver?

    An I2C driver is tied directly to the I2C subsystem and is usually auto-created by the I2C core.
    A Platform Driver is more generic and is often used when:

    • You need board-specific logic
    • The device uses multiple resources (IRQ, GPIO, regulators)
    • You want tighter control over initialization

    Both approaches are valid and used in production.

    7. How are interrupts handled in Platform Drivers?

    Interrupts are described in the Device Tree using the interrupts property.
    Inside the driver, you retrieve the IRQ number using platform_get_irq() and register a handler using request_irq() or devm_request_irq(). The interrupt handler should be fast and should avoid sleeping or heavy processing.

    8. What is devm_* and why should it be used?

    devm_* APIs automatically free resources when the device is removed.
    They reduce memory leaks and simplify error handling. In production drivers, devm_kzalloc(), devm_request_irq(), and similar APIs are strongly recommended.

    9. How do Platform Drivers expose data to user space?

    Common methods include:

    • sysfs attributes
    • character devices
    • standard kernel subsystems like IIO, input, or hwmon

    For simple data like sensor readings, sysfs is often enough. For high-performance or streaming data, character devices or IIO are better choices.

    10. What are the most common reasons probe() is not called?

    The most common reasons are:

    • Mismatch in compatible string
    • Device Tree node not compiled or loaded
    • Driver not enabled in kernel configuration
    • Incorrect Device Tree hierarchy (wrong bus node)

    Checking dmesg usually points you in the right direction.

    11. Are Platform Drivers used in real production kernels?

    Absolutely.
    Most SoC drivers, board-level drivers, and embedded peripherals in the Linux kernel are implemented using Platform Devices and Drivers. This model scales well and is heavily used by vendors and upstream kernel developers.

    12. When should I avoid using Platform Devices and Drivers?

    You should avoid platform drivers if:

    • The hardware is self-discoverable (USB, PCI)
    • The kernel already provides a dedicated subsystem driver
    • You are writing a pure user-space driver

    In those cases, platform drivers would add unnecessary complexity.

    You can also read : Linked List Coding Questions

  • Master Char Driver Model in Linux (2026): Architecture, Flow & Real Examples

    Learn the Char Driver Model in Linux with a clear, beginner-friendly explanation. Understand structure, flow, key APIs, and real interview-focused concepts step by step.

    The Char Driver Model is one of the most important building blocks in Linux device driver development. It defines how hardware devices that transfer data as a stream of bytes are exposed to user space and controlled through standard system calls. If you want to understand how Linux talks to real hardware, this is where the journey truly begins.

    The article starts by clearly explaining what character drivers are and why they are widely used in Linux systems, especially in embedded, automotive, and custom hardware platforms. You will understand how synchronous drivers work, why blocking behavior exists, and how the kernel efficiently puts processes to sleep instead of wasting CPU cycles.

    We then walk through driver registration and de-registration, explaining how major and minor numbers connect device files in /dev to the correct kernel driver. You will learn how Linux knows which driver should handle a read or write request and why proper cleanup during driver removal is critical for system stability.

    The guide dives deep into the driver file interface, showing how character devices integrate with the Virtual File System. Each device file operation such as open, read, write, release, ioctl, poll, and mmap is explained in plain language with real-world meaning, not just definitions.

    Special focus is given to driver data structures, helping you understand how drivers manage internal state, handle multiple devices, and support multiple processes safely. You will also learn how device configuration operations using ioctl allow flexible control of hardware without breaking user space compatibility.

    Advanced but essential topics like wait queues and polling are covered with clarity, explaining how Linux handles blocking and non-blocking I/O, event-driven applications, and efficient synchronization. The section on memory mapping explains how high-performance drivers avoid unnecessary data copying and safely expose device memory to user space.

    To prepare you for real-world interviews, the guide also aligns closely with Round 1 and Round 2 interview expectations, helping you understand not just what the Char Driver Model is, but how and why it is designed this way.

    By the end of this article, you will have a strong, practical understanding of the Char Driver Model, making you confident in Linux driver interviews, embedded system projects, and kernel-level development work.

    Introduction: Why the Char Driver Model Still Matters

    If you are learning Linux device drivers, the Char Driver Model is not optional knowledge. It is the foundation. Almost every serious kernel developer starts here, because character drivers teach you how the kernel and user space talk to each other.

    Whether you are working on:

    • Embedded Linux
    • Automotive platforms
    • BSP development
    • Custom hardware bring-up

    You will meet character drivers early and often.

    A char driver handles devices that:

    • Transfer data as a stream of bytes
    • Do not use fixed block sizes
    • Often require synchronous or event-driven access

    Examples include:

    • Serial ports
    • GPIO drivers
    • I2C and SPI devices
    • Sensors
    • Custom hardware peripherals

    Understanding the Char Driver Model means understanding how Linux exposes hardware safely, cleanly, and efficiently to user space.

    What Is the Char Driver Model?

    At its core, the Char Driver Model defines how a character device is:

    • Registered with the kernel
    • Exposed to user space as a device file
    • Accessed using standard system calls like open, read, write, and ioctl

    Unlike block drivers (used for disks) or network drivers (used for packets), a char driver:

    • Reads and writes bytes
    • Works sequentially
    • Often operates synchronously

    This makes char drivers simpler to understand and perfect for learning Linux driver architecture.

    Synchronous Drivers Defined

    Let’s clarify something early because this topic confuses beginners.

    What does “synchronous driver” mean?

    A synchronous driver blocks the calling process until an operation completes.

    Example:

    • A user calls read()
    • The driver waits until data is available
    • The process sleeps
    • Data arrives
    • The process wakes up
    • read() returns

    This behavior is extremely common in char drivers.

    Why synchronous behavior matters

    Synchronous drivers:

    • Are easier to reason about
    • Avoid race conditions when designed correctly
    • Match how real hardware behaves

    Linux also supports non-blocking and asynchronous I/O, but the Char Driver Model is built around synchronous behavior first, then extended using:

    • Wait queues
    • Polling
    • Select
    • Async notifications

    We will cover those later.

    Char Driver Model Architecture Overview

    Let’s zoom out and look at the big picture.

    User space talks to a char driver through:

    • /dev device files
    • Standard POSIX system calls

    The kernel connects everything using:

    • Major and minor numbers
    • File operations
    • Internal driver data structures

    The flow looks like this:

    1. Application opens /dev/mydevice
    2. Kernel maps it to a registered char driver
    3. Kernel calls driver callbacks
    4. Driver talks to hardware
    5. Data flows back to user space

    Simple concept. Powerful mechanism.

    Driver Registration and De-registration

    This is where every char driver begins and ends.

    Why registration exists

    Linux needs to know:

    • Which driver owns which device
    • How to route file operations to the correct code

    This is done through driver registration.

    Registering a Char Driver

    The kernel identifies char drivers using:

    • Major number: identifies the driver
    • Minor number: identifies devices handled by that driver

    There are two common approaches:

    Static major number

    You pick a number yourself (not recommended anymore).

    Dynamic major number

    The kernel assigns one for you.

    Modern drivers always use dynamic registration.

    Typical steps:

    1. Allocate device numbers
    2. Initialize character device structure
    3. Add the device to the kernel

    This is where the Char Driver Model starts to feel real.

    Driver De-registration

    When a driver is removed:

    • Device numbers must be freed
    • Kernel objects must be cleaned
    • Memory must be released

    Failing to de-register properly leads to:

    • Kernel crashes
    • Memory leaks
    • Broken /dev nodes

    Clean de-registration is a sign of a professional driver.

    Driver File Interface

    The driver file interface is how Linux makes your hardware look like a file.

    That is not a metaphor. It is literal.

    Everything in Linux is a file, including:

    • Sensors
    • LEDs
    • UARTs
    • Custom ASICs

    The Char Driver Model plugs into the VFS (Virtual File System) layer.

    The Role of /dev

    When you create a device file like:

    /dev/my_char_device
    

    Linux connects:

    • User space file operations
    • To your driver callbacks

    That connection happens through the file operations structure.

    Device File Operations

    This is the heart of the Char Driver Model.

    What are device file operations?

    They are function pointers that define how your driver responds to:

    • open()
    • read()
    • write()
    • close()
    • ioctl()
    • poll()
    • mmap()

    When a user calls read(), the kernel does not read hardware itself.
    It calls your function.

    Common file operations explained

    open

    Called when a process opens the device file.

    Used to:

    • Initialize private data
    • Allocate resources
    • Check permissions

    read

    Transfers data from kernel space to user space.

    Key responsibilities:

    • Copy data safely
    • Handle blocking behavior
    • Respect file position

    write

    Transfers data from user space to kernel space.

    Used for:

    • Sending commands
    • Writing configuration
    • Controlling hardware behavior

    release (close)

    Called when the file descriptor is closed.

    Used to:

    • Free resources
    • Decrement usage counters

    ioctl: Device configuration ops

    This deserves its own section.

    Device Configuration Ops (ioctl)

    Not all device control fits into read and write.

    That is why device configuration ops exist.

    The ioctl() system call allows:

    • Sending control commands
    • Passing structured data
    • Changing device modes

    Examples:

    • Set baud rate
    • Enable interrupts
    • Switch operating modes
    • Query device status

    In the Char Driver Model, ioctl is how drivers stay flexible without breaking APIs.

    Why ioctl must be designed carefully

    Bad ioctl design causes:

    • ABI breakage
    • Security issues
    • Maintenance nightmares

    Good ioctl design:

    • Uses versioned commands
    • Validates input
    • Copies data safely

    Driver Data Structures

    Behind every clean driver is a solid data model.

    Why driver data structures matter

    Drivers need to store:

    • Device state
    • Hardware configuration
    • Buffers
    • Synchronization primitives

    This data must:

    • Be private to the driver
    • Be safe in concurrent access
    • Scale across multiple devices

    Common driver data structures

    Most char drivers use:

    • A per-device structure
    • A pointer stored in file->private_data

    This allows:

    • Multiple processes
    • Multiple devices
    • Clean separation of state

    Good data structure design makes the rest of the driver simpler.

    Wait Queues and Polling

    Now we get into real-world behavior.

    Why wait queues exist

    Hardware is slow. CPUs are fast.

    Instead of busy-waiting, Linux uses wait queues.

    When a process needs data:

    • It sleeps
    • The driver puts it on a wait queue
    • Hardware interrupt occurs
    • Driver wakes the process

    This is efficient and scalable.

    Blocking vs non-blocking I/O

    Blocking:

    • read() waits until data is ready

    Non-blocking:

    • read() returns immediately
    • Application retries later

    The Char Driver Model supports both.

    Polling and select

    Applications often want to wait on:

    • Multiple devices
    • Timers
    • Sockets

    The poll() and select() interfaces allow this.

    Your driver must:

    • Implement a poll callback
    • Report readiness correctly

    This is essential for:

    • Event-driven applications
    • GUI programs
    • Embedded control loops

    Memory Mapping

    This is where char drivers become powerful.

    What is memory mapping?

    Memory mapping allows:

    • User space to access device memory directly
    • Zero-copy data transfer
    • High performance I/O

    Instead of copying data, the kernel maps memory into user space.

    When memory mapping is useful

    Common use cases:

    • Frame buffers
    • ADC buffers
    • DMA memory
    • High-speed sensors

    The Char Driver Model supports memory mapping using mmap().

    Safety considerations

    Memory mapping must:

    • Restrict access properly
    • Prevent kernel memory leaks
    • Validate ranges

    Done correctly, it is fast and safe.

    Done poorly, it crashes systems.

    How All Pieces Fit Together

    Let’s connect everything.

    A typical char driver:

    • Registers itself with the kernel
    • Creates a device file
    • Implements file operations
    • Manages driver data structures
    • Handles synchronous access
    • Uses wait queues for blocking I/O
    • Supports polling for event-driven apps
    • Exposes configuration via ioctl
    • Optionally supports memory mapping

    This is the Char Driver Model in action.

    Common Mistakes Beginners Make

    Let’s be honest.

    Most first drivers fail because of:

    • Poor synchronization
    • Missing error handling
    • Incorrect user memory access
    • Forgetting de-registration
    • Unsafe ioctl implementations

    Avoiding these mistakes puts you ahead of 80 percent of beginners.

    Why the Char Driver Model Is Still Relevant in 2026

    Despite newer frameworks:

    • Char drivers remain the backbone
    • Many subsystems still rely on them
    • Embedded Linux depends heavily on char devices

    If you want to:

    • Write custom drivers
    • Understand kernel internals
    • Debug low-level issues

    You must master the Char Driver Model.

    Char Driver Model Interview Questions and Answers

    ROUND 1: Basics & Conceptual Questions

    1. What is a character driver in Linux?

    A character driver is a Linux device driver that transfers data as a stream of bytes. It does not use fixed-size blocks like disk drivers. User space interacts with it using standard system calls like open, read, write, and ioctl through a device file in /dev.

    2. What is the Char Driver Model?

    The Char Driver Model defines how a character device is registered with the kernel, how it is exposed to user space, and how file operations from applications are handled inside the driver.

    3. What are some real examples of character devices?

    Serial ports, GPIO drivers, I2C devices, SPI devices, sensors, LEDs, RTCs, and many embedded peripherals are implemented as character drivers.

    4. What is meant by synchronous drivers?

    Synchronous drivers block the calling process until the requested operation completes. For example, a read call waits until data is available instead of returning immediately.

    5. What is a device file?

    A device file is a special file created in /dev that represents a hardware device. It acts as the connection point between user space and the kernel driver.

    6. What is a major number?

    The major number identifies the driver in the kernel. When a device file is accessed, the kernel uses the major number to find which driver should handle the request.

    7. What is a minor number?

    The minor number identifies a specific device instance handled by the same driver. One driver can manage multiple devices using different minor numbers.

    8. How does user space talk to a char driver?

    Through system calls like open, read, write, close, ioctl, poll, and mmap on the device file.

    9. What is driver registration?

    Driver registration is the process where a character driver informs the kernel about its existence, the device numbers it handles, and the file operations it supports.

    10. Why is driver de-registration important?

    If a driver is not properly de-registered, it can leave dangling references, memory leaks, or crash the kernel when the module is removed.

    11. What is the file operations structure?

    It is a structure that contains function pointers to driver callbacks like open, read, write, release, ioctl, poll, and mmap. The kernel calls these functions when user space performs file operations.

    12. What happens when an application calls read()?

    The kernel calls the driver’s read callback, and the driver copies data from kernel space to user space, possibly blocking until data is available.

    13. What is ioctl used for?

    Ioctl is used for device-specific control operations that do not fit into read or write, such as configuring hardware settings or querying device status.

    14. Can multiple processes access a char device?

    Yes, multiple processes can access a char device unless the driver explicitly restricts access using synchronization or open logic.

    15. What is blocking I/O?

    Blocking I/O means the calling process sleeps until the requested operation can be completed, such as waiting for data from hardware.

    ROUND 2: Deep-Dive & Scenario-Based Questions

    16. How does the kernel know which driver handles a device file?

    When a device file is opened, the kernel checks its major number and routes the request to the registered char driver associated with that major number.

    17. What happens internally when open() is called?

    The kernel creates a file structure, links it to the inode, and then calls the driver’s open callback, allowing the driver to initialize device-specific data.

    18. Why do drivers use file->private_data?

    It allows the driver to store per-open or per-device data so that each process has its own context when accessing the device.

    19. What are driver data structures?

    They are internal structures used by the driver to store device state, buffers, configuration, synchronization objects, and hardware-specific information.

    20. How does a driver handle concurrent access?

    Using synchronization mechanisms like mutexes, spinlocks, atomic variables, and wait queues to protect shared data.

    21. What are wait queues?

    Wait queues allow processes to sleep until a specific condition occurs, such as data becoming available or a hardware interrupt firing.

    22. Why are wait queues better than busy waiting?

    Busy waiting wastes CPU cycles. Wait queues put the process to sleep and wake it only when needed, making the system efficient.

    23. How does a driver wake up sleeping processes?

    Usually from an interrupt handler or workqueue using wake-up functions associated with the wait queue.

    24. What is polling in char drivers?

    Polling allows applications to check whether a device is ready for read or write without blocking, commonly used with select or poll system calls.

    25. When should poll() be implemented?

    When your device generates events or data asynchronously and applications need to monitor readiness along with other file descriptors.

    26. What is non-blocking I/O?

    Non-blocking I/O returns immediately if data is not available, instead of putting the process to sleep.

    27. How does a driver support non-blocking read?

    By checking the file flags and returning an error code instead of sleeping if data is not ready.

    28. What is memory mapping in char drivers?

    Memory mapping allows a driver to map kernel or device memory directly into user space so applications can access it without copying.

    29. Why is mmap useful?

    It improves performance for large data transfers like video frames, DMA buffers, or continuous sensor data.

    30. What are risks of memory mapping?

    If not handled carefully, it can expose kernel memory, cause security issues, or crash the system.

    31. What is the role of ioctl in device configuration ops?

    Ioctl allows structured control commands to configure hardware settings that cannot be represented as simple read or write operations.

    32. How do you design safe ioctl commands?

    By validating inputs, checking user memory, using versioned commands, and maintaining backward compatibility.

    33. What happens if a driver forgets to free resources on exit?

    It can cause memory leaks, dangling device nodes, or kernel panics when the module is unloaded.

    34. How does the Char Driver Model support multiple devices?

    By using multiple minor numbers and separate device data structures for each instance.

    35. Why is error handling important in char drivers?

    Because a mistake can crash the entire kernel, not just one application.

    36. What debugging methods are used for char drivers?

    Kernel logs, printk, dynamic debug, ftrace, crash dumps, and careful code review.

    37. What is the difference between char and block drivers?

    Char drivers work with byte streams and sequential access, while block drivers work with fixed-size blocks and random access.

    38. Is Char Driver Model still relevant today?

    Yes. It is widely used in embedded systems, automotive platforms, and custom hardware even in modern Linux kernels.

    39. What does an interviewer expect from a char driver engineer?

    Clear understanding of kernel-user interaction, synchronization, clean resource management, and safe hardware access.

    40. How do you explain Char Driver Model in one line?

    It is the Linux framework that lets hardware behave like a file so applications can interact with it safely and efficiently.

    Final Thoughts

    The Char Driver Model is not just a learning step.
    It is a professional skill.

    Once you understand:

    • Synchronous drivers
    • Driver registration and de-registration
    • Driver file interface
    • Device file operations
    • Driver data structures
    • Device configuration ops
    • Wait queues and polling
    • Memory mapping

    You are no longer “learning drivers.”
    You are writing real Linux drivers.

    FAQ : Char Driver Model in Linux

    1. What is the Char Driver Model in Linux?

    The Char Driver Model is a Linux kernel framework used to handle character devices that transfer data one byte at a time, such as keyboards, sensors, serial ports, and GPIO-based devices.

    2. Why is a character driver called a “char” driver?

    It is called a char driver because it handles data as a stream of characters (bytes) rather than fixed-size blocks like block drivers.

    3. Where is the Char Driver Model used in real systems?

    Char drivers are used in UART devices, I2C sensors, GPIO interfaces, RTCs, touch controllers, and many embedded and automotive Linux systems.

    4. What are the main components of the Char Driver Model?

    The core components are:

    • Major and minor numbers
    • file_operations structure
    • Device file in /dev
    • Kernel module initialization and cleanup functions

    5. What is a major and minor number in a char driver?

    The major number identifies the driver, while the minor number identifies individual devices handled by the same driver.

    6. What is the role of file_operations in a char driver?

    file_operations links user-space system calls like open(), read(), and write() to kernel-space driver functions.

    7. How does user space communicate with a char driver?

    User space communicates through system calls using a device file created in /dev, such as /dev/mydevice.

    8. What is register_chrdev() used for?

    register_chrdev() is used to register a character driver with the kernel and assign it a major number.

    9. What is cdev and why is it important?

    cdev is a kernel structure that represents a character device and connects it to the VFS layer for proper device handling.

    10. How is a device file created for a char driver?

    A device file can be created manually using mknod or automatically using udev with class_create() and device_create().

    11. What is the difference between char driver and block driver?

    Char drivers handle data byte-by-byte, while block drivers manage fixed-size blocks and support random access, such as hard disks.

    12. What happens when open() is called on a char device?

    The kernel invokes the driver’s open() callback, allowing the driver to initialize hardware or allocate resources.

    13. What is ioctl() in the Char Driver Model?

    ioctl() allows custom control commands from user space to the driver, commonly used for configuration and device control.

    14. Are char drivers used in embedded Linux?

    Yes, char drivers are heavily used in embedded Linux for sensors, communication interfaces, and hardware control.

    15. Is learning the Char Driver Model important for interviews?

    Yes, it is a core Linux driver topic and is frequently asked in embedded Linux and kernel developer interviews.

    Read More about Process : What is is Process

    Read More about System Call in Linux : What is System call

    Read More about IPC : What is IPC

  • Exporting Module Symbols in Linux: 5 Powerful Steps to Master It Easily

    Ever wondered how one Linux kernel module can use a function or variable from another module? . Imagine this — you’re working as an embedded Linux engineer, and your team is developing a new audio driver for a smart car infotainment system.

    Your colleague has already written a sound codec driver module that handles the core audio processing. Meanwhile, you’re building a speaker control module that needs to use one of their functions — let’s say set_audio_volume().

    Now, here’s the challenge:
    Your module needs that function, but it’s defined inside another kernel module. You can’t just include a header file like in user-space programs. So, how do you make one kernel module talk to another safely?

    That’s when you discover the magic of Exporting Module Symbols in Linux.

    By simply using EXPORT_SYMBOL(set_audio_volume);, your teammate’s module can “share” that function with your module — just like opening a door between two kernel spaces. Suddenly, your speaker driver can call the function, and your audio stack works perfectly in sync in real time! 🔊🚗

    This simple yet powerful mechanism — exporting module symbols — keeps the Linux kernel modular, flexible, and efficient.That’s where exporting module symbols in Linux comes into play!

    In this guide, we’ll explore what exporting module symbols means, why it’s used, and how you can easily do it — step by step. By the end, you’ll confidently understand how Linux modules share information using exported symbols.

    What Does “Exporting Module Symbols in Linux” Mean?

    In simple terms, exporting module symbols in Linux allows one kernel module to make its functions or variables accessible to other modules.

    Think of it like this:

    • You write a helper function inside one module.
    • Another module needs that function.
    • Instead of rewriting it, you just export it!

    This helps reusability and modularity — key principles of Linux kernel development.

    Why Do We Export Symbols?

    Let’s say you have:

    • A driver module for a hardware component, and
    • A utility module that performs logging or shared operations.

    If both need to share code, exporting symbols is the perfect solution. It’s a common scenario when working with kernel modules in the Linux operating system, where different modules often depend on one another.

    Instead of duplicating the same logic, you can export the symbol once and use it anywhere inside the kernel environment.

    So in short:
    Promotes code reuse
    Makes debugging easier
    Keeps the kernel modular and clean

    How to Export Module Symbols in Linux

    The Linux kernel provides two macros to export symbols:

    • EXPORT_SYMBOL(symbol_name);
    • EXPORT_SYMBOL_GPL(symbol_name);

    The difference?

    • EXPORT_SYMBOL — can be used by any module.
    • EXPORT_SYMBOL_GPL — can be used only by modules with a GPL-compatible license.

    Example: Exporting and Using Symbols

    Let’s understand this with a simple example

    Module 1: my_math.c

    This module defines a function and exports it.

    #include <linux/module.h>
    #include <linux/kernel.h>
    
    int add_numbers(int a, int b) {
        return a + b;
    }
    EXPORT_SYMBOL(add_numbers);  // Exporting the symbol
    
    static int __init my_math_init(void) {
        printk(KERN_INFO "my_math module loaded\n");
        return 0;
    }
    
    static void __exit my_math_exit(void) {
        printk(KERN_INFO "my_math module unloaded\n");
    }
    
    module_init(my_math_init);
    module_exit(my_math_exit);
    
    MODULE_LICENSE("GPL");
    MODULE_AUTHOR("Nish");
    MODULE_DESCRIPTION("Example of Exporting Module Symbols in Linux");
    

    Module 2: use_math.c

    This module imports and uses the exported function.

    #include <linux/module.h>
    #include <linux/kernel.h>
    
    extern int add_numbers(int a, int b);  // Declare the external symbol
    
    static int __init use_math_init(void) {
        int result = add_numbers(4, 5);
        printk(KERN_INFO "Result from exported symbol: %d\n", result);
        return 0;
    }
    
    static void __exit use_math_exit(void) {
        printk(KERN_INFO "use_math module unloaded\n");
    }
    
    module_init(use_math_init);
    module_exit(use_math_exit);
    
    MODULE_LICENSE("GPL");
    MODULE_AUTHOR("Nish");
    MODULE_DESCRIPTION("Using Exported Module Symbols in Linux");
    

    Steps to Try It Out

    1. Compile both modules: make
    2. Load the first module (exports the symbol): sudo insmod my_math.ko
    3. Load the second module (uses the symbol): sudo insmod use_math.ko
    4. Check dmesg for output: dmesg | tail
    5. Unload both: sudo rmmod use_math sudo rmmod my_math

    You’ll see the result of the shared function printed in your kernel log.

    Common Errors While Exporting Module Symbols in Linux

    If you face an error like:

    Unknown symbol in module
    

    It usually means:

    • The module that exports the symbol isn’t loaded yet.
    • The exported name doesn’t match exactly.
    • You forgot to declare it as extern in the using module.

    Always check dmesg for kernel logs — it gives clear hints about what went wrong.

    Real-World Example

    This mechanism is widely used in Linux device drivers.
    For instance:

    • The sound subsystem exports symbols for codecs and controllers.
    • The network stack exports helper functions that other modules reuse.

    It’s a clean way for the kernel to stay modular while still sharing functionality between components.

    Pro Tip

    If your module exports many symbols, you can list them in a Module.symvers file.
    This helps the kernel link everything correctly during module compilation.

    Wrapping Up

    Exporting module symbols in Linux isn’t scary at all — it’s just about sharing functions safely between kernel modules.
    It helps keep the Linux kernel modular, reusable, and easier to maintain.

    So next time you want one module to use a function from another, just remember:

    A simple EXPORT_SYMBOL() can do the magic!

    Key Takeaways

    ConceptDescription
    Exporting Module Symbols in LinuxAllows sharing of functions or variables between kernel modules.
    EXPORT_SYMBOL()Makes the symbol available to any module.
    EXPORT_SYMBOL_GPL()Restricts usage to GPL-compatible modules.
    Common Error“Unknown symbol” – means the exporting module isn’t loaded yet.

    ❓ Frequently Asked Questions (FAQ) — Exporting Module Symbols in Linux

    🧠 1. What is meant by exporting module symbols in Linux?

    Exporting module symbols in Linux means making a function or variable defined in one kernel module available for use in another module. This helps different parts of the kernel communicate and share functionality efficiently.

    ⚙️ 2. Why do we need to export symbols in kernel modules?

    We export symbols to promote code reuse and modularity. Instead of rewriting the same code across multiple modules, developers can export a function once and use it wherever needed — saving time and keeping the kernel codebase clean.

    🧩 3. What is the difference between EXPORT_SYMBOL and EXPORT_SYMBOL_GPL?

    EXPORT_SYMBOL() makes the symbol available to any module, while EXPORT_SYMBOL_GPL() restricts usage to GPL-licensed modules only. It ensures that only open-source compatible modules can use the exported symbol.

    🧾 4. How do you declare and use exported symbols in Linux?

    To export a symbol, use:

    EXPORT_SYMBOL(symbol_name);

    To use it in another module, declare it with:

    extern data_type symbol_name;

    Then load the exporting module before loading the module that uses the symbol.

    🧰 5. What causes the “Unknown symbol in module” error?

    This error occurs when:

    • The exporting module isn’t loaded yet.
    • The symbol name is misspelled or mismatched.
    • The module version doesn’t match the kernel build.

    Always check logs using dmesg to find the root cause.

    🔗 6. How does exporting module symbols relate to kernel modules in Linux?

    Exporting module symbols is a fundamental concept when working with kernel modules in the Linux operating system. It ensures that multiple kernel modules can work together without being hardcoded into a single file.

    🧑‍💻 7. Can I export variables as well as functions?

    Yes, both functions and global variables can be exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL(). Just make sure the variable has proper scope and type definition accessible to the other module.

    🚀 8. What are real-world applications of exporting module symbols in Linux?

    Exporting symbols is widely used in device driver development, especially when multiple drivers or kernel components need to share utility functions — like audio, network, or power management drivers.

    🔒 9. Can I use exported symbols from a proprietary module?

    Only if the symbol is exported using EXPORT_SYMBOL(). If it’s exported with EXPORT_SYMBOL_GPL(), proprietary or non-GPL modules cannot legally or technically use it.

    🧩 10. Where can I learn more about Linux kernel modules?

    You can explore a complete beginner-friendly guide on kernel modules in the Linux operating system to strengthen your understanding before diving deeper into symbol exporting.

  • Master Hello World using Yocto | Build & Run a Linux Kernel Driver on BeagleBone Black (2026)

    Hello World using Yocto : Learn how to build a simple “Hello World” Linux kernel module from scratch using the Yocto Project for the BeagleBone Black. This step-by-step guide covers everything you need — from installing essential build tools, cloning the Yocto and meta-ti layers, creating a custom meta layer for your kernel module, writing the driver code, creating the recipe, to building and deploying the image on your BeagleBone Black device. Perfect for embedded Linux developers and beginners, this tutorial ensures you understand how to integrate and run out-of-tree kernel modules efficiently using Yocto’s powerful build system.

    What is Yocto?

    Yocto Project is an open-source collaboration project that helps developers create custom Linux-based systems for embedded devices. It provides tools, templates, and methods to build your own Linux distribution tailored to your hardware and software needs.

    Why use Yocto?

    • Custom Linux builds: You can create a Linux system optimized for your specific hardware (like BeagleBone Black, Raspberry Pi, etc.).
    • Reproducible builds: You can reproduce the exact same Linux image anytime.
    • Cross-compilation: It simplifies building software on your desktop machine for another target platform.
    • Scalability: Use it for small embedded devices or large, complex systems.
    • Community support: Backed by many companies and contributors in the embedded world.

    Key components of Yocto

    • BitBake: The build engine (like make but more powerful for embedded Linux).
    • Poky: The reference distribution and set of metadata recipes.
    • Recipes: Scripts that define how to build packages, kernels, and images.
    • Layers: Collections of recipes and configuration that can be added to customize the build.

    Who uses Yocto?

    • Embedded system developers building custom Linux for hardware like automotive infotainment, IoT devices, industrial controllers, and more.
    • Companies wanting to maintain full control over their embedded Linux stack.

    What is Poky?

    Poky is the reference build system and distribution provided by the Yocto Project. It’s basically a set of metadata, tools, and configurations that you use as a starting point to build your own custom embedded Linux images.

    Details:

    • Poky = Yocto Project reference system
      It includes the BitBake build tool plus a collection of recipes, configuration files, and classes that define how to build software packages, the Linux kernel, and the overall system image.
    • It’s a base for your custom Linux
      When you start a Yocto Project build, most tutorials and examples use Poky because it’s a complete and tested setup.
    • Contains layers like:
      • meta: core metadata layer with basic recipes and configurations
      • meta-poky: specific poky configurations and utilities
      • meta-yocto: essential recipes for a minimal embedded Linux distribution

    Why is Poky important?

    • It’s the default “reference distro” for Yocto, meaning it provides a working baseline system.
    • You can extend or modify Poky with additional layers to support your hardware and software requirements.
    • It helps you understand how the Yocto build system works before diving into more complex customizations.

    What is BitBake?

    BitBake is the build engine/tool used by the Yocto Project (and Poky) to compile and assemble software components into a complete Linux image for embedded systems.

    Details:

    • It’s like “make” on steroids but designed specifically for building embedded Linux systems.
    • BitBake reads special files called recipes (.bb files), which describe how to fetch, configure, compile, and package software.
    • It manages complex build tasks, dependencies, and executes them in the right order.
    • BitBake supports cross-compilation, so you can build software on your development machine for a different target device.
    • It also handles layers, configuration, and task scheduling.

    Why is BitBake important?

    • It automates the entire build process for embedded Linux, from downloading source code to creating a final flashable image.
    • It ensures reproducibility — builds can be repeated with the same results.
    • BitBake is highly extensible and can be customized with your own recipes.

    Install Yocto Prerequisites

    On your Ubuntu/Debian build machine:

    sudo apt update
    sudo apt install -y gawk wget git-core diffstat unzip texinfo \
      gcc build-essential chrpath socat cpio python3 python3-pip python3-pexpect \
      xz-utils debianutils iputils-ping python3-git python3-jinja2 \
      libegl1-mesa libsdl1.2-dev pylint3 xterm
    

    These are the official Yocto host dependencies.

    Download Yocto (Poky) and BeagleBone BSP Layer

    We’ll use the Yocto Kirkstone LTS release and meta-ti for TI boards like the BBB.

    mkdir ~/yocto-bbb
    cd ~/yocto-bbb
    
    # Poky (Yocto core)
    git clone -b kirkstone git://git.yoctoproject.org/poky
    
    # TI BSP layer (BeagleBone support)
    git clone -b kirkstone git://git.yoctoproject.org/meta-ti
    

    Set Up the Build Environment

    cd poky
    source oe-init-build-env
    

    This creates and moves you into a build/ directory.

    Add BeagleBone Black Layers

    bitbake-layers add-layer ../meta-ti
    

    Set the Machine to BeagleBone Black

    Edit conf/local.conf:

    MACHINE = "beaglebone"
    

    Create Your Custom Layer for the Driver

    cd ~/yocto-bbb
    bitbake-layers create-layer meta-hello
    bitbake-layers add-layer ../meta-hello
    

    Create the Hello World Kernel Module

    Directory Structure:

    meta-hello/
    └── recipes-kernel/
        └── hello-module/
            ├── files/
            │   ├── hello.c
            │   ├── Makefile
            │   └── COPYING
            └── hello-module_0.1.bb
    

    hello.c

    #include <linux/module.h>
    #include <linux/kernel.h>
    #include <linux/init.h>
    
    MODULE_LICENSE("GPL");
    MODULE_AUTHOR("Nish");
    MODULE_DESCRIPTION("Hello World Kernel Module for BeagleBone Black");
    
    static int __init hello_init(void)
    {
        printk(KERN_INFO "Hello, BeagleBone World!\n");
        return 0;
    }
    
    static void __exit hello_exit(void)
    {
        printk(KERN_INFO "Goodbye, BeagleBone World!\n");
    }
    
    module_init(hello_init);
    module_exit(hello_exit);
    

    Makefile

    obj-m := hello.o
    

    COPYING

    GNU GENERAL PUBLIC LICENSE
    Version 2, June 1991
    

    Get its checksum:

    md5sum COPYING
    

    hello-module_0.1.bb

    SUMMARY = "Hello World Kernel Module for BeagleBone Black"
    DESCRIPTION = "A simple kernel module built with Yocto for BBB"
    LICENSE = "GPL-2.0"
    LIC_FILES_CHKSUM = "file://COPYING;md5=<paste-md5-here>"
    
    SRC_URI = "file://hello.c \
               file://Makefile \
               file://COPYING"
    
    S = "${WORKDIR}"
    
    inherit module
    

    Include the Module in the Image

    Edit conf/local.conf:

    IMAGE_INSTALL_append = " kernel-module-hello"
    

    (Optional: Auto-load at boot)

    KERNEL_MODULE_AUTOLOAD += "hello"
    

    Build the Image

    cd ~/yocto-bbb/poky
    source oe-init-build-env
    bitbake core-image-minimal
    

    After the build completes, the image will be in:

    tmp/deploy/images/beaglebone/
    

    Flash to SD Card

    Insert your SD card and find its device name:

    lsblk
    

    Flash:

    sudo dd if=tmp/deploy/images/beaglebone/core-image-minimal-beaglebone.wic of=/dev/sdX bs=4M status=progress
    sync
    

    Boot BeagleBone Black

    • Insert SD card into BBB
    • Power it up (hold BOOT button if needed to boot from SD)

    Test the Module on BBB

    # Check if auto-loaded
    lsmod | grep hello
    
    # If not, load manually
    sudo modprobe hello
    
    # Check kernel logs
    dmesg | tail
    
    # Remove module
    sudo rmmod hello
    dmesg | tail
    

    Expected output:

    [   15.123456] Hello, BeagleBone World!
    [   20.654321] Goodbye, BeagleBone World!
    

    ✅ You’ve successfully built, packaged, and run a Hello World Linux kernel driver on BeagleBone Black using Yocto!

    Frequently asked questions (FAQ) | Hello World using Yocto

    1. What is Yocto and why use it for building kernel modules?

    Yocto is a powerful open-source build system for creating custom Linux distributions for embedded devices like BeagleBone Black. Using Yocto to build kernel modules ensures reproducible builds, automatic packaging, and easy integration into your custom image.

    2. How do I install the necessary host tools for Yocto?

    On Ubuntu/Debian, run:

    sudo apt install gawk wget git-core diffstat unzip texinfo gcc build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils
    

    This installs all required tools and dependencies for Yocto to build properly.

    3. Why do I need to clone both ‘poky’ and ‘meta-ti’ repositories?

    ‘poky’ is the main Yocto reference distribution containing BitBake and core layers. ‘meta-ti’ provides board support packages (BSP) and recipes specific to Texas Instruments devices like the BeagleBone Black.

    4. How do I add my own kernel module to the Yocto build?

    Create a custom meta layer (meta-hello), add your kernel module source and recipe inside it, then add this layer to your build using bitbake-layers add-layer. Finally, append your kernel module package to IMAGE_INSTALL in local.conf.

    5. What does inherit module do in the recipe?

    It tells Yocto that this recipe builds a kernel module, so it sets up the proper build environment, compiles the code against the kernel headers, and packages the module correctly.

    6. How do I ensure my module loads automatically on boot?

    Set the variable KERNEL_MODULE_AUTOLOAD += "hello" in your local.conf or image recipe. Yocto will then create the necessary config files to load your module during system startup.

    7. What if my module doesn’t load or I get errors?

    • Check kernel logs with dmesg to see error messages.
    • Verify that the module is actually included in your image (IMAGE_INSTALL).
    • Make sure the kernel version on your target matches the one you built the module for.
    • Use modprobe instead of insmod to handle dependencies.

    8. How do I flash the Yocto-built image to the BeagleBone Black?

    Use dd to write the .wic image to your SD card:

    sudo dd if=core-image-minimal-beaglebone.wic of=/dev/sdX bs=4M status=progress && sync
    

    Replace /dev/sdX with your actual SD card device.

    9. Can I build and test the kernel module without building the entire image?

    Yes! You can build just the module by running:

    bitbake hello-module
    

    Then manually copy the resulting .ko file to the target and load it with insmod or modprobe.

    10. Where can I find more resources to learn Yocto and kernel module development?