Merge branch 'release/1.1.0'

Update README and made it international (en_US and fr_FR)
Added some config for Doxygen but not generated documentation
(need more configuration)

README.md

@@ -1,100 +1,145 @@
-# Projet VM pour le cours d'Architecture des ordinateurs
+# mini-MIPS Project
 
-## Description
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/lbf38/mini-MIPS-project?style=plastic)](https://github.com/lbf38/mini-MIPS-project/releases/latest)
 
-Projet concernant le cours d'Architecture des ordinateurs de l'ENSTA Bretagne.
-Création d'une Machine Virtuelle pour comprendre le fonctionnement des ordinateurs et leur architecture interne.
-Création d'un assembleur en python pour convertir des instructions rédigées en assembleur, en un fichier binaire à exécuter sur la VM.
+**README available in the following languages :**
 
-## Liste des instructions disponibles
+[![English documentation (en_US)](https://img.shields.io/badge/-en__US-blueviolet)](README.md)
+[![French documentation (fr_FR)](https://img.shields.io/badge/-fr__FR-blueviolet)](README_fr_FR.md)
 
-Lien vers le fichier qui contient l'ensemble des instructions disponibles dans la VM et reconnu par l'Assembleur :
-[Instructions](instructions.md)
+## Table of contents
 
-## Comment utiliser le projet
+- [mini-MIPS Project](#mini-mips-project)
+  - [Table of contents](#table-of-contents)
+  - [Short explanation of this project](#short-explanation-of-this-project)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Assembleur](#assembleur)
+    - [Virtual Machine](#virtual-machine)
+  - [Demonstration](#demonstration)
+  - [A list of simple examples](#a-list-of-simple-examples)
+  - [Ideas](#ideas)
+  - [Ressources](#ressources)
+  - [Credits](#credits)
+
+*****
+
+## Short explanation of this project
+
+This project is an academic project during the second year of study at ENSTA Bretagne (Brest, France).
+
+It aims to reproduce a simple version of the MIPS architecture (therefore the name "mini-MIPS") in order to understand the functioning of a computer and its internal architecture.
+
+It is composed of a virtual machine (VM) and an assembler.
+The first one is written in C and the second one in Python.
+
+## Installation
+
+1. To install the project, please clone this repository in a Linux environnement. You can use the following command :
+
+    ```bash
+    git clone https://github.com/LBF38/mini-MIPS-project.git
+    ```
+
+2. Then, you can go to the corresponding folder in your terminal and use the following command to compile the VM :
+
+    ```bash
+    make
+    ```
+
+3. You can now use the VM and the assembler.
+
+## Usage
 
 ### Assembleur
 
-Pour lancer l'assembleur, utiliser le format :
+To launch the assembler, use the format :
 
 ```bash
-./src/assembleur.py [dossier/source.txt] [dossier/destination.bin]
+./src/assembleur.py [folder/source.txt] [folder/destination.bin]
 ```
 
-Exemple :
+>**Note:** This command is executed in the project folder, for example under Linux : `~/mini-MIPS-project$`
+
+Example :
 
 ```bash
 ./src/assembleur.py data/asm.txt bin/asm.bin
 ```
 
-> Si vous ne mettez pas le nom du fichier de destination, par défaut l'assembleur écrira dans `bin/[nom source].bin`
+> If you don't specify the name of the destination file, by default the assembler will write in `bin/[source name].bin`
 
-### VM
+### Virtual Machine
 
-Pour lancer la VM, utiliser le format :
+To launch the VM, use the format :
 
 ```bash
 ./bin/vm bin/[source].bin
 ```
 
-Exemple :
+Example :
 
 ```bash
 ./bin/vm bin/asm.bin
 ```
 
-> Note: Vous pouvez compiler les fichiers de la VM (qui est en C) avec le makefile en utilisant `make`
-
-### Remarques
-
-Ces commandes sont exécutés dans le dossier du projet soit par exemple sous Linux : `~/projet_VM_archiNum$`
+> **Note:** You can compile the VM files (which is in C) with the makefile using `make`
 
-## Démonstration
+## Demonstration
 
-Pour démontrer l'utilisation de l'assembleur et de la VM, vous pourrez trouver des exemples de codes en assembleur dans le dossier `data/`.
+To demonstrate the use of the assembler and the VM, you can find some examples of assembly code in the `data/` folder.
 
-Ces fichiers respectent la sémantique choisie pour les instructions de base de la VM. Vous pouvez la retrouver dans le fichier [instructions.md](instructions.md).
+This files respect the semantic chosen for the basic instructions of the VM. You can find it in the file [instructions.md](docs/en_US/instructions.md).
 
-### Liste des fichiers d'exemples
+## A list of simple examples
 
 Je vais vous présenter les fichiers d'exemples que vous pouvez trouver dans le dossier `data/`, en vous donnant une courte explication de leur fonctionnement.
 
-- `asm.txt` : Ce fichier contient un exemple de code en assembleur. Il est utilisé pour démontrer l'utilisation de l'assembleur. Il permet de tester les commentaires, les instructions de base, les labels et les lignes vides.
-- `affiche12.txt` : Ce fichier contient un exemple de code en assembleur pour afficher 12 en effectuant une boucle de 12 itérations.
-- `factorial.txt` : Ce fichier contient un exemple de code en assembleur pour afficher le factoriel d'un nombre. On demande à l'utilisateur une valeur à calculer et on peut ainsi calculer la factorielle associée. On peut demander une valeur entre 0 et 12.
+In this part, I will present the files that you can find in the `data/` folder, giving you a short explanation of their functioning.
 
-> Pour ce programme, le facteur limitant est le stack pointer qui peut être trop faible par rapport à la valeur demandée par l'utilisateur.
-> A voir comment on peut améliorer cela en calculant une valeur de stack pointer plus grande en fonction de la valeur demandée par l'utilisateur et de la mémoire maximale disponible.
+- `asm.txt` : This file contains an example of assembly code. It is used to demonstrate the use of the assembler. It allows to test the comments, the basic instructions, the labels and the empty lines.
+- `affiche12.txt` : This file contains an example of assembly code to display 12 by performing a loop of 12 iterations.
+- `factorial.txt` : This file contains an example of assembly code to display the factorial of a number. The user is asked for a value to calculate and we can thus calculate the associated factorial. We can ask for a value between 0 and 12.
+
+> For this program, the limiting factor is the stack pointer which can be too low compared to the value requested by the user.
+> We can see to improve this by calculating a larger stack pointer value depending on the value requested by the user and the maximum available memory.
 >
-> On est également limité par la représentation des nombres. On ne peut pas dépasser 2^32-1 (4294967295) car on utilise un `uint32_t` pour stocker les nombres.
+> We are also limited by the representation of numbers. We cannot exceed 2^32-1 (4294967295) because we use a `uint32_t` to store the numbers.
+
+- `fibonnaci.txt` : This file contains an example of assembly code to display the Fibonacci sequence. The code will ask the user for a value and the Fibonacci sequence will be calculated depending on this value.
 
-- `fibonnaci.txt` : Ce fichier contient un exemple de code en assembleur pour afficher la suite de Fibonnaci. Le code va demander une valeur à l'utilisateur et la suite de Fibonnaci sera calculée en fonction de cette valeur.
-
-> Pour ce programme, le facteur limitant est le même que celui de `factorial.txt` : la représentation des nombres va conditionner la valeur maximale disponible à calculer et à afficher.
+> For this program, the limiting factor is the same as for `factorial.txt`: the representation of numbers will condition the maximum value available to calculate and display.
 
-- `boucle.txt` : Ce fichier contient un exemple de code en assembleur pour lancer une boucle et afficher son indice.
-- `helloworld.txt` : Ce fichier contient un exemple de code en assembleur pour afficher "Hello World!".
+- `boucle.txt` : This file contains an example of assembly code to launch a loop and display its index.
+- `helloworld.txt` : This file contains an example of assembly code to display "Hello World!".
 
-> Note: `helloworld.txt` ne fonctionne pas pour le moment car les données de type `string` ne sont pas encore reconnues ni traitées par l'assembleur.
+> Note: `helloworld.txt` does not work for the moment because the data of type `string` are not yet recognized or treated by the assembler.
 
-- `instruction_test.txt` : Ce fichier contient l'ensemble des instructions disponibles dans ma sémantique d'asm. Il m'a permis de tester toutes les fonctions une à une et de vérifier leur fonctionnement, lorsque j'avais des problèmes d'implémentation.
+- `instruction_test.txt` : This file contains all the instructions available in my asm semantic. It allowed me to test all the functions one by one and to check their functioning, when I had implementation problems.
 
-> Une meilleure méthode aurait été de faire des tests unitaires directement sur l'assembleur. Je les implémenterais si j'ai le temps. (voir [#10](https://github.com/LBF38/projet_VM_archiNum/issues/10))
+> A better method would have been to make unit tests directly on the assembler. I would implement them if I have the time. (see [#10](https://github.com/LBF38/projet_VM_archiNum/issues/10))
 
-### Autres idées de programme à réaliser
+## Ideas
 
-Vous trouverez ici quelques idées de programmes à réaliser en assembleur pour tester l'assembleur et la VM. Ces idées viennent du cours d'Architecture des ordinateurs de l'ENSTA Bretagne et des idées des professeurs.
+You will find here some ideas of programs to be made in assembly to test the assembler and the VM. These ideas come from the computer architecture course at ENSTA Bretagne and the ideas of the teachers.
 
-- Calcul des points de la droite $y = ax + b$ à partir des paramètres fournis par l'utilisateur.
-- Calcul matriciel, multiplication matricielle.
-- Implémentation de l'Algorithme de Bresenham pour tracer une droite. ([Algorithme de Bresenham](https://fr.wikipedia.org/wiki/Algorithme_de_trac%C3%A9_de_segment_de_Bresenham))
-- Suite de Syracuse. ([Suite de Syracuse](https://fr.wikipedia.org/wiki/Suite_de_Syracuse))
+- Calculate the points of the line $y = ax + b$ from the parameters provided by the user.
+- Matrix calculation, matrix multiplication.
+- Implementation of the Bresenham algorithm to draw a line. ([Bresenham algorithm](https://en.wikipedia.org/wiki/Bresenham%27s_line_algorithm))
+- Syracuse sequence. ([Syracuse sequence](https://en.wikipedia.org/wiki/Collatz_conjecture))
 
 ## Ressources
 
-Lien vers l'article "VM in C" : [Register VM in C](https://en.wikibooks.org/wiki/Creating_a_Virtual_Machine/Register_VM_in_C)
+- Link to the article "VM in C" : [Register VM in C](https://en.wikibooks.org/wiki/Creating_a_Virtual_Machine/Register_VM_in_C)
+- Link to another ressource "LC-3 VM": [LC-3 VM](https://www.jmeiners.com/lc3-vm/index.html)
+- <details>
+  <summary>ASCII Table</summary>
+
+  ![Table ASCII](https://www.asciitable.com/asciifull.gif)
+  </details>
+
+## Credits
 
-Lien vers une autre source "LC-3 VM": [LC-3 VM](https://www.jmeiners.com/lc3-vm/index.html)
+This project was made by [Mathis URIEN (@LBF38)](https://github.com/lbf38), student in Design of Digital Sytems at ENSTA Bretagne.
 
-Table ASCII : \
-![Table ASCII](https://www.asciitable.com/asciifull.gif)
+The course and project was given by ENSTA Bretagne's professors.

README_fr_FR.md

@@ -0,0 +1,142 @@
+# Projet mini-MIPS
+
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/lbf38/mini-MIPS-project?style=plastic)](https://github.com/lbf38/mini-MIPS-project/releases/latest)
+
+**README disponible dans les langues suivantes :**
+
+[![English documentation (en_US)](https://img.shields.io/badge/-en__US-blueviolet)](README.md)
+[![French documentation (fr_FR)](https://img.shields.io/badge/-fr__FR-blueviolet)](README_fr_FR.md)
+
+## Table des matières
+
+- [Projet mini-MIPS](#projet-mini-mips)
+  - [Table des matières](#table-des-matières)
+  - [Courte explication du projet](#courte-explication-du-projet)
+  - [Installation](#installation)
+  - [Utilisation](#utilisation)
+    - [Assembleur](#assembleur)
+    - [Machine Virtuelle](#machine-virtuelle)
+  - [Démonstration](#démonstration)
+  - [Une liste d'exemples simples](#une-liste-dexemples-simples)
+  - [Idées](#idées)
+  - [Ressources](#ressources)
+  - [Crédits](#crédits)
+
+*****
+
+## Courte explication du projet
+
+Ce projet est un projet académique réalisé lors de la deuxième année d'étude à l'ENSTA Bretagne (Brest, France).
+
+Il a pour but de reproduire une version simplifiée de l'architecture MIPS (d'où le nom "mini-MIPS") afin de comprendre le fonctionnement d'un ordinateur et de son architecture interne.
+
+Il est composé d'une machine virtuelle (VM) et d'un assembleur.
+La première est écrite en C et le second en Python.
+
+## Installation
+
+1. Pour installer le projet, veuillez cloner ce dépôt dans un environnement Linux. Vous pouvez utiliser la commande suivante :
+
+    ```bash
+    git clone https://github.com/LBF38/mini-MIPS-project.git
+    ```
+
+2. Ensuite, vous pouvez aller dans le dossier correspondant dans votre terminal et utiliser la commande suivante pour compiler la VM :
+
+    ```bash
+    make
+    ```
+
+3. Vous pouvez maintenant utiliser la VM et l'assembleur.
+
+## Utilisation
+
+### Assembleur
+
+Pour lancer l'assembleur, utilisez le format suivant :
+
+```bash
+./src/assembleur.py [folder/source.txt] [folder/destination.bin]
+```
+
+>**Note:** Cette commande est exécutée dans le dossier du projet, par exemple sous Linux : `~/mini-MIPS-project$`
+
+Exemple :
+
+```bash
+./src/assembleur.py data/asm.txt bin/asm.bin
+```
+
+> Si vous ne spécifiez pas le nom du fichier de destination, l'assembleur écrira par défaut dans le fichier `bin/[nom fichier source].bin`
+
+### Machine Virtuelle
+
+Pour lancer la Machine Virtuelle, utilisez le format suivant :
+
+```bash
+./bin/vm bin/[source].bin
+```
+
+Exemple :
+
+```bash
+./bin/vm bin/asm.bin
+```
+
+> **Note:** Vous pouvez compiler les fichiers de la Machine Virtuelle (qui sont en C) avec le makefile en utilisant `make`
+
+## Démonstration
+
+Pour démontrer l'utilisation de l'assembleur et de la VM, vous pouvez trouver quelques exemples de code assembleur dans le dossier `data/`.
+
+Ces fichiers respectent la sémantique choisie pour les instructions de base de la VM. Vous pouvez la trouver dans le fichier [instructions.md](docs/fr_FR/instructions.md).
+
+## Une liste d'exemples simples
+
+Dans cette partie, je vais vous présenter les fichiers que vous pouvez trouver dans le dossier `data/`, en vous donnant une courte explication de leur fonctionnement.
+
+- `asm.txt` : Ce fichier contient un exemple de code assembleur. Il est utilisé pour démontrer l'utilisation de l'assembleur. Il permet de tester les commentaires, les instructions de base, les labels et les lignes vides.
+- `affiche12.txt` : Ce fichier contient un exemple de code assembleur pour afficher 12 en effectuant une boucle de 12 itérations.
+- `factorial.txt` : Ce fichier contient un exemple de code assembleur pour afficher la factorielle d'un nombre. On demande à l'utilisateur une valeur à calculer et on peut ainsi calculer la factorielle associée. Nous pouvons demander une valeur entre 0 et 12.
+
+> Pour ce programme, le facteur limitant est le pointeur de pile qui peut être trop faible par rapport à la valeur demandée par l'utilisateur.
+> Nous pouvons voir pour améliorer cela en calculant une valeur de stack pointer plus grande en fonction de la valeur demandée par l'utilisateur et de la mémoire maximale disponible.
+>
+> Nous sommes également limités par la représentation des nombres. Nous ne pouvons pas dépasser 2^32-1 (4294967295) car nous utilisons un `uint32_t` pour stocker les nombres.
+
+- `fibonnaci.txt` : Ce fichier contient un exemple de code assembleur pour afficher la séquence de Fibonacci. Le code demandera à l'utilisateur une valeur et la séquence de Fibonacci sera calculée en fonction de cette valeur.
+
+> Pour ce programme, le facteur limitant est le même que pour `factorial.txt` : la représentation des nombres conditionnera la valeur maximale disponible à calculer et à afficher.
+
+- `boucle.txt` : Ce fichier contient un exemple de code assembleur pour lancer une boucle et afficher son index.
+- `helloworld.txt` : Ce fichier contient un exemple de code assembleur pour afficher "Hello World !".
+
+> Note : `helloworld.txt` ne fonctionne pas pour le moment car les données de type `string` ne sont pas encore reconnues ou traitées par l'assembleur.
+
+- `instruction_test.txt` : Ce fichier contient toutes les instructions disponibles dans ma sémantique asm. Il m'a permis de tester toutes les fonctions une par une et de vérifier leur fonctionnement, lorsque j'avais des problèmes d'implémentation.
+
+> Une meilleure méthode aurait été de faire des tests unitaires directement sur l'assembleur. Je les implémenterais si j'ai le temps. (voir [#10](https://github.com/LBF38/projet_VM_archiNum/issues/10))
+
+## Idées
+
+Vous trouverez ici quelques idées de programmes à réaliser en assembleur pour tester l'assembleur et la VM. Ces idées sont issues du cours d'architecture des ordinateurs de l'ENSTA Bretagne et des idées des professeurs.
+
+- Calculer les points de la droite $y = ax + b$ à partir des paramètres fournis par l'utilisateur.
+- Calcul matriciel, multiplication matricielle.
+- Mise en œuvre de l'algorithme de Bresenham pour tracer une droite. ([Algorithme de Bresenham](https://en.wikipedia.org/wiki/Bresenham%27s_line_algorithm))
+- Séquence de Syracuse. ([Séquence de Syracuse](https://en.wikipedia.org/wiki/Collatz_conjecture))
+
+## Ressources
+
+- Lien vers l'article "VM en C" : [Registre VM en C](https://en.wikibooks.org/wiki/Creating_a_Virtual_Machine/Register_VM_in_C)
+- Lien vers une autre ressource "LC-3 VM" : [LC-3 VM](https://www.jmeiners.com/lc3-vm/index.html)
+- <details>
+  <summary>Table ASCII</summary>
+
+  ![Table ASCII](https://www.asciitable.com/asciifull.gif)
+  </details>
+## Crédits
+
+Ce projet a été réalisé par [Mathis URIEN (@LBF38)](https://github.com/lbf38), étudiant en Conception de Systèmes Numériques à l'ENSTA Bretagne.
+
+Le cours et le projet ont été donnés par les professeurs de l'ENSTA Bretagne.