Hoshi Operating System

Hoshi Operating System icon

An operating system (OS) maps a model of computation, defined by its kernel interface, onto the underlying hardware. A simple and intuitive model of computation makes it easy for programmers to write applications. An efficient implementation of the mapping makes the applications run fast. Typical as interfaces for von Neumann hardware include processes (CPU), address spaces (memory), and I/O devices (I/O).

Hoshi 星 is an custom hobby operating system for the x86_64 platform. It’s not Linux but it is POSIX-compliant and runs on a custom kernel named Yukiko 幸子. It is written from scratch in C, including the kernel, boot-loader, standard library, GUI library and all major components.

It has a mode called HoshiMin (yes, I know) where it boots into console with minimal applications (but with network support active), minimal memory pressure (under 64MB used) no GUI window manager and kernel debugging dumped into the first serial port.

星 development started in 2015 and I am not looking for contributors. This page is still work-in-progress after so many years and it might not be updated with the latest changes in the tree.

Keep in mind that I have no intention of releasing the source code or an ISO, for now.

I’m developing 星 on a Debian arm64 virtual machine running on Parallels (macOS) and testing is done mainly on QEMU. Screenshots are taken in UTM under macOS.

Requirements

  • x86_64 CPU.
  • 64MB RAM (256MB for GUI).

Features

  • boots from a MBR using a custom bootloader.
  • has a Graphical User Interface with APIs.
  • multithreading.
  • has a network stack supporting IPv4 and IPv6, DNS, ICMP, TCP and UDP.
  • custom filesystem named HOFS (Hoshi File System), ISO 9660 filesystem, FAT32.
  • implements the POSIX API using a basic C library.
  • the GNU toolchain (binutils and GCC can run native on Hoshi).
  • can be compiled on a modern system using GCC 10.
  • has an Internet Relay Chat (IRC) client.
  • has a e-mail client with support for POP3 and SMTP.
  • Universal Serial Bus (USB) EHCI and xHCI support.
  • Symmetric Multiprocessing (SMP).
  • audio support and drivers.
  • runs Doom and Quake.
  • has a custom web browser.
  • has Nyancat.

Hardware support

  • Graphics: BGA for now.
  • Input devices: PS/2 mouse and keyboard.
  • PCI, VGA text mode, APIC.
  • Storage devices: AHCI and IDE.
  • Ethernet cards: Intel PRO/1000 (82540EM / 82545EM), Novell NE2000 and AMD PCNet (Am79C970A / Am79C973).
  • Boots and runs on bare-metal and VirtualBox, QEMU, VMware, UTM (QEMU under the hood) or Parallels.

Ports

Applications

  • Coreutils written from scratch.
  • Text file editor.
  • Akari, the code editor with syntax highlighting.
  • Daigo, Internet Relay Chat client.
  • Painter, painting application.
  • System Information.
  • Kiyoko, the e-mail client with support for POP3 and SMTP.
  • Process Manager.
  • Terminal.
  • Calculator.
  • Font viewer.
  • Image viewer with support for BMP, PNG and JPEG.
  • Tetsuya, RSS reader.
  • Notes, todo and contacts.

Servers

  • echo
  • httpd
  • sshd
  • ftpd

Games

  • 2048
  • Mines
  • Tetris
  • Breakout
  • Space Invaders
  • Pacman
  • Doom
  • Quake
  • Memory

Components

Akimitsu

Akimitsu 昭光 is the GUI compositor and window manager.

Daigo

Daigo 大悟 is the Internet Relay Chat client application.

HoSH

HoSH is the simple (and basic) POSIX-compliant 星 shell.

Keiko

Keiko 恵子 is the network manager, responsable for loading the correct network card driver, initializing it and bootstrapping the whole network stack.

Kiyoko

Kiyoko 清子 is the e-mail client with support for POP3 and SMTP.

Masashi

Masashi 雅志 is the two-stage boot-loader.

Tetsuya

Tetsuya 哲也 is the RSS reader.

Yukiko

Yukiko 幸子 is the monolithic kernel.

Libraries

  • libc - C library.
  • libgui - GUI controls for Akimitsu.
  • libhoshi - helper library with support for Bitmaps, basic crypto, IRC, POP3, SMTP, XML.

Akimitsu GUI controls

  • Buttons
  • Check boxes
  • Combo boxes
  • Data
  • Images
  • Menus
  • Progress bars
  • Radio boxes
  • Scroll bars
  • Tabs
  • Text fields
  • Toolbars

Syscalls

Below is the full list of 星 syscalls:

  • exit
  • write
  • pwrite
  • read
  • pread
  • open
  • close
  • ioctl
  • lseek
  • raise
  • stat
  • lstat
  • pause
  • fstat
  • chmod
  • fchmod
  • fsync
  • chown
  • fchown
  • mkdir
  • ftruncate
  • unlink
  • rmdir
  • dup
  • dup2
  • dup3
  • insmod
  • chdir
  • getcwd
  • mmap
  • munmap
  • rmmod
  • link
  • symlink
  • readlink
  • sleep
  • utime
  • umask
  • shutdown
  • uname
  • sigwait
  • sigsuspend
  • mcast
  • fpoll
  • oxperm
  • dxperm
  • fchxperm
  • chxperm
  • haveperm
  • sync
  • nice
  • procstat
  • cpuno
  • kill
  • time
  • nanotime
  • down
  • routetable
  • systat
  • statvfs
  • fstatvfs
  • chroot
  • modstat
  • mv
  • pathctlat
  • pathctl
  • flock_set
  • flock_get
  • fcntl_setfl
  • fcntl_getfl
  • fcntl_getfd
  • fcntl_setfd
  • bindif
  • block_on
  • unblock
  • unique
  • alarm
  • exec
  • sigaction
  • sigprocmask
  • getparsz
  • getpars
  • fsbase
  • gsbase
  • mprotect
  • fork
  • waitpid
  • yield
  • realpath
  • seterrnoptr
  • geterrnoptr
  • unmount
  • send
  • recv
  • getgroups
  • setgroups
  • getpid
  • getuid
  • geteuid
  • getsuid
  • getgid
  • getegid
  • getsgid
  • getppid
  • setsid
  • setpgid
  • getsid
  • getpgid
  • setuid
  • setgid
  • setreuid
  • setregid
  • seteuid
  • setegid
  • pthread_create
  • pthread_self
  • pthread_join
  • pthread_detach
  • pthread_kill
  • pthread_exit
  • aclput
  • aclclear
  • getdent
  • socket
  • bind
  • sendto
  • recvfrom
  • getsockname
  • listen
  • connect
  • getpeername
  • accept
  • accept4
  • setsockopt
  • getsockopt
  • sockerr

Statistics

The Python, C++, HTML, CSS, JavaScript and JSON files are just demos for Akari and not part of the 星 source code.

$ cloc src --quiet
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
C                              728          35559          50874         143889
C/C++ Header                   272           9256          21993          26385
Assembly                        34            403            270           1964
make                            53            319             22           1166
Bourne Shell                    24            167             69            915
CSS                              2            166            129            680
Markdown                         1             38              0             85
JSON                             1              0              0             43
JavaScript                       2              2              1             35
HTML                             3              0              0             33
C++                              1              2              6              5
Python                           1              1              0              2
-------------------------------------------------------------------------------
SUM:                          1122          45913          73364         175202
-------------------------------------------------------------------------------

Out of which Yukiko (the kernel) has:

$ cloc kernel --quiet
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
C                              226          20722          41571          67678
C/C++ Header                   127           6401          14210          18283
Assembly                        17            217            147           1089
make                             1              9              0             24
Bourne Shell                     1              2              0              8
-------------------------------------------------------------------------------
SUM:                           372          27351          55928          87082
-------------------------------------------------------------------------------

Building

If you happen to run into the source-code “by mistake”, build 星 by installing dependencies first:

$ sudo apt install wget patch gcc binutils genisoimage libz-dev texinfo nasm autoconf

Now it is possible to build a cross-compiler, create a directory called cross next to the src directory, then inside this directory run the command:

$ ../src/setup-toolchain.sh --sysroot=/sysroot

The sysroot does not have to be /sysroot but that’s just what I use. The script will download the source code for binutils and GCC and then patch it to support 星. It will also download all other dependencies (mpfr, gmp, mpc). This should take a few minutes. The next step is to run from the same directory:

$ sudo ./build-toolchain.sh

This installs the C compiler and binutils. It also creates symlinks under /usr/local/bin so that you can invoke commands like x86_64-hoshi-gcc without explicitly including them in your PATH. If you want to build the C++ compiler, you must first build and install the Hoshi C library in the sysroot, and then you can run:

$ sudo ./build-cpp-toolchain.sh

After the C++ compiler is built you can remove the cross directory unless you want to rebuild the toolchain again.

Suppose that you want to build a live ISO yourself, to start, create a working directory next to the src directory, named build and cd inside.

$ mkdir build && cd build
$ ../src/setup.sh --sysroot=/sysroot --iso

or if you’re building HoshiMin:

$ mkdir build-min && cd build-min
$ ../src/setup.sh --sysroot=/sysroot --min

To get the ISO, run make:

$ make

If everything went well, you should now have a file called hoshi.iso. Congratulations, you can now boot it!

星 tips & tricks

  • Starting and stopping Keiko is just a matter of typing those commands at the HoSH prompt:
$ net_start

or:

$ net_stop
  • Keiko will attempt to autoconfigure IPv4 networking using DHCP by default. If you want to enable IPv6, open /Config/Interfaces.conf and add this line:
interface eth0 ipv6 dhcp
  • Display or change the network configuration by using the net_conf utility.

  • There is a basic coreutils package so you’ll find most of the tools you’re used to, like cat, cp, date, dd, du, echo, etc.

  • Development headers are installed in /Develop/Headers.

  • While there is a POSIX layer, 星 is not Linux. Device filesystem is /Devices instead of /dev/, proc filesystem is /Processes instead of /proc, applications are split between /Applications and /System depending on the ACLs. For compatibility reasons there is a /usr directory and system libraries are installed into /usr/lib but this will change in future revisions to /Develop/Libraries.

  • Most of the GUI customization stuff (wallpapers, cursors, icons, themes) can be found inside /Data/System directory.

  • /bin exists only so that shell scripts that use /bin/sh or /bin/bash can find the Hoshi shell.

Directory structure

This is the basic 星 directory structure, keep in mind that things get added depending on the applications that get built and installed. Lowercase directories are added for compatibility reasons.

|-- Applications
|-- bin
|-- boot
|-- Config
|   |-- Init
|   `-- Services
|
|-- Data
|   |-- AppIcons
|   |-- Applications
|   |-- Demos
|   |   `-- Images
|   |-- Docs
|   `-- System
|       |-- Cursors
|       |-- Fonts
|       |-- Icons
|       |-- Images
|       |-- mime
|       |-- Themes
|       `-- Wallpapers
|
|-- Develop
|   |-- Demos
|   |-- Headers
|   |-- Libraries
|   `-- Source
|
|-- Devices
|-- initrd
|-- Internal
|   |-- Keiko
|   `-- Logs
|
|-- lib
|-- lib32
|-- Processes
|-- System
|-- Users
|   `-- Admin
|       |-- Desktop
|       |-- Documents
|       |-- Downloads
|       |-- Pictures
|       `-- Projects
|
|-- usr
`-- Volumes