kpython

kpython: MicroPython in the Linux Kernel

kpython is an innovative port of MicroPython that functions as a loadable Linux kernel module (kpython.ko). This project empowers users to execute Python code directly within the kernel address space, which is ideal for high-level scripting in kernel debugging, rapid prototyping, and dynamic policy handling.

Warning: This project is currently EXPERIMENTAL / PRE-ALPHA and carries inherent risks. It operates a garbage-collected runtime with a complex parser inside the Linux Kernel, which can potentially lead to kernel panics or memory corruption. This module is not recommended for production systems.

Caution: As this module operates in Ring 0, any bugs in the implementation could result in severe system instability. Developers should take precautions when testing.

Development Note: kpython is best developed and tested within the WSL2 environment (Windows Subsystem for Linux) utilizing a custom kernel with CONFIG_MODULES enabled. This setup is favored as it minimizes the impact of a kernel panic, which typically only crashes the lightweight utility VM without affecting the host Windows system. On bare-metal Linux systems, a similar issue could necessitate a complete reboot.

📁 Project Structure

• micropython/: This git submodule contains the upstream MicroPython source, maintained in its original form.
• embed_cfg/: Contains configuration files (like mpconfigport.h) necessary for generating the "Embed" source bundle.
• kernel_mod/: The source code for the Linux Kernel Module, which integrates the glue logic and shims along with the generated MicroPython embed source.
• Makefile: A top-level script that manages the build process for the MicroPython generation and Kernel Module compilation.

🚀 Usage

Loading the Module

Load the kernel module using the following command:

sudo insmod kernel_mod/kpython.ko

Check the initialization status with dmesg:

dmesg | tail
# [  123.456] kpython: MicroPython kernel module initialised

Executing Python

The module features a debugfs interface located at /sys/kernel/debug/kpython/exec, allowing the execution of Python scripts.

Example - Simple Print:

echo "print('Hello from Kernel Space!')" | sudo tee /sys/kernel/debug/kpython/exec

Example - Calculations:

echo "print(2 * 100)" | sudo tee /sys/kernel/debug/kpython/exec

Example - Defining Functions:

echo -e "def hello():\n  print('Called hello()')\nhello()" | sudo tee /sys/kernel/debug/kpython/exec

Unloading the Module

To unload the module, execute:

sudo rmmod kpython

🧠 Technical Details

Architecture

• Embed Port: Utilizes MicroPython's ports/embed to create a self-contained C source file, ensuring that the build process is independent of the kernel's Kbuild system.
• Shims:
  • libc: Provides minimal wrappers for functions in string.h, translating them to kernel equivalents (like memcpy, strlen).
  • Allocation: Maps malloc and free to vmalloc and vfree, or utilizes kmalloc for smaller allocations.
  • I/O: Wraps printf with printk, implementing puts via printk as well.
• Safety Features:
  • Stack Protection: Enforces stack limits (12KB) to prevent overflows on the limited kernel stack (16KB on x86_64).
  • Exception Handling: Uses a custom x86_64 assembly implementation of setjmp/longjmp (NLR) to manage Python exceptions without relying on user-space headers.
  • Atomic Context: Automatically alternates between msleep (process context) and mdelay (atomic context) for the sleep functions.

Limitations

• No Float Support: Operations involving floating points are disabled to avoid complications in managing FPU state in the kernel.
• No File I/O: The standard Python open() function is not yet integrated with the kernel VFS.
• Architecture: Currently, it has been tested mainly on x86_64, with the assembly setjmp implementation tailored to this architecture.

For anyone interested in delving into the intricacies of integrating Python within the Linux kernel, kpython offers a novel platform for experimentation and learning.