Adicionando Capa ao REAME.md

README.md

@@ -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 Cover](https://github.com/lucasgpulcinelli/goICMCsim/assets/11618151/da81d732-5cb4-4f41-9128-37ae864ceac9)
+
+<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](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](docs/README.md) for details.
+
+## 🤝 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.

docs/AddingModifyingInstructions.md

@@ -0,0 +1,51 @@
+# 📝 Adding/Modifying Instructions
+
+## 🛠️ How to Add/Modify Instructions in the Simulator
+
+To add or modify instructions in the simulator, follow these steps:
+
+1. Choose an opcode for your instruction.
+2. Add it to the constants list at [processor/Instruction.go](processor/Instruction.go).
+3. Below the constants list in the same file, add your instruction data to the `AllInstructions` list. This allows the simulator to find and execute your instruction.
+4. You need to provide four pieces of information:
+    - The opcode you just created.
+    - An instruction to generate its mnemonic string. If your instruction receives a list of registers, use `genRegM` (as most instructions do), or create a custom function and add it there.
+    - The instruction size in 16-bit words.
+    - A function to execute it.
+5. To create the execution function, you need a function that takes the processor context and returns an error (usually `nil` to indicate success).
+
+## 📋 An Instruction Example
+
+Let's create a new instruction called `incmod`. This instruction takes a register and adds 1 to it. If it becomes greater than or equal to another register, it wraps around like a modulo operation. Essentially, `incmod rx, ry` is equivalent to `rx = (rx + 1) % ry`.
+
+### 🔹 Instruction Encoding
+This instruction will have opcode `0b111111`, plus three bits for the first register and three more for the second, resulting in `0b111111xxxyyydddd` (where `x` represents 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`).
+
+### 🔹 Instruction Entry
+The entry in `AllInstructions` will be:
+```golang
+{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 specify that it has two register opcodes in the usual position. `1` indicates that a single word is necessary to encode the instruction.
+
+### 🔹 Execution Function
+The `execINCMOD` function is defined as follows:
+
+```golang
+func execINCMOD(pr *ICMCProcessor) error {
+    // Get the instruction binary data
+    inst := pr.Data[pr.PC]
+
+    // Retrieve register indices (0-7)
+    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 occurred
+    return nil
+}
+```
+
+This function performs the operation described by the `incmod` instruction and returns `nil` to indicate success.

docs/README.md

@@ -0,0 +1,52 @@
+# 🖥️ GO ICMC Simulator Documentation
+
+![GO ICMC Simulator Documentation Cover](https://github.com/lucasgpulcinelli/goICMCsim/assets/11618151/446bacdf-aada-499b-a6f5-0b0bd75afd64)
+
+Welcome to the documentation for the GO ICMC Simulator! This documentation serves as a guide for users and contributors to understand and utilize the features of the simulator effectively.
+
+## 📝 Summary
+
+The GO ICMC Simulator is a program designed to simulate the ICMC architecture, offering upgraded functionalities compared to the C++ simulator.
+
+## 📚 Table of Contents
+1. [🏠 Home](#🖥️-go-icmc-simulator-documentation)
+    * [📝 Summary](#📝-summary)
+    * [📚 Table of Contents](#📚-table-of-contents)
+    * [🤝 Contributing to the Documentation](#🤝-contributing-to-the-documentation)
+        - [⚠️ Keep our docs running smoother than a well-tuned simulator](#⚠️-keep-our-docs-running-smoother-than-a-well-tuned-simulator)
+2. [📝 Adding/Modifying Instructions](AddingModifyingInstructions.md/#📝-addingmodifying-instructions)
+    * [🛠️ How to add/modify instructions in the simulator](AddingModifyingInstructions.md/#🛠️-how-to-addmodify-instructions-in-the-simulator)
+    * [📋 An instruction example](AddingModifyingInstructions.md/#📋-an-instruction-example)
+        - [🔹Instruction Encoding](AddingModifyingInstructions.md/#🔹-instruction-encoding)
+        - [🔹Instruction Entry](AddingModifyingInstructions.md/#🔹-instruction-entry)
+        - [🔹Execution Function](AddingModifyingInstructions.md/#🔹-execution-function)
+## 🤝 Contributing to the Documentation
+
+Just as an open-source project is never complete, neither is its documentation. Here's how you can contribute:
+
+- **Fix Typos or Grammatical Errors**: Spotted a typo or a grammatical mistake? Feel free to correct it! Every little improvement counts.
+
+- **Improve Clarity or Organization**: Found a section that could be explained better? Want to reorganize the content for better flow? Your input is invaluable in making the documentation easier to understand.
+
+- **Add Missing Information or Sections**: Is there something important missing from the documentation? Don't hesitate to add it! Your contributions help make the documentation more comprehensive.
+
+- **Update Outdated Information**: Has something changed since the documentation was last updated? Help keep it current by updating outdated information.
+
+### ⚠️ Keep our docs running smoother than a well-tuned simulator
+
+To ensure that the documentation remains well-structured and easy to navigate, please follow these guidelines:
+
+1. **One Topic Per File**: When adding new documentation content, create a new file for each topic or section. This helps keep the documentation organized and focused.
+
+2. **Update Table of Contents**: After creating a new file or adding a new topic to an existing file, don't forget to update the table of contents in the `README.md` file. This makes it easier for users to find the information they need.
+
+3. **Label Pull Requests**: When creating a pull request for documentation changes, please add the `documentation` label to the pull request. This helps maintainers quickly identify and review documentation-related changes.
+
+Ready to make a difference in the documentation? Awesome! Your contributions are greatly appreciated and help make the GO ICMC Simulator even better. Thanks for being part of the documentation improvement team! 🎉
+
+## ✨ Contributors
+
+### 🏆 Main contributors to the documentation:
+
+- [Lucas Eduardo Gulka Pulcinelli](https://github.com/lucasgpulcinelli)
+- [Isaac Santos Soares](https://github.com/iss2718)