{"id":13314241,"url":"https://github.com/ecomaikgolf/alma","last_synced_at":"2025-10-22T02:56:58.874Z","repository":{"id":158745443,"uuid":"362642881","full_name":"ecomaikgolf/alma","owner":"ecomaikgolf","description":"toy kernel written in C++ for x86-64 machines with the mere purpose of learning OS development ","archived":false,"fork":false,"pushed_at":"2022-06-12T17:00:29.000Z","size":33575,"stargazers_count":10,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-06T11:45:50.004Z","etag":null,"topics":["academic-project","cmake","cpp","kernel","make","nasm","qemu","qemu-x86","stivale","stivale2","x86-64"],"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/ecomaikgolf.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}},"created_at":"2021-04-29T00:26:11.000Z","updated_at":"2025-03-09T16:38:10.000Z","dependencies_parsed_at":"2023-06-05T08:15:42.076Z","dependency_job_id":null,"html_url":"https://github.com/ecomaikgolf/alma","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ecomaikgolf/alma","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecomaikgolf%2Falma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecomaikgolf%2Falma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecomaikgolf%2Falma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecomaikgolf%2Falma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ecomaikgolf","download_url":"https://codeload.github.com/ecomaikgolf/alma/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecomaikgolf%2Falma/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280370895,"owners_count":26319317,"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-22T02:00:06.515Z","response_time":63,"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":["academic-project","cmake","cpp","kernel","make","nasm","qemu","qemu-x86","stivale","stivale2","x86-64"],"created_at":"2024-07-29T18:11:27.509Z","updated_at":"2025-10-22T02:56:58.836Z","avatar_url":"https://github.com/ecomaikgolf.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"200\" height=\"105\" src=\"/docs/img/alma_logo.png\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ci\u003ealma is a toy kernel written in C++ for x86_64 machines with the mere purpose of learning OS development\u003c/i\u003e\n\u003c/p\u003e\n\n# alma\n\n\u003e 6. f. Sustancia o parte principal de cualquier cosa.\n\n## Features\n\n_Note: GIF quality is vastly reduced and native executions look clear_\n\n\u003ctable\u003e\n   \u003ctr\u003e\n      \u003cth\u003ealma build system\u003c/th\u003e\n      \u003cth\u003e\u003c/th\u003e\n   \u003c/tr\u003e\n   \u003ctbody\u003e\n      \u003ctr\u003e\n         \u003ctd\u003e\n            \u003cul\u003e\n               \u003cli\u003e\n                  Setup toolchain\n                  \u003cul\u003e\n                     \u003cli\u003eapt install ...\u003c/li\u003e\n                     \u003cli\u003emake -C toolchain\u003c/li\u003e\n                     \u003cli\u003ealma build vm\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003e\n                  Configure with cmake\n                  \u003cul\u003e\n                     \u003cli\u003eOut of source builds\u003c/li\u003e\n                     \u003cli\u003eRecompile only what is needed\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003e\n                  Build with make or ninja\n                  \u003cul\u003e\n                     \u003cli\u003edefault target (build iso)\u003c/li\u003e\n                     \u003cli\u003etarget run (qemu)\u003c/li\u003e\n                     \u003cli\u003etarget debug (remote gdb)\u003c/li\u003e\n                     \u003cli\u003etarget doc (doxygen)\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003eSpeedup with ccache if found\u003c/li\u003e\n            \u003c/ul\u003e\n         \u003c/td\u003e\n         \u003ctd\u003e\u003cimg src=\n            \"/docs/img/alma_build.gif\"\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n   \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ctable\u003e\n   \u003ctr\u003e\n      \u003cth\u003ealma kernel\u003c/th\u003e\n      \u003cth\u003e\u003c/th\u003e\n   \u003c/tr\u003e\n   \u003ctbody\u003e\n      \u003ctr\u003e\n         \u003ctd\u003e\n            \u003cul\u003e\n               \u003cli\u003eTested in real hardware\u003c/li\u003e\n               \u003cli\u003eStivale2 specification \u003c/li\u003e\n               \u003cli\u003eCall ctors and dtors\u003c/li\u003e\n               \u003cli\u003e\n                  Rendering \n                  \u003cul\u003e\n                     \u003cli\u003esimple rendering\u003c/li\u003e\n                     \u003cli\u003efast console rendering\u003c/li\u003e\n                     \u003cli\u003ePSF1 fonts\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003e\n                  Segmentation\n                  \u003cul\u003e\n                     \u003cli\u003eNaive GDT\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003e\n                  Paging\n                  \u003cul\u003e\n                     \u003cli\u003eVirtual Memory\u003c/li\u003e\n                     \u003cli\u003ePage Allocation\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003e\n                  Keyboard\n                  \u003cul\u003e\n                     \u003cli\u003ePS2 Keyboard Support  \u003c/li\u003e\n                     \u003cli\u003esymbols \u0026 mayus\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003e\n                  Networking\n                  \u003cul\u003e\n                     \u003cli\u003eRTL8139 Driver\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003e\n                  ACPI\n                  \u003cul\u003e\n                     \u003cli\u003eQuery Tables\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003e\n                  PCI\n                  \u003cul\u003e\n                     \u003cli\u003eMCFG From ACPI\u003c/li\u003e\n                     \u003cli\u003eMMIO Configuration\u003c/li\u003e\n                     \u003cli\u003eEnumerate dev/bus/func \u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003e\n                  Interrupts\n                  \u003cul\u003e\n                     \u003cli\u003eManage IDT\u003c/li\u003e\n                     \u003cli\u003eRegister Interrupts\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003e\n                  Dynamic Memory\n                  \u003cul\u003e\n                     \u003cli\u003emalloc\u003c/li\u003e\n                     \u003cli\u003efree\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n            \u003c/ul\u003e\n         \u003c/td\u003e\n         \u003ctd\u003e\n            \u003cimg src=\"/docs/img/alma_virtmem.gif\"\u003e\n            \u003cimg src=\"/docs/img/alma_net.gif\"\u003e\n         \u003c/td\u003e\n      \u003c/tr\u003e\n   \u003c/tbody\u003e\n\u003c/table\u003e\n\u003ctable\u003e\n   \u003ctr\u003e\n      \u003cth\u003ealma bootloader\u003c/th\u003e\n      \u003cth\u003e\u003c/th\u003e\n   \u003c/tr\u003e\n   \u003ctbody\u003e\n      \u003ctr\u003e\n         \u003ctd\u003e\n            \u003cul\u003e\n               \u003cli\u003e\n                  Deprecated\n                  \u003cul\u003e\n                     \u003cli\u003ealma uses stivale2\u003c/li\u003e\n                     \u003cli\u003eships with the limine botloader \u0026nbsp;\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003eposix-uefi\u003c/li\u003e\n               \u003cli\u003e\n                  Load ELF\n                  \u003cul\u003e\n                     \u003cli\u003eParse headers\u003c/li\u003e\n                     \u003cli\u003eLoad segments\u003c/li\u003e\n                  \u003c/ul\u003e\n               \u003c/li\u003e\n               \u003cli\u003eInitialization tasks\u003c/li\u003e\n               \u003cul\u003e\n                  \u003cli\u003eGOP\u003c/li\u003e\n                  \u003cli\u003eMemory Map\u003c/li\u003e\n                  \u003cli\u003eRSDP\u003c/li\u003e\n                  \u003cli\u003ePSF1\u003c/li\u003e\n               \u003c/ul\u003e\n               \u003cli\u003eKernel launch\u003c/li\u003e\n               \u003cul\u003e\n                  \u003cli\u003eCall ctors\u003c/li\u003e\n                  \u003cli\u003eExit UEFI Services\u003c/li\u003e\n                  \u003cli\u003eJump to entry point\u003c/li\u003e\n               \u003c/ul\u003e\n            \u003c/ul\u003e\n         \u003c/td\u003e\n         \u003ctd\u003e\u003cimg src=\n            \"/docs/img/alma_bootloader.gif\"\u003e\u003c/td\u003e\n      \u003c/tr\u003e\n   \u003c/tbody\u003e\n\u003c/table\u003e\n\n## Run\n\n1. Install qemu:\n\n  **Ubuntu**:\n```bash\napt install qemu-system-x86 qemu-system-gui\n```\n\n  **Arch Linux**:\n```bash\npacman -S qemu qemu-arch-extra\n```\n\n2. Find a build to test https://ls.ecomaikgolf.com/alma/builds/\n\n3. Download a build with wget:\n\n```bash\nwget https://ls.ecomaikgolf.com/alma/builds/CHANGEME.tar.gz\ntar xf CHANGEME.tar.gz\ncd CHANGEME\n```\n\n4. Run\n\n```bash\nqemu-system-x86_64 -machine q35 -cpu qemu64 -m 256M -bios bios.bin -netdev user,id=user.0 -device rtl8139,netdev=user.0,mac=ca:fe:c0:ff:ee:00 -object filter-dump,id=f1,netdev=user.0,file=log.pcap -boot d -cdrom alma.iso\n```\n\nIf you want to run it in real hardware, flash it to a USB device:\n\n```bash\nsudo dd bs=4M if=alma.iso of=/dev/CHANGEME conv=fdatasync status=progress\n```\n\nRemember that you must have certain hardware for it to work (PS2 keyboard, RTL8139 NIC, PCIe...). Even with that, running in real hardware is a dark dark place... things can go wrong.\n\n## Build\n\n### Virtual Machine (Method 1)\n\n1. Download the alma build vm [.ova](https://drive.google.com/file/d/1ip2HidddB_fMC8Du4VQKbizl_cyselMz/view?usp=sharing) (a 6.31GB Xubuntu 20.04 virtualbox VM ready to compile)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"800\" height=\"400\" src=\"/docs/img/alma_vm.png\"\u003e\n\u003c/p\u003e\n\n2. Compile with the \"Build Alma\" icon\n3. Run with the \"Run Alma\" icon\n3. Update (pull) with the \"Update Alma\" icon\n\n### Manual (Method 2)\n\n_Note: Instructions tested on `Ubuntu 20.04`_\n\n1. Install dependencies\n\n```bash\napt install nasm iasl cmake make qemu-system-x86 qemu-system-gui git uuid-dev python python3-distutils bash texinfo bison flex build-essential mtools\n```\n\n2. `make -C toolchain/`\n\n* EDKII build can be manually disabled if a compiled binary is provided or not using UEFI\n* posix-uefi build can be manually disabled if bootloader is not going to be built (default behaviour)\n\n3. `cmake -B build` or `cmake -B build -GNinja` \n4. `make -C build run` or `ninja -C build run` \n\n## Mirrors\n\n* Github: `git@github.com:ecomaikgolf/alma.git`, `https://github.com/ecomaikgolf/alma.git`\n* Gitlab: `git@gitlab.com:ecomaikgolf/os-dev.git`, `https://gitlab.com/ecomaikgolf/os-dev.git`\n* Selfhost: `git@ecomaikgolf.com:alma.git`\n\n## Bugs\n\nPlease explain them to me: [me 𝒂𝒕 ecomaikgolf ꓒσ𝗍 c0m](https://ecomaikgolf.com/contact.html) \n\nTake into acccount this is a Bachelor Final Project and has been developed under the pressure of a deadline among other subjects. Some things could be improved, for example, with better (and more complex) data structures, but it's not the goal of the project.\n\n## FAQ\n\n\u003e Q: Muh tons of dependencies\n\u003e \n\u003e A: I'm compiling binutils, gdb, edk2 and posix-uefi from source\n\n\u003e Q: 6.31GB VM\n\u003e\n\u003e A: I can't do more. Xubuntu + \"zeroed\" free memory before exporting so it can be compressed.\n\n\u003e Q: Frequently asked questions?\n\u003e\n\u003e A: More like preanswered questions\n\n## Bibliography\n\n* https://wiki.osdev.org/Main_Page\n* https://youtu.be/NpcGMuI7hxk\n* https://0xax.gitbooks.io/linux-insides/content/Interrupts/\n* https://youtu.be/mpPbKEeWIHU\n* https://www.iaik.tugraz.at/teaching/materials/os/tutorials/paging-on-intel-x86-64/\n* https://git.musl-libc.org/cgit/musl/tree\n* https://maskray.me/blog/2021-11-07-init-ctors-init-array\n* https://blog.llandsmeer.com/tech/2019/07/21/uefi-x64-userland.html\n\n_The list is longer but I can't put each site where I read something. This list is a good place to start_\n\n## Author\n\nErnesto Martínez García\n* [me 𝒂𝒕 ecomaikgolf ꓒσ𝗍 c0m](https://ecomaikgolf.com/contact.html) `C79F 01CE 017F 57A4 FBBB 4E22 33DD FB0A EB94 20CB` \n* https://ecomaikgolf.com/\n* https://twitter.com/ecomaikgolf\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecomaikgolf%2Falma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecomaikgolf%2Falma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecomaikgolf%2Falma/lists"}