MIPS Using C and C++

Using C and C++

Create main.c for C, or main.cpp for C++, in a MIPS project. Replace its starting text with this complete program, which works in either language:

#include <stdio.h>

int main(void) {
    printf("Hello from MIPS\n");
    return 0;
}

Select the source file and choose Compile. The generated assembly opens beside it. Choose Build in the assembly pane, then Run. Open the Terminal to see Hello from MIPS. The program starts in main; return 0 finishes successfully.

Help while editing

Type sim_ to see the simulator functions for this project, or press Ctrl+Space to open suggestions. Small snippets help you write loops, functions and structures; press Tab to move through their editable fields. Suggestions inside an #include path offer available headers.

Hover over a known function such as printf to see its declaration, required header and a documentation link. Parameter hints highlight the current argument while you write a call. Selecting a function inserts its name; add the indicated header yourself.

Names you declare in the current file also appear in suggestions, with variable types or function declarations. Ordinary functions get parameter hints, and nearer block declarations take priority. Complex declarations may be missed.

Editing help works locally, before Compile. It covers known language and library names; Compile checks your program and reports errors.

Compiling a source file

The Compile controls offer Clang or GCC and an optimization level. Start with -O0 to follow your statements easily. Higher levels can combine statements, move instructions or remove work whose result is unused.

Compile creates an assembly file and makes it the project's entry file, which Build uses. Compile handles one C or C++ source file at a time; other .c or .cpp files are not compiled or linked automatically. Compilation needs an internet connection: your selected source and the project files its #include "…" lines reach are sent to Compiler Explorer, and nothing else of the project.

To use a local header, create helpers.h beside your source file in the same project:

#define ANSWER 42

Include it with quotes in main.c:

#include <stdio.h>
#include "helpers.h"

int main(void) {
    printf("The answer is %d\n", ANSWER);
    return 0;
}

A quoted #include may name a .c file too: the compiler pastes its text in, exactly as it does a header's, so a program can be split across several .c files that one source includes. Each file is then part of that one compilation, not a separate one linked later.

After changing the source or a file it includes, Compile again, then Build to run the updated program.

Libraries and simulator services

Runtime support is supplied automatically. The library provides functions declared by <assert.h>, <ctype.h>, <inttypes.h>, <math.h>, <stdio.h>, <stdlib.h>, <string.h> and <time.h>. For example, printf and scanf use the Terminal, fopen and fprintf read and write files, and malloc and free manage dynamic memory. The Runtime library page lists its supported functions with declarations and headers, and explains calling and debugging.

C uses C17 and C++ uses C++17. C++ supports constructors, new and delete, and the provided compatibility headers <cassert>, <cctype>, <cerrno>, <cfloat>, <cinttypes>, <climits>, <cmath>, <cstdarg>, <cstddef>, <cstdint>, <cstdio>, <cstdlib>, <cstring>, <ctime> and <new>. For example, include <cstdio> and use std::printf("Hello from MIPS\n");. The full C++ standard library is not provided: <iostream> and containers such as std::vector are unavailable. Exceptions and runtime type information (RTTI) are disabled, including typeid and casts that require RTTI.

When a standard input function waits, type in the Terminal and press Enter. Unread characters remain available to later calls. Press Ctrl+D or End of input to release pending text without a newline. On an empty input line, this signals end of file for that read.

For example, this reads one integer and prints it only when the input is valid:

#include <stdio.h>

int main(void) {
    int value;
    if (scanf("%d", &value) == 1) {
        printf("You entered %d\n", value);
    }
    return 0;
}

Include <sim.h> to use simulator services such as sim_print_string or sim_read_int. Find their signatures and results under From C in Syscalls, also available in the editor's Documentation panel. The number and string sim_read_* functions take a line, while sim_read_char takes one key. Standard input functions share buffered input; avoid mixing the two interfaces on one line.

Screen and device registers

Declare SIM_SCREEN outside any function, then assign colors to its array. Compile, Build and Run this program, and open the Screen to see a red pixel at column 10, row 10:

#include <sim.h>

SIM_SCREEN(pixels, 64, 64, 1);

int main(void) {
    pixels[10 * 64 + 10] = sim_rgb(255, 0, 0);
    return 0;
}

Width and height are display pixels; unit is the side length of each colored cell. Each row has width / unit cells; select a cell with y * (width / unit) + x. Width and height can be any whole number of pixels from 1 to 1024, and unit any from 1 to 32. MARS's own display only offers 64, 128, 256, 512 or 1024 and 1, 2, 4, 8, 16 or 32, so a program that also runs there keeps to those.

For keyboard and character display input and output, <sim.h> also provides sim_keyboard_ready, sim_keyboard_read, sim_display_ready and sim_display_write. For programmable waveforms and sample playback, it names the Synth's registers and provides sim_synth_play, sim_synth_gate and sim_synth_upload. For the keys held, key and button events, the mouse pointer and the wheel, it names the Input controller's registers and every key, and provides sim_input_present, sim_input_pending, sim_input_event, sim_input_key_down and sim_input_pointer. For streamed sound, it names the MIDI port and the sampled-audio output's registers, and provides sim_midi_present, sim_midi_write, sim_pcm_present, sim_pcm_start, sim_pcm_free and sim_pcm_write.

Following execution

Matching colors connect source lines with their generated assembly. Select a line to highlight its instructions. Use Step to follow those instructions, or place a breakpoint beside a source line and choose Run to stop at the start of its mapped assembly blocks. One source line can require several steps, especially with optimization. Use Undo to move back through recorded execution steps.

Compile again after reopening a saved project to restore source highlights and breakpoints. Editing generated assembly removes that connection; recompilation asks before replacing your manual assembly edits.

Linking assembly Files

Only the selected C or C++ source is compiled. Other assembly files in the same project can provide functions or data, even from a different folder.

A program's entry file is the assembly file Build starts from. The Explorer action New program from this file creates a program with that entry. Build excludes other programs' entry files and the files they include from this search.

Build links an assembly file when it supplies a symbol the program references: an exported name for a function or data. .globl triple exports triple, and the label triple: defines its address. References from a linked file can bring in further assembly files.

The C program below calls triple, defined in triple.mips. In C++, replace the first declaration with extern "C" int triple(int value); so the compiler uses the exact name triple:

int triple(int value);

int main(void) {
    return triple(14);
}
# triple.mips
        .text
        .globl  triple
triple:
        sll     $v0, $a0, 1
        addu    $v0, $v0, $a0
        jr      $ra

The assembly function must follow the calling convention used by compiled code, including register preservation and the rules for its argument and result types. In this integer example, value arrives in $a0 and the result returns in $v0.

Build leaves out assembly files the program does not need, without assembling them. Errors in those files do not affect the Build. The Problems panel marks each with the Hint: "The program doesn't use this File, so it is left out."

Linked files use this editor's GNU assembly subset, which accepts the compiler's output. Some MARS syntax is unavailable in that subset, including .eqv and .macro. For a numeric constant, use .equ NAME, value. If a linked file fails to assemble, its first error explains why it was included and identifies the required syntax.

Exception handlers

MIPS enters an exception handler at the fixed address 0x80000180, the start of .ktext. A file containing only a handler can therefore have no references that cause Build to include it. Export a name for the handler and request it with SIM_LINK from <sim.h>, once, outside any function:

#include <sim.h>

SIM_LINK(handler);

int main(void) {
    /* ... */
    return 0;
}
# handler.mips
        .globl  handler
        .ktext
handler:
        mfc0    $k0, $14        # EPC: the instruction that faulted
        addiu   $k0, $k0, 4     # skip it
        mtc0    $k0, $14
        eret

SIM_LINK requests the file that defines the name without calling the handler. Build fails if no file defines that name. Only one linked file may contain .ktext, because handlers share the fixed starting address 0x80000180. If two do, the error names both files. Files left out of the Build do not count. The Hint on such a file says that its handler never runs, and how to include it.

This minimal handler skips the faulting instruction by advancing EPC by 4. Use it only when skipping that instruction is appropriate. Interrupts and the timer explains exception causes and handler behavior.