>[!IMPORTANT]
-> HyperCPU is almost ready for use! Wait for 1.0 release to try it out or build the project locally, test and report found issues.
+> HyperCPU is almost ready for use! Wait for 1.0 release to try it out or build the project yourself, test and report found issues.
-## What is it?
+HyperCPU is a set of programs created to work with my own simple ISA (instruction set architecture). The project was created for fun, but it took a lot of time (and nerves) and I learned a lot while working on it.
-HyperCPU is a set of programs, created to work with my own simple ISA (instruction set architecture). The project was created for fun, but it took a lot of time (and nerves), and I learned a lot while working on it.
-
-HyperCPU toolkit includes:
+HyperCPU project includes:
* **hCPU emulator**;
* **hASM assembler**;
-* **hASM disassembler**.
+* ~~**hASM disassembler**~~ (planned).
+
+The project roadmap can be found [here](ROADMAP.md).
+
+### Installation
>[!WARNING]
-> HyperCPU supports Linux systems only. Do not even try to build it under Windows.
+> HyperCPU supports 64-bit GNU/Linux systems only. It is known to be successfully built and running on `amd64` and `aarch64` architectures.
+
+#### Dependencies
+
+* `gcc >= 14` or `clang >= 19`;
+* `cmake >= 3.28`;
+* `make`;
+* `ninja`;
+* `re2`;
+* `fmt`;
+* `googletest` (required for building tests in Release profile);
+* `python3`, `python3-pip`, `python3-sphinx`, `python3-sphinx-rtd-theme` (required for building a documentation).
+
+#### Build instructions
+
+```bash
+$ git clone https://github.com/HyperWinX/HyperCPU --recursive
+$ cd HyperCPU
+$ cmake -S . -B build -G "Ninja" -DCMAKE_BUILD_TYPE=Release
+$ ninja -C build default -j$(nproc)
+$ cd docs
+$ make html
+```
+
+`cmake` build options (use `-D` flag to define them):
+
+* `CMAKE_BUILD_TYPE:STRING` - project build profile (`Release` or `Debug`), mandatory to be specified;
+* `HCPU_SANITIZERS_ENABLED:BOOL` - HyperCPU sanitizers, enabled by default (use `-DHCPU_SANITIZERS_ENABLED:BOOL=OFF` to disable).
+
+The compiled binaries should be located in `build` directory. The generated documentation should be located in `docs/_build/html` directory. After building the project open `index.html` file and start reading the documentation.
+
+Do not forget to check out [examples](examples) folder for interesting code examples that will help you better understand the syntax of hASM and the power of HyperCPU.
+
+### Usage
+
+#### `hcasm` (hASM assembler)
+
+To compile a program to a binary file:
+
+```bash
+$ ./hcasm -o
+```
+
+To compile a program to an object file:
-## Roadmap
+```bash
+$ ./hcasm -c
+```
-You can find the project roadmap [here](ROADMAP.md).
+To do things with a different verbosity level (`debug`, `info`, `warning`, `error`):
-## Installation
+```bash
+$ ./hcasm -v ...
+```
-At the moment of writing this text, HyperCPU installation is done by building the whole project from source code. Maybe one day HyperCPU will start distributing release tarballs for much easier installation, but who knows.
+To display help message and exit:
-### Building from source codes
+```bash
+$ ./hcasm -h # = ./hcasm --help
+```
-HyperCPU requires these tools and libraries:
+To display program version and exit:
-* C++ compiler with C++23 standard support (i. e. `gcc` >= `14` or `clang` >= 19);
-* `cmake`, `ninja` - build systems;
-* `re2` - regular expressions parser;
-* `libfmt` - formatting library;
-* `googletest` - required for building tests in Release build profile;
-* `python3`, `python3-pip`, `sphinx` and `sphinx-rtd-theme` (should be installed through `pip` or your system package manager) - required for building a documentation.
+```bash
+$ ./hcasm --version
+```
-There are a few options (definitions) that can be used with `cmake`:
-* `CMAKE_BUILD_TYPE`:`STRING` - project build profile (`Release` or `Debug`), should be always specified;
-* `HCPU_SANITIZERS_ENABLED`:`BOOL` - HyperCPU sanitizers (enabled by default); use `-DHCPU_SANITIZERS_ENABLED:BOOL=OFF` to disable them.
+#### `hcemul` (hCPU emulator)
-After installing dependencies, open the terminal and run these commands:
+To run a binary:
```bash
-git clone https://github.com/HyperWinX/HyperCPU --recursive
-cd HyperCPU
-cmake -S. -Bbuild -G "Ninja" -DCMAKE_BUILD_TYPE=Release
-ninja -C build default -j$(nproc)
+$ ./hcasm
```
-That's all. The compiled binaries should be located in `build` directory.
+To do things with a different verbosity level (`debug`, `info`, `warning`, `error`):
-Run `cd docs && make html` to build a documentation. After that go to `docs/_build/html` directory, open `index.html` and start reading.
+```bash
+$ ./hcemul -v ...
+```
-## Usage
+To display help message and exit:
+```bash
+$ ./hcemul -h # = ./hcemul --help
```
-Usage: hcasm [--help] [--version] [-o VAR] [-c] [-v VAR] source
-
-Positional arguments:
- source source file to be assembled [required]
-
-Optional arguments:
- -h, --help shows help message and exits
- -v, --version prints version information and exits
- -o name of the binary file
- -c compile to object file
- -v set verbosity level. possible modes:
- - debug
- - info
- - warning
- - error [nargs=0..1] [default: "warning"]
-
-Usage: hcemul [--help] [--version] [-v VAR] binary
-
-Positional arguments:
- binary binary file to execute [required]
-
-Optional arguments:
- -h, --help shows help message and exits
- -v, --version prints version information and exits
- -v set verbosity level. possible modes:
- - debug
- - info
- - warning
- - error [nargs=0..1] [default: "debug"]
+
+To display program version and exit:
+
+```bash
+$ ./hcemul --version
```
-## Contributing
+### Contributing
-HyperCPU is in active development, and we will be happy to hear any feedback from you. Do not hesitate to report bugs or suggest any ideas using "Issues" page.
+HyperCPU is in active development and we will be happy to hear any feedback from you. Do not hesitate to report bugs or suggest any ideas using "Issues" page.
>[!IMPORTANT]
->Please send your pull requests to `dev` repository branch (not `master`).
+> Please send your pull requests to `dev` repository branch, not `master`.
Thank you for your interest in HyperCPU.
-## Authors
+### Authors
+
+HyperCPU is brought to you by:
* [HyperWin](https://github.com/HyperWinX) (2024 - present time) - idea, code, documentation.
-* [Ivan Movchan](https://github.com/ivan-movchan) (2025 - present time) - artwork.
+* [Ivan Movchan](https://github.com/ivan-movchan) (2025 - present time) - artwork, beta testing, sample programs.
+
+### License
+
+HyperCPU is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
-## License
+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 General Public License for more details.
-HyperCPU is a free software licensed under [GNU General Public License 3.0](LICENSE).
+You should have received a copy of the GNU General Public License
+along with this program. If not, see .
diff --git a/ROADMAP.md b/ROADMAP.md
index 6e096d88..d5b70027 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,21 +1,22 @@
# HyperCPU Roadmap
-**Current goal: release 1.0**.
+This document describes the roadmap of the project (some kind of TODO-list).
-- [ ] Review whole documentation
-- [ ] Improve test coverage
-- [x] Implement emulator entry point
-- [x] Implement low-latency console I/O mechanism for emulator (using ports)
-- [x] Solve not-yet-defined label references
+### *Release 1.0*
+- [ ] Review the whole documentation.
+- [ ] Improve test coverage.
+- [x] Implement emulator entry point.
+- [x] Implement low-latency console I/O mechanism for emulator (using ports).
+- [x] Solve not-yet-defined label references.
### Release 1.1
-- [ ] Add comparison instruction, conditional call/jmp
-- [ ] Add build system functionality to the assembler, implement build configurations
-- [ ] Write proper benchmarks
+- [ ] Add comparison instruction, conditional `CALL`/`JMP`.
+- [ ] Add build system functionality to hASM (assembler), implement build configurations.
+- [ ] Write proper benchmarks.
### Release 1.2
-- [ ] Implement ncurses-based UI and standard to communicate with it
+- [ ] Implement `ncurses`-based UI and standard to communicate with it.
### Release 2.0
-- [ ] Implement linking functionality
+- [ ] Implement linking functionality.
diff --git a/examples/hello_world.s b/examples/hello_world.s
index acee77d2..85d119e2 100644
--- a/examples/hello_world.s
+++ b/examples/hello_world.s
@@ -1,3 +1,12 @@
+/*
+
+This is a simple "Hello World" program written in HyperCPU assembly (hASM).
+It writes a string to the console char by char, then writes a newline byte (0x10) and does CPU halt.
+
+Copyrignt (c) 2025 Ivan Movchan
+
+*/
+
main:
write xlll0, 'H';
write xlll0, 'e';
@@ -13,4 +22,4 @@ main:
write xlll0, 'd';
write xlll0, '!';
write xlll0, 0u10;
- halt;
\ No newline at end of file
+ halt;
diff --git a/images/screenshot.png b/images/screenshot.png
index 0af2b7d8..61bb37d0 100644
Binary files a/images/screenshot.png and b/images/screenshot.png differ
-## What is it?
+HyperCPU is a set of programs created to work with my own simple ISA (instruction set architecture). The project was created for fun, but it took a lot of time (and nerves) and I learned a lot while working on it.
-HyperCPU is a set of programs, created to work with my own simple ISA (instruction set architecture). The project was created for fun, but it took a lot of time (and nerves), and I learned a lot while working on it.
-
-HyperCPU toolkit includes:
+HyperCPU project includes:
* **hCPU emulator**;
* **hASM assembler**;
-* **hASM disassembler**.
+* ~~**hASM disassembler**~~ (planned).
+
+The project roadmap can be found [here](ROADMAP.md).
+
+### Installation
>[!WARNING]
-> HyperCPU supports Linux systems only. Do not even try to build it under Windows.
+> HyperCPU supports 64-bit GNU/Linux systems only. It is known to be successfully built and running on `amd64` and `aarch64` architectures.
+
+#### Dependencies
+
+* `gcc >= 14` or `clang >= 19`;
+* `cmake >= 3.28`;
+* `make`;
+* `ninja`;
+* `re2`;
+* `fmt`;
+* `googletest` (required for building tests in Release profile);
+* `python3`, `python3-pip`, `python3-sphinx`, `python3-sphinx-rtd-theme` (required for building a documentation).
+
+#### Build instructions
+
+```bash
+$ git clone https://github.com/HyperWinX/HyperCPU --recursive
+$ cd HyperCPU
+$ cmake -S . -B build -G "Ninja" -DCMAKE_BUILD_TYPE=Release
+$ ninja -C build default -j$(nproc)
+$ cd docs
+$ make html
+```
+
+`cmake` build options (use `-D` flag to define them):
+
+* `CMAKE_BUILD_TYPE:STRING` - project build profile (`Release` or `Debug`), mandatory to be specified;
+* `HCPU_SANITIZERS_ENABLED:BOOL` - HyperCPU sanitizers, enabled by default (use `-DHCPU_SANITIZERS_ENABLED:BOOL=OFF` to disable).
+
+The compiled binaries should be located in `build` directory. The generated documentation should be located in `docs/_build/html` directory. After building the project open `index.html` file and start reading the documentation.
+
+Do not forget to check out [examples](examples) folder for interesting code examples that will help you better understand the syntax of hASM and the power of HyperCPU.
+
+### Usage
+
+#### `hcasm` (hASM assembler)
+
+To compile a program to a binary file:
+
+```bash
+$ ./hcasm -o