README.md

# mipsivm
The name of the project "mipsivm" is an abbreviation for "MIPS Interpreting Virtual Machine".

## Showcase
* mipsivm runs Hello World
![Showcase Hello World](test/mipsivm_show_helloworld.JPG)

* mipsivm runs CSE3666 Lab 2
![Showcase CSE3666 Lab2](test/mipsivm_show_lab2.JPG)

* mipsivm's Debug-Mode disassembly and Unaligned Memory Access Test-Case.
![Showcase Disasm and Unaligned](test/mipsivm_show_disasm_unaligned.JPG)

## Introduction
The "mipsivm" is a software-based Emulator project aiming to virtualize the minimum MIPS-based machine and efficient virtualized memory. <br>
This project is an interpreting emulator project - providing the accurate emulation.

## Processor Virtualization
To virtualize the processor, we implement the VMCB structure. VMCB is the acronym that stands for Virtual Machine Control Block. A single VMCB will control a single vCPU. The VMCB would include the followings:
- Memory Virtualization settings
- Register File, including GPR and FPU
- Execution Control, controlling the behavior of vCPU

Duly note that mipsivm simulates in `Little-Endian` byte order.

### Glossary of Processor Virtualization
| Acronyms  | Abbreviated for               | Explanation                           |
| --------- | ----------------------------- | ------------------------------------- |
| vCPU      | Virtual CPU                   | The virtual processor                 |
| FPU       | Floating Processing Unit      | Co-processor for floating number      |
| RF        | Register File                 | Storage of Registers                  |
| GPR       | General Purpose Register      | Register of CPU                       |
| VMCB      | Virtual Machine Control Block | Controlling Structure for a vCPU      |
| NPT       | Nested Page Table             | Page Table that translates GPA to HVA |
| MPT       | MIPS Page Table               | Page Table that translates GVA to GPA |

## Memory Virtualization
The memory virtualization is the special feature of the project. This project uses paging as inspired by AMD64 architecture. <br>
The "mipsivm" will implement memory virtualization through paging. Memory access would be translated from GPA to HVA with constant running time complexity. <br>
From AMD64 design, we may translate 32-bit address to 32-bit address through Non-PAE L2P; we may translate 32-bit address to 64-bit address through PAE L3P. Therefore, as a simulator running on Intel x86/AMD64, we have followings:

### L2P Translation
This option is for simulator being compiled as 32-bit code on Intel x86 platform. <br>
The 32-bit GPA is divided into three parts:
- 12-bit Offset: Offset to the page base.
- 10-bit PTE: Index of page table. A single PTE controls 4KiB Memory.
- 10-bit PDE: Index of page directory. A single PDE controls 4MiB Memory.

It is also necessary for simulator to setup a page table. A page table starts with an address to the page-directory. The page directory should be 4KiB sized. <br>
Each PDE is a 4-byte entry. Hence there are 1024 PDEs. For each entry, there are 32 bits. The higher 20 bits indicates the HVA of PTE. The lower 12 bits indicates the property of PDE, including the access control (to be read-only, read-write, executable, no-access, etc.) <br>
Each PTE is a 4-byte entry. The HVA of PTE should be 4KiB-aligned. For each entry, there are 32 bits. The higher 20 bits indicates the HVA of page base. The lower 12-bits indicates the property of PTE, including the access control.

### L3P Translation
This option is for simulator being compiled as 64-bit code on AMD64 platform. <br>
The 32-bit GPA is divided into four parts:
- 12-bit Offset: Offset to the page base.
- 9-bit PTE: Index of page table. A single PTE controls 4KiB Memory.
- 9-bit PDE: Index of page directory. A single PDE controls 2MiB Memory.
- 2-bit PDPTE: Index of page directory pointer table. A single PDPTE controls 1GiB Memory.

The page table starts with an address to the page directory pointer table. It should be 32-byte sized.
Each PDPTE is an 8-byte entry. There are 4 PDPTEs. For each entry, there are 64 bits. The higher 52 bits indicates the HVA of PDE. The lower 12 bits indicates the property of PDPTE, including the access control.
Each PDE is an 8-byte entry. There are 512 PDEs. For each entry, there are 64 bits. The higher 52 bits indicates the HVA of PTE. The lower 12 bits indicates the property of PDE, including the access control.
Each PTE is an 8-byte entry. There are 512 PTEs. For each entry, there are 64 bits. The higher 52 bits indicates the HVA of page base. The lower 12 bits indicates the property of PTE, including the access control.

### Glossary of Memory Virtualization
| Acronyms  | Abbreviated for                       | Explanation                                       |
| --------- | ------------------------------------- | ------------------------------------------------- |
| GPA       | Guest Physical Address                | Address that referenced in simulated MIPS VM      |
| HVA       | Host Virtual Address                  | Address that the Simulator would reference        |
| L2P       | 2-Level Paging                        | 32-bit GPA to 32-bit HVA translation mechanism    |
| L3P       | 3-Level Paging                        | 32-bit GPA to 64-bit HVA translation mechanism    |
| PTE       | Page-Table Entry                      | The first level of address-translation            |
| PDE       | Page-Directory Entry                  | The second level of address-translation           |
| PDPTE     | Page-Directory Pointer Table Entry    | The third level of address-translation            |
| XTLB      | Execution Translate Lookaside Buffer  | TLB that accelerates instruction fetching         |
| DTLB      | Data Translate Lookaside Buffer       | TLB that accelerates data reading/writing         |

## FAQ
Following lists the frequently asked questions, and corresponding answers.

### Why did I create this project?
In my sophomore year, I took the CSE3666 course - Introduction to Computer Architecture. In the final month of the semester, there is an emulator project - emulate an MIPS machine. The emulator skeleton is in either python or java implemention. I considered the implementation is not quite efficient. So this project is given birth by me - implement the emulator in an efficient interpreting method.

### Is there a well-known open-source MIPS emulator project?
Yes, there is. The famous PCSX2 is a free and open-source PlayStation 2 (PS2) emulator project. The processor inside the PS2 is based on MIPS Architecture.

### What big difference does this project make in comparison to CSE3666 assignment?
- There is access-controlled memory-virtualization feature.
- There is a simple implementation of TLB for instruction fetching.
- This project is written in C programming language.
- This software is implemented by inspirations from AMD64 architecture.
- This project aims to support more instructions.
- This project is designed to support multiple presets for simulation. With different preset, mipsivm may support multi-processing system.

## Build
If it is your first time to build mipsivm, you will have to execute `build_prep.bat` script file to prepare for compilation prior to execute any build scripts. <br>
Currently, mipsivm supports 64-bit Windows.

### Windows
To build mipsivm for Windows, you will need to download [Enterprise Windows Driver Kit 10](https://docs.microsoft.com/en-us/legal/windows/hardware/enterprise-wdk-license-2019) and mount it to T disk. I recommend using [WinCDEmu](https://wincdemu.sysprogs.org/download/) to mount ISO image. Make sure you downloaded EWDK 10 version 2004 with Visual Studio Tools 16.7. <br>
Execute `compchk_win10x64.bat` to compile mipsivm with `Debug/Checked` (unoptimized) compilation preset. <br>
Execute `compfre_win10x64.bat` to compile mipsivm with `Release/Free` (optimized) compilation preset.

## Command-Line Argument
Here list all command-line arguments.

- `/nologo` suppresses the logo printer.
- `/runtime` specifies the runtime preset of MIPS Virtual Machine. Default runtime preset is `MARS`.
- `/debug` specifies mipsivm to break at program startup.

Following runtime presets are available:

### MARS Runtime Preset
MARS, acronym that stands for MIPS Assembler and Runtime Simulator, is an MIPS Assembly Development IDE written by Dr. Pete Sanderson and Dr. Ken Vollmar at Missouri State University. This preset would let mipsivm to simulate the MARS environment. <br>
MARS runtime preset simulates the program in user-mode. It is a uniprocessor preset - no multi-processing is available. <br>
Here list command-line arguments specific to MARS Runtime Preset.

- `/ds` specifies the file path to `.data` section of program.
- `/ts` specifies the file path to `.text` section of program.
- `/ss` specifies the stack size in bytes for the program. Default stack size is 64KiB.

### Example
```bat
mipsivm /nologo /runtime mars /ds helloworld.data.bin /ts helloworld.text.bin
```
This code would suppress the logo printer then load `helloworld.data.bin` as `.data` section and `helloworld.text.bin` as `.text` section of the program, with 64KiB default stack, and run the program.

## Debug Mode
Debugging is the new feature of mipsivm. In case of break-on-startup, `break` instructions or `trap` instructions, mipsivm would enter debug mode and accepts command line input to debug. <br>
Following are debug commands:
- `d` is dumping command: Dump memory content and display in console. (Not started)
- `e` is editing command: Edit memory content. (Not started)
- `g` is continue command: Continue simulation of program.
- `r` is register dump command: Dump register file and display in console.
- `t` is single-step command: Start single-stepping with instruction-granularity.
- `u` is disassembly command: Disassemble instructions display in console. (Incomplete)

## License
This repository is licensed under the MIT license.