Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
241 changes: 147 additions & 94 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,94 +1,147 @@
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="git/logo_dark.png">
<source media="(prefers-color-scheme: light)" srcset="git/logo.png">
<img alt="yes" src="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
</picture>
</div>

<h4 align="center">Toolkit for custom ISA</h4>

<p align="center">
<a href="https://github.com/HyperWinX/HyperCPU/issues">
<img src="https://img.shields.io/github/issues/HyperWinX/HyperCPU"
alt="GitHub opened issues">
<img src="https://img.shields.io/badge/version-0.2.1-red"
alt="Version">
<img src="https://img.shields.io/github/actions/workflow/status/HyperWinX/HyperCPU/testing.yml?branch=dev"
alt="CI status">
<img src="https://img.shields.io/badge/status-in_development-red"
alt="Status">
<img src="https://img.shields.io/github/license/HyperWinX/HyperCPU"
alt="License">
<img src="https://img.shields.io/github/stars/HyperWinX/HyperCPU?color=lime"
alt="Stars">
</p>

<table>
<tr>
<td>

HyperCPU is a set of programs, created to work with my own simple ISA.
Project was created for fun, but took a lot of time, and i learned a lot in process.

</td>
</tr>
</table>

>[!IMPORTANT]
> Project is almost ready to be used. Wait for 1.0 release to try it out, or build it locally, test and report found issues.

Tools include:
- **hCPU emulator**
- **hASM assembler**
- **hASM disassembler**

### Roadmap
You can find roadmap [here](roadmap.md).

## Building guide
>[!WARNING]
> Project requires compiler with C++23 support. CLang 19 and GCC 14 satisfy that requirement.
### Dependencies
HyperCPU project has some external dependencies, like:
- re2
- libfmt
- googletest (optional, required for building tests on Release profile)

To install them, use the following listing:

APT-based distros:
```
sudo apt install libre2-dev libfmt-dev libgtest-dev googletest
```

Pacman-based distros:
```
sudo pacman -S re2 fmt gtest
```

Portage-based distros:
```
sudo emerge re2 libfmt gtest
```

### Building project
```
git clone https://github.com/HyperWinX/HyperCPU --recursive && cd HyperCPU
cmake -S. -Bbuild -G "Ninja" -DCMAKE_BUILD_TYPE=Release
ninja -C build default -j8
```

That's all, all tools are built.

### Configuring CMake
Available options:
- CMAKE_BUILD_TYPE:STRING - should be always specified. Release and Debug builds are available.
- HCPU_SANITIZERS_ENABLED:BOOL - sanitizers are always enabled even in Release build. Use -DHCPU_SANITIZERS_ENABLED:BOOL=OFF to disable them.

### Building documentation
Building documentation requires sphinx installed. After you installed sphinx, go to docs directory and do:
```
make html
```
After that, you will get output in docs/_build/html directory. Open index.html to get started.
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="images/logo_dark.png">
<source media="(prefers-color-scheme: light)" srcset="images/logo.png">
<img alt="HyperCPU" src="images/logo.png">
</picture>
</div>

<h4 align="center">HyperCPU - the <i>hyper</i> toolkit for custom <i>hyper</i> ISA</h4>

<p align="center">
<a href="#what-is-it">What is it?</a>

Check notice on line 12 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L12

Column: 1

Check notice on line 12 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L12

Element: a
|

Check notice on line 13 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L13

Column: 1
<a href="#roadmap">Roadmap</a>

Check notice on line 14 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L14

Column: 1

Check notice on line 14 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L14

Element: a
|
<a href="#installation">Installation</a>

Check notice on line 16 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L16

Column: 1

Check notice on line 16 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L16

Element: a
|
<a href="#usage">Usage</a>

Check notice on line 18 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L18

Column: 1

Check notice on line 18 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L18

Element: a
|
<a href="#contributing">Contributing</a>

Check notice on line 20 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L20

Column: 1

Check notice on line 20 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L20

Element: a
|
<a href="#authors">Authors</a>

Check notice on line 22 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L22

Column: 1

Check notice on line 22 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L22

Element: a
|
<a href="#license">License</a>

Check notice on line 24 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L24

Column: 1

Check notice on line 24 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L24

Element: a
</p>

<p align="center">
<a href="https://github.com/HyperWinX/HyperCPU/issues">
<img src="https://img.shields.io/github/issues/HyperWinX/HyperCPU"
alt="GitHub opened issues"></a>
<img src="https://img.shields.io/badge/version-0.2.0-red"

Check notice on line 31 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L31

Element: img
alt="Version">
<img src="https://img.shields.io/github/actions/workflow/status/HyperWinX/HyperCPU/testing.yml?branch=dev"
alt="CI status">
<img src="https://img.shields.io/badge/status-in_development-red"
alt="Status">
<img src="https://img.shields.io/github/license/HyperWinX/HyperCPU"
alt="License">
<img src="https://img.shields.io/github/stars/HyperWinX/HyperCPU?color=lime"
alt="Stars">
</p>

>[!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.

<img alt="HyperCPU screenshot" src="images/screenshot.png">

Check notice on line 46 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L46

Element: img

## 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 toolkit includes:
* **hCPU emulator**;

Check notice on line 53 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L53

Lists should be surrounded by blank lines
* **hASM assembler**;
* **hASM disassembler**.

>[!WARNING]
> HyperCPU supports Linux systems only. Do not even try to build it under Windows.

## Roadmap

You can find the project roadmap [here](ROADMAP.md).

## Installation

At the moment of writing this text, HyperCPU installation is done by building the whole project from source codes. Maybe one day HyperCPU will start distributing release tarballs for much easier installation, but who knows.

### Building from source codes

HyperCPU requires these tools and libraries:

* C++ compiler with C++23 standard support (i. e. `gcc` >= `14`);
* `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.

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;

Check notice on line 81 in README.md

View check run for this annotation

Codacy Production / Codacy Static Code Analysis

README.md#L81

Lists should be surrounded by blank lines
* `HCPU_SANITIZERS_ENABLED`:`BOOL` - HyperCPU sanitizers (enabled by default); use `-DHCPU_SANITIZERS_ENABLED:BOOL=OFF` to disable them.

After installing dependencies, open the terminal and run these commands:

```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)
```

That's all. The compiled binaries should be located in `build` directory.

Run `cd docs && make html` to build a documentation. After that go to `docs/_build/html` directory, open `index.html` and start reading.

## Usage

```
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"]
```

## 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.

>[!IMPORTANT]
>Please send your pull requests to `dev` repository branch (not `master`).

Thank you for your interest in HyperCPU.

## Authors

* [HyperWin](https://github.com/HyperWinX) (2024 - present time) - idea, code, documentation.
* [Ivan Movchan](https://github.com/ivan-movchan) (2025 - present time) - artwork.

## License

HyperCPU is a free software licensed under [GNU General Public License 3.0](LICENSE).
File renamed without changes.
16 changes: 16 additions & 0 deletions examples/hello_world.s
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
main:
write xlll0, 'H';
write xlll0, 'e';
write xlll0, 'l';
write xlll0, 'l';
write xlll0, 'o';
write xlll0, ',';
write xlll0, ' ';
write xlll0, 'w';
write xlll0, 'o';
write xlll0, 'r';
write xlll0, 'l';
write xlll0, 'd';
write xlll0, '!';
write xlll0, 0u10;
halt;
File renamed without changes
File renamed without changes
Binary file added images/screenshot.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading