{"id":24897251,"url":"https://github.com/markcwatson/toyos","last_synced_at":"2025-10-16T11:31:27.043Z","repository":{"id":244447419,"uuid":"815265319","full_name":"markCwatson/toyos","owner":"markCwatson","description":"Learning operating system and kernel development by building a multithreaded OS called ToyOS","archived":false,"fork":false,"pushed_at":"2025-07-06T21:20:54.000Z","size":3862,"stargazers_count":14,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-06T22:27:46.072Z","etag":null,"topics":["hobby-kernel","hobby-os","hobby-project","operating-system-kernel","operating-system-learning","operating-systems"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markCwatson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-06-14T18:03:25.000Z","updated_at":"2025-07-06T21:20:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"fb6c9fbf-e37b-44aa-9347-52a2aed69dbd","html_url":"https://github.com/markCwatson/toyos","commit_stats":null,"previous_names":["markcwatson/toyos"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/markCwatson/toyos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markCwatson%2Ftoyos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markCwatson%2Ftoyos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markCwatson%2Ftoyos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markCwatson%2Ftoyos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markCwatson","download_url":"https://codeload.github.com/markCwatson/toyos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markCwatson%2Ftoyos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279183687,"owners_count":26121448,"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","status":"online","status_checked_at":"2025-10-16T02:00:06.019Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["hobby-kernel","hobby-os","hobby-project","operating-system-kernel","operating-system-learning","operating-systems"],"created_at":"2025-02-01T20:17:11.532Z","updated_at":"2025-10-16T11:31:27.037Z","avatar_url":"https://github.com/markCwatson.png","language":"C","readme":"# ToyOS\n\n[![Build Status](https://github.com/markCwatson/toyos/workflows/Build%20ToyOS/badge.svg)](https://github.com/markCwatson/toyos/actions)\n\nToyOS is a work-in-progress (WIP) hobby operating system meant for educational purposes. The OS is being developed with a focus on foundational operating system concepts and practical implementations. The following GIF shows ToyOS running in QEMU. In this demonstration, the shell is interacting with the kernel to execute commands (currently, only the `ps`, `echo`, and `clear` commands are supported).\n\n![alt-text][1]\n\nCurrent features include:\n\n- **16-bit Bootloader:** A basic bootloader that initializes the system and loads the 32-bit kernel.\n- **32-bit Kernel:** The core of ToyOS, built for x86 platforms, handling essential system tasks.\n- **Virtual Memory with Paging:** Implements paging to manage memory, providing virtual memory support.\n- **Virtual Filesystem (VFS):** An abstraction layer for file system operations, allowing different filesystem types to be used seamlessly.\n- **FAT16 Filesystem:** Supports reading and writing files using the FAT16 format. Writing in append mode is under development.\n- **Interactive Shell:** A user-friendly command-line interface to interact with the OS.\n- **Simple Test Framework:** A basic test framework for functional testing, currently under development.\n- **Multi-threading:** Support for concurrent execution of processes, enabling more complex and efficient program execution.\n- **User-Level Programs:** Support for running user programs, expanding the OS's functionality beyond system-level operations.\n- **Loading ELF files at runtime:** The ability to dynamically load shared libraries and user programs at runtime.\n- **PCI Device driver:** PCI devices can be discovered and enumerated.\n- **Network Device abstraction:** An abstraction layer for networking devices such as the RTL8139.\n- **RTL8139 driver port:** The driver for sanos (originally developed by Donald Becker and Michael Ringgaard) has been ported to toyos.\n\nWork in progress:\n\n- **Networking**: see plan [here](./docs/networking.md)\n\n### Setup\n\nOn a Linux box:\n\n```shell\nsudo apt update\nsudo apt upgrade\n```\n\nThis project was developed for Linux. The assembler used here is `nasm`. It can be installed using\n\n```shell\nsudo apt install nasm\n```\n\nQEMU is used to emulate the x86 hardware. It can be installed using\n\n```shell\nsudo apt install qemu-system-x86\n```\n\nThe makefile invokes a gcc cross-compiler with a generic target (i686-elf) custom built to not include any reminants of the host OS (stdlib, etc.). It needs to be built from source. Follow the instructions [here](https://wiki.osdev.org/GCC_Cross-Compiler). Here is what worked for me.\n\n```shell\nsudo apt install build-essential\nsudo apt install bison\nsudo apt install flex\nsudo apt install libgmp3-dev\nsudo apt install libmpc-dev\nsudo apt install libmpfr-dev\nsudo apt install texinfo\nsudo apt install libisl-dev\n```\n\nThen we need to download the source code for gcc (10.2) and binutils (2.35):\n\n```shell\ncd ~\nmkdir src\ncurl -O https://ftp.gnu.org/gnu/binutils/binutils-2.35.tar.xz\ncurl -O https://ftp.lip6.fr/pub/gcc/releases/gcc-10.2.0/gcc-10.2.0.tar.gz\ntar -xf binutils-2.35.tar.xz -C ~/src/\ntar -xzf gcc-10.2.0.tar.gz -C ~/src/\nexport PREFIX=\"$HOME/opt/cross\"\nexport TARGET=i686-elf\nexport PATH=\"$PREFIX/bin:$PATH\"\n\n# binutils\ncd ~/src \nmkdir build-binutils\ncd build-binutils\n../binutils-2.35/configure --target=$TARGET --prefix=\"$PREFIX\" --with-sysroot --disable-nls --disable-werror\nmake\nmake install\n\n# gcc\ncd ~/src\nwhich -- $TARGET-as || echo $TARGET-as is not in the PATH\nmkdir build-gcc\ncd build-gcc\n../gcc-10.2.0/configure --target=$TARGET --prefix=\"$PREFIX\" --disable-nls --enable-languages=c,c++ --without-headers --disable-hosted-libstdcxx\nmake all-gcc\nmake all-target-libgcc\nmake all-target-libstdc++-v3\nmake install-gcc\nmake install-target-libgcc\nmake install-target-libstdc++-v3\n\n# test\n$HOME/opt/cross/bin/$TARGET-gcc --version\n```\n\n### Building\n\nFrom the root of the project, invoke the make build system (will need to make build script executable beforehand: `sudo chmod +x ./build.sh`)\n\n```shell\nmake clean\n./build.sh\n```\n\n### Emulation (QEMU) and debugging (GDB)\n\nTo run the kernel in the QEMU emulator without debugging, simply run the 32-bit x86 emulator\n\n```shell\nqemu-system-i386 \\\n    -hda ./bin/os.bin \\\n    -netdev user,id=net0,hostfwd=udp::8080-:7 \\\n    -device rtl8139,netdev=net0 \\\n    -monitor stdio \\\n    -m 128M\n```\n\n**⚠️ Warning: Snap VS Code Interference**\nIf you encounter symbol lookup errors when running QEMU inside a VS Code termianl (e.g., `undefined symbol: __libc_pthread_init, version GLIBC_PRIVATE`), this is likely due to having the snap version of VS Code installed. The snap version sets environment variables that interfere with system binaries. To fix this:\n- Remove the snap version: `sudo snap remove code`\n- Install using `apt` which doesn't have these conflicts\n- Alternatively, run QEMU in a regular terminal outside of VS Code.\n\nFor network testing and debugging, you can enable packet dumping:\n\n```shell\nqemu-system-i386 \\\n    -hda ./bin/os.bin \\\n    -netdev user,id=net0,hostfwd=udp::8080-:7 \\\n    -device rtl8139,netdev=net0 \\\n    -object filter-dump,id=dump0,netdev=net0,file=network.pcap \\\n    -m 128M \\\n    -monitor stdio \\\n    -S -gdb tcp::1234\n```\n\nThis will capture all network traffic to `network.pcap` which you can analyze with Wireshark. Try these commands one by one:\n\n```shell\nping 10.0.2.15\necho \"test\" | nc -u 10.0.2.15 7\necho \"test\" | nc -u 10.0.2.15 8080\n```\n\nTo debug with GDB, first start GDB\n\n```shell\n$ gdb\n```\n\nNext, manually load symbol file at the specified address for debugging (because the emulator does not load symbol information from `os.bin` automatically).\n\n```shell\n(gdb) add-symbol-file \"./build/kernelfull.o\" 0x100000\n```\n\nStart the QEMU instance with GDB server enabled on TCP port 1234 (in a separate terminal):\n\n```shell\nqemu-system-i386 \\\n    -hda ./bin/os.bin \\\n    -netdev user,id=net0,hostfwd=udp::8080-:7 \\\n    -device rtl8139,netdev=net0 \\\n    -m 128M \\\n    -monitor stdio \\\n    -S -gdb tcp::1234\n```\n\nThen, in GDB, connect to the QEMU instance:\n\n```shell\n(gdb) target remote localhost:1234\n```\n\nTo debug user programs, use address `0x400000` for user space.\n\n```shell\n(gdb) break *0x400000\n```\n\n### Tests\n\nTo run the tests (see [tests](https://github.com/markCwatson/toyos/tree/main/tests) folder at root of project), use the `--tests` flag\n\n```shell\nmake clean\n./build.sh --tests\n```\n\n### Elf Files\n\nTo view the content of ELF files, install `dumpelf`\n\n```shell\nsudo apt install pax-utils\n```\n\nand dump the contents of an ELF file, for example\n\n```shell\ndumpelf programs/shell/shell.elf\n```\n\n### AI Disclaimer\n\nMost of the code comments in this project were written by AI. I want this project to be well documented, and since most of the implementations of various features were obtained from tutorials and examples (believe it or not: I am not a professional OS developer), I used ChatGPT to add comments and explain what each thing is doing, to help us both (u and I), learn.\n\n### References\n\n1. [Developing a Multithreaded Kernel From Scratch! by Daniel McCarthy](https://www.udemy.com/course/developing-a-multithreaded-kernel-from-scratch)\n2. [The Little Book About OS Development by Erik Helin and Adam Renberg](https://littleosbook.github.io/)\n3. [OSdev.org](https://wiki.osdev.org/Expanded_Main_Page)\n4. [Modern Operating Systems 4th Edition by Andrew Tanenbaum and Herbert Bos](https://csc-knu.github.io/sys-prog/books/Andrew%20S.%20Tanenbaum%20-%20Modern%20Operating%20Systems.pdf)\n\n[1]: gif/toyos-demo.gif 'ToyOS running in QEMU'\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkcwatson%2Ftoyos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkcwatson%2Ftoyos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkcwatson%2Ftoyos/lists"}