MIPS Atlas Explorer

What Is MIPS Atlas Explorer

Atlas Explorer is an application that lets you fine-tune software performance using the MIPS Core Performance Simulator. Atlas Explorer does not require a hardware target or emulator.

Atlas Explorer is a combination of this Visual Studio Code Extension (the UI) and a cloud service platform (the Atlas Cloud). Atlas Explorer works on Linux, Windows,and macOS host computers.

Getting Up and Running

To use Atlas Explorer, you need to:

DO THIS FIRST: Get an API Access Key from the Atlas Explorer Team.

Immediately after the extension installation is complete, you will be asked if you would like to install your API key (the question will pop up at the lower right corner). If you do not yet have an API key, you can dismiss the question and enter it later. You cannot do anything with Atlas Explorer until you enter your API key.

Theory of Operation

An “experiment” captures the execution trace and performance characteristics of an ELF file compiled with a specific source code and compiler state. By running multiple experiments and varying the source code and compiler options each time, you can decide what changes improve or impair software performance. This can be as simple as changing the -o flag to the compiler, without editing the source. Or you can edit the source and try different algorithms or memory layouts.

With Atlas Explorer, you can run as many experiments as you like and compare them in the Atlas Explorer Report Viewer.

Atlas Explorer is not a “development environment” in and of itself. Atlas Explorer is meant to work with existing VSCode development environments. In theory, this means that you can open any existing VSCode workspace, install the Atlas Explorer extension (and your API key), and begin running experiments. Let us see how this works in practice…

Workloads

Workloads are simply the programs that you want to run and profile. These are ELF files built using a MIPS RISC-V toolchain. For now, Atlas Explorer only supports bare-metal programs. We plan to add support for Linux kernel and user space programs in the future.

Atlas Explorer is not intended to run extreme workloads. Large programs (where size is measured in the number of instructions executed, not the size of the ELF) can take an exceedingly long time to model. Keep in mind that the Performance Modeller does not run at native processor speeds, or even FPGA speeds, or even typical ISS speeds. It is…well…slow.

A good rule of thumb, for now, is to craft your workloads such that they are as small as possible while still allowing you to measure and tune what you need. If possible, try to extract the target algorithms into separate programs. Do not run code you do not need or care about. Extraneous, uninteresting code tales long to run and model and contributes unwanted cycles and instructions to the overall summary metrics modelled with Shinro and will make it more difficult to discern the degree of change in the code you do care about.

Running Experiments

Before we run the experiment let us provide a little detail on how the experiment is captured on your workstation. Your ELF file is in a folder. When you run an experiment using that ELF file a new child folder is created in the same folder as the ELF file. This folder is named “experiments.” Inside this folder another folder is created using a configurable template. This folder is the “experiment name” folder. By default, this folder name will be the ELF filename (w/o extension) with a timestamp. Everything related to the experiment will be kept in this folder. This includes a copy of the ELF file (in a hidden subfolder named “.experiment,” copies of any source files extracted from the debug info in the ELF file (in the “src” subfolder). Both the ELF and src files are used to help source code synchronization with execution addresses when viewing detail traces (a future feature). A generated README.md file that has general information about the experiment.

This README.md file is yours. You can edit it to keep notes about the experiment. Once generated, Atlas Explorer does not care what you do with it. You can delete it if you want. [Atlas Explorer keeps a backup so you can restore it if you accidentally delete it.] The first line of the README file can be used to describe the experiment. This brief description, if found, will be used in the Report Viewer to help provide some context.

Some assets are placed into the hidden “.experiment” folder. These are assets that Atlas Explorer needs to function properly, but that should not be “readily accessible” to you, the user. They should be considered immutable. All copied source files are marked as read-only to prevent you from accidentally editing them. The structure of this folder may change in the future.

Now let us run an Experiment!

Right-click on an ELF file and select “Run Experiment” at the top of the context menu.

Atlas Explorer will ask you to select a core model from a list of available models. Select “shogun.”

Atlas Explorer will generate the README.md file for the experiment and open it in an editor pane.

That is, it! Atlas Explorer will upload your ELF file to the cloud, execute it using ESESC, then run the Core Performance Modeller, and finally download various “results” files back to your workstation. Atlas Explorer will automatically open the “Summary” report in the Atlas Explorer Report Viewer. This report has basic summary performance results like Total Cycles Consumed and Total Instructions Executed.