Vizualizare sursă pentru „OS Lab 11 - Linux Kernel Modules”

De la WikiLabs

← OS Lab 11 - Linux Kernel Modules

Nu aveți permisiunea să modificați această pagină, din următorul motiv:

---

Puteți vizualiza și copia sursa acestei pagini.

<span id="objectives"></span> == Objectives == Upon completion of this lab, you will be able to: * Explain the kernel module lifecycle and how loadable modules extend kernel functionality without requiring a reboot or kernel recompilation. * Understand the miscdevice framework for creating character devices that appear in <code>/dev/</code> and respond to file operations. * Implement proper kernel-space buffer management with mutex-based synchronization to handle concurrent access safely. * Use the ioctl() interface to pass configuration structures between userspace and kernel space, enabling device-specific operations beyond standard read/write. * Apply safe data transfer techniques using copy_to_user() and copy_from_user() to respect memory protection boundaries. * Implement byte transformations (case conversion, character filtering) that execute in kernel context during write operations. * Debug kernel code using printk() and interpret kernel log messages to diagnose issues. * Connect kernel programming concepts to previous labs: device files (Lab 2), system calls (Lab 3), IPC mechanisms (Lab 6), and kernel primitives (Labs 7-10). <span id="introduction"></span> == Introduction == <span id="what-youll-build-the-superpipe-device"></span> === What You'll Build: The Superpipe Device === You'll implement a loadable kernel module called '''superpipe''' that creates a character device at <code>/dev/superpipe</code>. This device acts like a regular pipe with a twist: it can transform data as it passes through. '''How it works:''' # Userspace writes data to <code>/dev/superpipe</code> (normal <code>write()</code> syscall) # Your kernel module receives the data, applies a transformation (uppercase, lowercase, filter vowels, etc.), and stores it in a kernel buffer # Userspace reads data from <code>/dev/superpipe</code> (normal <code>read()</code> syscall) # Your kernel module returns the transformed data # Userspace configures the transformation mode using <code>ioctl()</code> (passing configuration structures) '''Example usage:''' <syntaxhighlight lang="bash"># Set transformation to uppercase via ioctl ./test_superpipe set_mode upper # Write lowercase text echo "hello world" > /dev/superpipe # Read back - gets uppercase version cat /dev/superpipe # Output: HELLO WORLD</syntaxhighlight> This demonstrates core kernel programming concepts: * '''Device registration:''' Creating a device file that appears in <code>/dev/</code> * '''File operations:''' Implementing the kernel side of open, read, write, close * '''Memory management:''' Allocating kernel buffers with <code>kmalloc()</code>, using <code>kfree()</code> * '''Data transfer:''' Safely moving data between user and kernel space * '''Synchronization:''' Using mutexes to protect shared data from concurrent access * '''ioctl interface:''' Passing configuration structures for device-specific operations * '''Transform-on-write:''' Applying byte transformations as data enters the kernel <span id="prerequisites"></span> == Prerequisites == <span id="system-requirements"></span> === System Requirements === '''Operating System:''' Linux-based system with kernel 5.x or 6.x Check your kernel version: <syntaxhighlight lang="bash">uname -r</syntaxhighlight> If you're running kernel 4.x or older, you may encounter compatibility issues with some kernel APIs used in this lab. '''Kernel Headers:''' You must have kernel headers installed that match your running kernel. The headers provide the necessary definitions and build infrastructure for compiling kernel modules. '''Build Tools:''' GCC compiler and make utility for building the module. '''Privileges:''' Root access via <code>sudo</code> is required for loading/unloading modules and accessing device files. '''Disk Space:''' At least 500MB free for kernel headers and build artifacts. '''IMPORTANT: Work in a Virtual Machine''' Kernel programming is different from userspace programming. Bugs in kernel code can cause kernel panics, system freezes, or data corruption. A simple null pointer dereference that would segfault in userspace can crash your entire system in kernel space. Therefore, it is '''strongly recommended''' to work in a virtual machine (VirtualBox, VMware, QEMU, or similar). This way, if your module crashes the kernel, you can simply restart the VM without affecting your host system. <span id="required-packages"></span> === Required Packages === Install the necessary packages: <syntaxhighlight lang="bash">sudo apt update sudo apt install -y \ build-essential \ linux-headers-$(uname -r) \ vim</syntaxhighlight> '''Package descriptions:''' * <code>build-essential</code>: Meta-package that installs GCC, make, and other compilation tools * <code>linux-headers-$(uname -r)</code>: Kernel header files matching your running kernel version * <code>vim</code>: Text editor (or use your preferred editor) '''Verify kernel headers installation:''' <syntaxhighlight lang="bash">ls -l /lib/modules/$(uname -r)/build</syntaxhighlight> This should show a symbolic link pointing to the kernel build directory (usually in <code>/usr/src/</code>). If this directory doesn't exist, your kernel headers are not properly installed. <span id="theoretical-background"></span> == Theoretical Background == <span id="kernel-modules-extending-the-kernel-dynamically"></span> === Kernel Modules: Extending the Kernel Dynamically === <span id="what-is-a-kernel-module"></span> ==== What is a Kernel Module? ==== The Linux kernel is the core of the operating system—it manages hardware, enforces security, schedules processes, and provides the abstractions (files, processes, sockets) that userspace programs rely on. But the kernel faces a design challenge: it must support thousands of different hardware devices, filesystems, network protocols, and features. If every possible driver and feature were compiled directly into the kernel, the kernel image would be enormous, and systems would waste memory loading features they never use. Linux solves this with '''loadable kernel modules'''—pieces of code that can be dynamically loaded into the running kernel and unloaded when no longer needed. Think of modules as plugins for the kernel. '''Benefits of kernel modules:''' # '''Flexibility:''' Load only the drivers and features you actually need # '''Development speed:''' Test kernel code without rebooting # '''Modularity:''' Separate concerns (network drivers, filesystem support, etc.) into independent modules # '''Distribution:''' Ship proprietary drivers separately from the GPL-licensed kernel # '''Memory efficiency:''' Don't waste RAM on unused features '''Examples of kernel modules:''' <syntaxhighlight lang="bash">lsmod</syntaxhighlight> This command lists currently loaded modules. You'll see entries like: * <code>nvidia</code> - NVIDIA graphics driver * <code>ext4</code> - ext4 filesystem support * <code>iwlwifi</code> - Intel wireless driver * <code>bluetooth</code> - Bluetooth protocol support Each of these started as a <code>.ko</code> file (kernel object) on disk and was loaded into the running kernel. <span id="module-lifecycle"></span> ==== Module Lifecycle ==== A kernel module progresses through a well-defined lifecycle: <pre>┌─────────────────────┐ │ Module Source │ module.c (your code) │ (.c file) │ └──────────┬──────────┘ │ Compilation (make) ↓ ┌─────────────────────┐ │ Module Binary │ module.ko (kernel object) │ (.ko file) │ Lives on disk └──────────┬──────────┘ │ insmod / modprobe ↓ ┌─────────────────────┐ │ Init Function │ module_init() runs │ Runs Once │ Allocates resources │ │ Registers device └──────────┬──────────┘ │ Success ↓ ┌─────────────────────┐ │ Module Loaded │ Module is active │ Functions Callable│ Handlers installed │ │ Device available └──────────┬──────────┘ │ rmmod ↓ ┌─────────────────────┐ │ Exit Function │ module_exit() runs │ Runs Once │ Frees resources │ │ Unregisters device └─────────────────────┘</pre> '''Key commands:''' * '''insmod''': Insert module (basic loader, requires full path) * '''rmmod''': Remove module (must not be in use) * '''lsmod''': List loaded modules * '''modprobe''': Smart loader (resolves dependencies, searches standard paths) * '''modinfo''': Display module information '''Example:''' <syntaxhighlight lang="bash"># Compile module make # Load module sudo insmod superpipe.ko # Verify loaded lsmod | grep superpipe # View module info modinfo superpipe.ko # Unload module sudo rmmod superpipe</syntaxhighlight> <span id="kernel-space-vs-user-space"></span> ==== Kernel Space vs. User Space ==== Modern operating systems divide memory into two distinct regions with different privilege levels: '''User Space:''' * Where normal applications run * Limited privileges * Cannot access hardware directly * Cannot access other processes' memory * Errors cause process to crash (segmentation fault), not system crash '''Kernel Space:''' * Where kernel code runs (including your module!) * Full privileges (can access all memory, all hardware) * Can execute privileged CPU instructions * Errors can crash the entire system (kernel panic) <pre>┌─────────────────────────────────────────────┐ │ User Space │ │ │ │ [Process 1] [Process 2] [Process 3] ... │ │ │ │ Limited privileges │ │ Protected memory │ │ Crash = segfault (only that process dies) │ │ │ └─────────────────┬───────────────────────────┘ │ System Call Interface │ (open, read, write, ioctl, ...) ┌─────────────────▼───────────────────────────┐ │ Kernel Space │ │ │ │ [Kernel Core] [Your Module] [Drivers] ... │ │ │ │ Full privileges │ │ Access to all memory │ │ Crash = kernel panic (entire system down) │ │ │ └─────────────────────────────────────────────┘</pre> '''Critical differences for kernel programming:''' {| class="wikitable" |- ! Aspect ! User Space ! Kernel Space |- | Memory allocation | <code>malloc()</code>, <code>free()</code> | <code>kmalloc()</code>, <code>kfree()</code> |- | Printing | <code>printf()</code> | <code>printk()</code> |- | Standard library | Full libc available | '''No libc!''' Only kernel functions |- | Floating point | Allowed | '''Forbidden''' (saves/restores FPU state manually) |- | Sleep/wait | Can block freely | Must use special functions |- | Error handling | Program crashes | System crashes |} '''Why these restrictions?''' The kernel is responsible for managing all system resources and mediating between competing processes. It cannot rely on any userspace code or libraries because it IS the foundation that everything else relies on. Additionally, the kernel must be extremely efficient—it gets invoked millions of times per second. <span id="character-devices-and-the-miscdevice-framework"></span> === Character Devices and the Miscdevice Framework === <span id="device-files-in-dev"></span> ==== Device Files in /dev/ ==== In Unix philosophy, &quot;everything is a file.&quot; This includes hardware devices. The <code>/dev/</code> directory contains special files that represent devices—when you read from or write to these files, you're actually communicating with hardware or kernel drivers. '''Examine your system:''' <syntaxhighlight lang="bash">ls -l /dev/</syntaxhighlight> You'll see entries like: <pre>crw-rw-rw- 1 root root 1, 3 Dec 19 10:00 null crw-rw-rw- 1 root root 1, 5 Dec 19 10:00 zero crw-rw-rw- 1 root root 1, 8 Dec 19 10:00 random crw-rw-rw- 1 root root 1, 9 Dec 19 10:00 urandom brw-rw---- 1 root disk 8, 0 Dec 19 10:00 sda crw------- 1 root root 10, 58 Dec 19 10:00 hw_random</pre> '''Decoding the first character:''' * <code>c</code> = character device * <code>b</code> = block device * <code>l</code> = symbolic link * <code>d</code> = directory <span id="character-devices-vs-block-devices"></span> ==== Character Devices vs. Block Devices ==== '''Character devices''' (c): * Data accessed as a stream of bytes * No random access (typically) * Examples: serial ports (<code>/dev/ttyS0</code>), terminals (<code>/dev/tty</code>), random number generator (<code>/dev/random</code>) * Used for devices where data flows sequentially '''Block devices''' (b): * Data accessed in fixed-size blocks (typically 512 bytes, 1kB or 4kB) * Random access supported * Examples: solid-state drives (<code>/dev/nvme0n1</code>), hard drives (<code>/dev/sda</code>), USB drives (<code>/dev/sdb</code>), loop devices * Used for storage devices with addressable blocks Our superpipe device is a '''character device''' because it operates on byte streams without random access. <span id="major-and-minor-numbers"></span> ==== Major and Minor Numbers ==== Every device file has two numbers associated with it: <pre>crw-rw-rw- 1 root root 1, 3 Dec 19 10:00 null ↑ ↑ Major Minor</pre> '''Major number:''' Identifies the driver * The kernel uses this to route operations to the correct driver * Example: Major 1 = memory devices (<code>/dev/null</code>, <code>/dev/zero</code>, <code>/dev/random</code>) * Example: Major 8 = SCSI disk devices (<code>/dev/sda</code>, <code>/dev/sdb</code>) '''Minor number:''' Identifies specific device instance within that driver * Interpreted by the driver, not the kernel * Example: <code>/dev/sda</code> (8,0), <code>/dev/sda1</code> (8,1), <code>/dev/sda2</code> (8,2) * The SCSI driver uses minor number to distinguish between disks and partitions <span id="the-miscdevice-framework"></span> ==== The Miscdevice Framework ==== Creating a character device traditionally requires: # Registering a major number with <code>register_chrdev()</code> # Implementing a full character device structure # Handling device creation in <code>/dev/</code> (or relying on udev) This is tedious for simple devices. The '''miscdevice''' framework simplifies this: '''Benefits:''' * '''Automatic major number:''' All miscdevices share major number 10 * '''Dynamic minor allocation:''' Kernel assigns minor numbers automatically * '''Simplified registration:''' Single function call to register * '''Automatic /dev/ creation:''' Device appears automatically when registered '''Perfect for:''' * Simple character devices * Pseudo-devices (devices not tied to hardware) * Control interfaces '''The miscdevice structure:''' <syntaxhighlight lang="c">#include <linux/miscdevice.h> struct miscdevice { int minor; /* Minor number (or MISC_DYNAMIC_MINOR) */ const char *name; /* Device name (creates /dev/<name>) */ const struct file_operations *fops; /* File operations */ /* ... other fields ... */ };</syntaxhighlight> '''Using miscdevice:''' <syntaxhighlight lang="c">static struct miscdevice my_device = { .minor = MISC_DYNAMIC_MINOR, /* Kernel assigns minor number */ .name = "mydevice", /* Creates /dev/mydevice */ .fops = &my_fops, /* Your file operations */ }; /* In module init */ misc_register(&my_device); /* Register device */ /* In module exit */ misc_deregister(&my_device); /* Unregister device */</syntaxhighlight> That's it! The device appears in <code>/dev/mydevice</code> and is ready to use. <span id="file-operations-the-kernel-side-of-system-calls"></span> === File Operations: The Kernel Side of System Calls === <span id="the-file_operations-structure"></span> ==== The file_operations Structure ==== When userspace makes system calls like <code>open()</code>, <code>read()</code>, or <code>write()</code> on your device file, the kernel needs to know which functions in your module to call. This mapping is provided by the <code>file_operations</code> structure. '''The structure (simplified):''' <syntaxhighlight lang="c">#include <linux/fs.h> struct file_operations { struct module *owner; /* Pointer to module (prevents unload while in use) */ /* Open/close */ int (*open)(struct inode *, struct file *); int (*release)(struct inode *, struct file *); /* Read/write */ ssize_t (*read)(struct file *, char __user *, size_t, loff_t *); ssize_t (*write)(struct file *, const char __user *, size_t, loff_t *); /* ioctl */ long (*unlocked_ioctl)(struct file *, unsigned int, unsigned long); /* ... many more operations (lseek, poll, mmap, etc.) ... */ };</syntaxhighlight> '''Example:''' <syntaxhighlight lang="c">static const struct file_operations my_fops = { .owner = THIS_MODULE, .open = my_open, .release = my_release, .read = my_read, .write = my_write, .unlocked_ioctl = my_ioctl, };</syntaxhighlight> You implement only the operations your device supports. Operations you don't implement default to appropriate behavior (typically returning -EINVAL or -ENOSYS). <span id="understanding-the-handlers"></span> ==== Understanding the Handlers ==== '''open handler:''' Called when userspace opens your device file. <syntaxhighlight lang="c">static int my_open(struct inode *inode, struct file *file) { /* Allocate per-file state, increment usage counters, etc. */ printk(KERN_INFO "Device opened\n"); return 0; /* Success */ }</syntaxhighlight> '''Parameters:''' * <code>inode</code>: Represents the device file on disk (contains major/minor numbers) * <code>file</code>: Represents an open file descriptor (contains file offset, flags, private_data) '''release handler:''' Called when userspace closes your device file. <syntaxhighlight lang="c">static int my_release(struct inode *inode, struct file *file) { /* Free resources, decrement counters, etc. */ printk(KERN_INFO "Device closed\n"); return 0; }</syntaxhighlight> '''Note:''' Called &quot;release&quot; not &quot;close&quot; because multiple file descriptors can point to the same open file (via <code>dup()</code> or <code>fork()</code>). Release is called when the last reference is closed. '''read handler:''' Called when userspace reads from your device. <syntaxhighlight lang="c">static ssize_t my_read(struct file *file, char __user *buffer, size_t count, loff_t *offset) { /* Copy data from kernel space to userspace buffer */ /* Return number of bytes read, 0 for EOF, negative for error */ }</syntaxhighlight> '''Parameters:''' * <code>file</code>: The open file * <code>buffer</code>: '''Userspace''' buffer (marked with <code>__user</code> annotation) * <code>count</code>: Number of bytes requested * <code>offset</code>: File offset (can be updated) '''Return value:''' * Positive: Number of bytes successfully read * 0: End of file * Negative: Error code '''write handler:''' Called when userspace writes to your device. <syntaxhighlight lang="c">static ssize_t my_write(struct file *file, const char __user *buffer, size_t count, loff_t *offset) { /* Copy data from userspace buffer to kernel space */ /* Return number of bytes written, negative for error */ }</syntaxhighlight> '''unlocked_ioctl handler:''' Called when userspace invokes ioctl() for device-specific operations. <syntaxhighlight lang="c">static long my_ioctl(struct file *file, unsigned int cmd, unsigned long arg) { /* Handle device-specific commands */ /* 'arg' can be a value or a pointer to userspace memory */ }</syntaxhighlight> We'll explore ioctl in detail in section 4.6. <span id="moving-data-between-kernel-and-user-space"></span> === Moving Data Between Kernel and User Space === <span id="why-we-cant-access-user-memory-directly"></span> ==== Why We Can't Access User Memory Directly ==== This is one of the most critical concepts in kernel programming and a common source of bugs for beginners. '''The problem:''' In userspace, when you have a pointer, you can just dereference it: <syntaxhighlight lang="c">char *str = "hello"; printf("%c", str[0]); /* Works fine in userspace */</syntaxhighlight> In kernel space, you '''cannot''' do this with pointers to userspace memory: <syntaxhighlight lang="c">/* WRONG - will crash the kernel! */ static ssize_t my_read(struct file *file, char __user *user_buffer, ...) { user_buffer[0] = 'A'; /* NEVER DO THIS! */ strcpy(user_buffer, kernel_data); /* NEVER DO THIS! */ }</syntaxhighlight> '''Why not?''' # '''Memory protection:''' User memory might not be mapped, might be swapped to disk, or might not exist at all (bad pointer) # '''Page faults:''' Accessing user memory can cause page faults, which need special handling in kernel context # '''Security:''' The kernel must validate that the user actually has permission to access that memory # '''MMU (Memory Management Unit):''' The CPU's MMU enforces that kernel code cannot directly access user address space '''What happens if you try?''' In the best case, you get a kernel oops (non-fatal kernel error). In the worst case, you corrupt memory and cause a kernel panic (crash). <span id="the-safe-way-copy_to_user-and-copy_from_user"></span> ==== The Safe Way: copy_to_user and copy_from_user ==== The kernel provides safe functions for transferring data between kernel and user space: '''copy_to_user:''' Copy from kernel to userspace <syntaxhighlight lang="c">#include <linux/uaccess.h> unsigned long copy_to_user(void __user *to, const void *from, unsigned long n);</syntaxhighlight> '''Parameters:''' * <code>to</code>: Destination in userspace (marked with <code>__user</code>) * <code>from</code>: Source in kernel space * <code>n</code>: Number of bytes to copy '''Return value:''' * 0: Success (all bytes copied) * Non-zero: Number of bytes that could NOT be copied (failure) '''Example:''' <syntaxhighlight lang="c">char kernel_buffer[100] = "Hello from kernel"; if (copy_to_user(user_buffer, kernel_buffer, strlen(kernel_buffer))) { return -EFAULT; /* Bad address - tell userspace */ }</syntaxhighlight> '''copy_from_user:''' Copy from userspace to kernel <syntaxhighlight lang="c">unsigned long copy_from_user(void *to, const void __user *from, unsigned long n);</syntaxhighlight> '''Parameters:''' * <code>to</code>: Destination in kernel space * <code>from</code>: Source in userspace (marked with <code>__user</code>) * <code>n</code>: Number of bytes to copy '''Return value:''' * 0: Success * Non-zero: Number of bytes that could NOT be copied '''Example:''' <syntaxhighlight lang="c">char kernel_buffer[100]; if (copy_from_user(kernel_buffer, user_buffer, count)) { return -EFAULT; /* Bad address */ }</syntaxhighlight> '''What these functions do:''' # Check that the user address is valid # Check that the user has permission to access that memory # Handle page faults if the memory is swapped out # Actually perform the copy # Return success/failure '''The __user annotation:''' The <code>__user</code> marker is a sparse (static analysis tool) annotation that helps catch bugs at compile time. It doesn't affect the generated code, but it helps ensure you're using the right functions. <span id="error-codes-communicating-failures"></span> ==== Error Codes: Communicating Failures ==== When something goes wrong in your kernel module, you communicate this to userspace by returning negative error codes. '''Common error codes:''' {| class="wikitable" |- ! Error Code ! Value ! Meaning ! When to use |- | <code>-EFAULT</code> | -14 | Bad address | copy_to_user/copy_from_user failed |- | <code>-EINVAL</code> | -22 | Invalid argument | Invalid ioctl command, bad parameter |- | <code>-ENOMEM</code> | -12 | Out of memory | kmalloc() failed |- | <code>-ENOSPC</code> | -28 | No space left | Device buffer full |- | <code>-ENODEV</code> | -19 | No such device | Device not found/initialized |- | <code>-EBUSY</code> | -16 | Device busy | Resource in use |- | <code>-EIO</code> | -5 | I/O error | Hardware error |} '''How to use:''' <syntaxhighlight lang="c">if (!buffer) { return -ENOMEM; /* Allocation failed */ } if (copy_from_user(buffer, user_ptr, len)) { return -EFAULT; /* Bad pointer from userspace */ } if (cmd != VALID_COMMAND) { return -EINVAL; /* Invalid command */ }</syntaxhighlight> Userspace sees these as errno values: <syntaxhighlight lang="c">/* Userspace code */ if (write(fd, data, len) < 0) { perror("write"); /* Prints "write: Bad address" for -EFAULT */ }</syntaxhighlight> <span id="synchronization-protecting-shared-data"></span> === Synchronization: Protecting Shared Data === <span id="the-concurrency-problem"></span> ==== The Concurrency Problem ==== Your kernel module can be accessed by multiple processes simultaneously. Consider this scenario: <pre>Time Process A Process B ---- --------------------- --------------------- 1 open(&quot;/dev/superpipe&quot;) 2 write(&quot;hello&quot;) open(&quot;/dev/superpipe&quot;) 3 [writing to buffer] write(&quot;world&quot;) 4 [writing to buffer] [writing to buffer] ← RACE! 5 [writing to buffer] ← DATA CORRUPTION!</pre> Without synchronization, both processes could write to the buffer simultaneously, resulting in garbled data, corrupted state, or kernel crashes. '''Types of concurrency:''' # '''Multiple processes:''' Different processes calling your module # '''Multiple threads:''' Threads in the same process # '''Interrupts:''' Interrupt handlers can preempt your code # '''Multiple CPUs:''' Code running simultaneously on different CPU cores '''The shared state problem:''' <syntaxhighlight lang="c">/* Global device state - shared by all processes */ static struct { char buffer[4096]; size_t len; } dev_state; /* UNSAFE - race condition! */ static ssize_t unsafe_write(...) { /* What if another process modifies dev_state.len right here? */ memcpy(&dev_state.buffer[dev_state.len], data, count); dev_state.len += count; /* Race! Another write could have happened */ }</syntaxhighlight> <span id="mutexes-in-the-kernel"></span> ==== Mutexes in the Kernel ==== A '''mutex''' (mutual exclusion lock) ensures that only one thread can access a critical section at a time. '''Declaring a mutex:''' <syntaxhighlight lang="c">#include <linux/mutex.h> static DEFINE_MUTEX(my_mutex); /* Declares and initializes */ /* Or for dynamic initialization: */ struct mutex my_mutex; mutex_init(&my_mutex);</syntaxhighlight> '''Using a mutex:''' <syntaxhighlight lang="c">/* Acquire lock - will sleep if already held */ mutex_lock(&my_mutex); /* Critical section - only one thread at a time */ /* Access shared data here */ /* Release lock */ mutex_unlock(&my_mutex);</syntaxhighlight> '''Interruptible locking:''' In syscall handlers (read, write, ioctl), use the interruptible version so users can interrupt with Ctrl+C: <syntaxhighlight lang="c">/* Try to acquire lock, but allow signals to interrupt */ if (mutex_lock_interruptible(&my_mutex)) { return -ERESTARTSYS; /* System call was interrupted */ } /* Critical section */ mutex_unlock(&my_mutex);</syntaxhighlight> '''Safe write example:''' <syntaxhighlight lang="c">static DEFINE_MUTEX(device_mutex); static ssize_t safe_write(struct file *file, const char __user *user_buffer, size_t count, loff_t *offset) { /* Acquire lock */ if (mutex_lock_interruptible(&device_mutex)) return -ERESTARTSYS; /* Critical section - safe from concurrent access */ if (dev_state.len + count > BUFFER_SIZE) { mutex_unlock(&device_mutex); return -ENOSPC; } if (copy_from_user(&dev_state.buffer[dev_state.len], user_buffer, count)) { mutex_unlock(&device_mutex); return -EFAULT; } dev_state.len += count; /* Release lock */ mutex_unlock(&device_mutex); return count; }</syntaxhighlight> '''Rules for mutex usage:''' # '''Always release:''' Every lock must have a corresponding unlock (even on error paths) # '''Short critical sections:''' Hold locks for the minimum time necessary # '''No sleeping with spinlocks:''' Don't use mutexes in interrupt context (use spinlocks instead) # '''Avoid deadlocks:''' Don't acquire multiple locks, or always acquire in the same order <span id="the-ioctl-interface-device-specific-commands"></span> === The ioctl Interface: Device-Specific Commands === <span id="what-is-ioctl"></span> ==== What is ioctl? ==== The standard file operations (<code>read</code>, <code>write</code>) are generic—they work the same way across all devices. But sometimes you need device-specific operations that don't fit the read/write model: * Configure a serial port's baud rate * Set video resolution on a graphics device * Enable a network interface * Set transformation mode on our superpipe device This is what <code>ioctl()</code> (input/output control) is for: device-specific commands that go beyond simple data transfer. '''Userspace signature:''' <syntaxhighlight lang="c">#include <sys/ioctl.h> int ioctl(int fd, unsigned long request, ...);</syntaxhighlight> '''Parameters:''' * <code>fd</code>: File descriptor * <code>request</code>: Command code (defined by driver) * <code>...</code>: Optional argument (pointer or value) '''Example usage:''' <syntaxhighlight lang="c">int fd = open("/dev/superpipe", O_RDWR); /* Simple command with no data */ ioctl(fd, SUPERPIPE_IOC_RESET); /* Command that passes a value */ int mode = TRANSFORM_UPPER; ioctl(fd, SUPERPIPE_IOC_SET_MODE, mode); /* Command that passes a structure */ struct superpipe_config cfg = { .mode = TRANSFORM_UPPER }; ioctl(fd, SUPERPIPE_IOC_SET_CONFIG, &cfg);</syntaxhighlight> <span id="defining-ioctl-commands"></span> ==== Defining ioctl Commands ==== ioctl commands are unsigned integers, but they're not arbitrary—they're constructed using macros that encode information about the command. '''Command encoding:''' <pre> Direction | Size of data | Magic | Sequence ____________|______________|_______|__________ | 2 bits | 14 bits | 8 bits | 8 bits | ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾</pre> '''The macros:''' <syntaxhighlight lang="c">#include <linux/ioctl.h> _IO(magic, number) /* No data transfer */ _IOR(magic, number, datatype) /* Read from device (copy_to_user) */ _IOW(magic, number, datatype) /* Write to device (copy_from_user) */ _IOWR(magic, number, datatype) /* Both read and write */</syntaxhighlight> '''Parameters:''' * <code>magic</code>: 8-bit magic number (identifies your driver, typically a character) * <code>number</code>: Command number (sequential numbering) * <code>datatype</code>: Type of data being transferred (for size encoding) '''Example:''' <syntaxhighlight lang="c">#define SUPERPIPE_IOC_MAGIC 'k' /* No data transfer */ #define SUPERPIPE_IOC_RESET _IO(SUPERPIPE_IOC_MAGIC, 0) /* Write an integer to device */ #define SUPERPIPE_IOC_SET_MODE _IOW(SUPERPIPE_IOC_MAGIC, 1, int) /* Read an integer from device */ #define SUPERPIPE_IOC_GET_MODE _IOR(SUPERPIPE_IOC_MAGIC, 2, int) /* Read and write a structure */ #define SUPERPIPE_IOC_CONFIG _IOWR(SUPERPIPE_IOC_MAGIC, 3, struct superpipe_config)</syntaxhighlight> '''Why use macros instead of simple numbers?''' # '''Type safety:''' Encodes the size of the data being transferred # '''Direction:''' Indicates whether data flows to/from device # '''Collision avoidance:''' Magic number helps avoid conflicts with other drivers # '''Self-documenting:''' The macro tells you what the command does <span id="passing-structures-with-ioctl"></span> ==== Passing Structures with ioctl ==== For complex configuration, passing structures is more flexible than passing simple values. '''Define the structure (in UAPI header, shared between kernel and userspace):''' <syntaxhighlight lang="c">/* superpipe_uapi.h */ struct superpipe_ioctl_config { __u32 mode; /* Transformation mode */ __u32 flags; /* Additional flags (for future expansion) */ };</syntaxhighlight> '''Note:''' Use <code>__u32</code>, <code>__u64</code>, etc. (double underscore types) in UAPI headers. These are guaranteed to have the same size in both 32-bit and 64-bit architectures. '''Define the ioctl command:''' <syntaxhighlight lang="c">#define SUPERPIPE_IOC_SET_CONFIG _IOW(SUPERPIPE_IOC_MAGIC, 1, struct superpipe_ioctl_config) #define SUPERPIPE_IOC_GET_CONFIG _IOR(SUPERPIPE_IOC_MAGIC, 2, struct superpipe_ioctl_config)</syntaxhighlight> '''Userspace usage:''' <syntaxhighlight lang="c">#include "superpipe_uapi.h" int fd = open("/dev/superpipe", O_RDWR); struct superpipe_ioctl_config cfg = { .mode = TRANSFORM_UPPER, .flags = 0, }; if (ioctl(fd, SUPERPIPE_IOC_SET_CONFIG, &cfg) < 0) { perror("ioctl"); }</syntaxhighlight> '''Kernel implementation:''' <syntaxhighlight lang="c">static long superpipe_ioctl(struct file *file, unsigned int cmd, unsigned long arg) { struct superpipe_ioctl_config cfg; switch (cmd) { case SUPERPIPE_IOC_SET_CONFIG: /* Copy structure from userspace */ if (copy_from_user(&cfg, (void __user *)arg, sizeof(cfg))) return -EFAULT; /* Validate */ if (cfg.mode >= TRANSFORM_MAX) return -EINVAL; /* Apply configuration */ device_state.mode = cfg.mode; return 0; case SUPERPIPE_IOC_GET_CONFIG: /* Prepare structure */ cfg.mode = device_state.mode; cfg.flags = 0; /* Copy to userspace */ if (copy_to_user((void __user *)arg, &cfg, sizeof(cfg))) return -EFAULT; return 0; default: return -EINVAL; /* Unknown command */ } }</syntaxhighlight> '''Key points:''' # '''arg is a userspace pointer:''' Must use copy_from_user/copy_to_user # '''Validate inputs:''' Check that values are in valid ranges # '''Return 0 on success:''' Negative error code on failure # '''Handle unknown commands:''' Return -EINVAL for commands you don't recognize <span id="the-uapi-header-sharing-definitions"></span> === The UAPI Header: Sharing Definitions === <span id="what-is-uapi"></span> ==== What is UAPI? ==== UAPI stands for &quot;User API&quot;—definitions that are shared between kernel code and userspace code. In the Linux kernel source tree, these headers live in <code>include/uapi/linux/</code>. '''Why separate UAPI headers?''' # '''Single source of truth:''' Define ioctl commands, structures, constants once # '''Consistency:''' Kernel and userspace always agree on command values and structure layouts # '''Stability:''' UAPI is part of the kernel's stable ABI—once defined, it shouldn't change (backward compatibility) # '''Clear boundary:''' Clearly separates internal kernel definitions from external interface '''What goes in a UAPI header?''' * ioctl command definitions * Structure definitions for data passed between kernel and userspace * Constant definitions (modes, flags, limits) * Enum definitions used in the interface '''What does NOT go in a UAPI header?''' * Internal kernel structures * Function declarations * Kernel-only constants '''Our UAPI header structure:''' <syntaxhighlight lang="c">/* superpipe_uapi.h - Shared between kernel and userspace */ #ifndef _SUPERPIPE_UAPI_H #define _SUPERPIPE_UAPI_H #include <linux/ioctl.h> #include <linux/types.h> /* For __u32, __u64, etc. */ /* Transform modes */ #define SUPERPIPE_MODE_NONE 0 #define SUPERPIPE_MODE_UPPER 1 #define SUPERPIPE_MODE_LOWER 2 #define SUPERPIPE_MODE_DROP_VOWELS 3 #define SUPERPIPE_MODE_DROP_SPACES 4 /* Configuration structure */ struct superpipe_ioctl_config { __u32 mode; /* One of SUPERPIPE_MODE_* */ __u32 flags; /* Reserved for future use */ }; /* ioctl commands */ #define SUPERPIPE_IOC_MAGIC 'k' #define SUPERPIPE_IOC_SET_CONFIG _IOW(SUPERPIPE_IOC_MAGIC, 1, struct superpipe_ioctl_config) #define SUPERPIPE_IOC_GET_CONFIG _IOR(SUPERPIPE_IOC_MAGIC, 2, struct superpipe_ioctl_config) #define SUPERPIPE_IOC_RESET _IO(SUPERPIPE_IOC_MAGIC, 3) #endif /* _SUPERPIPE_UAPI_H */</syntaxhighlight> '''Using in kernel code:''' <syntaxhighlight lang="c">/* superpipe.c */ #include "superpipe_uapi.h" static long superpipe_ioctl(...) { struct superpipe_ioctl_config cfg; switch (cmd) { case SUPERPIPE_IOC_SET_CONFIG: /* Use the definitions from UAPI header */ if (copy_from_user(&cfg, ...)) return -EFAULT; if (cfg.mode == SUPERPIPE_MODE_UPPER) { /* ... */ } break; } }</syntaxhighlight> '''Using in userspace code:''' <syntaxhighlight lang="c">/* test_superpipe.c */ #include "superpipe_uapi.h" /* Same header! */ int main() { struct superpipe_ioctl_config cfg = { .mode = SUPERPIPE_MODE_UPPER, .flags = 0, }; ioctl(fd, SUPERPIPE_IOC_SET_CONFIG, &cfg); }</syntaxhighlight> '''Benefits:''' * Change command codes in one place * Add new modes without editing two files * Compiler catches mismatches automatically * Standard Linux kernel practice <span id="design-the-superpipe-device"></span> == Design: The Superpipe Device == <span id="device-behavior"></span> === Device Behavior === The superpipe device implements a buffered pipe with configurable byte transformations. Here's the complete behavior specification: '''Basic operations:''' # '''Write:''' Userspace writes data → Kernel applies transformation → Stores in buffer # '''Read:''' Kernel copies data from buffer → Returns to userspace → Removes from buffer (consuming read) # '''ioctl:''' Userspace sends configuration → Kernel updates transformation mode '''Buffer properties:''' * '''Size:''' 4096 bytes (4KB) * '''Type:''' Circular/linear buffer (your choice) * '''Behavior when full:''' write() returns -ENOSPC * '''Behavior when empty:''' read() returns 0 (EOF) '''Transformation timing:''' Data is transformed '''during write''', not during read. '''Example flow:''' <pre>Time Action Buffer State Mode ---- ------------------------------ ----------------- ----------- 1 ioctl(SET_CONFIG, NONE) [] NONE 2 write(&quot;Hello&quot;) [&quot;Hello&quot;] NONE 3 read() → &quot;Hello&quot; [] NONE 4 ioctl(SET_CONFIG, UPPER) [] UPPER 5 write(&quot;world&quot;) [&quot;WORLD&quot;] UPPER 6 read() → &quot;WORLD&quot; [] UPPER 7 ioctl(SET_CONFIG, NONE) [] NONE 8 write(&quot;test&quot;) [&quot;test&quot;] NONE 9 ioctl(SET_CONFIG, UPPER) [&quot;test&quot;] UPPER (mode change doesn't affect existing data!) 10 write(&quot;NEW&quot;) [&quot;testNEW&quot;] UPPER 11 read() → &quot;testNEW&quot; [] UPPER</pre> '''Key insight from example:''' At time 9, we change mode to UPPER, but the existing data &quot;test&quot; stays lowercase. Only NEW data (written after the mode change) gets transformed. This is a consequence of transform-on-write: once data is in the buffer, its transformation is &quot;baked in.&quot; '''Implementation:''' <syntaxhighlight lang="c">/* Pseudo-code for transform-on-write */ static ssize_t superpipe_write(...) { char *write_position; size_t final_len; /* Copy from userspace to buffer */ write_position = buffer + buffer_len; copy_from_user(write_position, user_data, count); /* Transform in-place immediately */ final_len = count; /* Start with bytes copied */ switch (mode) { case TRANSFORM_UPPER: transform_upper(write_position, count); /* final_len stays count - no compaction */ break; case TRANSFORM_DROP_VOWELS: final_len = transform_drop_vowels(write_position, count); /* final_len may be less than count - data compacted */ break; } /* Update buffer length by actual stored bytes */ buffer_len += final_len; /* Return bytes consumed from user, not bytes stored */ return count; /* Standard UNIX semantics */ }</syntaxhighlight> '''Note for filtering transforms:''' When dropping characters (vowels, spaces), the amount of data stored may be less than the amount written. The write() call returns the actual number of bytes stored after filtering. <span id="device-state-structure"></span> === Device State Structure === All device state is stored in a single global structure: <syntaxhighlight lang="c">/* Transform modes - internal to kernel */ enum transform_mode { TRANSFORM_NONE = 0, TRANSFORM_UPPER, TRANSFORM_LOWER, TRANSFORM_DROP_VOWELS, TRANSFORM_DROP_SPACES, TRANSFORM_MAX /* Sentinel for validation */ }; /* Device state */ struct superpipe_device { char *buffer; /* Kernel buffer (allocated with kmalloc) */ size_t buffer_len; /* Current amount of data in buffer */ struct mutex lock; /* Protects buffer and mode from concurrent access */ enum transform_mode mode; /* Current transformation mode */ }; static struct superpipe_device dev_state;</syntaxhighlight> '''Design notes:''' '''Global state:''' We use a single global structure because we have exactly one device instance (<code>/dev/superpipe</code>). All opens share the same buffer and transformation mode. '''Alternative designs:''' * '''Per-file state:''' Each open() could have independent buffer and mode (use file-&gt;private_data) * '''Embedded miscdevice:''' Embed miscdevice in device structure, use container_of() to access For this lab, global state is simpler and clearer for learning. '''Initialization:''' <syntaxhighlight lang="c">static int __init superpipe_init(void) { /* Allocate buffer */ dev_state.buffer = kmalloc(BUFFER_SIZE, GFP_KERNEL); if (!dev_state.buffer) return -ENOMEM; /* Initialize state */ dev_state.buffer_len = 0; dev_state.mode = TRANSFORM_NONE; mutex_init(&dev_state.lock); /* Register device */ return misc_register(&superpipe_miscdev); }</syntaxhighlight> '''Cleanup:''' <syntaxhighlight lang="c">static void __exit superpipe_exit(void) { misc_deregister(&superpipe_miscdev); kfree(dev_state.buffer); }</syntaxhighlight> <span id="reference-implementation-superpipe-with-uppercase-transform"></span> == Reference Implementation: Superpipe with Uppercase Transform == In this section, we present a complete, working kernel module that implements the superpipe device with support for two transformation modes: NONE (pass-through) and UPPER (convert to uppercase). This reference implementation demonstrates all the concepts covered in the theoretical background. Study this code carefully. The exercise at the end asks you to extend it to support additional transformations. <span id="uapi-header-superpipe_uapih"></span> === UAPI Header: superpipe_uapi.h === This header is shared between kernel code and userspace programs. <syntaxhighlight lang="c">/* superpipe_uapi.h - User API definitions for superpipe device */ #ifndef _SUPERPIPE_UAPI_H #define _SUPERPIPE_UAPI_H #include <linux/ioctl.h> #include <linux/types.h> /* * Transform modes * These constants identify which transformation to apply */ #define SUPERPIPE_MODE_NONE 0 /* Pass through unchanged */ #define SUPERPIPE_MODE_UPPER 1 /* Convert to uppercase */ /* * Configuration structure * Passed between userspace and kernel via ioctl */ struct superpipe_ioctl_config { __u32 mode; /* One of SUPERPIPE_MODE_* constants */ __u32 flags; /* Reserved for future use (set to 0) */ }; /* * ioctl commands * Magic number 'k' chosen arbitrarily (could be any character) */ #define SUPERPIPE_IOC_MAGIC 'k' /* Set transformation configuration (write config to device) */ #define SUPERPIPE_IOC_SET_CONFIG _IOW(SUPERPIPE_IOC_MAGIC, 1, struct superpipe_ioctl_config) /* Get current configuration (read config from device) */ #define SUPERPIPE_IOC_GET_CONFIG _IOR(SUPERPIPE_IOC_MAGIC, 2, struct superpipe_ioctl_config) /* Reset device (clear buffer) */ #define SUPERPIPE_IOC_RESET _IO(SUPERPIPE_IOC_MAGIC, 3) #endif /* _SUPERPIPE_UAPI_H */</syntaxhighlight> <span id="kernel-module-superpipe_refc"></span> === Kernel Module: superpipe_ref.c === This is the complete kernel module implementation. <syntaxhighlight lang="c">/* superpipe_ref.c - Reference implementation of superpipe device */ #include <linux/module.h> /* Core module functionality */ #include <linux/kernel.h> /* Kernel types and macros */ #include <linux/init.h> /* module_init, module_exit */ #include <linux/miscdevice.h> /* Miscdevice framework */ #include <linux/fs.h> /* File operations structure */ #include <linux/uaccess.h> /* copy_to_user, copy_from_user */ #include <linux/mutex.h> /* Mutex synchronization */ #include <linux/slab.h> /* kmalloc, kfree */ #include <linux/ctype.h> /* toupper, tolower */ #include "superpipe_uapi.h" /* Shared UAPI definitions */ #define DEVICE_NAME "superpipe" #define BUFFER_SIZE 4096 /* * Internal transform modes * Maps to UAPI constants but kept internal to module */ enum transform_mode { TRANSFORM_NONE = SUPERPIPE_MODE_NONE, TRANSFORM_UPPER = SUPERPIPE_MODE_UPPER, TRANSFORM_MAX /* Sentinel for validation */ }; /* * Device state structure * All state is stored here (single global instance) */ struct superpipe_device { char *buffer; /* Dynamically allocated kernel buffer */ size_t buffer_len; /* Current amount of data in buffer */ struct mutex lock; /* Protects all fields from concurrent access */ enum transform_mode mode; /* Current transformation mode */ }; /* Global device state (single instance for one device) */ static struct superpipe_device dev_state; /* * transform_upper - Apply uppercase transformation in-place * @data: Pointer to data to transform * @len: Length of data in bytes * * Converts all ASCII lowercase letters (a-z) to uppercase (A-Z). * Other characters pass through unchanged. */ static void transform_upper(char *data, size_t len) { size_t i; for (i = 0; i < len; i++) { if (islower(data[i])) { data[i] = toupper(data[i]); } } } /* * superpipe_open - Handle device open * @inode: Inode representing the device file * @file: File structure for this open * * Called when userspace opens /dev/superpipe. * We don't need to do anything special, just log the event. * * Return: 0 on success */ static int superpipe_open(struct inode *inode, struct file *file) { printk(KERN_INFO "superpipe: Device opened by process %d (%s)\n", current->pid, current->comm); return 0; } /* * superpipe_release - Handle device close * @inode: Inode representing the device file * @file: File structure being closed * * Called when userspace closes /dev/superpipe. * Cleanup would go here if we allocated per-file resources. * * Return: 0 on success */ static int superpipe_release(struct inode *inode, struct file *file) { printk(KERN_INFO "superpipe: Device closed by process %d (%s)\n", current->pid, current->comm); return 0; } /* * superpipe_read - Handle read operation * @file: File structure * @user_buffer: Userspace buffer to copy data into * @count: Number of bytes requested * @offset: File offset (unused for character devices) * * Copies data from kernel buffer to userspace. * Data is removed from buffer after reading (consuming read). * With transform-on-write, data is already transformed, so we just copy. * * Return: Number of bytes read, 0 for EOF, negative error code on failure */ static ssize_t superpipe_read(struct file *file, char __user *user_buffer, size_t count, loff_t *offset) { size_t to_copy; /* Acquire lock - interruptible so Ctrl+C works */ if (mutex_lock_interruptible(&dev_state.lock)) return -ERESTARTSYS; /* Interrupted by signal */ /* Check if there's data available */ if (dev_state.buffer_len == 0) { mutex_unlock(&dev_state.lock); return 0; /* EOF - no data available */ } /* Determine how much to copy: minimum of requested and available */ to_copy = (count < dev_state.buffer_len) ? count : dev_state.buffer_len; /* Copy data to userspace - data is already transformed */ if (copy_to_user(user_buffer, dev_state.buffer, to_copy)) { mutex_unlock(&dev_state.lock); return -EFAULT; /* Bad userspace address */ } /* * Remove copied data from buffer by shifting remaining data forward * There are more efficient ways to do this (eg. ring buffers) */ dev_state.buffer_len -= to_copy; if (dev_state.buffer_len > 0) { memmove(dev_state.buffer, dev_state.buffer + to_copy, dev_state.buffer_len); } mutex_unlock(&dev_state.lock); printk(KERN_INFO "superpipe: Read %zu bytes\n", to_copy); return to_copy; } /* * superpipe_write - Handle write operation * @file: File structure * @user_buffer: Userspace buffer containing data to write * @count: Number of bytes to write * @offset: File offset (unused for character devices) * * Copies data from userspace to kernel buffer, applying transformation. * This is where transform-on-write happens: data is transformed as it * enters the buffer, not when it's read out. * * Return: Number of bytes written, negative error code on failure */ static ssize_t superpipe_write(struct file *file, const char __user *user_buffer, size_t count, loff_t *offset) { size_t space_available; size_t to_write; char *write_position; /* Acquire lock */ if (mutex_lock_interruptible(&dev_state.lock)) return -ERESTARTSYS; /* Check available space in buffer */ space_available = BUFFER_SIZE - dev_state.buffer_len; if (space_available == 0) { mutex_unlock(&dev_state.lock); return -ENOSPC; /* Buffer full - no space left */ } /* Determine how much we can actually write */ to_write = (count < space_available) ? count : space_available; /* Calculate where to write in buffer */ write_position = dev_state.buffer + dev_state.buffer_len; /* Copy from userspace to kernel buffer */ if (copy_from_user(write_position, user_buffer, to_write)) { mutex_unlock(&dev_state.lock); return -EFAULT; /* Bad userspace address */ } /* * TRANSFORM ON WRITE * Apply transformation to the newly written data in-place * Data in buffer is always in its final transformed state */ switch (dev_state.mode) { case TRANSFORM_UPPER: transform_upper(write_position, to_write); break; case TRANSFORM_NONE: /* No transformation - data already copied as-is */ break; default: /* Should never happen if validation is correct */ printk(KERN_WARNING "superpipe: Invalid mode %d\n", dev_state.mode); break; } /* Update buffer length - for this reference, same as to_write */ dev_state.buffer_len += to_write; mutex_unlock(&dev_state.lock); printk(KERN_INFO "superpipe: Wrote %zu bytes (mode=%d)\n", to_write, dev_state.mode); /* Return bytes consumed from user buffer */ return to_write; } /* * superpipe_ioctl - Handle ioctl commands * @file: File structure * @cmd: ioctl command code * @arg: ioctl argument (pointer or value, depends on command) * * Handles device-specific configuration commands. * Commands are defined in superpipe_uapi.h * * Return: 0 on success, negative error code on failure */ static long superpipe_ioctl(struct file *file, unsigned int cmd, unsigned long arg) { struct superpipe_ioctl_config cfg; int ret = 0; /* Acquire lock */ if (mutex_lock_interruptible(&dev_state.lock)) return -ERESTARTSYS; switch (cmd) { case SUPERPIPE_IOC_SET_CONFIG: /* Copy configuration structure from userspace */ if (copy_from_user(&cfg, (void __user *)arg, sizeof(cfg))) { ret = -EFAULT; break; } /* Validate mode */ if (cfg.mode >= TRANSFORM_MAX) { printk(KERN_WARNING "superpipe: Invalid mode %u\n", cfg.mode); ret = -EINVAL; break; } /* Apply configuration */ dev_state.mode = cfg.mode; printk(KERN_INFO "superpipe: Mode set to %u\n", cfg.mode); break; case SUPERPIPE_IOC_GET_CONFIG: /* Prepare configuration structure */ cfg.mode = dev_state.mode; cfg.flags = 0; /* Copy to userspace */ if (copy_to_user((void __user *)arg, &cfg, sizeof(cfg))) { ret = -EFAULT; break; } printk(KERN_INFO "superpipe: Returned config (mode=%u)\n", cfg.mode); break; case SUPERPIPE_IOC_RESET: /* Clear buffer */ dev_state.buffer_len = 0; printk(KERN_INFO "superpipe: Buffer reset\n"); break; default: /* Unknown command */ printk(KERN_WARNING "superpipe: Unknown ioctl command: 0x%x\n", cmd); ret = -EINVAL; break; } mutex_unlock(&dev_state.lock); return ret; } /* * File operations structure * Maps system calls to our handler functions */ static const struct file_operations superpipe_fops = { .owner = THIS_MODULE, .open = superpipe_open, .release = superpipe_release, .read = superpipe_read, .write = superpipe_write, .unlocked_ioctl = superpipe_ioctl, }; /* * Miscdevice structure * Defines our character device */ static struct miscdevice superpipe_miscdev = { .minor = MISC_DYNAMIC_MINOR, /* Kernel assigns minor number automatically */ .name = DEVICE_NAME, /* Creates /dev/superpipe */ .fops = &superpipe_fops, /* Our file operations */ .mode = 0666, /* Device permissions (rw-rw-rw-) */ }; /* * superpipe_init - Module initialization * * Called when module is loaded with insmod. * Allocates resources and registers the device. * * Return: 0 on success, negative error code on failure */ static int __init superpipe_init(void) { int ret; /* Allocate kernel buffer (4KB) */ dev_state.buffer = kmalloc(BUFFER_SIZE, GFP_KERNEL); if (!dev_state.buffer) { printk(KERN_ERR "superpipe: Failed to allocate buffer\n"); return -ENOMEM; } /* Initialize device state */ dev_state.buffer_len = 0; dev_state.mode = TRANSFORM_NONE; /* Start in pass-through mode */ mutex_init(&dev_state.lock); /* Register miscdevice - creates /dev/superpipe */ ret = misc_register(&superpipe_miscdev); if (ret) { printk(KERN_ERR "superpipe: Failed to register device (error %d)\n", ret); kfree(dev_state.buffer); return ret; } printk(KERN_INFO "superpipe: Module loaded successfully\n"); printk(KERN_INFO "superpipe: Device created at /dev/%s\n", DEVICE_NAME); printk(KERN_INFO "superpipe: Buffer size: %d bytes\n", BUFFER_SIZE); return 0; } /* * superpipe_exit - Module cleanup * * Called when module is unloaded with rmmod. * Unregisters device and frees resources. */ static void __exit superpipe_exit(void) { /* Unregister device - removes /dev/superpipe */ misc_deregister(&superpipe_miscdev); /* Free buffer */ kfree(dev_state.buffer); printk(KERN_INFO "superpipe: Module unloaded\n"); } /* Register initialization and cleanup functions */ module_init(superpipe_init); module_exit(superpipe_exit); /* Module metadata */ MODULE_LICENSE("GPL"); MODULE_AUTHOR("Your Name <your.email@example.com>"); MODULE_DESCRIPTION("Superpipe character device with configurable transformations"); MODULE_VERSION("1.0");</syntaxhighlight> <span id="understanding-the-reference-implementation"></span> === Understanding the Reference Implementation === Let's walk through the key components of this implementation. <span id="module-initialization"></span> ==== Module Initialization ==== <syntaxhighlight lang="c">static int __init superpipe_init(void) { /* 1. Allocate buffer */ dev_state.buffer = kmalloc(BUFFER_SIZE, GFP_KERNEL); /* 2. Initialize state */ dev_state.buffer_len = 0; dev_state.mode = TRANSFORM_NONE; mutex_init(&dev_state.lock); /* 3. Register device */ ret = misc_register(&superpipe_miscdev); }</syntaxhighlight> '''Step-by-step:''' # '''Allocate buffer:''' <code>kmalloc()</code> is the kernel equivalent of <code>malloc()</code>. <code>GFP_KERNEL</code> means &quot;can sleep, normal priority allocation.&quot; # '''Initialize state:''' Set buffer empty, mode to pass-through, initialize mutex # '''Register device:''' This creates <code>/dev/superpipe</code> and makes it available '''If anything fails:''' Clean up already-allocated resources before returning error code. <span id="the-open-handler"></span> ==== The Open Handler ==== <syntaxhighlight lang="c">static int superpipe_open(struct inode *inode, struct file *file) { printk(KERN_INFO "superpipe: Device opened by process %d (%s)\n", current->pid, current->comm); return 0; }</syntaxhighlight> '''What happens here:''' * <code>current</code> is a kernel global pointing to the current process's task_struct * <code>current-&gt;pid</code> is the process ID * <code>current-&gt;comm</code> is the process name (from argv[0]) * We don't need to allocate per-file resources, so just log and return success <span id="the-write-handler-transform-on-write"></span> ==== The Write Handler: Transform-on-Write ==== <syntaxhighlight lang="c">static ssize_t superpipe_write(...) { /* 1. Acquire lock */ mutex_lock_interruptible(&dev_state.lock); /* 2. Check space */ if (space_available == 0) return -ENOSPC; /* 3. Copy from user */ write_position = dev_state.buffer + dev_state.buffer_len; copy_from_user(write_position, user_buffer, to_write); /* 4. TRANSFORM IN-PLACE */ switch (dev_state.mode) { case TRANSFORM_UPPER: transform_upper(write_position, to_write); break; } /* 5. Update length */ dev_state.buffer_len += to_write; /* 6. Release lock */ mutex_unlock(&dev_state.lock); return to_write; }</syntaxhighlight> '''Key points:''' * Data is transformed immediately after being copied from userspace * The transformation happens on <code>write_position</code> (the buffer location), not a temporary copy * Once stored, data is in its final transformed state <span id="the-read-handler-simple-copy"></span> ==== The Read Handler: Simple Copy ==== <syntaxhighlight lang="c">static ssize_t superpipe_read(...) { /* 1. Check for data */ if (dev_state.buffer_len == 0) return 0; /* EOF */ /* 2. Copy to user - data already transformed */ copy_to_user(user_buffer, dev_state.buffer, to_copy); /* 3. Remove consumed data */ dev_state.buffer_len -= to_copy; memmove(dev_state.buffer, dev_state.buffer + to_copy, dev_state.buffer_len); return to_copy; }</syntaxhighlight> '''Why it's simple:''' * No transformation needed—data is already in final form * Just copy to userspace and remove from buffer * <code>memmove()</code> shifts remaining data to the beginning <span id="the-ioctl-handler-configuration-with-structs"></span> ==== The ioctl Handler: Configuration with Structs ==== <syntaxhighlight lang="c">static long superpipe_ioctl(...) { struct superpipe_ioctl_config cfg; switch (cmd) { case SUPERPIPE_IOC_SET_CONFIG: /* 1. Copy struct from userspace */ if (copy_from_user(&cfg, (void __user *)arg, sizeof(cfg))) return -EFAULT; /* 2. Validate */ if (cfg.mode >= TRANSFORM_MAX) return -EINVAL; /* 3. Apply */ dev_state.mode = cfg.mode; break; case SUPERPIPE_IOC_GET_CONFIG: /* 1. Prepare struct */ cfg.mode = dev_state.mode; cfg.flags = 0; /* 2. Copy to userspace */ if (copy_to_user((void __user *)arg, &cfg, sizeof(cfg))) return -EFAULT; break; } return 0; }</syntaxhighlight> '''Pattern for struct-based ioctl:''' # For SET (write to device): <code>copy_from_user</code> → validate → apply # For GET (read from device): prepare → <code>copy_to_user</code> # Always validate inputs before applying <span id="module-cleanup"></span> ==== Module Cleanup ==== <syntaxhighlight lang="c">static void __exit superpipe_exit(void) { misc_deregister(&superpipe_miscdev); /* Remove device */ kfree(dev_state.buffer); /* Free buffer */ }</syntaxhighlight> '''Cleanup must:''' * Undo everything done in init * Be safe to call even if init partially failed (though our init handles that) * Not leak resources <span id="compiling-and-testing-the-reference-implementation"></span> == Compiling and Testing the Reference Implementation == <span id="step-1-compile-the-module"></span> === Step 1: Compile the Module === Create a <code>Makefile</code>: <syntaxhighlight lang="makefile">obj-m += superpipe_ref.o KDIR := /lib/modules/$(shell uname -r)/build PWD := $(shell pwd) all: $(MAKE) -C $(KDIR) M=$(PWD) modules clean: $(MAKE) -C $(KDIR) M=$(PWD) clean</syntaxhighlight> '''Compile:''' <syntaxhighlight lang="bash">make</syntaxhighlight> '''Expected output:''' <pre>make -C /lib/modules/6.5.0-generic/build M=/home/user/lab11 modules make[1]: Entering directory '/usr/src/linux-headers-6.5.0-generic' CC [M] /home/user/lab11/superpipe_ref.o MODPOST /home/user/lab11/Module.symvers CC [M] /home/user/lab11/superpipe_ref.mod.o LD [M] /home/user/lab11/superpipe_ref.ko make[1]: Leaving directory '/usr/src/linux-headers-6.5.0-generic'</pre> You now have <code>superpipe_ref.ko</code> (kernel object file). <span id="step-2-load-the-module"></span> === Step 2: Load the Module === '''Load the module:''' <syntaxhighlight lang="bash">sudo insmod superpipe_ref.ko</syntaxhighlight> '''Verify it loaded:''' <syntaxhighlight lang="bash">lsmod | grep superpipe</syntaxhighlight> '''Expected output:''' <pre>superpipe_ref 16384 0</pre> The &quot;0&quot; means no one is currently using it. '''Check kernel messages:''' <syntaxhighlight lang="bash">sudo dmesg | tail -5</syntaxhighlight> '''Expected output:''' <pre>[12345.678] superpipe: Module loaded successfully [12345.678] superpipe: Device created at /dev/superpipe [12345.678] superpipe: Buffer size: 4096 bytes</pre> '''Verify device file:''' <syntaxhighlight lang="bash">ls -l /dev/superpipe</syntaxhighlight> '''Expected output:''' <pre>crw-rw-rw- 1 root root 10, 58 Dec 19 12:00 /dev/superpipe</pre> The device is ready to use! <span id="step-3-build-the-test-program"></span> === Step 3: Build the Test Program === Create <code>test_superpipe.c</code>: <syntaxhighlight lang="c">/* test_superpipe.c - Userspace test program for superpipe */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <fcntl.h> #include <unistd.h> #include <sys/ioctl.h> #include <errno.h> #include "superpipe_uapi.h" void usage(const char *progname) { fprintf(stderr, "Usage: %s <command> [args]\n", progname); fprintf(stderr, "Commands:\n"); fprintf(stderr, " set_mode <none|upper> - Set transformation mode\n"); fprintf(stderr, " get_mode - Get current mode\n"); fprintf(stderr, " write <text> - Write text to device\n"); fprintf(stderr, " read - Read from device\n"); fprintf(stderr, " reset - Reset device (clear buffer)\n"); exit(1); } int main(int argc, char *argv[]) { int fd; struct superpipe_ioctl_config cfg; char buffer[256]; ssize_t n; if (argc < 2) { usage(argv[0]); } /* Open device */ fd = open("/dev/superpipe", O_RDWR); if (fd < 0) { perror("Failed to open /dev/superpipe"); fprintf(stderr, "Make sure the module is loaded\n"); return 1; } /* Process command */ if (strcmp(argv[1], "set_mode") == 0) { if (argc < 3) { fprintf(stderr, "Error: set_mode requires mode argument\n"); close(fd); return 1; } if (strcmp(argv[2], "none") == 0) { cfg.mode = SUPERPIPE_MODE_NONE; } else if (strcmp(argv[2], "upper") == 0) { cfg.mode = SUPERPIPE_MODE_UPPER; } else { fprintf(stderr, "Error: Unknown mode '%s'\n", argv[2]); close(fd); return 1; } cfg.flags = 0; if (ioctl(fd, SUPERPIPE_IOC_SET_CONFIG, &cfg) < 0) { perror("ioctl SET_CONFIG"); close(fd); return 1; } printf("✓ Mode set to %s\n", argv[2]); } else if (strcmp(argv[1], "get_mode") == 0) { if (ioctl(fd, SUPERPIPE_IOC_GET_CONFIG, &cfg) < 0) { perror("ioctl GET_CONFIG"); close(fd); return 1; } printf("Current mode: "); switch (cfg.mode) { case SUPERPIPE_MODE_NONE: printf("NONE\n"); break; case SUPERPIPE_MODE_UPPER: printf("UPPER\n"); break; default: printf("UNKNOWN (%u)\n", cfg.mode); break; } } else if (strcmp(argv[1], "write") == 0) { if (argc < 3) { fprintf(stderr, "Error: write requires text argument\n"); close(fd); return 1; } n = write(fd, argv[2], strlen(argv[2])); if (n < 0) { perror("write"); close(fd); return 1; } printf("✓ Wrote %zd bytes\n", n); } else if (strcmp(argv[1], "read") == 0) { n = read(fd, buffer, sizeof(buffer) - 1); if (n < 0) { perror("read"); close(fd); return 1; } if (n == 0) { printf("(no data available)\n"); } else { buffer[n] = '\0'; printf("%s\n", buffer); } } else if (strcmp(argv[1], "reset") == 0) { if (ioctl(fd, SUPERPIPE_IOC_RESET) < 0) { perror("ioctl RESET"); close(fd); return 1; } printf("✓ Device reset\n"); } else { fprintf(stderr, "Error: Unknown command '%s'\n", argv[1]); close(fd); usage(argv[0]); } close(fd); return 0; }</syntaxhighlight> '''Compile:''' <syntaxhighlight lang="bash">gcc -o test_superpipe test_superpipe.c</syntaxhighlight> <span id="step-4-test-basic-write-and-read"></span> === Step 4: Test Basic Write and Read === '''Test pass-through mode:''' <syntaxhighlight lang="bash">./test_superpipe set_mode none ./test_superpipe write "Hello World 123" ./test_superpipe read</syntaxhighlight> '''Expected output:''' <pre>✓ Mode set to none ✓ Wrote 15 bytes Hello World 123</pre> The data passes through unchanged. <span id="step-5-test-uppercase-transformation"></span> === Step 5: Test Uppercase Transformation === '''Enable uppercase mode and test:''' <syntaxhighlight lang="bash">./test_superpipe set_mode upper ./test_superpipe write "hello world 123" ./test_superpipe read</syntaxhighlight> '''Expected output:''' <pre>✓ Mode set to upper ✓ Wrote 15 bytes HELLO WORLD 123</pre> The data was transformed to uppercase during the write! <span id="step-6-test-mixed-mode-writes"></span> === Step 6: Test Mixed Mode Writes === '''Test that mode changes only affect new writes:''' <syntaxhighlight lang="bash">./test_superpipe set_mode none ./test_superpipe write "plain " ./test_superpipe set_mode upper ./test_superpipe write "caps " ./test_superpipe set_mode none ./test_superpipe write "normal" ./test_superpipe read</syntaxhighlight> '''Expected output:''' <pre>✓ Mode set to none ✓ Wrote 6 bytes ✓ Mode set to upper ✓ Wrote 5 bytes ✓ Mode set to none ✓ Wrote 6 bytes plain CAPS normal</pre> Each write was transformed according to the mode at the time of writing! <span id="step-7-view-kernel-messages"></span> === Step 7: View Kernel Messages === '''Check what the kernel logged:''' <syntaxhighlight lang="bash">sudo dmesg | tail -20</syntaxhighlight> '''Expected output:''' <pre>[12345.678] superpipe: Module loaded successfully [12345.678] superpipe: Device created at /dev/superpipe [12346.123] superpipe: Device opened by process 1234 (test_superpipe) [12346.124] superpipe: Mode set to 0 [12346.125] superpipe: Device closed by process 1234 (test_superpipe) [12346.200] superpipe: Device opened by process 1235 (test_superpipe) [12346.201] superpipe: Wrote 15 bytes (mode=0) [12346.202] superpipe: Device closed by process 1235 (test_superpipe) [12346.300] superpipe: Device opened by process 1236 (test_superpipe) [12346.301] superpipe: Read 15 bytes [12346.302] superpipe: Device closed by process 1236 (test_superpipe) ...</pre> You can see every open, close, read, write, and ioctl operation logged. <span id="step-8-unload-the-module"></span> === Step 8: Unload the Module === '''Unload:''' <syntaxhighlight lang="bash">sudo rmmod superpipe_ref</syntaxhighlight> '''Verify device is gone:''' <syntaxhighlight lang="bash">ls -l /dev/superpipe</syntaxhighlight> '''Expected:''' <pre>ls: cannot access '/dev/superpipe': No such file or directory</pre> '''Check kernel log:''' <syntaxhighlight lang="bash">sudo dmesg | tail -1</syntaxhighlight> '''Expected:''' <pre>[12350.456] superpipe: Module unloaded</pre> <span id="exercise-full-superpipe-implementation"></span> == Exercise: Full Superpipe Implementation == <span id="objective"></span> === Objective === Extend the reference implementation to support five transformation modes: # '''NONE''' - Pass through unchanged (already implemented) # '''UPPER''' - Convert to uppercase (already implemented) # '''LOWER''' - Convert to lowercase (NEW) # '''DROP_VOWELS''' - Remove vowels (a, e, i, o, u, A, E, I, O, U) (NEW) # '''DROP_SPACES''' - Remove space characters (0x20) (NEW) <span id="requirements"></span> === Requirements === '''1. Update the UAPI Header''' Add new mode constants to <code>superpipe_uapi.h</code>: <syntaxhighlight lang="c">#define SUPERPIPE_MODE_NONE 0 #define SUPERPIPE_MODE_UPPER 1 #define SUPERPIPE_MODE_LOWER 2 /* NEW */ #define SUPERPIPE_MODE_DROP_VOWELS 3 /* NEW */ #define SUPERPIPE_MODE_DROP_SPACES 4 /* NEW */</syntaxhighlight> '''2. Implement Transformation Functions''' Add three new transformation functions to your kernel module: <syntaxhighlight lang="c">/* Convert to lowercase */ static void transform_lower(char *data, size_t len); /* Remove vowels (returns new length after filtering) */ static size_t transform_drop_vowels(char *data, size_t len); /* Remove spaces (returns new length after filtering) */ static size_t transform_drop_spaces(char *data, size_t len);</syntaxhighlight> '''3. Update the Write Handler''' Modify <code>superpipe_write()</code> to handle all transformation modes: <syntaxhighlight lang="c">/* Apply transformation - filtering may reduce length */ size_t final_len = to_write; switch (dev_state.mode) { case TRANSFORM_NONE: /* No transformation */ break; case TRANSFORM_UPPER: transform_upper(write_position, to_write); break; case TRANSFORM_LOWER: transform_lower(write_position, to_write); break; case TRANSFORM_DROP_VOWELS: final_len = transform_drop_vowels(write_position, to_write); break; case TRANSFORM_DROP_SPACES: final_len = transform_drop_spaces(write_position, to_write); break; } /* Update buffer length by actual stored data */ dev_state.buffer_len += final_len; return final_len; /* Return bytes actually stored */</syntaxhighlight> '''4. Update the Test Program''' Add support for new modes in <code>test_superpipe.c</code>: <syntaxhighlight lang="c">} else if (strcmp(argv[2], "lower") == 0) { cfg.mode = SUPERPIPE_MODE_LOWER; } else if (strcmp(argv[2], "drop_vowels") == 0) { cfg.mode = SUPERPIPE_MODE_DROP_VOWELS; } else if (strcmp(argv[2], "drop_spaces") == 0) { cfg.mode = SUPERPIPE_MODE_DROP_SPACES;</syntaxhighlight> <span id="transformation-specifications"></span> === Transformation Specifications === '''TRANSFORM_LOWER:''' Convert all ASCII uppercase letters (A-Z) to lowercase (a-z). Other characters unchanged. <pre>Input: &quot;Hello WORLD 123&quot; Output: &quot;hello world 123&quot;</pre> '''TRANSFORM_DROP_VOWELS:''' Remove all vowels (both upper and lowercase): a, e, i, o, u, A, E, I, O, U <pre>Input: &quot;beautiful day&quot; Output: &quot;btfl dy&quot; Input: &quot;AEIOU&quot; Output: &quot;&quot; (empty)</pre> '''TRANSFORM_DROP_SPACES:''' Remove all space characters (ASCII 0x20) <pre>Input: &quot;hello world test&quot; Output: &quot;helloworldtest&quot; Input: &quot; spaces &quot; Output: &quot;spaces&quot;</pre> '''Important for filtering transforms:''' When characters are removed, the data must be compacted in the buffer. However, the write() system call still returns the number of bytes consumed from the user's buffer (standard UNIX behavior). '''Example:''' <syntaxhighlight lang="bash">./test_superpipe set_mode drop_vowels ./test_superpipe write "hello" # Writes 5 bytes # Output: ✓ Wrote 5 bytes # Returns 5 (consumed all user data) ./test_superpipe read # Output: hll # But only 3 bytes stored in buffer</syntaxhighlight> <span id="implementation-guidance"></span> === Implementation Guidance === '''Helper function for vowel detection:''' <syntaxhighlight lang="c">static inline bool is_vowel(char c) { return (c == 'a' || c == 'e' || c == 'i' || c == 'o' || c == 'u' || c == 'A' || c == 'E' || c == 'I' || c == 'O' || c == 'U'); }</syntaxhighlight> '''Pattern for filtering (compacting) transformations:''' <syntaxhighlight lang="c">static size_t transform_drop_vowels(char *data, size_t len) { size_t i, j = 0; /* Iterate through input, copy only non-vowels */ for (i = 0; i < len; i++) { if (!is_vowel(data[i])) { data[j++] = data[i]; /* Keep this character */ } /* Vowels are skipped - not copied to output position */ } /* j now contains the number of characters kept */ return j; }</syntaxhighlight> '''Why this works:''' * We iterate with <code>i</code> through all input characters * We write kept characters to position <code>j</code> * <code>j</code> only advances when we keep a character * At the end, <code>j</code> is the new length '''Pattern for case conversion:''' <syntaxhighlight lang="c">static void transform_lower(char *data, size_t len) { size_t i; for (i = 0; i < len; i++) { if (isupper(data[i])) { data[i] = tolower(data[i]); } } }</syntaxhighlight> <span id="testing-requirements"></span> === Testing Requirements === Create a comprehensive test script <code>test.sh</code> that demonstrates: '''Test 1: NONE mode''' <syntaxhighlight lang="bash">./test_superpipe set_mode none ./test_superpipe write "Hello World 123" ./test_superpipe read # Expected: Hello World 123</syntaxhighlight> '''Test 2: UPPER mode''' <syntaxhighlight lang="bash">./test_superpipe set_mode upper ./test_superpipe write "hello world 123" ./test_superpipe read # Expected: HELLO WORLD 123</syntaxhighlight> '''Test 3: LOWER mode''' <syntaxhighlight lang="bash">./test_superpipe set_mode lower ./test_superpipe write "HELLO WORLD 123" ./test_superpipe read # Expected: hello world 123</syntaxhighlight> '''Test 4: DROP_VOWELS mode''' <syntaxhighlight lang="bash">./test_superpipe set_mode drop_vowels ./test_superpipe write "beautiful" ./test_superpipe read # Expected: btfl</syntaxhighlight> '''Test 5: DROP_SPACES mode''' <syntaxhighlight lang="bash">./test_superpipe set_mode drop_spaces ./test_superpipe write "hello world test" ./test_superpipe read # Expected: helloworldtest</syntaxhighlight> '''Test 6: Mixed modes (different modes for different writes)''' <syntaxhighlight lang="bash">./test_superpipe set_mode none ./test_superpipe write "plain " ./test_superpipe set_mode upper ./test_superpipe write "CAPS " ./test_superpipe set_mode lower ./test_superpipe write "lower" ./test_superpipe read # Expected: plain CAPS lower</syntaxhighlight> '''Test 7: Edge cases''' <syntaxhighlight lang="bash"># All vowels ./test_superpipe set_mode drop_vowels ./test_superpipe write "aeiou" ./test_superpipe read # Expected: (empty) # All spaces ./test_superpipe set_mode drop_spaces ./test_superpipe write " " ./test_superpipe read # Expected: (empty)</syntaxhighlight> <span id="deliverables"></span> === Deliverables === Submit a PDF with your code and screenshots of: * All transform modes tested and working * Detailed kernel logs <span id="reference-kernel-programming-quick-guide"></span> == Reference: Kernel Programming Quick Guide == <span id="module-macros-and-metadata"></span> === Module Macros and Metadata === <syntaxhighlight lang="c">#include <linux/module.h> #include <linux/kernel.h> #include <linux/init.h> /* Declare init and exit functions */ module_init(my_init_function); module_exit(my_exit_function); /* Module metadata (required) */ MODULE_LICENSE("GPL"); /* Must be GPL-compatible */ MODULE_AUTHOR("Your Name <email>"); MODULE_DESCRIPTION("Brief description"); MODULE_VERSION("1.0"); /* Init function signature */ static int __init my_init_function(void) { /* Return 0 on success, negative error code on failure */ } /* Exit function signature */ static void __exit my_exit_function(void) { /* No return value */ }</syntaxhighlight> <span id="memory-management"></span> === Memory Management === <syntaxhighlight lang="c">#include <linux/slab.h> /* Allocate memory */ void *ptr = kmalloc(size, GFP_KERNEL); if (!ptr) return -ENOMEM; /* Allocate and zero memory */ void *ptr = kzalloc(size, GFP_KERNEL); /* Free memory */ kfree(ptr); /* GFP flags: * GFP_KERNEL - Normal allocation, can sleep * GFP_ATOMIC - Cannot sleep (use in interrupt context) * GFP_USER - Allocate for userspace */</syntaxhighlight> <span id="data-transfer-functions"></span> === Data Transfer Functions === <syntaxhighlight lang="c">#include <linux/uaccess.h> /* Copy to userspace */ if (copy_to_user(user_ptr, kernel_ptr, size)) return -EFAULT; /* Copy from userspace */ if (copy_from_user(kernel_ptr, user_ptr, size)) return -EFAULT; /* Get a single value from userspace */ int val; if (get_user(val, (int __user *)user_ptr)) return -EFAULT; /* Put a single value to userspace */ if (put_user(val, (int __user *)user_ptr)) return -EFAULT;</syntaxhighlight> <span id="synchronization"></span> === Synchronization === <syntaxhighlight lang="c">#include <linux/mutex.h> /* Declare mutex */ static DEFINE_MUTEX(my_mutex); /* Or dynamic initialization */ struct mutex my_mutex; mutex_init(&my_mutex); /* Lock (sleeps if unavailable) */ mutex_lock(&my_mutex); /* ... critical section ... */ mutex_unlock(&my_mutex); /* Lock (interruptible by signals) */ if (mutex_lock_interruptible(&my_mutex)) return -ERESTARTSYS; /* ... critical section ... */ mutex_unlock(&my_mutex); /* Try lock (non-blocking) */ if (mutex_trylock(&my_mutex)) { /* Got lock */ /* ... critical section ... */ mutex_unlock(&my_mutex); } else { /* Lock held by someone else */ }</syntaxhighlight> <span id="logging-and-debugging"></span> === Logging and Debugging === <syntaxhighlight lang="c">#include <linux/kernel.h> /* Log levels */ printk(KERN_EMERG "Emergency\n"); /* System unusable */ printk(KERN_ALERT "Alert\n"); /* Action must be taken */ printk(KERN_CRIT "Critical\n"); /* Critical condition */ printk(KERN_ERR "Error\n"); /* Error condition */ printk(KERN_WARNING "Warning\n"); /* Warning */ printk(KERN_NOTICE "Notice\n"); /* Normal but significant */ printk(KERN_INFO "Info\n"); /* Informational */ printk(KERN_DEBUG "Debug\n"); /* Debug messages */ /* Formatted output (like printf) */ printk(KERN_INFO "Value: %d, String: %s\n", value, string); /* Access current process info */ printk(KERN_INFO "PID: %d, Name: %s\n", current->pid, current->comm); /* View logs */ /* dmesg */ /* tail -f /var/log/kern.log */</syntaxhighlight> <span id="common-error-codes"></span> === Common Error Codes === <syntaxhighlight lang="c">#include <linux/errno.h> return 0; /* Success */ return -ENOMEM; /* Out of memory */ return -EFAULT; /* Bad address (copy_to/from_user failed) */ return -EINVAL; /* Invalid argument */ return -ENOSPC; /* No space left on device */ return -EBUSY; /* Device or resource busy */ return -EIO; /* I/O error */ return -ENODEV; /* No such device */ return -EPERM; /* Operation not permitted */ return -EACCES; /* Permission denied */ return -ERESTARTSYS; /* Interrupted system call */</syntaxhighlight> <span id="common-issues-and-troubleshooting"></span> == Common Issues and Troubleshooting == <span id="compilation-errors"></span> === Compilation Errors === '''Issue: &quot;No rule to make target&quot;''' <pre>make: *** No rule to make target 'modules'. Stop.</pre> '''Cause:''' Wrong KDIR path in Makefile '''Fix:''' Verify kernel headers are installed and path is correct: <syntaxhighlight lang="bash">ls -l /lib/modules/$(uname -r)/build # Should exist and link to kernel source</syntaxhighlight> '''Issue: &quot;missing MODULE_LICENSE&quot;''' <pre>WARNING: modpost: missing MODULE_LICENSE() in ...</pre> '''Cause:''' Forgot to add MODULE_LICENSE macro '''Fix:''' Add to your module: <syntaxhighlight lang="c">MODULE_LICENSE("GPL");</syntaxhighlight> '''Issue: &quot;implicit declaration of function&quot;''' '''Cause:''' Missing <code>#include</code> directive '''Fix:''' Add appropriate header. Common headers: * <code>&lt;linux/kernel.h&gt;</code> - Core kernel functions * <code>&lt;linux/uaccess.h&gt;</code> - copy_to_user, copy_from_user * <code>&lt;linux/slab.h&gt;</code> - kmalloc, kfree * <code>&lt;linux/mutex.h&gt;</code> - Mutex functions <span id="module-loading-issues"></span> === Module Loading Issues === '''Issue: &quot;Invalid module format&quot;''' <pre>insmod: ERROR: could not insert module: Invalid module format</pre> '''Cause:''' Module compiled for different kernel version '''Fix:''' Clean and rebuild: <syntaxhighlight lang="bash">make clean make</syntaxhighlight> Ensure <code>uname -r</code> matches the kernel you're running. '''Issue: &quot;Operation not permitted&quot;''' '''Cause:''' Need root privileges '''Fix:''' Use sudo: <syntaxhighlight lang="bash">sudo insmod module.ko</syntaxhighlight> '''Issue: &quot;Device or resource busy&quot;''' <pre>rmmod: ERROR: Module is in use</pre> '''Cause:''' Device is still open or module is in use '''Fix:''' Close all programs using the device: <syntaxhighlight lang="bash">lsof /dev/superpipe # Find processes using device kill <PID> # Kill processes if necessary sudo rmmod module</syntaxhighlight> <span id="runtime-issues"></span> === Runtime Issues === '''Issue: &quot;Bad address&quot; (-EFAULT) from read/write''' '''Cause:''' Forgot copy_to_user/copy_from_user '''Fix:''' Never directly access user pointers: <syntaxhighlight lang="c">/* WRONG */ strcpy(user_buffer, kernel_data); /* CORRECT */ if (copy_to_user(user_buffer, kernel_data, len)) return -EFAULT;</syntaxhighlight> '''Issue: Kernel panic on module load''' '''Cause:''' Accessing NULL pointer or uninitialized memory '''Fix:''' Always check return values: <syntaxhighlight lang="c">buffer = kmalloc(size, GFP_KERNEL); if (!buffer) { printk(KERN_ERR "Failed to allocate\n"); return -ENOMEM; /* Don't continue with NULL pointer! */ }</syntaxhighlight> '''Issue: Data corruption with concurrent access''' '''Cause:''' Missing mutex locks '''Fix:''' Protect all shared data: <syntaxhighlight lang="c">/* Acquire lock before accessing shared state */ mutex_lock_interruptible(&dev_state.lock); /* Access shared data */ /* Release lock */ mutex_unlock(&dev_state.lock);</syntaxhighlight> '''Issue: Module stuck, can't unload''' '''Cause:''' Process stuck in kernel code (infinite loop or deadlock) '''Fix:''' * Kill the hung process * If that doesn't work, reboot (this is why VMs are recommended!) <span id="debugging-strategies"></span> === Debugging Strategies === '''Strategy 1: Liberally use printk''' <syntaxhighlight lang="c">printk(KERN_DEBUG "Entering function, buffer_len=%zu\n", dev_state.buffer_len); printk(KERN_DEBUG "After copy, to_write=%zu\n", to_write); printk(KERN_DEBUG "Exiting function, returning %zd\n", ret);</syntaxhighlight> '''Strategy 2: Check return values''' <syntaxhighlight lang="c">ret = copy_from_user(...); printk(KERN_DEBUG "copy_from_user returned %lu\n", ret); if (ret) { printk(KERN_ERR "Failed to copy %lu bytes\n", ret); return -EFAULT; }</syntaxhighlight> '''Strategy 3: Dump buffer contents''' <syntaxhighlight lang="c">/* Hexdump helper */ void hexdump(const char *data, size_t len) { size_t i; printk(KERN_DEBUG "Hexdump (%zu bytes):\n", len); for (i = 0; i < len; i++) { printk(KERN_CONT "%02x ", (unsigned char)data[i]); if ((i + 1) % 16 == 0) printk(KERN_CONT "\n"); } printk(KERN_CONT "\n"); }</syntaxhighlight> '''Strategy 4: Monitor kernel logs in real-time''' In one terminal: <syntaxhighlight lang="bash">sudo dmesg -w</syntaxhighlight> In another terminal, run your tests. You'll see kernel messages appear immediately. '''Strategy 5: Add assertions''' <syntaxhighlight lang="c">#define ASSERT(cond) \ do { \ if (!(cond)) { \ printk(KERN_ERR "Assertion failed: %s\n", #cond); \ BUG(); \ } \ } while (0) ASSERT(buffer_len <= BUFFER_SIZE); ASSERT(mode < TRANSFORM_MAX);</syntaxhighlight> '''Note:''' <code>BUG()</code> causes a kernel oops. Use only for debugging, remove before submission. <span id="for-further-study"></span> == For Further Study == <span id="advanced-topics"></span> === Advanced Topics === '''1. Multiple Device Instances''' Extend superpipe to support multiple independent devices (<code>/dev/superpipe0</code>, <code>/dev/superpipe1</code>, etc.) with separate buffers and modes. '''Hint:''' Use dynamic miscdevice allocation and embed miscdevice in device structure. '''2. Per-File-Descriptor State''' Allow each open() to have independent buffer and transformation mode using <code>file-&gt;private_data</code>. '''3. Non-Blocking I/O and Poll''' Implement <code>O_NONBLOCK</code> support and <code>poll()</code> operation so userspace can use <code>select()</code> or <code>epoll()</code>. '''4. Sysfs Interface''' Expose device statistics via sysfs (<code>/sys/class/misc/superpipe/</code>): * Total bytes read * Total bytes written * Current mode * Buffer usage '''5. Advanced Transformations''' Implement more complex transformations: * ROT13 cipher * Base64 encoding/decoding * Compression (simple run-length encoding) '''6. Ring Buffer Implementation''' Replace linear buffer with circular ring buffer for better performance (no memmove on read). <span id="relevant-documentation"></span> === Relevant Documentation === '''Kernel Documentation:''' <syntaxhighlight lang="bash"># View kernel documentation cd /usr/src/linux-headers-$(uname -r) ls Documentation/ # Useful sections: # - kernel-hacking/ # - driver-api/ # - core-api/</syntaxhighlight> '''Online Resources:''' * '''Linux Kernel Documentation:''' https://www.kernel.org/doc/html/latest/ * '''Linux Device Drivers (LDD3):''' Classic book, available online * '''Kernel Newbies:''' https://kernelnewbies.org/ * '''KernelCI:''' https://kernelci.org/ * '''LKML Archives:''' https://lkml.org/ * '''Bootlin Linux Source View:''' https://elixir.bootlin.com/linux '''Manual pages:''' <syntaxhighlight lang="bash">man 2 open # open() system call man 2 read # read() system call man 2 write # write() system call man 2 ioctl # ioctl() system call man 7 capabilities # Linux capabilities</syntaxhighlight> '''Kernel source as reference:''' <syntaxhighlight lang="bash"># Find examples of miscdevice usage cd /usr/src/linux-source-*/ grep -r "misc_register" drivers/ # Example drivers to study: # - drivers/char/mem.c (/dev/null, /dev/zero, /dev/random) # - drivers/char/misc.c (miscdevice framework itself)</syntaxhighlight> '''Debugging:''' * <code>addr2line</code>: Convert addresses in oops messages to source lines * <code>objdump</code>: Disassemble kernel modules * <code>gdb</code> with <code>/proc/kcore</code>: Debug live kernel * <code>SystemTap</code> / <code>eBPF</code>: Dynamic kernel tracing '''Remember:''' The Linux kernel is one of the largest open-source projects. Reading kernel code is the best way to learn kernel programming.

Înapoi la OS Lab 11 - Linux Kernel Modules.