Hoshi Operating System

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
author
created April 22, 2016
updated July 12, 2023
words 1557
tags #hoshi, #projects, #operating system, #osdev