Platform

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/. ...

SPI (Serial Peripheral Interface) Overview Synchronous, full-duplex serial bus. Master-slave architecture (1 master, multiple slaves). Uses 4 wires: SCLK (clock), MOSI (Master Out Slave In), MISO (Master In Slave Out), SS/CS (Slave Select). Physical Layer Push-pull outputs (faster than open-drain). Each slave requires a dedicated SS line. Data Frame Structure No start/stop bits – continuous stream synchronized to SCLK. Data sampled on clock edges defined by CPOL (clock polarity) and CPHA (clock phase): Mode 0: CPOL=0 (idle low), CPHA=0 (sample on rising edge). Mode 3: CPOL=1 (idle high), CPHA=1 (sample on falling edge). SCLK | MOSI (Data from Master) | MISO (Data from Slave) | CS (Active Low) Key Features Full-duplex communication (simultaneous MOSI/MISO). No addressing – slaves selected via SS lines. Speeds: Up to 100+ Mbps (depends on hardware). Pros & Cons Pros Cons High-speed communication High pin count (n+3 for n slaves) Simple protocol, flexible modes No built-in error detection Full-duplex support No multi-master support Use Cases High-speed sensors (e.g., IMUs). Display controllers (OLED, TFT). SD cards, NOR flash memory. Comparison Table Feature UART I2C SPI Clock None (async) Shared (SCL) Shared (SCLK) Duplex Full-duplex Half-duplex Full-duplex Topology Point-to-point Multi-device Master-slave Speed Low (≤115kbps) Moderate (≤3.4Mbps) High (≥10Mbps) Addressing None 7/10-bit Hardware (SS lines) Pins 2 (TX/RX) 2 (SCL/SDA) 4 + n (SS per slave) Error Handling Parity bit ACK/NACK None

UART (Universal Asynchronous Receiver-Transmitter) UART is a simple, asynchronous serial communication protocol used for full-duplex communication between two devices. Key Features: Asynchronous: No clock signal – relies on pre-agreed baud rate (e.g., 9600, 115200 bps). Uses two main lines: TX (Transmit) and RX (Receive). Configurable baud rate (e.g., 9600, 115200 bps). Error detection: Parity bit (optional). Flow control: Hardware (RTS/CTS) or software (XON/XOFF). No addressing – only two devices per bus. Data Frame Structure Start bit (1 bit, logic low). Data bits (5–9 bits, LSB-first). Parity bit (optional, even/odd/none). Stop bit(s) (1 or 2 bits, logic high). Start Bit | Data Bits (5-9) | Parity Bit (Optional) | Stop Bit (1-2) Points to Remember If the baud rate is set as 115200, then the recever will expect stop bit that is high state for 1 baud period(generally). Usage in Linux Kernel: #include <linux/serial_core.h> struct uart_port *port; uart_write(port, "Hello", 5); Use Cases Debugging consoles (e.g., Linux kernel printk via UART). GPS modules, Bluetooth/Wi-Fi modules.

Monolithic Kernel All core OS services (memory management, process scheduling, file systems, drivers) reside in kernel space. Example: Linux Kernel. Pros: Fast performance, direct access to hardware. Cons: Large codebase, difficult debugging, crashes can affect the whole system. Microkernel Minimal core kernel, with most services running in user space. Example: QNX, Minix. Pros: Stability, modularity, better security. Cons: Performance overhead due to inter-process communication (IPC).

1. Overview RTOS (Real-Time Operating System): Designed for deterministic, time-critical applications with low-latency response. Why RTOS over Linux? Deterministic Execution: RTOS ensures tasks meet strict timing deadlines, unlike Linux, which has non-deterministic scheduling. Low Overhead: RTOS has minimal context switching overhead and no user/kernel space separation. Resource-Constrained Devices: Ideal for microcontrollers (MCUs) with limited memory and processing power. Fast Boot Times: RTOS boots in milliseconds, while Linux requires a much longer initialization process. Interrupt Handling: More responsive to real-time interrupts, whereas Linux introduces latency due to its complex scheduler. FreeRTOS: A lightweight, open-source RTOS widely used in embedded systems. Linux Kernel: A general-purpose OS with multi-user capabilities, used in complex embedded and desktop/server systems. 2. FreeRTOS vs. Linux Kernel (Key Differences) Kernel vs. User Space FreeRTOS: It doesn’t have the concept of a user space and kernel space like Linux. The whole system is essentially one space, and tasks directly interact with the kernel (RTOS). You can think of FreeRTOS as a single program running with different tasks that can interact with each other or with hardware directly. Linux Kernel: Linux operates with a strict separation between user space and kernel space. User applications cannot directly interact with hardware; they must go through system calls, which are handled by the kernel. Scheduler FreeRTOS: Preemptive, cooperative, or tickless scheduling. Supports priority-based scheduling (fixed priority, round-robin, etc.). Simple task model, each task runs in its own stack but shares memory. Linux Kernel Also has a preemptive scheduler, but it is much more complex, as it must handle multiple users, system calls, different types of scheduling (e.g., real-time, normal tasks), and various priorities. Linux is optimized for fairness CFS (Completely Fair Scheduler) and general-purpose multitasking. The FreeRTOS scheduler, by contrast, is simpler and more deterministic. Processes FreeRTOS: Does not have a “process” model like Linux. Instead, it has tasks. Tasks in FreeRTOS can be thought of as lightweight threads. FreeRTOS doesn’t manage the memory space for each task in the same way Linux does for processes. All tasks share the same address space and run in the same context. Linux Kernel: Linux uses processes, each of which has its own memory space. Processes in Linux can be multi-threaded, and each thread can have different scheduling characteristics. Linux processes are isolated from each other, so one process crashing doesn’t affect others. Memory Management FreeRTOS: Memory management is more manual. FreeRTOS does not have sophisticated memory management like Linux. It provides basic functions for allocating fixed-size blocks or dynamic memory pools (pvPortMalloc, vPortFree). It doesn’t have virtual memory, so all tasks have access to the same memory space, making it much simpler but also more prone to memory corruption if not managed properly. Linux Kernel: Linux includes virtual memory, meaning each process has its own virtual address space. It supports advanced features like paging and memory protection. The Linux kernel has a memory management unit (MMU) and sophisticated memory allocators for heap, stack, and memory mapping. Drivers FreeRTOS: Drivers in FreeRTOS are usually written to interface directly with the hardware. Embedded developers write hardware-specific drivers for devices such as GPIO, UART, SPI, I2C, etc. The drivers are tightly coupled with the hardware and typically run in the same task context as the rest of the application. Interfacing with hardware is done via direct memory-mapped registers and interrupt service routines (ISRs). Linux Kernel: The Linux kernel has a comprehensive set of device drivers for a wide variety of hardware. Drivers in Linux are implemented as kernel modules, which can be dynamically loaded and unloaded. These drivers abstract hardware interactions and often provide a system call interface for user-space applications to interact with hardware. GPIO Management FreeRTOS: Direct register manipulation or vendor-specific HAL libraries. No standard GPIO subsystem like Linux. GPIO interrupts are handled using ISR (Interrupt Service Routines) with FreeRTOS primitives like queues for event notification. Linux Kernel: GPIO Subsystem: Provides an abstraction layer using sysfs, character devices, or device tree bindings. Uses kernel interrupt handling with debounce and polling mechanisms. Interrupt Handling FreeRTOS: Interrupt handling is done through Interrupt Service Routines (ISRs), which are small, time-critical functions that handle hardware interrupts. FreeRTOS provides mechanisms to synchronize tasks with ISRs via semaphores or queues. Linux Kernel: Linux also uses ISRs, but in addition to regular interrupts, it has a more complex mechanism for handling asynchronous events, such as software interrupts, tasklets, work queues, etc. The kernel abstracts much of the interrupt management for portability. Synchronization Mechanisms FreeRTOS: Offers simple synchronization primitives like semaphores, mutexes, queues, and event groups. These are lightweight and highly optimized for small systems with limited resources. Linux Kernel: Linux also provides synchronization mechanisms like semaphores, mutexes, and spinlocks. However, these mechanisms are more complex and support features like priority inversion prevention, as well as various types of locking for different kernel contexts. Filesystem and I/O FreeRTOS: By default, FreeRTOS does not provide any filesystem management or complex I/O subsystem. I/O is typically done through simple APIs provided by the BSP or device driver code. Linux Kernel: Linux supports a full-fledged filesystem with many types (e.g., ext4, NTFS) and includes complex device I/O management, including file descriptors, blocking/non-blocking I/O, and extensive support for network file systems (NFS, CIFS). Conclusion: Feature FreeRTOS Linux Kernel Kernel/User Space Single space Separated Scheduler Priority-based, Preemptive CFS, RT scheduling Driver Model Direct access, HAL-based Kernel module-based GPIO Management Direct register access Standard GPIO subsystem Process Model Tasks only Processes & Threads Memory Management Heap-based, no MMU Virtual memory, MMU support Use Cases Real-time, MCUs High-performance, SBCs, SoCs FreeRTOS and Linux serve different purposes in embedded systems: ...

Overview Character devices allow byte-by-byte communication between user-space applications and kernel drivers. They are commonly used for devices like serial ports, sensors, and custom hardware interfaces. The Linux kernel provides mechanisms for registering, managing, and interacting with character devices via a device file in /dev. Registering a Character Device To register a character device, the driver needs to: 1. Allocate a Major and Minor Number: Each character device is identified by a major number (device type) and a minor number (specific device). The major number indicates the driver associated with the device, while the minor number is used to differentiate between multiple devices handled by the same driver. If major and minor numbers are repeated, it can cause conflicts and lead to incorrect device identification. To avoid this, the kernel provides alloc_chrdev_region, a function to dynamically allocate major and minor numbers, ensuring uniqueness. These numbers are used in the /dev directory to associate device files with their corresponding drivers. Use alloc_chrdev_region to dynamically allocate a major number. dev_t dev; int result; // kernel/fs/char_dev.c // int alloc_chrdev_region(dev_t *dev, unsigned baseminor, unsigned count, const char *name) result = alloc_chrdev_region(&dev, 0, 1, "my_char_device"); if (result < 0) { pr_err("Failed to allocate major number\n"); return result; } pr_info("Device registered with major %d, minor %d\n", MAJOR(dev), MINOR(dev)); 2. Initialize and Register the Device: Define a cdev structure and initialize it with file operations. Use cdev_add to register the device with the kernel. struct cdev my_cdev; cdev_init(&my_cdev, &my_fops); my_cdev.owner = THIS_MODULE; result = cdev_add(&my_cdev, dev, 1); if (result < 0) { pr_err("Failed to add cdev\n"); unregister_chrdev_region(dev, 1); return result; } 3. Create a Device File (Optional): Creating a device file in /dev is optional because character devices can be accessed directly using their major and minor numbers through system calls or user-space libraries, bypassing the need for a device file. However, creating a file in /dev makes interaction more user-friendly by providing a standard interface. To interact with a character device without creating a device file, you can use system calls like mknod to create a temporary device node or interact with the device directly using its major and minor numbers programmatically. Use class_create and device_create to automatically create a device file in /dev. struct class *my_class; my_class = class_create(THIS_MODULE, "my_device_class"); if (IS_ERR(my_class)) { pr_err("Failed to create class\n"); cdev_del(&my_cdev); unregister_chrdev_region(dev, 1); return PTR_ERR(my_class); } device_create(my_class, NULL, dev, NULL, "my_char_device"); File Operations Character devices are controlled through a set of file operations defined in a struct file_operations. These operations determine how the device responds to system calls like open, read, write, and ioctl. ...

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: Register the ioctl handler in the file_operations structure. 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. ...

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 Debug Debugging messages. 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.

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 ...

Preparation Install Dependencies sudo pacman -S base-devel xmlto kmod inetutils bc libelf git --needed Downloading source and local setup It is recommended to create a separate build directory for your kernel(s). In this example, the directory kernelbuild will be created in the home directory: mkdir ~/kernelbuild cd ~/kernelbuild Goto kernel.org and download kernel source wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.14.5.tar.xz Note: you can verify signature of the downloaded tarball if you want Extract tarball tar -xvJf linux-5.14.5.tar.xz Check ...