Hello World Linux Character Device Driver

Target Platform: BeagleBone Black (ARM)

---

📌 Overview

This repository contains a Hello World Linux character device driver developed for learning and demonstration purposes.
The project shows the complete workflow of writing, building, deploying, and testing a pseudo character device driver on both a host machine and a BeagleBone Black target.

The driver creates a device file under /dev and supports simple read and write operations using a fixed-size kernel buffer.

---

🎯 Target Platform

Item	Description
Board	BeagleBone Black
Architecture	ARM
OS	Embedded Linux system built using Yocto
Kernel Module Type	Character Device Driver

---

🧠 Concepts Covered

• Linux kernel modules
• Character device drivers
• Major and minor number allocation
• cdev registration
• File operations (open, read, write, release)
• User space ↔ kernel space communication
• Automatic device node creation (/dev)
• Cross-compilation for embedded targets
• Module lifecycle management

---

📁 Repository Structure

.
├── hello.c        # Character device driver source code
├── Makefile       # Host & BeagleBone Black build configuration
├── script.sh      # Script to build, insert, test, and remove the driver
└── README.md      # Project documentation

⚙️ Requirements

Host Machine

• Linux OS (tested on Ubuntu 22.04)
• GNU Make
• GCC compiler
• Linux kernel headers

    sudo apt update
    sudo apt install build-essential linux-headers-$(uname -r)

Target: BeagleBone Black

• Running Linux OS
• Kernel headers or full kernel source
• Cross-compilation toolchain (arm-linux-gnueabihf-)

Download BeagleBone Black Kernel Source :

The official BeagleBone kernel source can be obtained from the BeagleBoard GitHub repository.

git clone https://github.com/beagleboard/linux.git
cd linux

Checkout a kernel version matching the one running on the BeagleBone Black:

git checkout <kernel-version>

Check the kernel version on the board:

uname -r

Example toolchain installation for cross compilation:

sudo apt install gcc-arm-linux-gnueabihf

🔧 Build Configuration

The project supports native host builds and cross-compiled target builds.

🖥️ Host Build (Native)

    make host

🎯 Target Build (BeagleBone Black))

    make 

Cross-compilation parameters such as ARCH, CROSS_COMPILE, and KERNEL_SRC are defined in the Makefile.

📦 Driver Management Script

A helper script (script.sh) is provided to simplify common operations.

Script Usage

./script.sh insert <host|target> <module_name> <device_file>
./script.sh remove <host|target> <module_name>
./script.sh test   <host|target> <module_name> <device_file>

Example (BeagleBone Black)

./script.sh insert target hello test_file
./script.sh test target hello test_file

Deployment to BeagleBone Black

1. Copy the kernel module to the board:

scp hello.ko <BBB_Hostname>@<BBB_IP>:/home/

2.On the BeagleBone Black:

sudo insmod hello.ko

3. Verify module insertion:

lsmod | grep hello

🧪 Usage Example

Verify Device File

ls /dev/test_file

Write to Device

echo "Hello BeagleBone Black" > /dev/test_file

Read from Device

cat /dev/test_file

View Kernel Logs

dmesg | tail

🔍 Driver Architecture

1️⃣ Module Initialization

• Allocates major and minor device numbers
• Registers a character device (cdev)
• Creates device class and device node

2️⃣ File Operations

Operation	Description
open	Called when the device is opened
read	Copies data from kernel buffer to user space
write	Copies data from user space to kernel buffer
release	Called when the device is closed

3️⃣ Kernel Buffer

• Fixed-size internal buffer (15 bytes)
• Overflow protection
• Data transfer via copy_from_user() and copy_to_user()

4️⃣ Module Cleanup

• Removes device node
• Destroys class
• Unregisters character device
• Frees allocated device numbers

🧹 Module Removal

Using Script

./driver_ctl.sh remove target hello

Manually

sudo rmmod hello

🛠️ Troubleshooting

Device file not found

ls /dev | grep test_file

Check kernel logs:

dmesg

Module insertion failed

• Verify kernel version matches headers
• Ensure correct architecture build

uname -r
file hello.ko

👤 Author

Achraf Mansour

Embedded Systems Engineer