{"id":15060048,"url":"https://github.com/mssola/fbos","last_synced_at":"2025-07-10T20:31:29.860Z","repository":{"id":254508094,"uuid":"846467625","full_name":"mssola/fbos","owner":"mssola","description":"A RISC-V operating system devoted to running fizz/buzz processes.","archived":false,"fork":false,"pushed_at":"2024-12-05T13:04:06.000Z","size":212,"stargazers_count":7,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-05T17:11:16.636Z","etag":null,"topics":["assembly","c","fizzbuzz","kernel","risc-v"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mssola.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-23T09:17:57.000Z","updated_at":"2024-12-05T13:03:34.000Z","dependencies_parsed_at":"2024-12-03T08:18:25.334Z","dependency_job_id":"65fdcd8e-a759-4af3-a2d2-0ac0c3c95deb","html_url":"https://github.com/mssola/fbos","commit_stats":null,"previous_names":["mssola/fbos"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mssola/fbos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mssola%2Ffbos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mssola%2Ffbos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mssola%2Ffbos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mssola%2Ffbos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mssola","download_url":"https://codeload.github.com/mssola/fbos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mssola%2Ffbos/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264652673,"owners_count":23644306,"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":["assembly","c","fizzbuzz","kernel","risc-v"],"created_at":"2024-09-24T22:51:46.350Z","updated_at":"2025-07-10T20:31:29.848Z","avatar_url":"https://github.com/mssola.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"A RISC-V operating system devoted to running fizz/buzz processes.\n\nFizzBuzz OS (or just `fbos`) is an excuse to better grasp the fundamentals of\nlow level RISC-V machines. In practice, this is a small Operating System kernel\nthat is able to launch three processes: one that simply prints \"Fizz\", another\nthat prints \"Buzz\", and a final third which prints \"FizzBuzz\". These processes\nare unaware of each other and it's up to the kernel to schedule them by using\nthe timer interrupts as given by openSBI (`fizz` on % 3 seconds, `buzz` on % 5\nseconds, and `fizzbuzz` on % 15 seconds).\n\nThis kernel provides just one system call, `write`, which allows any program to\npass the string to be written into the serial port and wait for the kernel to\nre-schedule it.\n\n## Build\n\nIn order to build `fbos` you only need GCC. That being said, if you are not on a\nRISC-V system you will also need cross compilation tools for it (check your\ndistribution for this, on openSUSE I simply installed `cross-riscv64-gcc14`).\nWith that installed, simply set the `CROSS_COMPILE` environment variable as\nyou'd do for building the Linux kernel (e.g. in my case, using openSUSE, I set\nit to `riscv64-suse-linux-`). After all of that, just:\n\n```\n$ make\n```\n\nAnd that's basically it! The build process should've produced a `fbos` binary\nsitting at the root of the project.\n\n### Verbose output\n\nYou will notice that the output is suspiciously quiet. You can go back into\nverbose output by passing `V=1` to any make target. Hence, for the build step,\nyou can do something like:\n\n```\n$ make V=1\n```\n\n### Debug mode\n\nBy default the kernel will be built with optimizations on. You can disable this\nby passing the `DEBUG=1` option to any make target. This will also come in handy\nwhenever you'd want to debug the kernel via QEMU+GDB. Read more on this below.\n\n## Test\n### QEMU\n\nThe easiest way to test the `fbos` binary from the build step is with QEMU. You\nneed a QEMU version that is recent enough (see [requirements](#requirements))\nand that is able to virtualize a RISC-V system. With that, simply run:\n\n```\n$ make qemu\n```\n\nThis will open up QEMU in `-nographic` mode (hence the serial output will be\nsimply redirected to stdout), and you will be able to see the whole thing\nworking. Just like this:\n\n![Demo on QEMU](./doc/qemu.svg)\n\nMoreover, the `qemu` target can be paired with the `DEBUG` parameter that you\ncan pass to make. Hence, you can also call it like so:\n\n```\n$ make qemu DEBUG=1\n```\n\nThis will make QEMU wait for a GDB connection. On another terminal then type:\n\n```\n$ make gdb\n```\n\nNow you have a debugging session for this kernel with debug symbols loaded.\nHence, upon starting the GDB session you can simply type:\n\n```\n(gdb) break _start\n(gdb) continue\n```\n\nFrom there you are already out of firmware code and right into the kernel.\nMoreover, you can also pass the `GDB_EXTRA_FLAGS` variable to the `make gdb`\ntarget. This way you can pass extra parameters to gdb, such as:\n\n```\n$ make gdb GDB_EXTRA_FLAGS=\"-tui\"\n```\n\nAnd now you have started a GDB session with a nice TUI interface.\n\n### VisionFive 2\n\nThis kernel can also be run on real hardware. In particular, I have tested it\nwith the Starfive VisionFive 2 board. I have tested this with an existing Linux\ninstallation. In there, I have modified the bootloader configuration so I have\nnow this entry:\n\n```\nlabel l6\n\tmenu label FizzBuzz OS\n\tlinux /fbos\n\tinitrd /initramfs.cpio\n\tfdtdir /dtbs/\u003cversioned directory\u003e\n```\n\nIn order to get the needed files, you can use the `archive` make target:\n\n```\nmake archive\n```\n\nCopy this tarball to your board and then place the `fbos` binary image and the\n`initramfs.cpio` file into `/boot`. When you reset your board, you will get the\nnew entry from U-Boot and you will be able to run the kernel from there. Like\nthis:\n\n![Demo on VisionFive 2](./doc/vf2.svg)\n\n## Requirements\n\nWe do not want to support a myriad of different scenarios, but we want to keep\nthings simple. Hence, here there are some limitations/requirements:\n\n- You need a recent enough OpenSBI running on your firmware. I have tested this\n  on a QEMU which has OpenSBI v1.5, but any firmware that implements a Runtime\n  SBI version of 2.0 should be fine.\n- You are supposed to pass an `initrd` always. This kernel will not try to\n  magically come up with a made up file system or try to fetch something from an\n  existing one. An `initrd` is already provided for you on the default `make`\n  target, and that's what you are supposed to be passing to the kernel.\n- RISC-V is ambivalent on the endianness. Not this kernel. Out of simplicity we\n  require a little-endian RISC-V system.\n- This kernel makes use of the `Zaamo` Extension for Atomic Memory Operations,\n  which is included under the `A` Extension for Atomic Instructions.\n\n## Special thanks to\n\n- SUSE for organizing [Hack Week 24](https://hackweek.opensuse.org/24/projects).\n  This project was mainly developed during this time.\n- [Ricardo B. Marliere](https://github.com/rbmarliere) for contributing to the\n  project with code, ideas and shared knowledge.\n- I have also taken lots of valuable input by reading [Popovic's\n  blog](https://popovicu.com/), so thanks a lot for writing such clear articles\n  on a rather obscure topic.\n- In a similar way, I have also taken the time to read a lot of code from the\n  Linux Kernel. My understanding of both RISC-V and the Linux Kernel itself has\n  vastly improved with this exercise, so I'd also like to take the chance to be\n  grateful to the many people who have contributed to this vast undertaking that\n  is the Linux Kernel.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmssola%2Ffbos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmssola%2Ffbos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmssola%2Ffbos/lists"}