Setup project skeleton

1 files changed, 133 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fe66a7a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,133 @@
+# 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