navidpadid · navidpadid · Jan 4, 2026 · Dec 20, 2025 · Jan 4, 2026 · Jan 4, 2026
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,63 @@
+Dual BSD/GPL License
+
+This project is licensed under a dual license model:
+- You may use this software under the BSD License, OR
+- You may use this software under the GNU General Public License version 2 (GPLv2)
+
+You may choose which license you prefer to follow.
+
+================================================================================
+BSD License
+================================================================================
+
+Copyright (c) 2026, Navid Malek
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+================================================================================
+GNU General Public License version 2
+================================================================================
+
+Copyright (C) 2026 Navid Malek
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 2 as
+published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+================================================================================
+
+The full text of the GNU General Public License version 2 can be found at:
+https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
diff --git a/Makefile b/Makefile
@@ -18,7 +18,7 @@ SRC_DIR := src
 # Build directory for user program
 BUILD_DIR := build
 
-.PHONY: all clean module user install uninstall test help
+.PHONY: all clean module user install uninstall test help unit
 
 # Default target
 all: module user
@@ -38,6 +38,17 @@ user:
 	gcc -Wall -o $(BUILD_DIR)/$(USER_PROG) $(SRC_DIR)/$(USER_PROG).c
 	@echo "User program built successfully!"
 
+# Function-level unit tests (user-space)
+unit:
+	@echo "Building function-level unit tests..."
+	@mkdir -p $(BUILD_DIR)
+	gcc -Wall -I$(SRC_DIR) -o $(BUILD_DIR)/elf_det_tests $(SRC_DIR)/elf_det_tests.c
+	gcc -Wall -I$(SRC_DIR) -o $(BUILD_DIR)/proc_elf_ctrl_tests $(SRC_DIR)/proc_elf_ctrl_tests.c
+	@echo "Running unit tests..."
+	@$(BUILD_DIR)/elf_det_tests
+	@$(BUILD_DIR)/proc_elf_ctrl_tests
+	@echo "All function-level unit tests passed!"
+
 # Install kernel module (requires root)
 install: module
 	@echo "Installing kernel module..."

diff --git a/README.md b/README.md
@@ -47,6 +47,10 @@ kernel_module/
 ├── src/
 │   ├── elf_det.c           # Kernel module source code
 │   ├── proc_elf_ctrl.c     # User-space controller program
+│   ├── elf_det_tests.c     # Unit tests for elf_det functions
+│   ├── proc_elf_ctrl_tests.c  # Unit tests for proc_elf_ctrl helpers
+│   ├── elf_helpers.h       # Helper functions for CPU usage and BSS range
+│   ├── user_helpers.h      # Helper functions for path building
 │   └── Kbuild              # Kernel build configuration
 ├── Makefile                # Build system
 ├── .gitignore              # Git ignore rules
@@ -55,7 +59,9 @@ kernel_module/
 Generated after build:
 └── build/                  # Build artifacts (created by make)
     ├── elf_det.ko          # Compiled kernel module
-    └── proc_elf_ctrl       # Compiled user program
+    ├── proc_elf_ctrl       # Compiled user program
+    ├── elf_det_tests       # Compiled unit tests for elf_det
+    └── proc_elf_ctrl_tests # Compiled unit tests for proc_elf_ctrl
 ```
 
 ## Prerequisites
@@ -168,18 +174,6 @@ For maximum safety, test the kernel module in an isolated QEMU virtual machine t
 ./scripts/qemu-test.sh
 ```
 
-### Requirements
-
-```bash
-# Ubuntu/Debian
-sudo apt-get install qemu-system-x86 qemu-utils cloud-image-utils
-
-# macOS
-brew install qemu
-
-# Fedora
-sudo dnf install qemu-system-x86 qemu-img cloud-utils
-```
 
 ### What QEMU Testing Does
 
@@ -201,6 +195,7 @@ See [scripts/README.md](scripts/README.md) for detailed QEMU testing documentati
 | `make install` | Install kernel module (requires root) |
 | `make uninstall` | Remove kernel module (requires root) |
 | `make test` | Install module and run user program |
+| `make unit` | Build and run function-level unit tests (no kernel required) |
 | `make clean` | Remove all build artifacts |
 | `make help` | Display help message |
 
@@ -213,7 +208,7 @@ The kernel module creates entries in `/proc/elf_det/`:
 - `/proc/elf_det/det` - Read-only file to retrieve process information
 
 **Key Functions:**
-- `tops_show()` - Main function to gather and format process information
+- `elfdet_show()` - Main function to gather and format process information
 - `procfile_write()` - Handles PID input from user space
 - `procfile_read()` - Returns formatted process data
 
@@ -225,10 +220,23 @@ The kernel module creates entries in `/proc/elf_det/`:
 
 ### User Program (`proc_elf_ctrl.c`)
 
-Simple C program that:
-1. Prompts user for a PID
-2. Writes PID to `/proc/elf_det/pid`
-3. Reads and displays process information from `/proc/elf_det/det`
+Simple C program that supports two modes:
+1. Interactive: prompts for a PID, writes to `/proc/elf_det/pid`, then reads `/proc/elf_det/det` and prints two lines
+2. Argument mode: run `./build/proc_elf_ctrl <PID>` to write the PID and print exactly two lines non-interactively
+
+You can override the proc directory for testing with the environment variable `ELF_DET_PROC_DIR`.
+
+Example:
+
+```bash
+ELF_DET_PROC_DIR=/tmp/fakeproc ./build/proc_elf_ctrl 12345
+```
+
+Internally, path construction is handled via helper `build_proc_path()`.
+
+Helper headers used:
+- `src/user_helpers.h` – path building with env override
+- `src/elf_helpers.h` – pure functions for CPU usage and BSS range
 
 ## Testing
 
@@ -243,17 +251,23 @@ The module has been tested on:
 - The code has been updated to use modern kernel APIs including VMA iterators and proc_ops
 
 **Safe Testing Options:**
-1. **Dev Container** (current setup) - Isolated from host kernel
-2. **QEMU VM** (recommended for extra safety) - See [scripts/README.md](scripts/README.md)
-3. **Cloud VM** - Disposable testing environment
+### Function-Level Unit Tests
 
-## Related Documentation
+Run pure function tests (no kernel required):
 
-For detailed implementation guides, refer to the blog posts:
+```bash
+make unit
+```
+
+This builds and runs:
+- `src/elf_det_tests.c` – verifies `compute_usage_permyriad()` and `compute_bss_range()`
+- `src/proc_elf_ctrl_tests.c` – verifies `build_proc_path()` with and without `ELF_DET_PROC_DIR`
+
+Artifacts are created under `build/`.
+1. **Dev Container** (current setup) - Isolated from host 
+2. **QEMU VM** (recommended for extra safety from kernel) - See [scripts/README.md](scripts/README.md)
+3. **Cloud VM** - Disposable testing environment
 
-- **Part 2.1**: [Implementation of Simple "hello world" Module and Run](http://navidmalek.blog.ir/1396/07/07/Linux-2-1-Implementation-of-Simple-%E2%80%9Chello-world%E2%80%9D-Module-and-Run)
-- **Part 2.2**: [Finding specified information and necessary functions](http://navidmalek.blog.ir/1396/07/07/Linux-2-2-Part-2-2-Finding-specified-information-and-necessary-functions-to-implement-desired-module)
-- **Part 2.3**: [Implementation of kernel module and user program](http://navidmalek.blog.ir/1396/07/07/Linux-2-3-Part-2-3-Implementation-of-desired-kernel-module-and-user-program)
 
 ## Important Notes
 
@@ -302,23 +316,24 @@ This project is licensed under **Dual BSD/GPL** license.
 
 ## Author
 
-**Navid Malek**
-
-- Blog: [navidmalek.blog.ir](http://navidmalek.blog.ir)
-- Project: [process-info-kernel-module](https://github.com/navidpadid/process-info-kernel-module)
+**Navid Malekghaini**
 
 ## Contributing
 
-Contributions, issues, and feature requests are welcome! Feel free to check the issues page.
+Contributions, issues, and feature requests are welcome!
 
 ## Changelog
 
 ### Version 1.0
 - Initial release with basic process information extraction
 - Support for CPU usage, memory layout, and ELF sections
 - User-space controller program
-- Dev container support
+- Function-level unit tests for core functionality
+- Dev container support for isolated development
 - CI/CD pipeline with GitHub Actions
+- QEMU testing environment for safe kernel module testing
+- Comprehensive documentation and quick reference guides
+- Dual BSD/GPL license
 
 ---
 

diff --git a/scripts/README.md b/scripts/README.md
@@ -1,6 +1,10 @@
 # QEMU Testing Scripts
 
-Scripts for safely testing the kernel module in an isolated QEMU virtual machine.
+Scripts for safely testing the Linux Process Information Kernel Module in an isolated QEMU virtual machine.
+
+## Overview
+
+These scripts provide a complete QEMU-based testing environment that isolates kernel module testing from your host system. This is the recommended approach for testing kernel modules as it prevents potential system crashes or instability from affecting your development machine.
 
 ## Quick Start
 
@@ -11,7 +15,7 @@ Scripts for safely testing the kernel module in an isolated QEMU virtual machine
 # 2. Start the QEMU VM
 ./scripts/qemu-run.sh
 
-# 3. In another terminal, test the module
+# 3. In another terminal, run automated tests
 ./scripts/qemu-test.sh
 ```
 
@@ -40,15 +44,21 @@ Scripts for safely testing the kernel module in an isolated QEMU virtual machine
 - Exit QEMU: Press `Ctrl+A` then `X`
 
 ### `qemu-test.sh`
-- Automated testing script (run from host)
-- Builds module locally
+- Automated end-to-end testing script (run from host)
+- Builds kernel module and user program locally
 - Copies files to VM via SCP
-- Installs, tests, and uninstalls module
+- Installs module, runs tests, and uninstalls cleanly
 - Shows kernel logs and test results
+- Verifies module functionality in isolated environment
 
 **Prerequisites:**
 - VM must be running (`qemu-run.sh`)
-- SSH must be accessible
+- SSH must be accessible on port 2222
+
+### `quick-reference.sh`
+- Quick reference guide for common QEMU commands
+- Display usage: `./scripts/quick-reference.sh`
+- Includes setup, testing, and troubleshooting commands
 
 ## Manual Testing
 
@@ -67,7 +77,13 @@ ssh -p 2222 ubuntu@localhost
 # Inside VM
 cd ~/
 make clean && make all
+
+# Run unit tests (no kernel required)
+make unit
+
+# Test kernel module
 sudo make install
+lsmod | grep elf_det
 ./build/proc_elf_ctrl
 sudo make uninstall
 ```
@@ -92,19 +108,35 @@ sudo make uninstall
 
 ## Why QEMU Testing?
 
-- Complete isolation from host kernel
-- Safe crash recovery (just restart VM)
-- No risk to host system stability
-- Test on exact kernel version
-- Easy to reset to clean state
-- Reproducible testing environment
+Testing kernel modules in QEMU provides critical safety benefits:
+
+- **Complete Isolation**: Host kernel remains untouched
+- **Safe Crash Recovery**: Simply restart the VM if module crashes
+- **No Risk to Host**: System instability won't affect your machine
+- **Kernel Version Control**: Test on specific kernel versions
+- **Easy Reset**: Delete VM and start fresh anytime
+- **Reproducible Environment**: Consistent testing across systems
+- **CI/CD Integration**: Automate testing in isolated environments
+
+## Testing Workflow
+
+1. **Unit Tests First**: Run `make unit` to test pure functions locally (no kernel required)
+2. **QEMU Integration**: Use QEMU scripts to test full kernel module in isolation
+3. **Dev Container**: Use provided dev container for consistent build environment
+4. **Production**: Only deploy to production systems after thorough QEMU testing
 
 ## File Locations
 
 - VM images: `scripts/qemu-env/`
 - Cloud-init: `scripts/qemu-env/user-data.yaml`
 - Disk image: `scripts/qemu-env/ubuntu-24.04.img`
 
+## Additional Resources
+
+- **Main README**: [../README.md](../README.md) - Complete project documentation
+- **Quick Reference**: Run `./scripts/quick-reference.sh` for command cheat sheet
+- **Makefile Targets**: See main README for all available build and test targets
+
 ## Cleanup
 
 To remove QEMU environment:
@@ -117,3 +149,11 @@ To start fresh:
 rm -rf scripts/qemu-env/
 ./scripts/qemu-setup.sh
 ```
+
+## Notes
+
+- First boot takes 1-2 minutes for cloud-init to complete
+- VM uses Ubuntu 24.04 LTS with Kernel 6.8+
+- KVM acceleration is automatically enabled if available
+- Default credentials: ubuntu/ubuntu (change after first login)
+- SSH port forwarding: Host port 2222 → VM port 22