README.org

June 24, 2025 · View on GitHub

#+title: octox #+author: Hayato Ohhashi #+email: o8@vmm.dev

octox is a Unix-like operating system inspired by xv6-riscv. octox loosely follows the structure and style of xv6, but is implemented in pure Rust.

[[https://vhs.charm.sh/vhs-6MQBIyAo3DpBrARBxHxL35.gif]]

  • Everything from kernel, userland, mkfs, to build system is written in safe Rust as much as possible.
  • There are no dependencies on external crates.
  • The userland has a library similar to Rust’s std with K&R malloc.
  • Multi-core support, buddy allocator as kernel-side memory allocator, file system with logging support, etc.
  • Getting Started

** Requirements

** Build and Run

  • Clone this project & enter: git clone ... && cd octox
  • Build: cargo build --target riscv64gc-unknown-none-elf.
  • Run: cargo run --target riscv64gc-unknown-none-elf, then qemu will boot octox. To exit, press Ctrl+a and x.

** Play with the Shell

A very simple shell is implemented. In addition to executing commands, you can only do the following things.

  • Pipe: cat file | head | grep test
  • Dump processes: Ctrl + P
  • End of line: Ctrl + D
  • Redirect output: >, >>
  • Development

** Userland Application

The userland comes with a user library called ulib (located at src/user/lib) that is similar to Rust’s std, so you can use it to develop your favorite commands. If you create a bin crate named _command in src/user/bin, the build.rs and mkfs.rs will place a file named command in the file system and make it available for use.

  • In src/user/Cargo.toml, define a bin crate with the name of the command you want to create with a _ prefix #+begin_src toml [[bin]] name = "_rm" path = "bin/rm.rs" #+end_src

  • userland is also no_std, so don’t forget to add #[no_std]. Use ulib to develop any command you like. Here is an example of the rm command. #+begin_src rust #![no_std] use ulib::{env, fs};

    fn main() { let mut args = env::args().skip(1).peekable();

      if args.peek().is_none() {
      panic!("Usage: rm files...")
  }
  for arg in args {
      fs::remove_file(arg).unwrap()
  }

    } #+end_src

  • Then, cargo run --target riscv64gc-unknown-none-elf in the root of octox.

  • To use Vec and String, etc, do the following: #+begin_src rust extern crate alloc; use alloc::{string::String, vec::Vec}; #+end_src

** Kernel

Developing in src/kernel. Here is an example of adding a system call. If you want to add a new system call, you only need to add a definition to the system call table in libkernel, and the userland library will be automatically generated by build.rs.

  • Add a variant and Syscall Number to enum SysCalls in src/kernel/syscall.rs. Here is Dup2 as an example: #+begin_src rust pub enum SysCalls { Fork = 1, ..., Dup2 = 23, Invalid = 0, } #+end_src
  • Define the function signature of the system call in the TABLE of SysCalls. Use the enum type Fn to describe the return type(U (Unit), I (Integer), N (never)) and use &str to represent arguments. then, define kernel-side implementation as a method on SysCalls. cfg flag is used to control the compilation target for kernel and the rest. Here is an example of dup2: #+begin_src rust impl SysCalls { pub const TABLE: [(fn, &'static str); variant_count::()] = [ (Fn::N(Self::Invalid), ""), (Fn::I(Self::fork), "()"), (Fn::N(Self::exit), "(xstatus: i32)"), ..., (Fn::I(Self::dup2), "(src: usize, dst: usize)"), ]; pub fn dup2() -> Result { #[cfg(not(all(target_os = "none", feature = "kernel")))] return Ok(0); #[cfg(all(target_os = "none", feature = "kernel"))] { let p = Cpus::myproc().unwrap().data_mut(); let src_fd = argraw(0); let dst_fd = argraw(1); if src_fd != dst_fd { let mut src = p.ofile.get_mut(src_fd).unwrap() .take().unwrap(); src.clear_cloexec(); p.ofile.get_mut(dst_fd) .ok_or(FileDescriptorTooLarge)?.replace(src); } Ok(dst_fd) } } #+end_src
  • With just these steps, the dup2 system call is implemented in both kernel and userland.
  • License

Licensed under either of

at your option.

  • Acknowledgments

octox is inspired by [[https://github.com/mit-pdos/xv6-riscv][xv6-riscv]].

I'm also grateful for the bug reports and discussion about the implementation contributed by Takahiro Itazuri and Kuniyuki Iwashima.

  • Contribution

This is a hobby learning project, but contributions are welcome! However, please note that reviews may take considerable time. Discussions and advice are always appreciated.