# Wnix

**DISCLAIMER: this project is in early stage development, and therefore**
**not suitable for production environments.**

Wnix (pronounced _woo-nix_ or _double u-nix_) is a small, Unix-like operating
system aimed towards resource-constrained devices without a [MMU].
Virtual memory semantics are instead achieved by *exclusively* running
[WebAssembly] applications on its userspace, using the small and flexible
interpreter [NanoWasm] as its backend.

For the sake of simplicity, and as opposed to most operating systems,
Wnix only requires one execution thread to perform all tasks. In other words,
Wnix is highly concurrent, but not parallel, and relies entirely on
co-operative execution of asynchronous (i.e., fast) tasks to achieve
[concurrency].

**Note:** while designed to remain portable, Wnix currently only targets the
original [PlayStation].

## Dependencies

- A `mipsel-unknown-elf` cross-toolchain (i.e., GNU `binutils` and GCC).
Here are [some notes](https://www.psxdev.net/forum/viewtopic.php?t=40)
to build it from source.
- `clang-18`
- `libclang-18-dev`
- Copy `libclang_rt.builtins-wasm32.a` (get from WASI-SDK) to
`/usr/lib/llvm-18/lib/clang/18/lib`.
- C and C++ compilers for the host platform.

## How to build

Configure with:

```
cmake -B build -DCMAKE_TOOLCHAIN_FILE=cmake/ps1-toolchain.cmake -DVIDEO_MODE=VMODE_PAL
```

Build with:

```
cmake --build build/ # Optionally, add -j$(nproc)
```

## FAQ

### Why not a fully-fledged operating system like GNU/Linux or BSDs?

While all these projects truly deserve uttermost respect, these are very
complex projects that target a diverse range of highly sophisticated hardware.

More specifically, regarding the original PlayStation there have been
[several unsuccessful attempts](https://www.psxdev.net/forum/viewtopic.php?t=152&start=40)
at running ancient versions of the Linux kernel (circa `2.4`), with
[concerns](https://www.psxdev.net/forum/viewtopic.php?p=19405#p19405)
about newer versions not being able to fit into the console's 2 MiB RAM.

On the other hand, kernels like Linux are focused on running native
executables (i.e., ELF files), where the semantics provided by MMUs would not
be available on limited hardware like the original PlayStation.
While it might still be possible to configure Linux to exclusively
run WebAssembly applications somehow, Linux is still a very large and complex
project that would require a big effort to port to a PlayStation.

Since binary compatibility with existing Linux software is not a requirement,
a simple operating system with Unix-like semantics is enough to allow
WebAssembly applications to interact with the system via [WASI].

Moreover, not having a MMU available would typically mean executables
would be dumped to RAM before execution, with a non-negligible footprint.
On the other hand, NanoWasm is designed to allow direct execution from any
source, including read-only media like CD-ROMs.

Similarly, NanoWasm allows to allocate and manipulate WebAssembly memories
(linear memory, stack, etc.) from any source, including but not limited to
memory cards or any other external mass storage, therefore allowing the system
to outgrow its RAM size limitations, similarly to how fully-fledged operating
systems like GNU/Linux implement virtual memory.

More importantly, running userspace applications without a MMU would allow a
malicious application to read/write memory from/to other processes, or even
the kernel itself. Confining userspace applications into a sandbox can be
achieved via WebAssembly, a bytecode representation that can be easily compiled
down to from popular programming languages, such as C or C++, via [`wasi-sdk`].

Of course, the design decisions above were made with memory efficiency and
security in mind, at the cost of execution speed. Wnix is meant to provide
similar tools compared to fully-fledged operating systems, at a fraction of
their size.

And last, but not least, Wnix was written as an attempt to learn about
operating systems in general, and a way to have fun while implementing
interesting ways to achieve virtual memory semantics and concurrency by
software.

## License

```
wnix, a Unix-like operating system for WebAssembly applications.
Copyright (C) 2025  Xavier Del Campo Romero

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
```

Wnix includes source code from other projects under various free software
licenses. Unless explicitly noted otherwise, Wnix is licensed according to
[`LICENSE`](LICENSE).

## Disclaimer

- Linux is a registered trademark of Linus Torvalds.
- PlayStation is a registered trademark of its respective owners.
- Unix is a registered trademark of its respective owners.

[MMU]: https://en.wikipedia.org/wiki/Memory_management_unit
[WebAssembly]: https://en.wikipedia.org/wiki/Webassembly
[NanoWasm]: https://gitea.privatedns.org/xavi/nanowasm
[PlayStation]: https://en.wikipedia.org/wiki/PlayStation_(console)
[concurrency]: https://en.wikipedia.org/wiki/Concurrent_computing
[WASI]: https://wasi.dev/
[`wasi-sdk`]: https://github.com/WebAssembly/wasi-sdk
