Module 5 · Lesson 4 of 30

Character drivers I

Device numbers, cdev and file_operations: build a character driver with safe user copies, correct read/write/llseek returns and automatic /dev nodes.

  • Beginner to advanced
  • 29 min read
  • 60 min lab
What you will need

Ubuntu 24.04 (VM or WSL2) with the kernel build tree and the QEMU plus BusyBox initramfs loop from the earlier lessons; root inside the guest

By the end you can 7 objectives
  • Explain how major and minor numbers route a system call to a driver, and allocate them with alloc_chrdev_region
  • Register a character device with cdev_init and cdev_add, and wire a struct file_operations to it
  • Implement open, release, read, write and llseek with correct return codes, partial transfers and offset updates
  • Move data across the user/kernel boundary with copy_to_user, copy_from_user and the get_user/put_user family, handling -EFAULT
  • Recover per-device state with container_of and carry per-open state through private_data
  • Create /dev nodes automatically with class_create and device_create via devtmpfs, and manually with mknod
  • Diagnose common character-driver failures and evaluate the compat_ioctl and llseek choices for a product
Read the lesson below; the video will appear here when published.
01

Why devices look like files

3 min read

The previous lesson built a module that loads, prints, and unloads. It registered nothing, so nothing could call it. This lesson gives it a face that applications can use: a file under /dev.

A is the simplest kind of device Linux exposes. A serial port is the classic example. You write bytes to it and they leave on the wire; you read bytes from it and they arrived from the wire. There is no notion of a block or a sector.

Linux sorts devices into three families. Character devices stream bytes. Block devices, like disks, are read and written in fixed-size blocks and can be accessed at random offsets. Network devices do not appear as files at all; you reach them through sockets. This lesson is about the first family, because it is the one you write yourself most often, and the one the later subsystems build on.

The bridge between an application and a driver is a . It looks like a file, but it has no contents on disk. Its whole payload is two numbers and a type bit. Look at a few:

bash
ls -l /dev/null /dev/ttyS0 /dev/sda

Typical output (yours will differ):

text
crw-rw-rw- 1 root root    1, 3 Nov 17 09:12 /dev/null
crw-rw---- 1 root dialout 4, 64 Nov 17 09:12 /dev/ttyS0
brw-rw---- 1 root disk    8, 0 Nov 17 09:12 /dev/sda

The first letter is the type: c for character, b for block. Where a normal file shows its size, a device shows two numbers, 1, 3 or 4, 64. Those are the major and minor. The major selects the driver; the minor selects which device that driver handles. /dev/null and /dev/zero share major 1 because one driver answers for both. The four serial ports ttyS0 to ttyS3 share major 4 and differ only in the minor.

This design is old. Special files have been part of Unix since the 1970s, and the idea has never needed replacing: applications already know how to open, read, write and close, so a driver that implements those operations inherits every tool in the box. cat, dd, echo, shell redirection, strace — all of them work on your device the day you register it, with no special client library.

From an application to a character deviceApplicationscat, dd, echoSystem callsopen, read, writeVFSdispatches by file typecdev + fopsyour driver's methodsDevice bufferkmalloc memoryrequests go down, data comes upApplicationscat, dd, echoSystem callsopen, read, writeVFSdispatches by file typecdev + fopsyour driver's methodsDevice bufferkmalloc memoryrequests go down, data comes up
The layers between an application and a character device

For an embedded engineer this is the daily interface. A GPIO controller appears as /dev/gpiochip0, an I2C bus as /dev/i2c-1, an SPI device as /dev/spidev0.0, a hardware watchdog as /dev/watchdog. Each is a character device with a driver behind it. When you write a driver for a new sensor on your board, you are writing exactly the kind of code this lesson builds, and userspace will talk to it with read and write.

Everything is a file, but not everything is a character device

Pipes, sockets and regular files also use file descriptors, but they are handled by other parts of the kernel. The character-device path described here applies only to nodes whose type bit is c. The same struct file_operations table is reused across the kernel, which is why learning it once pays off everywhere.

02

Device numbers: major, minor and dev_t

4 min read

Inside the kernel the pair lives in a . It is a plain u32. The top 12 bits hold the major, so majors run from 0 to 4095; the low 20 bits hold the minor, so minors run from 0 to 1048575. You never shift the bits yourself. Three macros in <linux/kdev_t.h> do it:

c
#define MINORBITS   20
#define MINORMASK   ((1U << MINORBITS) - 1)

#define MAJOR(dev)  ((unsigned int) ((dev) >> MINORBITS))
#define MINOR(dev)  ((unsigned int) ((dev) & MINORMASK))
#define MKDEV(ma, mi)   (((ma) << MINORBITS) | (mi))

MKDEV(4, 64) builds the number for ttyS0; MAJOR and MINOR take it apart again. The layout is an implementation detail, and it has changed before: kernels before 2.6 used 8 bits for each part, limiting the system to 255 majors and 255 minors. The widening in 2.6 (2003) is why old code that masks with 0xff is wrong today. Use the macros and the layout never bites you.

0x400040 is MKDEV(4, 64): shifting right 20 bits gives major 4, masking with 0xFFFFF gives minor 64, the packed number for ttyS0. MKDEV(1, 3) for /dev/null packs to 0x100003.

  • fields: [{"name": "Major", "lsb": 20, "width": 12}, {"name": "Minor", "lsb": 0, "width": 20}]
  • value: 0x400040
  • width: 32
How a dev_t packs major and minorBits31..2019..0Fieldmajor(12)minor (20)ttyS0464MKDEV(4, 64) builds the dev_t for ttyS0
How a dev_t packs the major and minor

Before you use a number you must reserve it, so two drivers never answer the same major. The kernel keeps a registry, and you can read the character half of it:

bash
cat /proc/devices

Typical output (yours will differ):

text
Character devices:
  1 mem
  4 ttyS
  5 tty
 10 misc
 13 input
254 gpiochip

Block devices:
  7 loop
  8 sd

Each line is a major and the name its owner registered. There are two ways to claim a range. The first says exactly which numbers you want:

c
int register_chrdev_region(dev_t first, unsigned int count, const char *name);

first is the starting number, usually MKDEV(major, 0), count is how many consecutive minors you need, and name is what shows up in /proc/devices. It returns 0 on success or a negative error code, for example -EBUSY if the range is already taken. This is fine when you control the whole system and have picked a number you know is free.

The second, and the one you should default to, lets the kernel pick a free major:

c
int alloc_chrdev_region(dev_t *dev, unsigned int firstminor,
            unsigned int count, const char *name);

dev is an output parameter: on success it holds the first number assigned. firstminor is usually 0. The kernel chooses a major that nobody else is using, so your driver loads cleanly on any machine. The price is that you cannot know the number in advance, which matters only if you create nodes by hand — a problem the automatic node creation later in this lesson removes.

Whichever you used, release the range when the module unloads:

c
void unregister_chrdev_region(dev_t first, unsigned int count);

A typical init fragment looks like this:

c
static dev_t mychar_devt;

err = alloc_chrdev_region(&mychar_devt, 0, 1, "mychar");
if (err)
    return err;
pr_info("mychar: major %d minor %d\n",
    MAJOR(mychar_devt), MINOR(mychar_devt));
Going deeperThe legacy register_chrdev

Older code, and many older tutorials, call register_chrdev(major, name, fops) instead. It registers all 256 minors of a major at once and hides the cdev entirely. It still exists for compatibility, but it cannot express the 20-bit minor space, forces you to handle opens on minors you never intended, and gives you no per-device structure. New drivers use alloc_chrdev_region plus an explicit cdev. The same applies to unregister_chrdev: it pairs only with the old call.

03

cdev and file_operations: wiring a driver

4 min read

A is defined in <linux/cdev.h>. Its fields are few:

c
struct cdev {
    struct kobject kobj;
    struct module *owner;
    const struct file_operations *ops;
    struct list_head list;
    dev_t dev;
    unsigned int count;
};

The kobj is a ; it is what lets the kernel track who is still using the device, and a later section opens it up. owner is the module that owns the device, ops points at your operations table, and dev plus count record the number range. You rarely touch list or kobj directly.

The is defined in <linux/fs.h>. It is large, but every field is optional. For this lesson you need six:

c
static const struct file_operations mychar_fops = {
    .owner   = THIS_MODULE,
    .open    = mychar_open,
    .release = mychar_release,
    .read    = mychar_read,
    .write   = mychar_write,
    .llseek  = mychar_llseek,
};

Designated initialisers (the .field = value form) name each member, so you can list them in any order and leave the rest zero. A zero field means "not implemented", and the kernel has a defined fallback for each: a missing read or write makes the call fail with -EINVAL; a missing open simply succeeds without notifying you; a missing mmap returns -ENODEV; a missing unlocked_ioctl returns -ENOTTY. The .owner = THIS_MODULE entry is not optional in practice: it lets the kernel hold a reference on your module while a file is open, so rmmod cannot pull the code out from under a running call.

You initialise a cdev and hand it to the kernel in three moves:

c
cdev_init(&mychar.cdev, &mychar_fops);
mychar.cdev.owner = THIS_MODULE;
err = cdev_add(&mychar.cdev, mychar_devt, 1);
if (err)
    goto err_buffer;

cdev_init zeroes the structure, sets ops, and prepares the kobject. It does not set owner, so you set it yourself. cdev_add publishes the device for the number range starting at mychar_devt, covering count numbers (here one). It returns an int and can fail, so check it. To withdraw the device later, call cdev_del(&mychar.cdev), which returns nothing.

Registration from numbers to a live devicealloc_chrdev_regionreservenumberskzallocbufferpreparestatecdev_initbind fopsset ownercdev_adddevice goeslivedevice_create/dev nodeappearsalloc_chrdev_regionreservenumberskzallocbufferpreparestatecdev_initbind fopsset ownercdev_adddevice goeslivedevice_create/dev nodeappears
The registration sequence from numbers to a live device
The device is live the moment cdev_add returns

As soon as cdev_add succeeds, any process can open the node and call your operations, possibly before your init function has finished. Allocate the buffer, fill the device structure and set every field before you call cdev_add, never after. A driver that adds the cdev and then initialises its buffer has a window where a read dereferences a NULL pointer.

If you prefer a standalone cdev rather than one embedded in your own structure, cdev_alloc() returns a freshly allocated one whose release function frees it automatically. Embedding is more common, because it lets one allocation hold the cdev and all your device state together, and the next section shows why that pairing is useful.

Step by stepFrom insmod to a live device
  1. Reserve numbers: alloc_chrdev_region hands back a free major and the first minor.

  2. Prepare state: allocate the buffer and fill the device structure that embeds the cdev.

  3. Init the cdev: cdev_init binds your file_operations table to the embedded cdev.

  4. Set the owner: assign cdev.owner = THIS_MODULE so the module cannot be unloaded while in use.

  5. Publish: cdev_add maps the number range to the cdev; from this instant the device answers calls.

  6. Create the node: class_create and device_create make /dev/mychar appear, covered later.

04

open, release and per-device state

4 min read

When a process opens /dev/mychar, the kernel passes your open method two pointers:

c
int (*open)(struct inode *inode, struct file *file);

The struct inode represents the file itself. There is one inode per node, no matter how many processes open it. For a device node, two fields matter: i_rdev, the raw dev_t, and i_cdev, a pointer to the cdev that answers for it. Two helpers, iminor(inode) and imajor(inode), read the numbers without touching i_rdev directly.

The struct file represents one open instance. Each successful open creates a fresh one, and it is passed to every later operation on that descriptor. Its important fields are f_pos, the current 64-bit read/write offset; f_mode, the access bits FMODE_READ and FMODE_WRITE; f_flags, the O_* flags such as O_NONBLOCK; f_op, the operations table in force; and private_data, a void * the kernel sets to NULL before calling your open and then leaves entirely to you.

The distinction explains a common surprise. Two processes opening the same node get two struct file objects with independent offsets, but they share one inode and one underlying device. Your driver decides whether the data behind the device is shared or per-open; the kernel does not decide for you.

Your device state usually lives in a structure that embeds the cdev:

c
struct mychar_dev {
    struct cdev cdev;
    char *buffer;
    size_t size;
};

In open you receive inode->i_cdev, a pointer to the cdev member, but you want the whole mychar_dev. The kernel's does the conversion safely:

c
static int mychar_open(struct inode *inode, struct file *file)
{
    struct mychar_dev *dev;

    dev = container_of(inode->i_cdev, struct mychar_dev, cdev);
    file->private_data = dev;
    return 0;
}

container_of(ptr, type, member) subtracts the member's byte offset from ptr, yielding the address of the enclosing structure. It is type-checked, so a wrong member name is a compile error rather than a silent miscalculation. Once you stash the result in file->private_data, every later method recovers it with one line:

c
struct mychar_dev *dev = file->private_data;
One inode, many open filesstruct inodestruct fileRepresentsthe fileitselfone openinstanceCountone per nodeone per openKey fieldsi_rdev,i_cdevf_pos,private_dataLifetimewhile nodeexistsopen to lastclose
One inode, many open files

release is the counterpart of open, but its name is precise: it runs when the last reference to the struct file drops, not on every close. After fork or dup, several descriptors share one struct file; closing one of them does not call release. Only the final close does. So you get exactly one release per open, which is what makes it safe to free per-open state there. If you need an action on every close, that is the separate flush method, which few drivers implement.

c
static int mychar_release(struct inode *inode, struct file *file)
{
    return 0;
}

Our device keeps its buffer for the lifetime of the module, so release has nothing to free. A driver that allocates a private context in open would free it here:

c
kfree(file->private_data);

You do not check read or write permission inside your methods. The kernel verifies f_mode before it calls you, so a read on a write-only descriptor is rejected before your code runs. You may inspect f_flags & O_NONBLOCK to decide whether a later blocking operation should sleep or return immediately; blocking I/O is a later session.

Per-device versus per-open state

Put data shared by all users of the device in the structure that embeds the cdev, and reach it with container_of. Put data private to one open instance in a separate allocation stored in private_data, and free it in release. Mixing the two is a classic source of bugs: a per-open offset stored in the shared device, or a shared buffer freed on the first release.

05

Crossing the boundary: safe user copies

4 min read

The buf argument of your read and write methods points into the calling process's memory. It is annotated char __user *. The __user marker is documentation for a static checker called sparse; it has no effect on the compiled code, but it tells every reader and every tool that this address is untrusted and must not be dereferenced.

There are three reasons you cannot just use memcpy. First, security: a malicious program could pass a kernel address, and a blind copy would let it read or overwrite kernel memory. Second, paging: user memory can be swapped out, so touching it may need to wait for a page to come back from disk, which ordinary kernel code is not allowed to do. Third, portability: on some architectures user and kernel addresses live in separate spaces, and a raw dereference simply faults.

The transfer helpers live in <linux/uaccess.h>:

c
unsigned long copy_to_user(void __user *to, const void *from, unsigned long n);
unsigned long copy_from_user(void *to, const void __user *from, unsigned long n);

copy_to_user moves data from the kernel to the process (your read path); copy_from_user moves it the other way (your write path). The return value is the number of bytes that could NOT be copied. Zero means complete success. This inverted convention catches everyone once: you test if (copy_to_user(...)) and treat any nonzero result as failure, usually returning -EFAULT, the error code for a bad address.

c
if (copy_to_user(buf, dev->buffer + *offp, count))
    return -EFAULT;

On a partial failure, current kernels zero the bytes of the destination that were not copied, so a short read never leaks stale kernel data into the user buffer. The helpers also check the address range internally, so you do not need a separate check before calling them.

For a single small value, the get_user and put_user macros are faster than a one-element copy:

c
int val;

if (get_user(val, (int __user *)arg))
    return -EFAULT;
if (put_user(val, (int __user *)arg))
    return -EFAULT;

They transfer one, two, four or eight bytes, choosing the size from the pointer type at compile time. They return 0 on success or -EFAULT on failure, and get_user sets its destination to zero when it fails. The double-underscore variants __get_user and __put_user skip the address check; use them only after you have already validated the range yourself.

That validation is access_ok(addr, size). It returns true if the range lies in user space and false if it points into the kernel. It does not check that the memory is actually mapped or writable; it only rules out kernel addresses. The copy helpers call it for you, so most drivers never call it directly.

Old books show a three-argument access_ok

Code written before kernel 5.0 (2019) calls access_ok(VERIFY_READ, addr, size) or access_ok(VERIFY_WRITE, ...). The type argument was removed; the current form is access_ok(addr, size). If you copy an old snippet verbatim it will not compile on a modern kernel. The same caution applies to other uaccess helpers whose signatures have been tidied over the years.

The path of a read into application memoryApplicationVFSmychar driverread(fd, buf, 4096)f_op->read(...)copy_to_user(buf, ...)return countreturn count1. Application → VFSread(fd, buf, 4096)2. VFS → mychar driverf_op->read(...)3. mychar driver →Applicationcopy_to_user(buf, ...)4. mychar driver → VFSreturn count5. VFS → Applicationreturn count
The path of a read from driver buffer to application memory
Going deeperHow a bad pointer becomes -EFAULT instead of a crash

The copy helpers are written in assembly with a special trick. Each instruction that touches user memory is recorded in an exception table, a kernel-wide list mapping a faulting instruction address to a fixup address. If the access faults, the page-fault handler searches this table; finding an entry, it jumps to the fixup, which returns the uncopied byte count instead of killing the kernel. On modern CPUs the hardware also blocks kernel access to user pages by default — SMAP on x86, PAN on ARMv8.1 — and the helpers open a brief, controlled window around the copy. The result is that an invalid user pointer produces a clean -EFAULT, not an oops.

06

read and write: the return-value contract

6 min read

The prototypes are:

c
ssize_t (*read)(struct file *file, char __user *buf,
        size_t count, loff_t *offp);
ssize_t (*write)(struct file *file, const char __user *buf,
         size_t count, loff_t *offp);

count is how many bytes the caller asked for. offp points at the current offset, a loff_t, which is a 64-bit position on every architecture. ssize_t is a signed size, because the return value carries both a byte count and a negative error. The rules for that return value are the contract every application relies on:

  • A positive value equal to count means the whole request was served.
  • A positive value smaller than count means a partial transfer. This is normal, not an error; well-written callers loop until they have what they need. The C library's fread does this for you.
  • For read, zero means end of file: there is no more data at this offset. For write, zero means nothing was accepted; it is not an error, but a caller that loops on zero can spin forever, so prefer a real error when the device is full.
  • A negative value is an error code from <linux/errno.h>, such as -EFAULT for a bad buffer or -EINVAL for a bad argument.
  • If some bytes transferred and then an error occurred, return the count now and report the error on the next call. The caller must see the partial progress.

The offset deserves care. Update *offp, the pointer you were given, rather than file->f_pos directly. For an ordinary read or write the kernel passes the address of f_pos, so your update lands in the file. For pread and pwrite, which read at a given offset without moving the file position, the kernel passes a pointer to a temporary copy and discards your change. Writing through *offp is correct in both cases; writing file->f_pos directly would break pread.

Our device is a fixed-capacity buffer, so it needs a place to keep the bytes. The kernel's allocator is kmalloc, declared in <linux/slab.h>:

c
void *kmalloc(size_t size, gfp_t flags);
void *kzalloc(size_t size, gfp_t flags);
void kfree(const void *ptr);

kmalloc returns physically contiguous kernel memory, or NULL on failure. kzalloc is the same but zeroes the bytes first, which you want for a buffer that will be read back. kfree releases it and safely accepts NULL. The allocator is backed by the slab layer, a set of caches of pre-sized objects, so a request is rounded up to the nearest cache size; asking for 100 bytes may hand you a 128-byte slot. Keep kmalloc allocations modest, a few pages at most; very large buffers belong to other allocators covered in a later session.

The flags argument is a set of . The two you must distinguish are GFP_KERNEL and GFP_ATOMIC. GFP_KERNEL is the normal choice in process context: it may sleep while the allocator reclaims memory, so it must never be called from an interrupt handler or while holding a spinlock. GFP_ATOMIC never sleeps and draws on emergency reserves; it is for interrupt handlers and other atomic contexts, and it can fail more readily under pressure. Your module init and your file operations run in process context, so they use GFP_KERNEL.

Here is the device structure and its buffer, allocated once at init:

c
#define MYCHAR_CAP 4096

struct mychar_dev {
    struct cdev cdev;
    char *buffer;
    size_t size;
};

static struct mychar_dev mychar;

/* in init, before cdev_add */
mychar.buffer = kzalloc(MYCHAR_CAP, GFP_KERNEL);
if (!mychar.buffer) {
    err = -ENOMEM;
    goto err_region;
}

size records how many bytes are currently stored; the capacity is the constant MYCHAR_CAP. Now the read method:

c
static ssize_t mychar_read(struct file *file, char __user *buf,
               size_t count, loff_t *offp)
{
    struct mychar_dev *dev = file->private_data;
    size_t avail;

    if (*offp >= dev->size)
        return 0;

    avail = dev->size - *offp;
    if (count > avail)
        count = avail;

    if (copy_to_user(buf, dev->buffer + *offp, count))
        return -EFAULT;

    *offp += count;
    return count;
}

Read it as the contract in code. At or past the stored size, return 0 for end of file. Otherwise clamp count to what remains, so a large request yields a partial read rather than running off the buffer. Copy, and on failure return -EFAULT. On success advance the offset and return the count actually delivered.

The write method mirrors it, with one design decision: when the buffer is full it returns -ENOSPC (no space left) rather than looping, and a write that runs past the capacity is clamped to a partial write:

c
static ssize_t mychar_write(struct file *file, const char __user *buf,
                size_t count, loff_t *offp)
{
    struct mychar_dev *dev = file->private_data;
    size_t space;

    if (*offp >= MYCHAR_CAP)
        return -ENOSPC;

    space = MYCHAR_CAP - *offp;
    if (count > space)
        count = space;

    if (copy_from_user(dev->buffer + *offp, buf, count))
        return -EFAULT;

    *offp += count;
    if (*offp > dev->size)
        dev->size = *offp;
    return count;
}

After a successful copy it advances the offset and grows size if the write extended the stored data. A write into the middle of existing data overwrites those bytes without changing size, exactly as a write into the middle of a file does.

The decision path of mychar_readpos >=size?clamp countto bytesremainingcopy_to_useradvance*offpExit from step 3: bytes not copiedreturn -EFAULTreturncountpos >=size?clamp countto bytesremainingcopy_to_useradvance*offpExit from step 3: bytes notcopiedreturn -EFAULTreturncount
The decision path of mychar_read

One more return code belongs to this contract: -ERESTARTSYS. When a driver sleeps waiting for data and a signal interrupts that sleep, it returns -ERESTARTSYS. The kernel then either restarts the system call automatically, if the signal handler was installed with SA_RESTART, or converts it to -EINTR for the application. You return -ERESTARTSYS, never -EINTR yourself; the restart decision is the kernel's. This driver does not sleep yet, so it never returns that code, but blocking I/O in a later session is built on it.

No locking yet, on purpose

Two processes writing at once can interleave and corrupt size and the buffer. This lesson keeps the driver single-threaded in spirit so the return-value contract stays visible. The next session adds the mutex that makes these methods safe under concurrency; do not ship a shared buffer without one.

07

llseek, offsets and proving it with strace

4 min read

The llseek method implements the lseek system call:

c
loff_t (*llseek)(struct file *file, loff_t offset, int whence);

loff_t is a 64-bit offset on every architecture, so large devices work even on 32-bit systems. whence is one of SEEK_SET (from the start), SEEK_CUR (from the current position) or SEEK_END (from the end). The method returns the new absolute position, or a negative error. For our memory-backed device:

c
static loff_t mychar_llseek(struct file *file, loff_t offset, int whence)
{
    struct mychar_dev *dev = file->private_data;
    loff_t newpos;

    switch (whence) {
    case SEEK_SET:
        newpos = offset;
        break;
    case SEEK_CUR:
        newpos = file->f_pos + offset;
        break;
    case SEEK_END:
        newpos = dev->size + offset;
        break;
    default:
        return -EINVAL;
    }

    if (newpos < 0)
        return -EINVAL;

    file->f_pos = newpos;
    return newpos;
}

This is the one method that writes file->f_pos directly, because changing the position is its whole job. SEEK_END uses the stored size, so seeking past the end is allowed and a subsequent read there returns 0. A negative resulting position is rejected with -EINVAL.

Here is the trap: if you leave .llseek NULL, the kernel does not refuse seeking. It falls back to a generic helper, default_llseek, which simply moves f_pos. For a memory device that is harmless, but for a stream such as a serial port it is wrong — there is no position to move. The kernel gives you three explicit choices:

  • default_llseek: the generic mover, used when you leave the field NULL.
  • no_llseek: returns -ESPIPE (illegal seek). Use it for true streams.
  • noop_llseek: returns the current position unchanged, pretending the seek succeeded. Use it for devices where seeking is meaningless but you do not want to break applications that seek out of habit, such as log-like devices.

For a stream you also call nonseekable_open(inode, file) in your open method. It clears the file's seekable flag, so the kernel rejects lseek, pread and pwrite before they ever reach you. Pair it with .llseek = no_llseek to make the intent explicit in the table.

The three llseek helpersdefault_llseekno_llseeknoop_llseekUsed when.llseek isNULLtrue streamsseek isharmlessEffectmoves f_posreturns-ESPIPEreturnscurrent posExamplememory deviceserial portlog-likedevice
The three llseek helpers and when to use each

Applications are supposed to loop over partial transfers, and you should verify that your driver actually produces them. The fastest way to see the real system calls is strace. Write ten bytes, then read them back in four-byte chunks:

bash
printf 'abcdefghij' > /dev/mychar
strace -e trace=openat,read,close dd if=/dev/mychar bs=4 count=3

Typical output (yours will differ):

text
openat(AT_FDCWD, "/dev/mychar", O_RDONLY) = 3
read(3, "abcd", 4)                        = 4
read(3, "efgh", 4)                        = 4
read(3, "ij", 4)                          = 2
close(3)                                  = 0

The third read asked for 4 and got 2: a partial read, exactly as the contract allows. A fourth read would return 0, the end-of-file signal. dd with count=3 stops after three reads, so it never sees the zero; raise the count and you will. If your initramfs has no strace, add the BusyBox strace applet or a static binary; you can practise the same commands on a regular file on the host.

You can also exercise seeking without writing C. dd's skip option seeks before reading:

bash
strace -e trace=lseek,read dd if=/dev/mychar bs=1 skip=3 count=2

Typical output (yours will differ):

text
lseek(3, 3, SEEK_SET)                     = 3
read(3, "d", 1)                           = 1
read(3, "e", 1)                           = 1

The lseek line is your mychar_llseek running with SEEK_SET. A scripted test harness that writes a known pattern, reads it back in awkward chunk sizes, seeks to a few offsets, and checks the byte counts is the lab for this session; strace is how you prove the return values rather than guessing them.

cat and dd already loop for you

You do not need a custom client to test a character driver. echo hello > /dev/mychar writes, cat /dev/mychar reads to end of file, and dd lets you fix the block size and count to force partial transfers. These tools issue ordinary system calls, so they exercise exactly the contract your methods implement.

08

/dev nodes: mknod, devtmpfs and the class API

6 min read

Everything so far registered a device in the kernel, but nothing created /dev/mychar. A node is just a type plus a major:minor, so the oldest way to make one is the mknod command, run as root:

bash
cat /proc/devices | grep mychar     # find the major, say 250
mknod /dev/mychar c 250 0
ls -l /dev/mychar

Typical output (yours will differ):

text
crw-r--r-- 1 root root 250, 0 Nov 17 09:30 /dev/mychar

The c says character; 250 0 are the major and minor you read from /proc/devices. This works, and it is worth doing once by hand so you understand what a node is. But it is fragile: with dynamic allocation the major changes between loads, the node survives rmmod as a stale entry, and the permissions are whatever root's umask left. For a product you want the node to appear and disappear with the driver.

That is what does. It arrived in kernel 2.6.32 (2009), replacing an earlier in-kernel devfs experiment that was removed. With CONFIG_DEVTMPFS enabled and CONFIG_DEVTMPFS_MOUNT set, the kernel mounts it on /dev early in boot and creates a node whenever a device is registered with the driver core. Your QEMU initramfs from the earlier lesson already mounts it explicitly:

sh
mount -t devtmpfs devtmpfs /dev

devtmpfs creates nodes owned by root with mode 0600. It does not decide policy; it only guarantees that a node exists. Adjusting permissions, ownership and symlinks is the job of a userspace helper, classically .

To get a node you register a class and a device. A class is a grouping visible under /sys/class, the kernel's exported tree of device objects. The API is in <linux/device.h>:

c
struct class *class_create(const char *name);
void class_destroy(struct class *class);

struct device *device_create(struct class *class, struct device *parent,
                 dev_t devt, void *drvdata, const char *fmt, ...);
void device_destroy(struct class *class, dev_t devt);

class_create("mychar") makes /sys/class/mychar. device_create then registers a device in that class; with a NULL parent it lands under /sys/devices/virtual/mychar/mychar, and devtmpfs creates /dev/mychar from the name you pass. Both class_create and device_create return an error pointer on failure, so test them with IS_ERR and read the code with PTR_ERR, exactly as the previous lesson taught.

class_create lost its first argument in 6.4

Books and code written before kernel 6.4 (2023) call class_create(THIS_MODULE, name). The owner argument was removed; class_create is now a macro that supplies THIS_MODULE itself, so you pass only the name. The two-argument form no longer compiles on a current kernel. If an old snippet fails to build with a macro argument error, this is usually why.

The device directory exposes a file named dev containing the numbers as text, which is how helpers learn what node to create:

bash
cat /sys/class/mychar/mychar/dev      # for example 250:0

/sys/class/mychar is a symlink, so /sys/class/mychar/mychar/dev resolves to /sys/devices/virtual/mychar/mychar/dev, the real device directory where the dev file lives.

  • cwd: /
  • value: /sys/class/mychar/mychar/dev

When the device is registered the kernel also emits a uevent, a message to userspace announcing the change. udev listens for these and applies rules from /etc/udev/rules.d/. A rule to give a group access looks like:

text
# /etc/udev/rules.d/99-mychar.rules
KERNEL=="mychar", MODE="0660", GROUP="plugdev"

0660 = -rw-rw-r--: owner and group may read and write, others have no access, the mode the rule above grants /dev/mychar. Without the rule devtmpfs leaves the stricter 0600 (-rw-------, owner only).

  • octal: 0660

After editing rules, reload and re-trigger them:

bash
sudo udevadm control --reload-rules
sudo udevadm trigger
How device_create becomes a /dev nodeDriverDriver coredevtmpfsudevdevice_create(...)create nodeueventapply MODE,GROUP1. Driver → Driver coredevice_create(...)2. Driver core → devtmpfscreate node3. Driver core → udevuevent4. udev → devtmpfsapply MODE, GROUP
How device_create turns into a /dev node with the right permissions
Step by stepHow /dev/mychar appears
  1. Class: class_create("mychar") creates the class directory under /sys/class.

  2. Device: device_create registers a device with the driver core, giving it a name and the dev_t.

  3. sysfs: the device directory appears, with a dev file holding the major:minor text.

  4. devtmpfs: the kernel creates /dev/mychar, owned by root, mode 0600.

  5. uevent: the kernel sends an event describing the new device to userspace.

  6. Policy: udev (or mdev) matches a rule and adjusts the mode, group or symlinks.

On a small BusyBox system there is no udev. The lightweight replacement is mdev, a BusyBox applet. At boot you scan the existing devices once, and for hotplug you tell the kernel to call it:

sh
mdev -s
echo /sbin/mdev > /proc/sys/kernel/hotplug

mdev -s walks /sys/class, reads each dev file, and creates the matching nodes. It reads simple rules from /etc/mdev.conf. The mechanism is the same as udev's — sysfs plus uevents — with a fraction of the code, which is why embedded products favour it.

The init uses three file-scope variables: the mychar device structure, mychar_devt for the numbers, and a class pointer declared as static struct class *mychar_class;. Here is the full init and exit, with the goto unwinding the previous lesson introduced applied to every registration step:

c
static int __init mychar_init(void)
{
    struct device *d;
    int err;

    err = alloc_chrdev_region(&mychar_devt, 0, 1, "mychar");
    if (err)
        return err;

    mychar.buffer = kzalloc(MYCHAR_CAP, GFP_KERNEL);
    if (!mychar.buffer) {
        err = -ENOMEM;
        goto err_region;
    }

    cdev_init(&mychar.cdev, &mychar_fops);
    mychar.cdev.owner = THIS_MODULE;
    err = cdev_add(&mychar.cdev, mychar_devt, 1);
    if (err)
        goto err_buffer;

    mychar_class = class_create("mychar");
    if (IS_ERR(mychar_class)) {
        err = PTR_ERR(mychar_class);
        goto err_cdev;
    }

    d = device_create(mychar_class, NULL, mychar_devt, NULL, "mychar");
    if (IS_ERR(d)) {
        err = PTR_ERR(d);
        goto err_class;
    }

    pr_info("mychar: ready, major %d minor %d\n",
        MAJOR(mychar_devt), MINOR(mychar_devt));
    return 0;

err_class:
    class_destroy(mychar_class);
err_cdev:
    cdev_del(&mychar.cdev);
err_buffer:
    kfree(mychar.buffer);
err_region:
    unregister_chrdev_region(mychar_devt, 1);
    return err;
}

static void __exit mychar_exit(void)
{
    device_destroy(mychar_class, mychar_devt);
    class_destroy(mychar_class);
    cdev_del(&mychar.cdev);
    kfree(mychar.buffer);
    unregister_chrdev_region(mychar_devt, 1);
}

Read the labels bottom to top: each undoes one more step than the last, and the exit function runs the same sequence in reverse. If device_create fails, the class is destroyed, the cdev deleted, the buffer freed and the numbers released, in that order. Note that the buffer is allocated before cdev_add, so the device is never live without its storage.

09

Inside chrdev_open: the cdev lifecycle

3 min read

How does the kernel get from a major:minor to your mychar_open? Every character-device inode is created with a default operations table whose only job is to perform the real open. That table's open handler is chrdev_open, in fs/char_dev.c. It runs before your code and does the dispatch.

The steps are:

  1. Look up the device number inode->i_rdev in cdev_map, a kernel-wide map from device numbers to cdev kobjects. The lookup is kobj_lookup.
  2. Recover the cdev from the returned kobject with container_of.
  3. Cache the result in inode->i_cdev, so later opens of the same inode skip the search.
  4. Take the operations table with fops_get, which also takes a reference on the module named by fops->owner.
  5. Replace the file's temporary operations with yours, and call your open method.
The chrdev_open dispatch pathopen(/dev/mychar)chrdev_openkobj_lookupsearchcdev_mapcachei_cdevfops_gettake modulerefcall driveropenopen(/dev/mychar)chrdev_openkobj_lookupsearchcdev_mapcachei_cdevfops_gettake modulerefcall driveropen
The chrdev_open dispatch path

If the lookup finds nothing — a node whose major nobody registered — chrdev_open returns -ENXIO, which is the "no such device or address" error you see when you cat a stale node left behind after rmmod. That single error code tells you the node exists but the driver does not.

The reference counting is what makes unloading safe. fops_get calls try_module_get on your module, so while any file is open the module's use count is above zero and rmmod refuses. When the last file closes, the matching fops_put drops the reference. This is the automatic version of the manual try_module_get/module_put pattern the previous lesson showed; setting .owner = THIS_MODULE is what enables it.

The cdev itself is a kobject, and kobjects have a release function that runs when their reference count reaches zero. The kobject starts with one reference from initialisation. cdev_add inserts it into the map; cdev_del removes it from the map and drops a reference. But an in-flight open holds its own reference, so the cdev is not destroyed the instant you delete it — it survives until the last user lets go.

Going deeperWhy cdev_del does not free your cdev

For a cdev you embedded in your own structure, the kobject's release function does not free the enclosing memory; it only drops the module reference. You own that memory, and you free it yourself after cdev_del, typically in your exit function. This is safe because the module reference count, held by every open file, prevents your exit function from running until all users have closed. For a cdev obtained from cdev_alloc, the release function does free the cdev itself, which is the difference between the two allocation styles. The rule to remember: cdev_del unregisters; it never frees memory you allocated.

This lifecycle explains a subtle ordering point in the exit function. You destroy the node and delete the cdev before freeing the buffer, but a process that already had the device open can still call read for a moment. That is fine: the module reference keeps your code and your static device structure resident until the last close, so the buffer pointer stays valid. What you must never do is free the buffer while a read could still be running, which is exactly what the reference count prevents.

Stale nodes are a debugging signal

If open returns -ENXIO, the node's numbers point at a cdev that is not registered. Either the module is not loaded, or it registered a different major than the node records. Compare /proc/devices with the node's ls -l numbers. With automatic node creation this class of bug disappears, because the node is removed when the device is destroyed.

10

Faults, compat and failure injection

6 min read

The copy helpers can sleep. If the user page being touched is swapped out, the page-fault handler must wait for it to come back from disk, and that wait sleeps. The helpers are marked so that a debug kernel checks this: with CONFIG_DEBUG_ATOMIC_SLEEP enabled, calling them from an interrupt handler or while holding a spinlock produces a warning, because sleeping there would deadlock. The rule is simple: user copies belong in process context with page faults enabled, never in atomic context. If you must touch user memory from a path that cannot sleep, the kernel provides pagefault_disable and the copy then fails fast with -EFAULT instead of waiting.

For large transfers, copying through a kernel buffer costs a full extra copy. Zero-copy paths avoid it. mmap lets the process map the device memory directly, and get_user_pages pins the process's pages so the kernel can access them without copying. The current get_user_pages takes a start address, a page count, flags such as FOLL_WRITE, and an output array of struct page pointers; it may sleep and must run in process context. For pins that live a long time, the modern variant is pin_user_pages, which marks the pages so the memory-management code can track them correctly. These are the tools behind high-throughput drivers such as video capture; a small sensor driver rarely needs them.

The other production concern is word size. A 64-bit kernel often runs 32-bit applications — a 32-bit ARM userspace on an arm64 board is a common embedded configuration. When such a process calls ioctl, the kernel prefers the method if you provide one; otherwise it falls back to unlocked_ioctl with the raw argument. The danger is that a struct passed by a 32-bit process has 4-byte pointers and longs where the 64-bit kernel expects 8, and different padding.

32-bit versus 64-bit ioctl argument layout32-bitargument64-bitargumentPointer4 bytes8 byteslong4 bytes8 bytes__u32 field4 bytes4 bytesPaddingcompactmay add gapsFixed-width fields keep both layouts identical
Why a 32-bit ioctl argument needs translation on a 64-bit kernel

The clean solution is to design ioctl arguments with fixed-width types (__u32, __u64) and no implicit longs, so the layout is identical in both worlds. Then point both methods at the same function:

c
static const struct file_operations mychar_fops = {
    .owner          = THIS_MODULE,
    .unlocked_ioctl = mychar_ioctl,
    .compat_ioctl   = mychar_ioctl,
    /* ... */
};

If a command must pass a pointer, the kernel offers a helper, compat_ptr_ioctl, that converts the 32-bit pointer argument and forwards to your native handler. If the layouts genuinely differ, you write a real compat handler that translates field by field. The ioctl commands themselves are the subject of the next lesson; the point here is that the compat decision is part of designing the interface, not an afterthought.

Finally, the failure paths. Your -ENOMEM and -EFAULT branches are the ones least likely to run in normal testing, and most likely to be wrong. The kernel can force them to run. With CONFIG_FAULT_INJECTION and CONFIG_FAULT_INJECTION_DEBUG_FS enabled, plus the specific options CONFIG_FAILSLAB and CONFIG_FAULT_INJECTION_USERCOPY, the kernel exposes controllers through debugfs, a debugging filesystem mounted at /sys/kernel/debug/:

bash
mount -t debugfs none /sys/kernel/debug
cd /sys/kernel/debug/fail_usercopy
echo 100 > probability     # fail every eligible call
echo 1   > times           # ...once, then stop
cat /dev/mychar            # exercise the -EFAULT path

fail_usercopy makes copy_to_user and copy_from_user report failure; failslab makes kmalloc return NULL. The knobs include probability (0 to 100), times (how many failures, -1 for unlimited) and task-filter (restrict to a chosen process). Run your test harness with these armed and confirm the driver returns the right error and unwinds cleanly, rather than crashing or leaking.

Going deeperTesting the unwind, not just the happy path

A driver that loads fine but leaks the device number on a failed device_create is broken in a way normal testing never reveals. Arm failslab with a low probability and load and unload the module in a loop; each forced allocation failure exercises one more goto label. Check /proc/devices after each failed load to confirm the number was released, and watch for stale nodes. This is the same discipline as the previous lesson's forced init failure, now applied to every registration step of a real driver.

The common mistakes, with their symptoms:

  • open returns -ENXIO. Cause: a stale node whose major no driver registers. Diagnose: compare ls -l /dev/mychar with /proc/devices. Fix: remove the stale node, or use automatic creation so it disappears with the driver.
  • read or write returns -EFAULT on a valid-looking buffer. Cause: the buffer is in kernel space, or the pointer was copied wrong, or a __user address was dereferenced directly. Diagnose: check that you used the copy helpers and that the address came from the method argument, not a kernel allocation. Fix: route every user transfer through copy_to_user/copy_from_user.
  • cat prints nothing, or prints stale data. Cause: read returns 0 too early, or size is never updated on write. Diagnose: strace the read and check the returned counts against what you wrote. Fix: update size when a write extends the data, and return 0 only at or past size.
  • A partial write is reported as an error. Cause: returning -EINVAL when count exceeds the remaining space instead of clamping. Diagnose: write a buffer larger than the free space and read the return value. Fix: clamp to the space available and return the count accepted.
  • rmmod refuses with "module in use" after every client exited. Cause: a descriptor is still open somewhere, or a manual module reference was taken and never dropped. Diagnose: read the use count in lsmod, look for a lingering open descriptor, and check for an unbalanced try_module_get. Fix: close the descriptor or drop the reference in release; with .owner set the VFS balances open and release for you.
  • The two-argument class_create will not compile. Cause: code copied from a pre-6.4 source. Diagnose: read the macro error. Fix: pass only the name.
11

Try it

1 min read

Do the lab for this session: write the mychar driver with a kmalloc buffer and correct read, write and llseek return codes, then add class_create and device_create so /dev/mychar appears automatically. Test it with echo, cat and dd, and build a scripted harness that forces partial reads and end-of-file, verifying the exact byte counts with strace. Finish with the practice pack, which drills the return-value contract, the copy helpers and the registration sequence without repeating the lab steps.

Key takeaways

  • A device node stores only a type and a major:minor pair; the kernel uses the major to find the cdev and its file_operations.
  • alloc_chrdev_region reserves numbers, cdev_init and cdev_add connect them to your operations, and the device is live the moment cdev_add returns.
  • struct inode is the file itself; struct file is one open instance, carrying f_pos and private_data.
  • Never dereference a __user pointer: copy_to_user and copy_from_user return the number of bytes NOT copied, and 0 means success.
  • read returns a byte count and 0 at end of file; write returns the count accepted; both advance the offset, and errors are negative errno.
  • container_of turns the inode's i_cdev pointer back into your device struct; private_data carries it to every later call.
  • class_create plus device_create makes devtmpfs create /dev/mychar automatically; udev or mdev then fixes permissions.
  • kmalloc with GFP_KERNEL may sleep; GFP_ATOMIC is for atomic context; every init step needs a matching goto unwind.

Reflect

  1. Explain to a colleague, in two sentences: explain how major and minor numbers route a system call to a driver, and allocate them with alloc_chrdev_region
  2. Which objective are you least sure about? Re-read that section, then do its exercise in the practice pack.
  3. What surprised you when you ran the commands yourself?

On a real board

Repeat the key commands on your Raspberry Pi or lab board over SSH or the serial console. Note anything that behaves differently from your PC, such as missing tools, a BusyBox shell or a read-only filesystem.

Practise this lessonExercises, quiz, interview preparation and spaced review

References and further reading

Official documentation first. Links checked when the lesson was published.

Find your next step

↑ ↓ to move · Enter to open · Esc to close