{"id":13599859,"url":"https://github.com/o8vm/octox","last_synced_at":"2025-05-15T19:06:10.494Z","repository":{"id":172505998,"uuid":"360037018","full_name":"o8vm/octox","owner":"o8vm","description":"Unix-like OS in Rust inspired by xv6-riscv","archived":false,"fork":false,"pushed_at":"2024-07-31T17:15:30.000Z","size":185,"stargazers_count":1542,"open_issues_count":4,"forks_count":62,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-05-15T19:05:28.566Z","etag":null,"topics":["osdev","riscv","rust","xv6-riscv"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/o8vm.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","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-21T04:57:46.000Z","updated_at":"2025-05-14T10:59:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"3c4cb9e3-f6d9-4d8c-b559-e1e1e1209c74","html_url":"https://github.com/o8vm/octox","commit_stats":null,"previous_names":["o8vm/octox"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o8vm%2Foctox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o8vm%2Foctox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o8vm%2Foctox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o8vm%2Foctox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/o8vm","download_url":"https://codeload.github.com/o8vm/octox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254404357,"owners_count":22065641,"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":["osdev","riscv","rust","xv6-riscv"],"created_at":"2024-08-01T17:01:14.082Z","updated_at":"2025-05-15T19:06:10.469Z","avatar_url":"https://github.com/o8vm.png","language":"Rust","funding_links":[],"categories":["Rust","Active","Rust 程序设计","Open Source Operating Systems"],"sub_categories":["网络服务_其他"],"readme":"#+title: octox\n#+author: Hayato Ohhashi\n#+email: o8@vmm.dev\n\noctox is a Unix-like operating system inspired by xv6-riscv. octox loosely\nfollows the structure and style of xv6, but is implemented in pure Rust.\n\n[[https://vhs.charm.sh/vhs-6MQBIyAo3DpBrARBxHxL35.gif]]\n\n- Everything from kernel, userland, mkfs, to build system is written in safe\n  Rust as much as possible.\n- There are no dependencies on external crates.\n- The userland has a library similar to Rust’s std with K\u0026R malloc.\n- Multi-core support, buddy allocator as kernel-side memory allocator, file\n  system with logging support, etc.\n\n* Getting Started\n\n** Requirements\n\n- Install the rust toolchain to have cargo installed by following\n  [[https://www.rust-lang.org/tools/install][this]] guide.\n- Install ~qemu-system-riscv~\n- (option) Install ~gdb-multiarch~\n\n** Build and Run\n\n- Clone this project \u0026 enter: ~git clone ... \u0026\u0026 cd octox~\n- Build: ~cargo build --target riscv64gc-unknown-none-elf~.\n- Run: ~cargo run --target riscv64gc-unknown-none-elf~, then qemu will boot\n  octox. To exit, press ~Ctrl+a~ and ~x~.\n\n** Play with the Shell\n\nA very simple shell is implemented.\nIn addition to executing commands, you can only do the following things.\n\n- Pipe: ~cat file | head | grep test~\n- Dump processes: ~Ctrl + P~\n- End of line: ~Ctrl + D~\n- Redirect output: ~\u003e~, ~\u003e\u003e~\n\n* Development\n\n** Userland Application\n\nThe userland comes with a user library called ulib (located at src/user/lib)\nthat is similar to Rust’s std, so you can use it to develop your favorite \ncommands. If you create a bin crate named ~_command~ in src/user/bin, the \nbuild.rs and mkfs.rs will place a file named ~command~ in the file system \nand make it available for use.\n\n- In src/user/Cargo.toml, define a bin crate with the name of the command you\n  want to create with a ~_~ prefix\n  #+begin_src toml\n    [[bin]]\n    name = \"_rm\"\n    path = \"bin/rm.rs\"\n  #+end_src\n- userland is also no_std, so don’t forget to add ~#[no_std]~. Use ulib to\n  develop any command you like. Here is an example of the rm command.\n  #+begin_src rust\n    #![no_std]\n    use ulib::{env, fs};\n\n    fn main() {\n        let mut args = env::args().skip(1).peekable();\n\n        if args.peek().is_none() {\n            panic!(\"Usage: rm files...\")\n        }\n        for arg in args {\n            fs::remove_file(arg).unwrap()\n        }\n    }\n  #+end_src\n- Then, ~cargo run --target riscv64gc-unknown-none-elf~ in the root of octox.\n- To use ~Vec~ and ~String~, etc, do the following:\n  #+begin_src rust\n    extern crate alloc;\n    use alloc::{string::String, vec::Vec};\n  #+end_src\n\n** Kernel\n\nDeveloping in src/kernel. Here is an example of adding a system call. If you\nwant to add a new system call, you only need to add a definition to the system\ncall table in libkernel, and the userland library will be automatically\ngenerated by build.rs.\n\n- Add a variant and Syscall Number to ~enum SysCalls~ in src/kernel/syscall.rs.\n  Here is ~Dup2~ as an example:\n  #+begin_src rust\n    pub enum SysCalls {\n        Fork = 1,\n        ...,\n        Dup2 = 23,\n        Invalid = 0,\n    }\n  #+end_src\n- Define the function signature of the system call in the ~TABLE~ of\n  ~SysCalls~. Use the enum type ~Fn~ to describe the return type(~U~ (Unit),\n  ~I~ (Integer), ~N~ (never)) and use ~\u0026str~ to represent arguments. then,\n  define kernel-side implementation as a method on ~SysCalls~. ~cfg~ flag is\n  used to control the compilation target for kernel and the rest. Here is an\n  example of ~dup2~:\n  #+begin_src rust\n    impl SysCalls {\n        pub const TABLE: [(fn, \u0026'static str); variant_count::\u003cSelf\u003e()] = [\n            (Fn::N(Self::Invalid), \"\"),\n            (Fn::I(Self::fork), \"()\"),\n            (Fn::N(Self::exit), \"(xstatus: i32)\"),\n            ...,\n            (Fn::I(Self::dup2), \"(src: usize, dst: usize)\"),\n        ];\n        pub fn dup2() -\u003e Result\u003cusize\u003e {\n            #[cfg(not(all(target_os = \"none\", feature = \"kernel\")))]\n            return Ok(0);\n            #[cfg(all(target_os = \"none\", feature = \"kernel\"))]\n            {\n                let p = Cpus::myproc().unwrap().data_mut();\n                let src_fd = argraw(0); let dst_fd = argraw(1);\n                if src_fd != dst_fd {\n                    let mut src = p.ofile.get_mut(src_fd).unwrap()\n                        .take().unwrap();\n                    src.clear_cloexec();\n                    p.ofile.get_mut(dst_fd)\n                        .ok_or(FileDescriptorTooLarge)?.replace(src);\n                }\n                Ok(dst_fd)\n            }\n        }\n  #+end_src\n- With just these steps, the dup2 system call is implemented in both kernel and\n  userland.\n\n* License\n\nLicensed under either of\n\n- [[http://www.apache.org/licenses/LICENSE-2.0][Apache License, Version 2.0]]\n- [[http://opensource.org/licenses/MIT][MIT license]]\n\nat your option.\n\n* Acknowledgments\n\noctox is inspired by [[https://github.com/mit-pdos/xv6-riscv][xv6-riscv]].\n\nI'm also grateful for the bug reports and discussion about the implementation\ncontributed by Takahiro Itazuri and Kuniyuki Iwashima.\n\n* Contribution\n\nThis is a learning project for me, and I will not be accepting pull requests\nuntil I consider the implementation complete. However, discussions and advice\nare welcome.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fo8vm%2Foctox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fo8vm%2Foctox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fo8vm%2Foctox/lists"}