7.4. Writing the Ranging Sensor Kernel Module

#include <linux/module.h>
#include <linux/kernel.h>
#include <linux/init.h>
#include <linux/gpio.h>
#include <linux/delay.h>
#include <linux/fs.h>
#include <linux/uaccess.h>
#define TRIGGER_PIN 17 // GPIO pin for trigger
#define ECHO_PIN 27 // GPIO pin for echo
#define DEVICE_NAME "ranging_sensor"
// Variables to store device data
static int distance = 0;
static int major_number;

In this step, we include the necessary header files to access the kernel functions and definitions for our module. Each header file serves a specific purpose:

• #include <linux/module.h>: This allows us to define a kernel module.
• #include <linux/kernel.h>: This is needed for kernel-related functions (like printk).
• #include <linux/init.h>: This is used for initialization functions in modules.
• #include <linux/gpio.h>: This header allows access to GPIO functionality.
• #include <linux/delay.h>: Helps in creating delays in microseconds.
• #include <linux/fs.h>: This includes definitions for file structures needed for device handling.
• #include <linux/uaccess.h>: For transferring data between user space and kernel space.

Additionally, we define constants for the GPIO pins and declare variables to store the distance measurement and the major number for our device.

Think of these header files as the toolbox for a mechanic. Just like a mechanic needs specific tools to fix cars, the kernel module needs these headers to perform specific tasks like handling GPIO and operating the kernel.

static int __init sensor_init(void)
{
    printk(KERN_INFO "Ranging Sensor Kernel Module: Initializing...\n");
    // Request GPIO pins
    if (!gpio_is_valid(TRIGGER_PIN) || !gpio_is_valid(ECHO_PIN)) {
        printk(KERN_ERR "Invalid GPIO pins\n");
        return -ENODEV;
    }
    // Request Trigger Pin
    if (gpio_request(TRIGGER_PIN, "Trigger") < 0) {
        printk(KERN_ERR "Failed to request Trigger Pin\n");
        return -EBUSY;
    }
    // Request Echo Pin
    if (gpio_request(ECHO_PIN, "Echo") < 0) {
        printk(KERN_ERR "Failed to request Echo Pin\n");
        gpio_free(TRIGGER_PIN);
        return -EBUSY;
    }
    // Set GPIO direction (Trigger as output, Echo as input)
    gpio_direction_output(TRIGGER_PIN, 0);
    gpio_direction_input(ECHO_PIN);
    // Register device with major number dynamically assigned
    major_number = register_chrdev(0, DEVICE_NAME, &fops);
    if (major_number < 0) {
        printk(KERN_ERR "Failed to register device\n");
        gpio_free(TRIGGER_PIN);
        gpio_free(ECHO_PIN);
        return major_number;
    }
    printk(KERN_INFO "Ranging Sensor Kernel Module: Device registered with major number %d\n", major_number);
    return 0;
}

In this step, we write the initialization function for our kernel module, called sensor_init. The function performs the following tasks:

1. It logs a message indicating that the module is initializing.
2. It checks if the specified GPIO pins are valid.
3. It requests access to the Trigger and Echo pins, and handles any errors if the requests fail.
4. It sets the Trigger pin as an output and the Echo pin as an input to configure them for the sensor.
5. Finally, it registers the device with a dynamic major number. This allows user space to interact with the device. If the registration fails, it frees the GPIO pins and returns an error. Overall, this step is critical for preparing the sensor for operation.

Consider this step like preparing a bicycle before a race. You need to ensure that all the parts are functioning (like checking the brakes and tires) and making adjustments (like setting the handlebars) before you can start racing.

static int measure_distance(void)
{
    int duration;
    unsigned long start_time, end_time;
    // Send a 10us pulse to the Trigger Pin
    gpio_set_value(TRIGGER_PIN, 1);
    udelay(10); // 10 microseconds
    gpio_set_value(TRIGGER_PIN, 0);
    // Wait for the Echo Pin to go high (indicating signal return)
    start_time = jiffies;
    while (gpio_get_value(ECHO_PIN) == 0) {
        if (time_after(jiffies, start_time + msecs_to_jiffies(1))) {
            return -1; // Timeout if no echo received
        }
    }
    // Measure the duration of the high pulse
    start_time = jiffies;
    while (gpio_get_value(ECHO_PIN) == 1) {
        if (time_after(jiffies, start_time + msecs_to_jiffies(100))) {
            return -1; // Timeout if no echo received
        }
    }
    end_time = jiffies;
    // Calculate duration in microseconds
    duration = jiffies_to_usecs(end_time - start_time);
    // Calculate distance in centimeters (based on the speed of sound in air)
    distance = duration / 58; // Distance in cm
    return 0;
}

This chunk describes how the module measures the distance using the sensor. The measure_distance function does the following:

1. It initializes a variable to store the duration of the echo.
2. It sends a trigger pulse of 10 microseconds to start the sensor measurement.
3. Then it waits for the Echo pin to go high, indicating that the sound wave has bounced back.
4. It measures the duration that the Echo pin stays high, which indicates how long it took for the sound to travel to the object and back.
5. Finally, it calculates the distance using the time measured and the known speed of sound, dividing by 58 to convert to centimeters. This function is the core functionality of the module by allowing it to convert time into a distance measurement.

Think of measuring distance like using a tape measure. You first stretch the tape out (sending the pulse), wait for it to reflect back from the wall (the echo), and then read the measurement of how far the wall is from you (calculating distance).

static ssize_t device_read(struct file *file, char __user *buffer, size_t len, loff_t *offset)
{
    char dist_str[10];
    int ret;
    // Measure the distance
    if (measure_distance() < 0) {
        printk(KERN_ERR "Failed to measure distance\n");
        return -EIO;
    }
    // Convert distance to string and copy to user space
    snprintf(dist_str, sizeof(dist_str), "%d\n", distance);
    ret = copy_to_user(buffer, dist_str, strlen(dist_str));
    if (ret) {
        printk(KERN_ERR "Failed to send data to user space\n");
        return -EFAULT;
    }
    return strlen(dist_str); // Return number of bytes sent to user space
}

This step focuses on how the module provides distance data to user space. The function device_read is designed to:

1. Call the measure_distance function to get the latest distance measurement.
2. Convert that measurement from an integer to a string format.
3. Copy that string back to the user space through the buffer provided.
4. Return the number of bytes sent. If an error occurs at any step, it reports the error via printk and returns an appropriate error code. This function forms the interface for user applications to receive distance data.

Imagine a mail courier delivering your measuring tape result. The device_read is the courier who measures the distance using a method and then delivers a written report (the string format of distance) back to you.

static void __exit sensor_exit(void)
{
    unregister_chrdev(major_number, DEVICE_NAME); // Unregister device
    gpio_free(TRIGGER_PIN); // Free Trigger Pin
    gpio_free(ECHO_PIN); // Free Echo Pin
    printk(KERN_INFO "Ranging Sensor Kernel Module: Unloaded\n");
}
module_init(sensor_init);
module_exit(sensor_exit);
MODULE_LICENSE("GPL");
MODULE_AUTHOR("Your Name");
MODULE_DESCRIPTION("A simple kernel module for ultrasonic ranging sensor");

In this final step, we define the cleanup process for the module within sensor_exit. The function does the following:

1. It unregisters the character device using the previously assigned major number, which removes the device from the system.
2. It frees the GPIO pins that were used, ensuring there are no resource leaks.
3. It logs a message indicating that the module has been successfully unloaded. The macros module_init and module_exit link the initialization and cleanup functions to the module's lifecycle. These are important for ensuring the module can be loaded and unloaded correctly in the kernel, maintaining system stability.

Think of this cleanup as putting away all the tools and equipment after a project is finished. You want to ensure everything is properly stored (freed) and that your workspace is clean (unregistered) before you leave.

--