MIPS Syscalls

Asking the simulator for a service

Simulator services and behavior

The services are part of this simulator environment. Their behavior can depend on the Terminal, Project Files, Testcase, or other editor panels, so programs that use them are not limited to the instructions built into the MIPS processor.
Input services read from the Terminal. Number and string input uses a line; service 12 reads one key and completes immediately, with Enter represented by 10. A Testcase supplies scripted input instead. Standard input (descriptor 0) ends when you press Ctrl+D or use End of input; a read then reports end of input.
Service 30 measures milliseconds since the run started. It starts at zero in a Testcase. Service 32 pauses an interactive run while keeping the page responsive; in a Testcase, the wait completes immediately and advances the program's clock.
Random services (40–44) use a separate stream for each generator. A stream that has not been seeded starts from host randomness during an interactive run and from a fixed seed in a Testcase. Service 40 sets the seed, and Undo restores a stream to its earlier state before a draw or reseed.
Files live in the Project's Files, not on the computer's disk, and open files receive descriptors starting at 3. File errors return -1 where the service returns a result. Undo restores file changes, and each Testcase starts with its own copy of the Project Files.
The keyboard device queues typed keys and accepts scripted input, so a fast typist or a Testcase does not lose keys. The display transmitter is always ready.
Exit (10) reports code 0. Exit2 reports its signed code in the Log. A runtime error stops execution; Undo can reverse the last step, and Stop or Build ends that run. Undo also restores program state while keeping the Terminal transcript visible.
Compiled C and C++ programs place the heap after static data when it needs to move. Static data occupies 4,128,768 bytes starting at 0x10010000; its last byte is 0x103FFFFF and the exclusive end is 0x10400000. Constants, globals, and a SIM_SCREEN grid share this range. Assembly programs use the assembler's memory layout.
MIDI services 31 and 33 are unavailable; calling either stops the program with an unsupported-service error.
Strings, dialogs, and file paths use UTF-8. Print-character service 11 prints the low byte of $a0; read-character service 12 returns one UTF-16 code unit (a 16-bit value, which may be half of a supplementary Unicode character). File-write service 15 returns the number of bytes written. Service 62 seeks within files; descriptors 0–2 cannot be used with it.
Open supports read-write extensions: flag 2 opens an existing File (r+), 3 creates or truncates (w+), and 10 creates and appends writes (a+). All three allow reading and writing with one shared position. Original flags 0, 1 and 9 retain their reference behavior. Runtime-only service 1100 returns -1 for heap exhaustion; service 9 still stops with a runtime error.

Print integer

$v0 = 1

In: $a0 = Integer to print
From C: void sim_print_int(int value)

Print float

$v0 = 2

In: $f12 = Float to print
From C: void sim_print_float(float value)

Print double

$v0 = 3

In: $f12 = Double to print
From C: void sim_print_double(double value)

Print string

$v0 = 4

In: $a0 = Address of null-terminated string to print
From C: void sim_print_string(const char *text)

Read integer

$v0 = 5

Out: $v0 = Contains the integer parsed from the input line
Note: Reads one line, trims surrounding whitespace, and parses it as an integer. Invalid input stops the program with an input error.
From C: int sim_read_int(void)

Read float

$v0 = 6

Out: $f0 = Contains the floating-point value parsed from the input line
Note: Reads one line, trims surrounding whitespace, and parses it as a floating-point value. Invalid input stops the program with an input error.
From C: float sim_read_float(void)

Read double

$v0 = 7

Out: $f0 = Contains the double-precision value parsed from the input line
Note: Reads one line, trims surrounding whitespace, and parses it as a double-precision value. Invalid input stops the program with an input error.
From C: double sim_read_double(void)

Read string

$v0 = 8

In: $a0 = Address of input buffer; $a1 = Maximum number of characters to read
Out: Memory at the address passed in $a0 is written through the buffer pointer.
Note: Service 8 - Follows semantics of UNIX 'fgets'. For specified length n, string can be no longer than n-1. If less than that, adds newline to end. In either case, then pads with null byte If n = 1, input is ignored and null byte placed at buffer address. If n < 1, input is ignored and nothing is written to the buffer.
From C: void sim_read_string(char *buffer, int size)

Sbrk (allocate heap memory)

$v0 = 9

In: $a0 = Number of bytes to allocate
Out: $v0 = Contains address of allocated memory
From C: void *sim_sbrk(int bytes)

Exit (terminate execution)

$v0 = 10

From C: void sim_exit(void)

Print character

$v0 = 11

In: $a0 = Character to print
Note: Prints the ASCII character whose code is in the low-order byte.
From C: void sim_print_char(int character)

Read character

$v0 = 12

Out: $v0 = Contains the input character code
From C: int sim_read_char(void)

Open file

$v0 = 13

In: $a0 = Address of null-terminated string containing filename; $a1 = Flags; $a2 = Mode
Out: $v0 = Contains file descriptor (negative if error)
Note: Use flag 0 to open for reading, 1 to open for writing (creating the file if needed), or 9 to open for writing and append (creating the file if needed). Editor extensions 2, 3, and 10 open for reading and writing: 2 requires an existing file, 3 creates or truncates, and 10 creates and appends writes. They share one file position. The mode argument is ignored. A negative descriptor means the operation failed. Descriptors 0, 1, and 2 are reserved for standard input, standard output, and standard error; project files receive descriptors starting at 3.
From C: int sim_open(const char *path, int flags, int mode)

Read from file

$v0 = 14

In: $a0 = File descriptor; $a1 = Address of input buffer; $a2 = Maximum number of characters to read
Out: $v0 = Contains number of characters read (0 if end-of-file, negative if error); Memory at the address passed in $a1 is written through the buffer pointer.
Note: The result, including a negative value on failure, is returned in $v0.
From C: int sim_read(int fd, void *buffer, int length)

Write to file

$v0 = 15

In: $a0 = File descriptor; $a1 = Address of output buffer; $a2 = Number of characters to write
Out: $v0 = Contains number of characters written (negative if error)
Note: The result, including a negative value on failure, is returned in $v0.
From C: int sim_write(int fd, const void *buffer, int length)

Close file

$v0 = 16

In: $a0 = File descriptor
From C: void sim_close(int fd)

Exit2 (terminate with value)

$v0 = 17

In: $a0 = Termination result
Note: Ends the program with the signed exit code in $a0. The editor shows this code in the Log.
From C: void sim_exit2(int code)

Time (program time)

$v0 = 30

Out: $a0 = Low order 32 bits of the program time; $a1 = High order 32 bits of the program time
Note: Returns milliseconds since 1970-01-01 UTC. In a Testcase, calendar time starts at 2000-01-01 UTC and advances through waits of service 32.
From C: long long sim_time(void)

Sleep

$v0 = 32

In: $a0 = The length of time to sleep in milliseconds
Note: Service 32 - Lets that much program time pass before the next instruction. The editor stays responsive while it waits and the wait costs no instructions, so a program idling on the keyboard never reaches the execution limit; in a testcase it completes at once and advances the virtual clock instead.
From C: void sim_sleep(int milliseconds)

Print integer in hexadecimal

$v0 = 34

In: $a0 = Integer to print
Note: Displayed value is 8 hexadecimal digits, left-padding with zeroes if necessary.
From C: void sim_print_hex(int value)

Print integer in binary

$v0 = 35

In: $a0 = Integer to print
Note: Displayed value is 32 bits, left-padding with zeroes if necessary.
From C: void sim_print_binary(int value)

Print integer as unsigned

$v0 = 36

In: $a0 = Integer to print
Note: Displayed as unsigned decimal value.
From C: void sim_print_unsigned(unsigned value)

Set seed

$v0 = 40

In: $a0 = Generator ID: any integer selects an independent pseudorandom sequence; $a1 = Seed for corresponding pseudorandom number generator
Note: Seeds the generator selected by $a0. Each generator ID has an independent sequence. An unseeded ID starts from host randomness in an interactive run and a fixed per-ID seed in a testcase, making testcase runs repeatable. Values follow Java’s Random sequence for the same seed. Undo restores the state before a draw or reseed.
From C: void sim_random_seed(int generator, int seed)

Random int

$v0 = 41

In: $a0 = Generator ID: any integer selects an independent pseudorandom sequence
Out: $a0 = Contains the next pseudorandom, uniformly distributed int value from this random number generator's sequence
Note: Each generator ID has an independent sequence. An unseeded ID starts from host randomness in an interactive run and a fixed per-ID seed in a testcase, making testcase runs repeatable. Service 40 sets an explicit seed. Values follow Java’s Random sequence for the same seed. Undo restores the state before a draw or reseed.
From C: int sim_random_int(int generator)

Random int range

$v0 = 42

In: $a0 = Generator ID: any integer selects an independent pseudorandom sequence; $a1 = Upper bound of range of returned values
Out: $a0 = Contains pseudorandom, uniformly distributed int value in the range 0 <= [int] < [upper bound], drawn from this random number generator's sequence
Note: Each generator ID has an independent sequence. An unseeded ID starts from host randomness in an interactive run and a fixed per-ID seed in a testcase, making testcase runs repeatable. Service 40 sets an explicit seed. Values follow Java’s Random sequence for the same seed. Undo restores the state before a draw or reseed.
From C: int sim_random_int_range(int generator, int bound)

Random float

$v0 = 43

In: $a0 = Generator ID: any integer selects an independent pseudorandom sequence
Out: $f0 = Contains the next pseudorandom, uniformly distributed float value in the range 0.0 <= f < 1.0 from this random number generator's sequence
Note: Each generator ID has an independent sequence. An unseeded ID starts from host randomness in an interactive run and a fixed per-ID seed in a testcase, making testcase runs repeatable. Service 40 sets an explicit seed. Values follow Java’s Random sequence for the same seed. Undo restores the state before a draw or reseed.
From C: float sim_random_float(int generator)

Random double

$v0 = 44

In: $a0 = Generator ID: any integer selects an independent pseudorandom sequence
Out: $f0 = Contains the next pseudorandom, uniformly distributed double value in the range 0.0 <= f < 1.0 from this random number generator's sequence
Note: Each generator ID has an independent sequence. An unseeded ID starts from host randomness in an interactive run and a fixed per-ID seed in a testcase, making testcase runs repeatable. Service 40 sets an explicit seed. Values follow Java’s Random sequence for the same seed. Undo restores the state before a draw or reseed.
From C: double sim_random_double(int generator)

ConfirmDialog

$v0 = 50

In: $a0 = Address of null-terminated string that is the message to user
Out: $a0 = Contains value of user-chosen option 0: Yes 1: No 2: Cancel
From C: int sim_confirm_dialog(const char *message)

InputDialogInt

$v0 = 51

In: $a0 = Address of null-terminated string that is the message to user
Out: $a0 = Contains int read; $a1 = Contains status value 0: OK status -1: input data cannot be correctly parsed -2: Cancel was chosen -3: OK was chosen but no data had been input into field
From C: int sim_input_dialog_int(const char *message, int *status)

InputDialogFloat

$v0 = 52

In: $a0 = Address of null-terminated string that is the message to user
Out: $f0 = Contains the floating-point value parsed from the input line; $a1 = Contains status value 0: OK status -1: input data cannot be correctly parsed -2: Cancel was chosen -3: OK was chosen but no data had been input into field
From C: float sim_input_dialog_float(const char *message, int *status)

InputDialogDouble

$v0 = 53

In: $a0 = Address of null-terminated string that is the message to user
Out: $f0 = Contains the double-precision value parsed from the input line; $a1 = Contains status value 0: OK status -1: input data cannot be correctly parsed -2: Cancel was chosen -3: OK was chosen but no data had been input into field
From C: double sim_input_dialog_double(const char *message, int *status)

InputDialogString

$v0 = 54

In: $a0 = Address of null-terminated string that is the message to user; $a1 = Address of input buffer; $a2 = Maximum number of characters to read
Out: $a1 = Contains status value 0: OK status. Buffer contains the input string. -2: Cancel was chosen. No change to buffer. -3: OK was chosen but no data had been input into field. No change to buffer. -4: length of the input string exceeded the specified maximum. Buffer contains the maximum allowable input string plus a terminating null.; Memory at the address passed in $a1 is written through the buffer pointer.
Note: See Service 8 note below table
From C: int sim_input_dialog_string(const char *message, char *buffer, int size)

MessageDialog

$v0 = 55

In: $a0 = Address of null-terminated string that is the message to user; $a1 = The type of message to be displayed: 0: error message, indicated by Error icon 1: information message, indicated by Information icon 2: warning message, indicated by Warning icon 3: question message, indicated by Question icon other: plain message (no icon displayed)
From C: void sim_message_dialog(const char *message, int type)

MessageDialogInt

$v0 = 56

In: $a0 = Address of null-terminated string that is an information-type message to user; $a1 = Int value to display in string form after the first string
From C: void sim_message_dialog_int(const char *message, int value)

MessageDialogFloat

$v0 = 57

In: $a0 = Address of null-terminated string that is an information-type message to user; $f12 = Float value to display in string form after the first string
From C: void sim_message_dialog_float(const char *message, float value)

MessageDialogDouble

$v0 = 58

In: $a0 = Address of null-terminated string that is an information-type message to user; $f12 = Double value to display in string form after the first string
From C: void sim_message_dialog_double(const char *message, double value)

MessageDialogString

$v0 = 59

In: $a0 = Address of null-terminated string that is an information-type message to user; $a1 = Address of null-terminated string to display after the first string
From C: void sim_message_dialog_string(const char *message, const char *text)

Lseek (move file position)

$v0 = 62

In: $a0 = File descriptor; $a1 = Offset in bytes; $a2 = Where the offset counts from: 0 the start of the file, 1 the current position, 2 the end of the file
Out: $v0 = Contains the new position, counted from the beginning of the file (-1 if error)
Note: Seeks to a byte position in the file. Descriptors 0, 1, and 2 cannot seek.
From C: int sim_lseek(int fd, int offset, int whence)