pyOS-kernel 0.2.0__tar.gz → 1.0.0__tar.gz

pyos_kernel-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 i87kxxzz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyos_kernel-1.0.0/PKG-INFO

@@ -0,0 +1,474 @@
+Metadata-Version: 2.4
+Name: pyOS-kernel
+Version: 1.0.0
+Summary: Build real x86 operating systems with a Python DSL — freestanding C kernel + ASM bootloader
+Author-email: i87kxxzz <redtgx32@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 i87kxxzz
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/i87kxxz/pyOS
+Project-URL: Documentation, https://github.com/i87kxxz/pyOS#readme
+Project-URL: Repository, https://github.com/i87kxxz/pyOS
+Project-URL: Issues, https://github.com/i87kxxz/pyOS/issues
+Keywords: operating-system,os,kernel,x86,bootloader,qemu,nasm,systems-programming,cybersecurity
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Operating System Kernels
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# pyOS
+
+**Build a real x86 operating system — in Python.**
+
+You write a small, readable Python API.  
+pyOS turns it into a freestanding **C kernel** + **ASM bootloader**, then boots it in **QEMU**.
+
+```text
+  Python DSL  ──►  C glue + C kernel  ──►  GCC -m32  ─┐
+                                                      ├─►  os.bin  ─►  QEMU
+  bootloader.asm  ──────────────────────►  NASM      ─┘
+```
+
+[![PyPI](https://img.shields.io/pypi/v/pyOS-kernel.svg)](https://pypi.org/project/pyOS-kernel/)
+[![Python](https://img.shields.io/pypi/pyversions/pyOS-kernel.svg)](https://pypi.org/project/pyOS-kernel/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Table of contents
+
+1. [What is pyOS?](#what-is-pyos)
+2. [What it is not](#what-it-is-not)
+3. [Features](#features)
+4. [Requirements](#requirements)
+5. [Install](#install)
+6. [Quick start](#quick-start)
+7. [CLI](#cli)
+8. [API overview](#api-overview)
+9. [Capabilities (flags)](#capabilities-flags)
+10. [Project layout](#project-layout)
+11. [Examples](#examples)
+12. [Guest shell](#guest-shell)
+13. [Debugging](#debugging)
+14. [Tests](#tests)
+15. [Architecture](#architecture)
+16. [Roadmap](#roadmap)
+17. [Security notes](#security-notes)
+18. [Contributing](#contributing)
+19. [License](#license)
+
+---
+
+## What is pyOS?
+
+pyOS is a **Python DSL for building real OS kernels**.
+
+| Layer | Role |
+|-------|------|
+| **Python** | Describe boot screens, handlers, and features at *build time* |
+| **Codegen** | Emit honest C glue (no silent stubs) |
+| **C kernel** | VGA, keyboard, heap, timer, IDT/PIC, syscalls, paging, tasks, VFS, shell |
+| **ASM** | 16→32-bit bootloader only |
+
+Typical flow:
+
+```bash
+pip install pyOS-kernel
+# write main.py with Kernel + Screen
+pyos build main.py -o myos.bin
+pyos run myos.bin
+pyos debug myos.bin
+```
+
+---
+
+## What it is not
+
+- **Not** CPython running inside the kernel  
+- **Not** a full Linux clone (no networking stack, no ext4, no SMP yet)  
+- **Not** “fake” APIs: unsupported calls raise `CapabilityError` / `UnsupportedOpError`
+
+Boot functions run on your **host** during `build()`. Only recorded operations become C calls in the guest.
+
+---
+
+## Features
+
+**Core**
+
+- Freestanding **32-bit x86** kernel + floppy boot image
+- VGA text mode (`Screen.clear`, `print`, colors, cursor, scroll)
+- PS/2 keyboard IRQ + optional echo / shell input
+- PIT timer + `@kernel.on_timer`
+- Human-readable **serial panics** (`pyos debug`)
+
+**Memory & syscalls**
+
+- Free-list **heap** (`malloc` / `free` / `calloc` / `realloc`)
+- Syscalls: `EXIT`, `READ`, `WRITE`, `OPEN`, `CLOSE`, `GETPID`, `MALLOC`, `FREE`, `SLEEP`, `TIME`, `YIELD`, `SPAWN`
+
+**Security-oriented building blocks**
+
+- Optional **GDT + TSS**
+- Optional **paging** (identity map)
+- `copy_from_user` / range checks when `enable_user_mode=True`
+
+**OS services**
+
+- Cooperative **process table** + round-robin on IRQ0
+- **VFS / ramfs** + build-time `seed_file(...)`
+- Built-in **shell**: `help`, `ls`, `cat`, `ps`, `free`, `clear`, `echo`
+
+---
+
+## Requirements
+
+| Tool | Why | Install (Windows) |
+|------|-----|-------------------|
+| **Python 3.8+** | DSL + CLI | [python.org](https://www.python.org/) |
+| **MinGW-w64 GCC** (`-m32`) | Compile the C kernel | `winget install -e --id BrechtSanders.WinLibs.POSIX.UCRT` |
+| **NASM** | Assemble the bootloader | `winget install -e --id NASM.NASM` |
+| **QEMU** | Run the OS | `winget install -e --id SoftwareFreedomConservancy.QEMU` |
+
+Verify:
+
+```bash
+pyos check
+```
+
+---
+
+## Install
+
+**From PyPI**
+
+```bash
+pip install pyOS-kernel
+```
+
+**From source (dev)**
+
+```bash
+git clone https://github.com/i87kxxz/pyOS.git
+cd pyOS
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick start
+
+```python
+# main.py
+from pyos import Kernel, Screen
+
+kernel = Kernel(arch="x86")
+
+@kernel.on_boot
+def main():
+    Screen.clear()
+    Screen.set_color("green", "black")
+    Screen.print("Hello from pyOS!")
+    Screen.print("Python DSL  ->  C kernel  ->  QEMU", row=2)
+
+if __name__ == "__main__":
+    kernel.build("myos.bin")
+```
+
+```bash
+python main.py
+pyos run myos.bin
+```
+
+Or with the CLI:
+
+```bash
+pyos build main.py -o myos.bin
+pyos run myos.bin
+pyos debug myos.bin
+```
+
+---
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `pyos check` | Verify gcc / nasm / qemu |
+| `pyos new <name>` | Scaffold a new project |
+| `pyos build <file.py> -o out.bin` | Build a bootable image |
+| `pyos run <image.bin>` | Boot in QEMU |
+| `pyos debug <image.bin>` | Headless serial log + panic translation |
+| `pyos c <file.py> -o glue.c` | Inspect generated C glue |
+
+---
+
+## API overview
+
+```python
+from pyos import (
+    Kernel, Screen, Keyboard, Memory,
+    SysCall, Interrupts, GDT,
+    File, Process,
+    CapabilityError, UnsupportedOpError,
+)
+```
+
+### Boot
+
+```python
+kernel = Kernel(arch="x86", heap_size=2*1024*1024)
+
+@kernel.on_boot(priority=0)
+def early():
+    Screen.clear()
+    Screen.print("booting...", row=0)
+
+@kernel.on_boot(priority=1)
+def later():
+    ptr = Memory.malloc(256)
+    Memory.memset(ptr, 0, 256)
+    Memory.free(ptr)
+```
+
+### Keyboard & timer
+
+```python
+@kernel.on_keypress(mode="echo")
+def on_key(key=None):
+    pass  # enables IRQ1 path; shell handles lines
+
+@kernel.on_timer(interval_ms=1000)
+def tick():
+    pass
+```
+
+### Files (build-time seeds)
+
+```python
+kernel = Kernel(arch="x86", enable_filesystem=True)
+kernel.seed_file("motd.txt", "Welcome to pyOS\n")
+```
+
+Honest errors:
+
+```python
+# raises CapabilityError if filesystem is off
+kernel.seed_file("x.txt", "nope")
+
+# raises UnsupportedOpError / ValueError for bad ops / colors / non-ASCII VGA text
+Screen.set_color("not_a_color")
+Screen.print("عربي")  # VGA text is ASCII/CP437 only
+```
+
+---
+
+## Capabilities (flags)
+
+Enable real kernel subsystems with constructor flags:
+
+```python
+kernel = Kernel(
+    arch="x86",
+    stack_size=32768,
+    heap_size=2 * 1024 * 1024,
+    enable_interrupts=True,
+    enable_paging=True,
+    enable_user_mode=True,
+    enable_processes=True,
+    enable_filesystem=True,
+    debug_level="lab",      # or "quiet"
+    keypress_mode="echo",   # or "custom"
+)
+```
+
+| Flag | Effect |
+|------|--------|
+| `enable_interrupts` | IDT + PIC + PIT + syscalls |
+| `enable_paging` | Identity-map paging |
+| `enable_user_mode` | GDT rings + TSS + stricter user copy |
+| `enable_processes` | Task table + IRQ0 round-robin |
+| `enable_filesystem` | VFS/ramfs + `seed_file` |
+
+Inspect:
+
+```python
+print(kernel.get_info())
+print(kernel.capabilities)
+```
+
+---
+
+## Project layout
+
+```text
+pyos/
+  api/          # Python DSL (Kernel, Screen, Memory, ...)
+  build/        # codegen, toolchain, floppy builder
+  boot/         # ASM bootloader
+  kernel/       # freestanding C kernel
+    arch/x86/   # GDT, IDT, PIC, paging, syscalls
+    mm/         # heap, pmm
+    drivers/    # VGA, keyboard, PIT, shell
+    proc/       # tasks, ELF helper
+    fs/         # VFS, ramfs, seed loader
+    lib/        # debug, string
+examples/
+  basic/        # hello world, keyboard
+  advanced/     # shell, full flags demo
+  lab/          # probes (outputs gitignored)
+tests/
+  unit/
+  integration/
+docs/
+  ARCHITECTURE.md
+  ROADMAP.md
+```
+
+---
+
+## Examples
+
+```bash
+python examples/basic/hello_world.py
+python examples/basic/keyboard_input.py
+python examples/advanced/shell_echo.py
+python examples/advanced/advanced_os.py
+```
+
+---
+
+## Guest shell
+
+With `@kernel.on_keypress` enabled, type in the QEMU window:
+
+| Command | Action |
+|---------|--------|
+| `help` | List commands |
+| `ls` | List VFS files |
+| `cat motd.txt` | Print a seeded file |
+| `ps` | Show tasks |
+| `free` | Heap hint |
+| `clear` | Clear VGA |
+| `echo hi` | Print text |
+
+---
+
+## Debugging
+
+```bash
+pyos debug myos.bin
+```
+
+Panics look like:
+
+```text
+========== pyOS PANIC ==========
+Where : @kernel Screen.print
+Why   : Print position is outside the VGA text screen (0..24 rows, 0..79 cols)
+Hint  : Pass a valid row/col, or omit them to use the cursor
+================================
+```
+
+Also emitted: `*.symbols.json` and linker `*.map` beside the image.
+
+---
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests/ -q
+```
+
+Includes codegen honesty tests and QEMU serial smoke tests.
+
+---
+
+## Architecture
+
+```text
+┌─────────────┐     build-time      ┌─────────────┐
+│  Python API │ ──────────────────► │  glue.c     │
+└─────────────┘                     └──────┬──────┘
+                                           │
+┌─────────────┐                     ┌──────▼──────┐
+│ bootloader  │ ──────────────────► │  C kernel   │
+└─────────────┘                     └──────┬──────┘
+                                           │
+                                    ┌──────▼──────┐
+                                    │  QEMU i386  │
+                                    └─────────────┘
+```
+
+More detail: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+
+---
+
+## Roadmap
+
+Shipped in **1.0**: honest API, free-list heap, timer, syscalls, paging/GDT hooks, tasks, VFS, shell.
+
+Next (Linux-like direction): per-process address spaces, `fork`/`exec`, ELF userland, virtio disk/net, x86_64.
+
+See [docs/ROADMAP.md](docs/ROADMAP.md).
+
+---
+
+## Security notes
+
+pyOS is a **lab / teaching / research** kernel:
+
+- Default builds are still largely ring0-centric unless you enable user-mode flags
+- Serial debug can leak EIP and boot traces (`debug_level="lab"`)
+- Do not treat guest images as a hardened production OS
+
+Report issues: [GitHub Issues](https://github.com/i87kxxz/pyOS/issues)
+
+---
+
+## Contributing
+
+1. Fork & clone  
+2. `pip install -e ".[dev]"`  
+3. Keep the API **honest** (no silent stubs)  
+4. Add tests for new codegen / QEMU behavior  
+5. Open a PR
+
+---
+
+## License
+
+MIT © 2026 i87kxxzz — see [LICENSE](LICENSE).