The hyper toolkit for custom hyper ISA.

Important

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.

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 project includes:

• hCPU emulator;
• hASM assembler;
• hASM disassembler (planned).

The project roadmap can be found here.

Installation

Warning

HyperCPU supports 64-bit GNU/Linux systems only. It is known to be successfully built and running on amd64 and aarch64 architectures.

Dependencies

• gcc >= 12 or clang >= 14;
• cmake >= 3.25;
• 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

$ git clone https://github.com/HyperWinX/HyperCPU --recursive
$ cd HyperCPU
$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
$ make -C build default -j$(nproc)

cmake build options (use -D flag to define them):

• CMAKE_BUILD_TYPE:STRING - project build profile (Release, RelWithDebInfo or Debug), mandatory to be specified;

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 folder for interesting code examples that will help you better understand the syntax of hASM and the power of HyperCPU.

Advanced building

HyperCPU build system supports multiple flags to customize the building process. For example:

• HCPU_COMPILER:STRING - allows to select compiler. Possible modes:
  • auto - don't do anything. Use CMake autodetection or passed compiler paths.
  • clang - searches for clang and clang++ binaries. Supports hinting, so, for example, if clang binary is called clang-19, you can pass: -DHCPU_COMPILER=clang -DCMAKE_C_COMPILER=clang-19.
  • gcc - searches for gcc and g++ binaries. Be careful, in some environments Clang can do gcc -> clang symlinks. You can hint the binary name the same was as with clang mode: -DHCPU_COMPILER=gcc -DCMAKE_C_COMPILER=gcc-14.
• HCPU_LTO:BOOL - enable building with LTO. If Clang is used, searches for LLD. If LLD is found, LTO will be enabled, otherwise LTO will be unavailable. In case of GCC there are no dependencies.
• HCPU_MARCH_NATIVE:BOOL - use -march=native flag.
• HCPU_SANITIZERS:BOOL - set to OFF if you want to disable ASan and LSan, otherwise it will be enabled.

Usage

hcasm (hASM assembler)

To compile a program to a binary file:

$ ./hcasm -o <target> <source>

To compile a program to an object file:

$ ./hcasm -c <target> <source>

To do things with a different verbosity level (debug, info, warning, error):

$ ./hcasm -v <verbosity_level> ...

To display help message and exit:

$ ./hcasm -h # = ./hcasm --help

To display program version and exit:

$ ./hcasm --version

hcemul (hCPU emulator)

To run a binary:

$ ./hcasm <target>

To do things with a different verbosity level (debug, info, warning, error):

$ ./hcemul -v <verbosity_level> ...

To display help message and exit:

$ ./hcemul -h # = ./hcemul --help

To display program version and exit:

$ ./hcemul --version

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.

See how you can contribute in CONTRIBUTION.MD.

Thank you for your interest in HyperCPU.

Authors

HyperCPU is brought to you by:

• HyperWin (2024 - present time) - idea, code, documentation.
• 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.

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.

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