Why devices look like files
3 min readThe 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 a device accessed as a stream of bytes through a file, like a serial port or a sensor, with no fixed block size 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 a special file, usually under /dev, that stores a type and a major:minor pair instead of data. 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:
ls -l /dev/null /dev/ttyS0 /dev/sda
Typical output (yours will differ):
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.
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.
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.
Device numbers: major, minor and dev_t
4 min readInside the kernel the pair lives in a the kernel's 32-bit type holding a device number, with 12 bits for the major and 20 for the minor. 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:
#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.
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:
cat /proc/devices
Typical output (yours will differ):
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:
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:
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:
void unregister_chrdev_region(dev_t first, unsigned int count);
A typical init fragment looks like this:
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.
cdev and file_operations: wiring a driver
4 min readA the kernel structure that represents one character device and binds a range of device numbers to a set of file operations is defined in <linux/cdev.h>. Its fields are few:
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 the kernel's base object carrying a name, a parent and a reference count, embedded in structures like cdev to give them a shared lifecycle; 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 a table of function pointers, one per file system call, that the kernel calls when a process operates on the device is defined in <linux/fs.h>. It is large, but every field is optional. For this lesson you need six:
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:
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.
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.
Reserve numbers:
alloc_chrdev_regionhands back a free major and the first minor.Prepare state: allocate the buffer and fill the device structure that embeds the cdev.
Init the cdev:
cdev_initbinds yourfile_operationstable to the embedded cdev.Set the owner: assign
cdev.owner = THIS_MODULEso the module cannot be unloaded while in use.Publish:
cdev_addmaps the number range to the cdev; from this instant the device answers calls.Create the node:
class_createanddevice_createmake/dev/mycharappear, covered later.
open, release and per-device state
4 min readWhen a process opens /dev/mychar, the kernel passes your open method two pointers:
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:
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 a macro that, given a pointer to a member, returns a pointer to the structure that contains it does the conversion safely:
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:
struct mychar_dev *dev = file->private_data;
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.
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:
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.
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.
Crossing the boundary: safe user copies
4 min readThe 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>:
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.
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:
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.
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.
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.
read and write: the return-value contract
6 min readThe prototypes are:
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
countmeans the whole request was served. - A positive value smaller than
countmeans a partial transfer. This is normal, not an error; well-written callers loop until they have what they need. The C library'sfreaddoes 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-EFAULTfor a bad buffer or-EINVALfor 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>:
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 Get Free Pages masks passed to kernel allocators that say whether the call may sleep and which memory zones to use. 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:
#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:
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:
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.
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.
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.
llseek, offsets and proving it with strace
4 min readThe llseek method implements the lseek system call:
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:
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.
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:
printf 'abcdefghij' > /dev/mychar
strace -e trace=openat,read,close dd if=/dev/mychar bs=4 count=3
Typical output (yours will differ):
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:
strace -e trace=lseek,read dd if=/dev/mychar bs=1 skip=3 count=2
Typical output (yours will differ):
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.
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.
/dev nodes: mknod, devtmpfs and the class API
6 min readEverything 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:
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):
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 a kernel-maintained filesystem mounted on /dev that creates a node for every registered device automatically 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:
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 the userspace daemon that receives device events and adjusts node permissions, ownership and symlinks according to rules.
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>:
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.
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:
cat /sys/class/mychar/mychar/dev # for example 250:0
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:
# /etc/udev/rules.d/99-mychar.rules
KERNEL=="mychar", MODE="0660", GROUP="plugdev"
After editing rules, reload and re-trigger them:
sudo udevadm control --reload-rules
sudo udevadm trigger
Class:
class_create("mychar")creates the class directory under /sys/class.Device:
device_createregisters a device with the driver core, giving it a name and the dev_t.sysfs: the device directory appears, with a
devfile holding the major:minor text.devtmpfs: the kernel creates
/dev/mychar, owned by root, mode 0600.uevent: the kernel sends an event describing the new device to userspace.
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:
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:
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.
Inside chrdev_open: the cdev lifecycle
3 min readHow 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:
- Look up the device number
inode->i_rdevincdev_map, a kernel-wide map from device numbers to cdev kobjects. The lookup iskobj_lookup. - Recover the cdev from the returned kobject with
container_of. - Cache the result in
inode->i_cdev, so later opens of the same inode skip the search. - Take the operations table with
fops_get, which also takes a reference on the module named byfops->owner. - Replace the file's temporary operations with yours, and call your
openmethod.
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.
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.
Faults, compat and failure injection
6 min readThe 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 the file operation a 64-bit kernel calls for ioctl requests from a 32-bit process, so arguments can be translated 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.
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:
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/:
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/mycharwith/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
__useraddress 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 throughcopy_to_user/copy_from_user. - cat prints nothing, or prints stale data. Cause: read returns 0 too early, or
sizeis never updated on write. Diagnose:stracethe read and check the returned counts against what you wrote. Fix: updatesizewhen a write extends the data, and return 0 only at or pastsize. - A partial write is reported as an error. Cause: returning
-EINVALwhencountexceeds 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 unbalancedtry_module_get. Fix: close the descriptor or drop the reference in release; with.ownerset 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.
Try it
1 min readDo 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
- 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
- Which objective are you least sure about? Re-read that section, then do its exercise in the practice pack.
- 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.
References and further reading
- Official docsLinux kernel documentation: the driver model
- Official docsioctl based interfaces
- Official docsFault injection capabilities
- Man pageread(2) — Linux manual page
- Man pagelseek(2) — Linux manual page
- ArticleBootlin Linux kernel and driver development training slides
Official documentation first. Links checked when the lesson was published.