Drivers on Rishav's Digital Garden

Character Device Management in Kernel Drivers

Sat, 03 Jan 2026 21:29:00 +0000

Overview

Character devices are distinguished by the fact that they are accessed as a stream of bytes, much like a file. A character driver is responsible for implementing this behavior by mapping standard system calls to device-specific operations. Unlike block devices, which require an intermediate layer for buffering and management, character devices communicate directly with the Virtual File System (VFS).

In the Linux kernel, character devices are identified by a major number (identifying the driver) and a minor number (distinguishing between specific device instances).

Make Simple Kernel Module (.ko)

Tue, 25 Nov 2025 23:34:00 +0000

1. Overview

A kernel module provides a way to extend kernel functionality without rebuilding the entire kernel. Using the Buildroot toolchain ensures the module is ABI‑compatible with the kernel generated during your Buildroot build. QEMU then offers a convenient emulation environment to test modules without hardware.

Linux kernel modules are dynamically loadable pieces of code that extend the functionality of the kernel without requiring a reboot or recompilation. They are widely used for device drivers, filesystems, and various kernel extensions.

System Call (Software Interrupt)

Sun, 04 May 2025 14:24:00 +0000

1. System Call Basics

System calls (syscalls) are the interface for user-space programs to request services from the kernel. Examples include:

File I/O: read(), write(), open(), close().
Device Control: ioctl().
Signal Handling: kill(), signal().

2. System Call Table and Registration

Syscall Table:

A table (sys_call_table) maps syscall numbers to handler functions.
Architecture-Specific:
- x86: Defined in arch/x86/entry/syscalls/syscall_64.tbl.
- ARM: Defined in arch/arm/tools/syscall.tbl.
Registration:
- Syscalls are registered at compile time using macros like SYSCALL_DEFINE (e.g., SYSCALL_DEFINE3(write, ...) for write()).
- For custom syscalls (rare and discouraged), you would:
  1. Add an entry to the syscall table.
  2. Define the handler using SYSCALL_DEFINE.
  3. Recompile the kernel (or use modules for dynamic insertion).

3. Flow of System Calls

1. User-Space Invocation

The libc wrapper (e.g., read(), ioctl()) triggers a software interrupt (int 0x80 on x86) or uses the syscall instruction (modern x86/ARM).

// User-space code
fd = open("/dev/mydevice", O_RDWR); // Syscall 1: open()
read(fd, buf, 100); // Syscall 2: read()
ioctl(fd, MY_CMD, arg); // Syscall 3: ioctl()
close(fd); // Syscall 4: close()

2. Transition to Kernel Mode

Switches to kernel mode (ring 0 on x86, EL1 on ARM).
Saves user-space registers (e.g., RIP, RSP, EFLAGS).
Jumps to the kernel’s syscall entry point (e.g., entry_SYSCALL_64 on x86)

3. Syscall Dispatching

Syscall Number:
- The syscall number is stored in a register (e.g., RAX on x86, R7 on ARM).
- Example: __NR_read (syscall number for read()).
Syscall Table:
- The kernel uses sys_call_table (array of function pointers) to find the handler.
- Example: sys_call_table[__NR_read] points to sys_read().

4. Handler Execution in Process Context

Generic Steps for All Syscalls:

Argument Validation:
- Check pointers (e.g., buf in read()) using access_ok()
- Copy arguments from user space with copy_from_user() or get_user()
Kernel Function Execution:
- Perform the requested operation (e.g., read from a file, send an ioctl command)

File Operations (`read`/`write`):

File Descriptor Resolution:
- Convert fd to a struct file using fdget().
- Check file permissions (FMODE_READ/FMODE_WRITE).
Driver Interaction:
- Call the read/write method from the file’s file_operations struct.
- Example: For /dev/mydevice, this invokes the driver’s .read function.

I/O Control (`ioctl`):

The ioctl syscall (sys_ioctl()) calls the driver’s .unlocked_ioctl method.

5. Return to User Space:

Result is stored in eax/r0, and the kernel restores user registers
Execute iret (x86) or exception return (ARM) to resume user-mode execution.

4. Device File Operations

Character devices (e.g., /dev/char_dev) expose operations via file_operations:

Generic GPIO Management in Linux

Wed, 19 Feb 2025 11:29:00 +0000

Introduction

GPIO (General Purpose Input/Output) is a fundamental interface in embedded systems and Linux-based platforms. Linux provides multiple methods to control GPIOs, including the deprecated /sys/class/gpio/ interface and the modern libgpiod (GPIO character device) API. This document provides a comprehensive guide to managing GPIOs in Linux.

GPIO Interfaces in Linux

Linux provides three primary ways to manage GPIOs:

Legacy Sysfs Interface (/sys/class/gpio/) - Deprecated but still present on some systems.
GPIO Character Device (/dev/gpiochipX) - The recommended approach using libgpiod.
Direct Kernel Access - Through kernel drivers or device tree configurations.

1. Sysfs GPIO Interface (Deprecated)

The sysfs-based interface was historically used to control GPIOs but has been marked as deprecated in favor of gpiod. If still available, it can be accessed via /sys/class/gpio/.

IOCTL in Kernel Device Drivers

Fri, 24 Jan 2025 17:24:00 +0000

ioctl Implementation in Kernel Device Drivers

Overview

ioctl (Input/Output Control) is a powerful system call in Linux used to perform device-specific operations that are not covered by standard system calls like read, write, or open. It allows user-space applications to interact with kernel-space drivers for device-specific configurations and data exchanges.

How ioctl Works

1. User-Space Interaction:

A user-space application invokes ioctl using the following prototype:

int ioctl(int fd, unsigned long cmd, void *arg);

fd: File descriptor for the device.
cmd: Command defining the operation.
arg: Pointer to the data or argument passed between user-space and kernel-space.

2. Driver-Side Handling:

The ioctl system call is routed to the driver by the kernel.
The driver implements a specific unlocked_ioctl or compat_ioctl callback in the file_operations structure.

3. Data Flow:

Arguments passed via arg can be pointers to user-space data, requiring the driver to use helper functions like copy_from_user and copy_to_user for secure data transfer.

Steps to Implement ioctl in a Kernel Driver

1. Define ioctl Commands:

Use macros to define command numbers, typically with the _IO, _IOR, _IOW, and _IOWR macros provided in <linux/ioctl.h>.

#define MY_IOCTL_BASE 'M'
#define IOCTL_CMD_GET _IOR(MY_IOCTL_BASE, 1, int)
#define IOCTL_CMD_SET _IOW(MY_IOCTL_BASE, 2, int)

_IOR: Read data from the kernel.
_IOW: Write data to the kernel.
_IOWR: Read and write data.
_IO: Command without data.

2. Implement ioctl Callback:

Define the unlocked_ioctl function in the driver.
Handle commands appropriately based on cmd.

static long my_ioctl(struct file *file, unsigned int cmd, unsigned long arg) {
 int value;

 switch (cmd) {
 case IOCTL_CMD_GET:
 value = 1234; // Example value
 if (copy_to_user((int __user *)arg, &value, sizeof(value)))
 return -EFAULT;
 break;

 case IOCTL_CMD_SET:
 if (copy_from_user(&value, (int __user *)arg, sizeof(value)))
 return -EFAULT;
 pr_info("Value set by user: %d\n", value);
 break;

 default:
 return -ENOTTY; // Command not supported
 }
 return 0;
}

3. Integrate into file_operations:

static const struct file_operations my_fops = {
 .owner = THIS_MODULE,
 .open = my_open,
 .release = my_release,
 .unlocked_ioctl = my_ioctl,
};

4. Test the ioctl Implementation:

Write a user-space application to interact with the driver.

#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
#include <sys/ioctl.h>

#define MY_IOCTL_BASE 'M'
#define IOCTL_CMD_GET _IOR(MY_IOCTL_BASE, 1, int)
#define IOCTL_CMD_SET _IOW(MY_IOCTL_BASE, 2, int)

int main() {
 int fd, value = 42;

 fd = open("/dev/my_device", O_RDWR);
 if (fd < 0) {
 perror("Failed to open device");
 return -1;
 }

 if (ioctl(fd, IOCTL_CMD_SET, &value) < 0) {
 perror("ioctl SET failed");
 }

 if (ioctl(fd, IOCTL_CMD_GET, &value) < 0) {
 perror("ioctl GET failed");
 } else {
 printf("Value from device: %d\n", value);
 }

 close(fd);
 return 0;
}

Best Practices for ioctl

Use Explicit Command Definitions:
- Follow a consistent naming convention for command macros.
Secure User-Kernel Data Transfer:
- Always validate pointers and sizes.
- Use copy_from_user and copy_to_user for safe data exchange.
Error Handling:
- Return appropriate error codes for unsupported commands or invalid inputs.
Limit ioctl Usage:
- Avoid using ioctl for operations that can be implemented using read or write.
Magic Number: Ensure it’s unique (check Documentation/ioctl/ioctl-number.txt in kernel sources).
Atomicity: Use locks if hardware operations are not atomic.
Cross-Platform: Handle 32/64-bit compatibility with compat_ioctl if needed.

Real-World Example: Custom ARM Board

For a custom ARM board, you might need an ioctl to configure hardware parameters like GPIO modes or clock frequencies.

Kernel Log Level

Wed, 20 Nov 2024 16:23:00 +0000

Number	Macro	Log Level	Description	Equivalent
0	`pr_emerg`	Emergency	System is unusable.	`KERN_EMERG`
1	`pr_alert`	Alert	Action must be taken immediately.	`KERN_ALERT`
2	`pr_crit`	Critical	Critical conditions.	`KERN_CRIT`
3	`pr_err`	Error	Error conditions.	`KERN_ERR`
4	`pr_warn`	Warning	Warning conditions.	`KERN_WARNING`
5	`pr_notice`	Notice	Normal but significant condition.	`KERN_NOTICE`
6	`pr_info`	Informational	Informational messages.	`KERN_INFO`
7	`pr_debug` `pr_devel`	Debug	Debugging messages. `pr_debug()` and `pr_devel()` if DEBUG is defined	`KERN_DEBUG`

The number corresponds to the log level used by the Linux kernel, with lower numbers indicating higher severity.
For example, if the log level is set to 4 (Warning), only messages from pr_emerg to pr_warn will appear in the system logs. Default log level is generally set to 6.
You can check the current console_loglevel with:

cat /proc/sys/kernel/printk
4 4 1 7

echo 8 > /proc/sys/kernel/printk

dmesg -n 5

Reference

https://www.kernel.org/doc/html/next/core-api/printk-basics.html

I2C

Fri, 08 Nov 2024 21:40:00 +0000

Basics of I2C

Overview

Synchronous, multi-master, multi-slave serial bus.
Half-duplex communication (bidirectional SDA line).
Uses 2 wires: SCL (clock), SDA (data).
Speeds: Standard (100 kHz), Fast (400 kHz), High-Speed (3.4 MHz).

Physical Layer

Open-drain outputs – requires pull-up resistors.
7-bit or 10-bit addressing (supports up to 128/1024 devices).

Data Frame Structure

Start condition: SDA ↓ while SCL is high.
Address frame: 7/10-bit address + R/W bit.
ACK/NACK: Slave pulls SDA low to acknowledge.
Data frames (8-bit chunks, MSB-first).
Stop condition: SDA ↑ while SCL is high.

Start | Address | Read/Write | ACK/NACK | Data | Stop

Key Features

Clock stretching: Slaves can hold SCL low to pause communication.
Multi-master arbitration: Masters detect collisions via SDA monitoring.
Speeds: Standard (100 kbps), Fast (400 kbps), High-Speed (3.4 Mbps).

Use Cases

Sensors (temperature, accelerometers).
EEPROMs, RTC (Real-Time Clock) modules.

Device Tree

TODO

Writing client device drivers

TODO

I2C-Tools Package in Userspace

Useful for debugging, testing, some simple prototyping
Accesses the I²C bus via /dev/i2c-0, /dev/i2c-1…
Assume devices have registers, SMBus-like

i2cdetect

scan an I2C bus for devices
No guarantee it works (I²C is not discoverable by the spec)

[rishav] ➜ ~ i2cdetect -l
i2c-0 i2c i915 gmbus dpc I2C adapter
i2c-1 i2c i915 gmbus dpb I2C adapter
i2c-2 i2c i915 gmbus dpd I2C adapter
i2c-3 i2c AUX A/DDI A/PHY A I2C adapter
i2c-4 unknown Synopsys DesignWare I2C adapter N/A
i2c-5 unknown Synopsys DesignWare I2C adapter N/A
i2c-6 unknown SMBus I801 adapter at f040 N/A
[rishav] ➜ ~ i2cdetect -y 2
 0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- 28 -- -- -- -- -- -- --
30: -- -- -- UU -- -- -- -- -- -- -- -- -- -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- --

-- No response
28 Response from address 28
UU Address in use (by driver)

i2cget, i2cset

i2cget: read a register value
i2cset: set a register value
Can use various types of SMBus and I2C transactions
Limited to 8-bit register address

# i2cget -y 2 0x28 0x1b
0x21
# i2cset -y 2 0x28 0x55
#

i2cdump

dump value of all registers

i2ctransfer

i2ctransfer: the “swiss army knife of Linux I2C”, in userspace
Example: reimplement the i2cget -y 2 0x28 0x1b command:

# i2ctransfer -y 2 w1@0x28 0x1b r1@0x28
0x21
#

w1@0x28 Write transaction, 1 byte, client address 0x28
0x1b Data to send in the write transaction
r1@0x28 Read transaction, 1 byte, client address 0x28

Troubleshooting

Return code from i2c_*() functions — Never ignore errors!
Kernel logs
i2c-tools
Oscilloscope or logic analyzer

No ACK from client - systematic

Problem: a client never responds to transactions

Drivers on Rishav's Digital Garden

Character Device Management in Kernel Drivers

Overview

Make Simple Kernel Module (.ko)

1. Overview

System Call (Software Interrupt)

1. System Call Basics

2. System Call Table and Registration

Syscall Table:

3. Flow of System Calls

1. User-Space Invocation

2. Transition to Kernel Mode

3. Syscall Dispatching

4. Handler Execution in Process Context

Generic Steps for All Syscalls:

File Operations (read/write):

I/O Control (ioctl):

5. Return to User Space:

4. Device File Operations

Generic GPIO Management in Linux

Introduction

GPIO Interfaces in Linux

1. Sysfs GPIO Interface (Deprecated)

IOCTL in Kernel Device Drivers

ioctl Implementation in Kernel Device Drivers

Overview

How ioctl Works

1. User-Space Interaction:

2. Driver-Side Handling:

3. Data Flow:

Steps to Implement ioctl in a Kernel Driver

1. Define ioctl Commands:

2. Implement ioctl Callback:

3. Integrate into file_operations:

4. Test the ioctl Implementation:

Best Practices for ioctl

Real-World Example: Custom ARM Board

Kernel Log Level

Reference

I2C

Basics of I2C

Overview

Physical Layer

Data Frame Structure

Key Features

Use Cases

Device Tree

Writing client device drivers

I2C-Tools Package in Userspace

i2cdetect

i2cget, i2cset

i2cdump

i2ctransfer

Troubleshooting

No ACK from client - systematic

File Operations (`read`/`write`):

I/O Control (`ioctl`):