{"id":28962708,"url":"https://github.com/r1toaster/piztwo-os","last_synced_at":"2026-05-17T01:44:21.959Z","repository":{"id":300752030,"uuid":"1007021585","full_name":"r1TOASTER/PiZTwo-OS","owner":"r1TOASTER","description":"Experimental OS for RPi Zero 2W","archived":false,"fork":false,"pushed_at":"2025-06-23T11:25:29.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-23T12:31:36.941Z","etag":null,"topics":["bare-metal","baremetal","embedded","operating-system","os","raspberry-pi","raspberry-pi-zero-w","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/r1TOASTER.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-23T10:46:39.000Z","updated_at":"2025-06-23T11:25:57.000Z","dependencies_parsed_at":"2025-06-23T12:44:16.321Z","dependency_job_id":null,"html_url":"https://github.com/r1TOASTER/PiZTwo-OS","commit_stats":null,"previous_names":["r1toaster/piztwo-os"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/r1TOASTER/PiZTwo-OS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r1TOASTER%2FPiZTwo-OS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r1TOASTER%2FPiZTwo-OS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r1TOASTER%2FPiZTwo-OS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r1TOASTER%2FPiZTwo-OS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r1TOASTER","download_url":"https://codeload.github.com/r1TOASTER/PiZTwo-OS/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r1TOASTER%2FPiZTwo-OS/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261595784,"owners_count":23182249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bare-metal","baremetal","embedded","operating-system","os","raspberry-pi","raspberry-pi-zero-w","rust"],"created_at":"2025-06-24T03:11:51.102Z","updated_at":"2026-05-17T01:44:21.879Z","avatar_url":"https://github.com/r1TOASTER.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# PiZTwo-OS\n\nAn experimental operating system written from scratch in Rust for the Raspberry Pi Zero 2W, targeting the aarch64 architecture.\n\n## Overview\n\nPiZTwo-OS is a lightweight, experimental OS designed to explore low-level system programming on the Raspberry Pi Zero 2W. Built entirely in Rust, it leverages the language's safety and performance features to create a minimal, reliable, and secure environment for the aarch64 architecture. This project is intended for hobbyists, researchers, and developers interested in OS development and embedded systems.\n\n## Features\n\n- **Minimal Kernel**: A bare-bones kernel with memory management, interrupt handling, drivers and etc.\n- **Rust-Based**: Utilizes Rust's memory safety guarantees to reduce common low-level bugs.\n- **aarch64 Support**: Optimized for the Raspberry Pi Zero 2W's 64-bit ARM Cortex-A53 processor.\n- **UART Output**: Basic serial console output for debugging and interaction.\n- **Modular Design**: Structured for easy experimentation and extension.\n\n## Hardware Requirements\n\n- **Raspberry Pi Zero 2W**\n- MicroSD card (size determained by release builds)\n- USB-to-serial adapter: for console interaction (upcoming HDMI support)\n- Power supply: micro USB\n\n## Getting Started\n\n### Prerequisites\n\n- **Rust Toolchain**: Install the nightly Rust toolchain with `rustup`.\n  ```bash\n  rustup default nightly\n  rustup target add aarch64-unknown-none\n  ```\n- **QEMU**: Optional, for emulation.\n  ```bash\n  sudo apt install qemu-system-arm\n  ```\n- **Minicom** or similar: For serial communication.\n\n### Building the OS\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/yourusername/PiZTwo-OS.git\n   cd PiZTwo-OS\n   ```\n\n2. Download the required toolchain binaries (check out versions tab):\n  - `aarch64-none-elf-as`: For assembling.\n  - `aarch64-none-elf-ld`: For linking.\n  - `aarch64-none-elf-gdb`: If wanting to debug QEMU.\n  - `qemu-system-aarch64`: If wanting to emulate.\n\n3. Build the kernel:\n   ```bash\n   make release\n   ```\n  \n4. Image would be named `kernel8.img` under `output` folder, with `kernel-release.elf` and object files.\n\n### Flashing the SD Card\nTODO: check the flashing SD card instructions\n1. Insert the MicroSD card into your computer.\n2. Copy the generated image to the SD card:\n   ```bash\n   sudo dd if=kernel8.img of=/dev/sdX bs=4M status=progress\n   ```\n   Replace `/dev/sdX` with your SD card's device path.\n\n3. Eject the SD card and insert it into the Raspberry Pi Zero 2W.\n\n### Running on Hardware\nThe terminal emulator configuration should be checked (baud rate, data bits, etc)\n1. Connect a USB-to-serial adapter to the Raspberry Pi Zero 2W's UART pins (GPIO x and x).\n2. Open a terminal emulator (e.g., Minicom):\n   ```bash\n   minicom -b 115200 -D /dev/ttyUSB0\n   ```\n3. Power on the Raspberry Pi Zero 2W and observe the boot output.\n\n### Testing Hardware through QEMU Emulation\n1. Make sure you have the required tools for building an image (assembler, linker, Cargo nightly toolchain and target).\n2. Make sure you have `qemu-system-aarch64` (should be under qemu-system-arm package)\n3. Make sure you have `aarch64-none-elf-gdb`, if wanting to debug QEMU\n4. Build and run the kernel using: \n    ```bash \n    make run\n    ```\n5. On another terminal window run the run-gdb script:\n    ```bash \n    ./run-gdb.sh\n    ```\n\n## Structure\n\n- **Root**:\n  - `aarch64-unknown-none.json`: `aarch64` target spec.\n  - `Cargo.toml`, `Cargo.lock`: Rust project config.\n  - `Makefile`: Build automation.\n  - `LICENSE`: MIT License.\n  - `linker.ld`: Custom linker script for RPi Zero 2W hardware needs.\n  - `qemu_connect.gdb`: GDB script for QEMU debugging.\n  - `run-gdb.sh`: Running GDB with it's script for QEMU debugging. \n\n- **`asm`**:\n  - `entry.S`: Entry point for the kernel before passing kernel_main control\n  - `util.S`: Current utilities in raw assembly.\n\n- **`src`**:\n  - `buses/{i2c,spi,uart,usb}`: Communication bus drivers.\n  - `common`: Shared utilities.\n  - `cpu`: CPU functionality.\n  - `graphics`: Display drivers.\n  - `interrupt`: Interrupt handling.\n  - `lib.rs`: Kernel official entry point.\n  - `memory/{alloc,dma,mmio}`: Memory management.\n  - `net/{bluetooth/{ble,classic},wlan}`: Networking protocols.\n  - `peripherals/{emmc,gpio,i2s,pwm}`: Peripheral drivers.\n  - `process/{ipc}`: Task management and inter-process communication.\n  - `timer`: Timer support.\n\n- **`target`**: Cargo build artifacts.\n- **`output`**: Main output folder when building images.\n\n## Contributing\n\nContributions are welcome! Please fork the repository, create a feature branch, and submit a pull request. Ensure your code follows Rust's style guidelines and includes appropriate documentation.\n\n### Guidelines\n\n- Use `cargo fmt` for code formatting.\n- Write clear commit messages.\n- Add tests for new features where possible.\n- Report issues or suggest improvements via the GitHub Issues page.\n\n## Roadmap\n\n- [ ] Interrupt handling\n- [ ] Console interaction\n- [ ] Debug support using SWD\n- [ ] Peripherals and Buses support\n- [ ] USB driver for peripherals / boot\n- [ ] Graphics and desktop environment using HDMI \n- [ ] Basic virtual memory support\n- [ ] Simple task scheduling\n- [ ] Filesystem support (e.g., FAT32)\n- [ ] Network stack (WLAN, Bluetooth classic / BLE)\n- [ ] RTC from NTP\n- [ ] User-space application support (ELF loading)\n\n### Toolchain Versions\nCurrenty using:\n- `aarch64-none-elf-as`: GNU assembler (Arm GNU Toolchain 13.2.rel1 (Build arm-13.7)) 2.41.0.20231009\n- `aarch64-none-elf-ld`: GNU ld (Arm GNU Toolchain 13.2.rel1 (Build arm-13.7)) 2.41.0.20231009\n- `aarch64-none-elf-gdb`: GNU gdb (Arm GNU Toolchain 13.2.rel1 (Build arm-13.7)) 13.2.90.20231008-git\n- `qemu-system-aarch64`: QEMU emulator version 10.0.0\n- `cargo nightly toolchain`: cargo 1.89.0-nightly (2251525ae 2025-06-16)\n- `python 3.8`: Python 3.8.20\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Thanks to the Rust community for excellent documentation and tools.\n- Raspberry Pi Foundation for the Zero 2W platform.\n\n## Contact\n\nFor questions or feedback, open an issue on GitHub.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr1toaster%2Fpiztwo-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr1toaster%2Fpiztwo-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr1toaster%2Fpiztwo-os/lists"}