mipsivm

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

Showcase

• mipsivm runs Hello World

• mipsivm runs CSE3666 Lab 2

• mipsivm's Debug-Mode disassembly and Unaligned Memory Access Test-Case.

Introduction

The "mipsivm" is a software-based Emulator project aiming to virtualize the minimum MIPS-based machine and efficient virtualized memory.
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.
The "mipsivm" will implement memory virtualization through paging. Memory access would be translated from GPA to HVA with constant running time complexity.
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.
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.
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.)
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.
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.
Currently, mipsivm supports 64-bit Windows.

Windows

To build mipsivm for Windows, you will need to download Enterprise Windows Driver Kit 10 and mount it to T disk. I recommend using WinCDEmu to mount ISO image. Make sure you downloaded EWDK 10 version 2004 with Visual Studio Tools 16.7.
Execute compchk_win10x64.bat to compile mipsivm with Debug/Checked (unoptimized) compilation preset.
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.
MARS runtime preset simulates the program in user-mode. It is a uniprocessor preset - no multi-processing is available.
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

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