{"id":13836171,"url":"https://github.com/willdurand/ArvernOS","last_synced_at":"2025-07-10T13:32:08.244Z","repository":{"id":42445542,"uuid":"91887197","full_name":"willdurand/ArvernOS","owner":"willdurand","description":":floppy_disk: A minimal, experimental and \"toy\" monolithic kernel to learn about OS development // Work In Progress","archived":false,"fork":false,"pushed_at":"2024-01-30T19:20:11.000Z","size":13663,"stargazers_count":325,"open_issues_count":20,"forks_count":32,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-04-14T04:18:57.848Z","etag":null,"topics":["32-bit","64-bit","aarch32","aarch64","asm","hobby-os","kernel","learning-by-doing","operating-system","x86-64"],"latest_commit_sha":null,"homepage":"https://williamdurand.fr/ArvernOS/","language":"C","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/willdurand.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2017-05-20T12:19:26.000Z","updated_at":"2024-04-17T17:04:19.033Z","dependencies_parsed_at":"2024-04-17T17:14:20.947Z","dependency_job_id":null,"html_url":"https://github.com/willdurand/ArvernOS","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willdurand%2FArvernOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willdurand%2FArvernOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willdurand%2FArvernOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willdurand%2FArvernOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/willdurand","download_url":"https://codeload.github.com/willdurand/ArvernOS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":213924295,"owners_count":15657945,"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":["32-bit","64-bit","aarch32","aarch64","asm","hobby-os","kernel","learning-by-doing","operating-system","x86-64"],"created_at":"2024-08-04T15:00:37.280Z","updated_at":"2024-11-20T22:32:12.770Z","avatar_url":"https://github.com/willdurand.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"\u003c!-- doxygen: \\mainpage Introduction --\u003e\n\n# ArvernOS\n\n[![CircleCI](https://circleci.com/gh/willdurand/ArvernOS/tree/master.svg?style=svg)](https://circleci.com/gh/willdurand/ArvernOS/tree/master)\n\nArvernOS (formerly known as \"willOS\") is a minimal and experimental monolithic\nkernel (not really an Operating System because it cannot do a lot of things\ncurrently).\n\n## Goals\n\nThe main goal of this project is to learn about operating systems, kernel\ndevelopment, different architectures and improve my C skills. ArvernOS is a\nmonolithic (and hopefully modular) [kernel](./src/kernel/README.md) with a\nunified homemade [libc/libk](./src/libc/README.md), and\n[userland](./src/userland/README.md) programs.\n\nThe roadmap isn't clearly defined yet and it mainly depends on what I'd like to\nwork on when I have time to spend on this project.\n\n## Architectures, boards and tiers\n\nArvernOS supports the architectures and boards listed below. Support for\ndifferent architectures and boards are organized into two tiers, each with a\ndifferent set of guarantees.\n\n### Tier 1\n\nTier 1 is the reference implementation and very likely the most advanced.\n\nCurrent Tier 1 archs/boards:\n\n- **x86_64**\n  - generic\n\n### Tier 2\n\nTier 2 is guaranteed to build but not all features have been implemented yet.\nFeatures are defined by the reference implementation and once feature parity is\nachieved, an architecture and/or board should move to Tier 1. Boards for which\nwe cannot run enough tests in CI (e.g., because QEMU does not support the board)\nshould stay in Tier 2, though.\n\nCurrent Tier 2 archs/boards:\n\n- **aarch32**\n  - [Raspberry Pi 2](./src/kernel/arch/aarch32/board/raspi2/README.md)\n- **aarch64**\n  - [Raspberry Pi 3](./src/kernel/arch/aarch64/board/raspi3/README.md)\n\n## Hacking on ArvernOS\n\nThis section (and its sub-sections) are written for everyone interested in\nbuilding and working on ArvernOS.\n\n### Setting up a development environment\n\nThe following dependencies are required to build this project:\n\n- `llvm` (version 17 currently)\n- `make`\n- `qemu` (version \u003e= 5)\n\nIf you want to work on the `x86_64` architecture, you'll need the following\nextra dependencies:\n\n- `nasm`\n- `grub-mkrescue`\n- `xorriso`\n\nIf you want to work on ARM architectures (`aarch32` or `aarch64`), you'll need\nthe following extra dependencies:\n\n- `gcc-arm-none-eabi`\n- `u-boot-tools`\n\nNote: The recommended way to work on this project is to use Docker.\n\n#### Getting the sources\n\nThis project contains [git submodules][git-submodules]. You have to clone the\nmain project as well as the submodules, either by using this command:\n\n```\n$ git clone --recurse-submodules \u003curl pointing to this repo\u003e\n```\n\nor by using this command if you already have a copy of this git repository:\n\n```\n$ git submodule update --init\n```\n\n#### Docker (recommended way)\n\nUse [Docker](https://docs.docker.com/) with the provided\n[`Dockerfile`][dockerfile]. You can either use the\n[`willdurand/arvernos-toolchain` image from DockerHub][dockerhub-toolchain] or\nbuild your own:\n\n```\n$ docker build -t willdurand/arvernos-toolchain .\n[...]\n```\n\nYou can then use it with `docker run`:\n\n```\n$ docker run -it --rm -v $(pwd):/app willdurand/arvernos-toolchain make help\nArvernOS - available commands for arch=x86_64\n\nclean                          remove build artifacts\ndebug                          build the project in debug mode\ndocs                           build the docs\nfmt                            automatically format the code with clang-format\ngdb                            build, run the project in debug mode and enable GDB\nhelp                           show this help message\nlibc                           build the libc\nrelease                        build the project in release mode\nrun-debug                      run the project in debug mode\nrun-release                    run the project in release mode\nrun-test                       run the project in test mode\ntest                           run the unit tests\nuserland                       compile the userland programs (statically linked to libc)\nversion                        print tool versions\n```\n\nNote: The output of the `make help` command may contain different commands\ndepending on the architecture and board configured.\n\n#### MacOS\n\nInstall [Homebrew](https://brew.sh/), then run the following commands:\n\n```\n$ brew install nasm xorriso qemu llvm u-boot-tools\n```\n\n#### Linux\n\nThe `tools/install-linux-deps` script is used to install the dependencies. It is\ncurrently used by both the `Dockerfile` and Circle CI.\n\n### Building ArvernOS\n\nYou first need to install the development dependencies in order to build\nArvernOS. The different final files are located in the `build/\u003carch\u003e/dist/` or\n`build/\u003carch\u003e/\u003cboard\u003e/dist/` folder.\n\n#### Debug mode\n\nTo build the image in debug mode, run:\n\n```\n$ make clean ; make debug\n```\n\nTo compile the OS in debug mode, build the image, and start `qemu` with the OS\nloaded, run:\n\n```\n$ make clean ; make run-debug\n```\n\nNote: Some boards aren't supported in QEMU.\n\n##### QEMU monitor\n\nWhen running `make run-debug`, the [QEMU monitor][] can be accessed over TCP on\nport `5555`. You can use tools like `telnet` or `nc`:\n\n```\n$ telnet 127.0.0.1 5555\n```\n\n##### Logging\n\nIn debug mode, logging very likely uses the serial port `COM1` to write various\ndebugging information. QEMU is configured to write the output of this serial\nport to a logfile in `./log/`. `DEBUG` level logs are not necessarily written by\ndefault, though, and it is possible to enable `DEBUG` logs for specific modules\nlike this:\n\n```\n# Enable the debug logs for the \"net\" and \"fs\" modules\n$ make clean ; make run-debug ENABLE_NET_DEBUG=1 ENABLE_FS_DEBUG=1\n```\n\nThe available debug variables are:\n\n- `ENABLE_CONFIG_DEBUG`\n- `ENABLE_CORE_DEBUG`\n- `ENABLE_FS_DEBUG`\n- `ENABLE_MMU_DEBUG`\n- `ENABLE_NET_DEBUG`\n- `ENABLE_PROC_DEBUG`\n- `ENABLE_SYS_DEBUG`\n- `ENABLE_USERLAND_DEBUG`\n\n##### Stack traces\n\nLog files may contain stack traces without debug symbols if the symbols haven't\nbeen loaded:\n\n```\n[...]\nDEBUG    | src/kernel/arch/x86_64/kshell/kshell.c:108:run_command(): command='selftest' argc=1\nDEBUG    | src/kernel/arch/x86_64/kernel/panic.c:30:kernel_dump_stacktrace(): kernel stacktrace:\nDEBUG    | src/kernel/arch/x86_64/kernel/panic.c:39:kernel_dump_stacktrace(): 00000000001163B3 - ???+0x0\nDEBUG    | src/kernel/arch/x86_64/kernel/panic.c:39:kernel_dump_stacktrace(): 0000000000115941 - ???+0x0\nDEBUG    | src/kernel/arch/x86_64/kernel/panic.c:39:kernel_dump_stacktrace(): 0000000000115BE1 - ???+0x0\nDEBUG    | src/kernel/arch/x86_64/kernel/panic.c:39:kernel_dump_stacktrace(): 00000000001152BF - ???+0x0\nDEBUG    | src/kernel/arch/x86_64/kernel/panic.c:39:kernel_dump_stacktrace(): 000000000010935B - ???+0x0\n```\n\nUse the `tools/fix-stacktrace.py` script to add missing symbol names to the\noutput:\n\n```\n$ ./tools/fix-stacktrace.py build/x86_64/dist/symbols.txt log/x86_64-debug.log\n[...]\nDEBUG    | src/kernel/arch/x86_64/kshell/kshell.c:108:run_command(): command='selftest' argc=1\nDEBUG    | src/kernel/arch/x86_64/kernel/panic.c:30:kernel_dump_stacktrace(): kernel stacktrace:\nDEBUG    | src/kernel/arch/x86_64/kernel/panic.c:39:kernel_dump_stacktrace():   00000000001163B3 - selftest+0x63\nDEBUG    | src/kernel/arch/x86_64/kernel/panic.c:39:kernel_dump_stacktrace():   0000000000115941 - run_command+0x271\nDEBUG    | src/kernel/arch/x86_64/kernel/panic.c:39:kernel_dump_stacktrace():   0000000000115BE1 - kshell_run+0x181\nDEBUG    | src/kernel/arch/x86_64/kernel/panic.c:39:kernel_dump_stacktrace():   00000000001152BF - kmain+0x107f\nDEBUG    | src/kernel/arch/x86_64/kernel/panic.c:39:kernel_dump_stacktrace():   000000000010935B - long_mode_start+0x13\n```\n\nIn addition, you might want to find the corresponding line of code in the source\nfiles by using `llvm-addr2line` or `llvm-symbolizer`:\n\n```\n$ llvm-symbolizer --obj=build/x86_64/dist/kernel-x86_64.bin 0x01163B3\nprint_selftest_header\n/path/to/ArvernOS/src/kernel/kshell/selftest.c:12:3\nselftest\n/path/to/ArvernOS/src/kernel/kshell/selftest.c:30:3\n```\n\n```\n$ llvm-addr2line -e build/x86_64/dist/kernel-x86_64.bin 01163B3\n/path/to/ArvernOS/src/kernel/kshell/selftest.c:12\n```\n\n##### Debugging\n\nUse `make gdb` to run the project in debug mode with QEMU configured to wait for\n[gdb][] to connect. This has been tested with `vim` (`:Termdebug`) and VS Code.\n\nA sensible configuration is automatically generated when this command is\nexecuted (see also: `make gdbinit`). If a file named `.gdbinit.local` exists in\nthe project's root directory, its content will be appended to the generated\n`.gdbinit` file.\n\nNote: `make gdb` calls `make run-debug` under the hood so all configuration\noptions are also supported. For example, it is possible to run `make gdb KERNEL_CMDLINE=\"kshell selftest\"`.\n\n#### Release mode\n\nTo compile the OS in release mode, build the image, and start `qemu` with the OS\nloaded, run:\n\n```\n$ make clean ; make run-release\n```\n\n#### config files\n\n`config` files are used to configure how a build works. The content must be\ncompatible with `make`. Here is an example:\n\n```\n# LLVM config on MacOS with Homebrew\nLLVM_PREFIX = /usr/local/opt/llvm@13/bin/\nLLVM_SUFFIX =\n\n# Always enable the Undefined Behavior sanitizer\nUBSAN = 1\n\n# Logging\nENABLE_CORE_DEBUG     = 1\nENABLE_PROC_DEBUG     = 1\nENABLE_SYS_DEBUG      = 1\nENABLE_USERLAND_DEBUG = 1\n```\n\n## License\n\nArvernOS is released under the MIT License. See the bundled\n[LICENSE][license] file for\ndetails. In addition, some parts of this project have their own licenses\nattached (either in the source files or in a `LICENSE` file next to them).\n\n[dockerfile]: https://github.com/willdurand/ArvernOS/blob/master/Dockerfile\n[dockerhub-toolchain]: https://hub.docker.com/repository/docker/willdurand/arvernos-toolchain\n[gdb]: https://www.sourceware.org/gdb/\n[git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules\n[license]: https://github.com/willdurand/ArvernOS/blob/master/LICENSE.md\n[qemu monitor]: https://www.qemu.org/docs/master/system/monitor.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilldurand%2FArvernOS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilldurand%2FArvernOS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilldurand%2FArvernOS/lists"}