Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adicionando Capa ao REAME.md #15

Merged
merged 10 commits into from
Feb 12, 2024
Merged

Adicionando Capa ao REAME.md #15

Changes from 5 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f8fb7c1
Mudando README.md
ISS2718 Feb 8, 2024
0eec0fc
Readme Update
ISS2718 Feb 8, 2024
0596beb
Update README.md
ISS2718 Feb 8, 2024
a3d9270
Melhorando
ISS2718 Feb 8, 2024
5d8269b
emojis
ISS2718 Feb 8, 2024
41fd7a7
Starting the documentation
ISS2718 Feb 11, 2024
82541e1
Documentation Image
ISS2718 Feb 11, 2024
4e58c77
Revert "Documentation Image"
ISS2718 Feb 11, 2024
ead76a3
Covers
ISS2718 Feb 11, 2024
98f9964
Fixing the link's
ISS2718 Feb 11, 2024
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
148 changes: 71 additions & 77 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,77 +1,71 @@
# GO ICMC Simulator
This program is a simulator for the ICMC architecture (defined [here](https://github.com/simoesusp/Processador-ICMC/)), it has many upgraded functionalities in comparision with the c++ simulator, namely:
- A resizable window and fullscreen cabability;
- An instruction scroll to view all instructions and data being modified in real time;
- Ability to edit the stack pointer and program counter directly;
- Better error handling: the simulator will stop and point the error to the programmer instead of carrying on;
- Better parsing of MIF files, relying only in it's syntax definition and showing line, collumn pairs and cause if errors are found;
- Capability to change character mapping MIF during runtime (without reseting);
- Shortcuts that do not rely on keys that may not be present in a laptop keyboard (for instance insert, home and end keys);
- Support for windows, macOS and linux;

# Installation
If you don't want to compile anything, go to the [releases page](https://github.com/lucasgpulcinelli/goICMCsim/releases) and download a precompiled binary for your system.

# Usage
The first thing you will want to do is add a program to run and test it. This can be done by either specifing MIF files in the ICMC architecture format in the command line or by using the file -\> open code/char MIF menu. Remember to always specify a char MIF, otherwise the code's outchars will always output blank characters!

# How to Compile from the Source Code
First, install a recent version of go (at least 1.13), either from your package manager or from [here](https://go.dev/doc/install). After that, you will also need git and a C compiler (on windows, you need to use MinGW).

On debian/ubuntu based systems, you will need to install `libgl1-mesa-dev xorg-dev`;
On fedora and red hat based systems, you will need to install `libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel mesa-libGL-devel libXi-devel libXxf86vm-devel`;

Then, Just use `go build .` to compile and `./goICMCsim` to start an empty processor. You can see the command line options with `--help`.

If you don't want to clone the repository and just want to compile and install it directly into $GOPATH/bin, just use `go install github.com/lucasgpulcinelli/goICMCsim@latest` (you will still need the tools listed before).

# How to add/modify instructions in the simulator
First, you will need to choose an opcode for your instruction, then add it in the constants list at [processor/Instruction.go](processor/Instruction.go).
After that, right below in the same file, you will need to add your instruction data to the AllInstructions list, for it to be actually found and executed by the simulator.

You will need to add four informations:
- the opcode you just created,
- an instruction to generate it's mnemonic string (if your instruction receives a list of registers, just use genRegM as most instructions, or create a function yourself and add it there),
- the instruction size in 16 bit words,
- and a function to execute it.

To make the execution function, you will need a function that takes the processor context and returns an error (usually nil, to indicate everything went right).

## An instruction example
Let's create a new instruction, called `incmod`, that takes a register and adds 1 to it, but if it becomes greater than or equal to another register, it wraps around in the same way a mod would. Basically, `incmod rx, ry` is equal to `rx = (rx+1) % ry`.
This instruction is going to have opcode 0b111111, plus three bits for the first register, and three more for the second, resulting in 0b111111xxxyyydddd (where x is the first bits for the first register, y is for the second, and d is a don't care value, meaning an unused 0 or 1).

The entry in AllInstructions will be `{OpINCMOD, genRegM("incmod", 2), 1, execINCMOD},`, where OpINCMOD is defined above in the constant block as `OpINCMOD = 0b111111`. `genRegM` is used with those arguments to define the mnemonic and to say that it has two register opcodes in the usual position. 1 is to say that a single word is necessary to encode the instruction. execINCMOD is defined as follows:

```golang
func execINCMOD(pr *ICMCProcessor) error {
// get the instruction binary data
inst := pr.Data[pr.PC]

// remember, those are indices from 0-7, not the actual values
rx_index := getRegAt(inst, 7) // 7 is the first bit from right to left encoding the register index for rx
ry_index := getRegAt(inst, 4) // same for ry

// set the value in rx to the result of our operation
pr.GPRRegs[rx_index] = (pr.GPRRegs[rx_index] + 1) % pr.GPRRegs[ry_index]

// no errors happend
return nil
}
```

# What you can do to help the GO ICMC Simulator's development
An open source project is never complete. Please help the project by submitting issues and pull requests! They will be happly accepted if they help the overall project. Some examples of what can be done:
- Fully complete the MIF syntax parsing in the MIF package and official quartus documentation.
- Increase processor speed by changing processor.fetchInstruction, for now the instruction fetching based on opcodes is the main bottleneck for performace.
- Create a default "hello world" MIF code and character set and use it if the user did not pass any files themselves. To do that take a look at [the embed package](https://pkg.go.dev/embed).
- Add a right click options menu for each instruction in the list to edit memory in place or add breakpoints. This is possible using a new type and go struct inheritance in the instructionList and some remodeling in processor.RunUntilHalt.
- Documentation of instruction execution and mnemonic generation.

# Contributors
The main contributors to the project are listes here:
- Lucas Eduardo Gulka Pulcinelli ([github](https://github.com/lucasgpulcinelli))

Special thanks to:
- Artur Brenner Weber ([github](https://github.com/ArturWeber)), for providing macOS/arm64 builds and helping with documentation
- Daniel Contente Romanzini ([github](https://github.com/Dauboau)), for providing macOS/amd64 builds
# GO ICMC Simulator 🖥️

![GO ICMC Simulator](https://github.com/lucasgpulcinelli/goICMCsim/assets/11618151/da81d732-5cb4-4f41-9128-37ae864ceac9)
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pera, você poderia me explicar isso? Eu entendi que esse é o link para a imagem, mas como isso foi gerado, e onde esse asset foi definido? Tem documentação sobre para eu dar uma olhada? Gostei bastante

Copy link
Collaborator Author

@ISS2718 ISS2718 Feb 9, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Acho q é uma "bugfeature" do GitHub KKKKKK
Aqui nas issues vc consegue fazer upload de imagem e pra isso ele faz upload dessa imagem. Só que como usa markdown aqui tbm ele coloca o link da imagem que foi feito upload e aí eu copiei e usei esse link.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

goICMCsim_08_T

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Outra versão da capa.
Mas devem existir outras formas de fazer isso tbm. Porque no repositório tem como definir uma imagem de Social Preview. Inclusive essas imagens já estão na resolução correta pra ser usadas tbm se vc quiser.


<p align="center">
<img src="https://img.shields.io/github/go-mod/go-version/lucasgpulcinelli/goICMCsim?logo=go"/>
<a href="https://github.com/lucasgpulcinelli/goICMCsim/issues?q=is%3Aopen+is%3Aissue+label%3Afeature-request+sort%3Areactions-%2B1-desc">
<img src="https://img.shields.io/github/issues/lucasgpulcinelli/goICMCsim/feature-request.svg">
</a>
<a href="https://github.com/lucasgpulcinelli/goICMCsim/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3Abug">
<img src="https://img.shields.io/github/issues/lucasgpulcinelli/goICMCsim/bug.svg">
</a>
<a href="https://github.com/lucasgpulcinelli/goICMCsim/releases">
<img src="https://img.shields.io/github/v/release/lucasgpulcinelli/goICMCsim"/>
</a>
<img src="https://img.shields.io/github/license/lucasgpulcinelli/goICMCsim"/>
</p>

## Overview 📝
This program is a simulator for the ICMC architecture (defined [here](https://github.com/simoesusp/Processador-ICMC/)). It features several upgraded functionalities compared to the C++ simulator, including:

- A resizable window and fullscreen capability.
- An instruction scroll to view all instructions and data being modified in real-time.
- Ability to edit the stack pointer and program counter directly.
- Enhanced error handling: the simulator will halt and indicate errors to the programmer.
- Improved parsing of MIF files, adhering strictly to syntax definition and providing detailed error messages.
- Capability to change character mapping MIF during runtime (without resetting).
- Shortcuts that do not rely on keys that may not be present on laptop keyboards (e.g., insert, home, and end keys).
- Support for Windows, macOS, and Linux.

## Installation 💻
If you prefer not to compile anything, you can download a precompiled binary for your system from the [releases page](https://github.com/lucasgpulcinelli/goICMCsim/releases).

## Usage 🚀
To get started, add a program to run and test it. You can specify MIF files in the ICMC architecture format in the command line or use the file -> open code/char MIF menu. Always specify a char MIF to ensure proper output of characters.

## How to Compile from Source Code 🛠️
1. Install a recent version of Go (at least 1.13) from [here](https://go.dev/doc/install).
2. Install Git and a C compiler (on Windows, use MinGW).
3. On Debian/Ubuntu-based systems, install `libgl1-mesa-dev xorg-dev`; on Fedora and Red Hat-based systems, install `libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel mesa-libGL-devel libXi-devel libXxf86vm-devel`.
4. Clone the repository and navigate to the project directory.
5. Run `go build .` to compile and `./goICMCsim` to start an empty processor. Use `--help` to see command line options.
6. Optionally, you can install directly into `$GOPATH/bin` with `go install github.com/lucasgpulcinelli/goICMCsim@latest`.

## How to Add/Modify Instructions in the Simulator ⚙️
To add or modify instructions:
1. Choose an opcode for your instruction.
2. Add it to the constants list in `processor/Instruction.go`.
3. Add your instruction data to the `AllInstructions` list in the same file, including the opcode, mnemonic string, instruction size, and execution function.
4. Implement the execution function. See the example in the documentation for details.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Essa documentação está em algum lugar? Eu gosto da ideia de deixar bem explicadinho esses passos para criar uma nova instrução porque é algo que será necessário conforme o processador se tornar mais complexo com o passar do tempo.

Copy link
Collaborator Author

@ISS2718 ISS2718 Feb 9, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ainda não tem a Documentação eu não sei onde colocar o arquivo pra ser sincero. Mas dá pra fazer uma mais simples com o exemplo que você usou no README atual.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How to add/modify instructions in the simulator

  1. Choose an opcode for your instruction.
  2. Add it to the constants list at processor/Instruction.go.
  3. Right below, in the same file, add your instruction data to the AllInstructions list so it can be found and executed by the simulator.
  4. You will need to add four pieces of information:
    • The opcode you just created.
    • An instruction to generate its mnemonic string (if your instruction receives a list of registers, just use genRegM as most instructions, or create a function yourself and add it there).
    • The instruction size in 16-bit words.
    • And a function to execute it.
  5. To make the execution function, you will need a function that takes the processor context and returns an error (usually nil, to indicate everything went right).

An instruction example

Let's create a new instruction, called incmod, that takes a register and adds 1 to it, but if it becomes greater than or equal to another register, it wraps around in the same way a mod would. Basically, incmod rx, ry is equal to rx = (rx+1) % ry.
This instruction is going to have opcode 0b111111, plus three bits for the first register, and three more for the second, resulting in 0b111111xxxyyydddd (where x is the first bits for the first register, y is for the second, and d is a don't care value, meaning an unused 0 or 1).

The entry in AllInstructions will be {OpINCMOD, genRegM("incmod", 2), 1, execINCMOD},, where OpINCMOD is defined above in the constant block as OpINCMOD = 0b111111. genRegM is used with those arguments to define the mnemonic and to say that it has two register opcodes in the usual position. 1 is to say that a single word is necessary to encode the instruction. execINCMOD is defined as follows:

func execINCMOD(pr *ICMCProcessor) error {
    // get the instruction binary data
    inst := pr.Data[pr.PC]

    // remember, those are indices from 0-7, not the actual values
    rx_index := getRegAt(inst, 7) // 7 is the first bit from right to left encoding the register index for rx
    ry_index := getRegAt(inst, 4) // same for ry

    // set the value in rx to the result of our operation
    pr.GPRRegs[rx_index] = (pr.GPRRegs[rx_index] + 1) % pr.GPRRegs[ry_index]

    // no errors happend
    return nil
}

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A gente cria um arquivo pra servir de documentação e coloca essa parte de adicionar uma instrução lá. E vai melhorando essa documentação com o tempo.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

O que eu vi em repositórios grandes é q eles tem um repositório só pra documentação. Acho q é pra quando alguém clonar não clonar a documentação junto.


## Contributing 🤝
An open-source project is never complete. You can contribute by:

- [Submitting bugs and feature requests](https://github.com/lucasgpulcinelli/goICMCsim/issues).
- Reviewing [source code changes](https://github.com/lucasgpulcinelli/goICMCsim/pulls).
- [Testing on macOS](https://github.com/lucasgpulcinelli/goICMCsim/labels/macOS%20test) and helping maintain compatibility on all platforms.

If you're interested in solving problems and contributing directly to the codebase, check out the [issue page](https://github.com/lucasgpulcinelli/goICMCsim/issues) and look for [good first issues](https://github.com/lucasgpulcinelli/goICMCsim/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).

## Contributors ✨

### Main contributors to the project:

- [Lucas Eduardo Gulka Pulcinelli](https://github.com/lucasgpulcinelli)
- [Isaac Santos Soares](https://github.com/iss2718)

### Special thanks to:

- [Artur Brenner Weber](https://github.com/ArturWeber) for providing macOS/arm64 builds and assisting with documentation.
- [Daniel Contente Romanzini](https://github.com/Dauboau) for providing macOS/amd64 builds.