# CPUSim64 Software Interrupts

The CPUSim64 comes with many functions defined as part of its operating system. These functions are accessed via software interrupts. To access the defines that give symbolic names to the interrupt values you must include the appropriate system include file.

Input to interrupt functions is passed through known registers, specifically r1, r2, r3 for integers and f1 and f2 for floating point. Output is in either `r0` or `f0` if the function returns a value.

When invoking interrupts, there is no guarantee that the input registers will not be modified.

### <system/io.def>

Interrupt | Pneumonic | Input Registers | Operation
--- | --- | --- | ---
200 | iPUT_NL | r1: output port | Outputs the newline character(s) to the output port.
201 | iPUT_INT | r1: output port r2: output value r3: base | Converts the output value to a string using the specified base and outputs it to the specified port.
202 | iPUT_DEC | r1: output port r2: output value | Converts the output value to a string using base 10 and outputs it to the specified port.
203 | iPUT_HEX | r1: output port r2: output value r3: pad size | Converts the output value to a string using base 16 and outputs it to the specified port padded with zeros to the pad size.
204 | iPUT_FP | r1: output port r2: precision f1: output value | Converts the output value to a string and outputs it to the specified port using the specified precision.
205 | iPUTS | r1: output port r2: output string address | Outputs a string to the specified port.
206 | iPUT_LINE | r1: output port r2: output string address | Outputs a string to the specified port and adds a newline.
207 | iGET_INT | r1: input port r2: base | Gets string from the specified port and converts it to an integer using base.
208 | iGET_DEC | r1: input port | Gets string from the specified port and converts it to an integer using base 10.
209 | iGET_HEX | r1: input port | Gets string from the specified port and converts it to an integer using base 16.
210 | iGET_FP | r1: input port | Gets string from the specified port and converts it to floating point.
211 | iGETS | r1: input port r2: buffer to hold string (from iALLOC) | Gets string from the specified port. r2 will change if buffer is realloced to a larger size. If r2 is 0 then an allocation from the heap will be made to store the string. r0 will be -1 on EOF or the length of the string read.
212 | iGET_LINE | r1: input port r2: buffer to hold string (from iALLOC) | Gets a line from the specified port. r2 will change if buffer is realloced to a larger size. If r2 is 0 then an allocation from the heap will be made to store the string. The newline is removed from the resultant string. r0 will be -1 on EOF or the length of the string read.
213 | iPRINTF | Arg1: port Arg2: format string address Arg3: first value Arg4: second value ... | Stack-based interrupt that implements C-style printf(). Arguments are pushed in reverse order onto the stack. Return address and stack frame are expected to be pushed last which means this interrupt should only be used inside a called function like fprintf().
214 | iCOND_PRINTF | Arg1: condition code Arg2: port Arg3: format string address Arg4: first value Arg4: second value ... | Stack-based interrupt that implements C-style printf(). Arguments are pushed in reverse order onto the stack. Return address and stack frame are expected to be pushed last which means this interrupt should only be used inside a called function like fprintf(). Only prints if the condition is TRUE.
220 | iOPEN_FILE_READ | r1: port (3-255) r2: filepath string | Opens the file for text reading. Returns FALSE in r0 on error. TRUE on success.
221 | iOPEN_FILE_WRITE | r1: port (3-255) r2: filepath string | Opens the file for text writing. Returns FALSE in r0 on error. TRUE on success.
222 | iOPEN_FILE_APPEND | r1: port (3-255) r2: filepath string | Opens the file for text append. Returns FALSE in r0 on error. TRUE on success.
223 | iOPEN_RAW_FILE_READ | r1: port (3-255) r2: filepath string | Opens the file for raw read. Returns FALSE in r0 on error. TRUE on success.
224 | iOPEN_RAW_FILE_WRITE | r1: port (3-255) r2: filepath string | Opens the file for raw write. Returns FALSE in r0 on error. TRUE on success.
225 | iOPEN_RAW_FILE_APPEND | r1: port (3-255) r2: filepath string | Opens the file for raw append. Returns FALSE in r0 on error. TRUE on success.
226 | iCLOSE_FILE | r1: port | Closes the file on port.
227 | iFLUSH | r1: port | Flushes output to the file on port.
228 | iDELETE_FILE | r1: filepath string | Deletes the file specified. Returns FALSE in r0 on error. TRUE on success.
229 | iMAKE_DIR | r1: path string | Creates the specified directory. Returns FALSE in r0 on error. TRUE on success.
230 | iDELETE_DIR | r1: path string | Deletes the specified directory. Must be empty. Returns FALSE in r0 on error. TRUE on success.
231 | iIS_DIR | r1: filepath string | Returns TRUE in r0 if the specified filepath belongs to a directory.
232 | iIS_FILE | r1: filepath string | Returns TRUE in r0 if the specified filepath belongs to a file.
233 | iFILE_EXISTS | r1: filepath string | Returns TRUE in r0 if the specified filepath exists as a file or directory.
234 | iFILES | r1: path string | Returns an array of strings containing the files/dirs residing in the path specified.
235 | iTEMP_DIR | r1: prefix string | Returns a heap allocated string containing the name of a randomly generated tempory directory. Returns null on error.
236 | iTEMP_FILE | r1: prefix string r2: extension string | Returns an heap allocated string containing the name of a randomly generated tempory filepath. Returns null on error.

### <system/math.def>

Interrupt | Pneumonic | Input Registers | Operation
--- | --- | --- | ---
100 | iPI | none | Returns the floating point constant π.
101 | iE | none | Returns the floating point constant base of the natural logarithm.
102 | iABS_FP | f1: value | Returns the absolute value of the floating point value.
103 | iABS | r1: value | Returns the absolute value of the integer value.
104 | iCEIL | f1: value | Returns the smallest whole number greater than or equal to value.
105 | iFLOOR | f1: value | Returns the largest whole number less than or equal to value.
106 | iROUND | f1: value | Returns the nearest whole number to value. Ties round away from 0.
107 | iSQRT | f1: value | Returns the square root of value.
108 | iEXP | f1: value | Returns evalue.
109 | iLOG | f1: value | Returns the natural logarithm of value.
110 | iPOW | f1: base f2: exponent | Returns baseexponent
111 | iREMAINDER | f1: num f2: denom | Returns the fractional portion of num / denom using IEEE 754 remainder rules.
112 | iMAX_FP | f1: value f2: value | Returns the larger of the two floating point values.
113 | iMIN_FP | f1: value f2: value | Returns the smaller of the two floating point values.
114 | iMAX | r1: value r2: value | Returns the larger of the two integer values.
115 | iMIN | r1: value r2: value | Returns the larger of the two integer values.
116 | iRANDOM | none | Returns a pseudorandom floating point greater than or equal to 0.0 and less than 1.0.
117 | iRAND | r1: lower r2: upper | Returns a uniformly distributed random integer on the interval [lower,upper]
118 | iTO_DEGREES | f1: value | Returns value converted from radians to degrees.
119 | iTO_RADIANS | f1: value | Returns value converted from degrees to radians.
120 | iSIN | f1: value in radians | Returns sin(value).
121 | iCOS | f1: value in radians | Returns cos(value).
122 | iTAN | f1: value in radians | Returns tan(value).
123 | iASIN | f1: value | Returns arcsin(value) in radians.
124 | iACOS | f1: value | Returns arccos(value) in radians.
126 | iATAN | f1: value | Returns arctan(value) in radians.
125 | iATAN2 | f1: num f2: denom | Returns arctan(num/denom) in radians even if denom is 0.

### <system/string.def>

Interrupt | Pneumonic | Input Registers | Operation
--- | --- | --- | ---
301 | iFMT_DEC | r1: value | Formats the integer value in decimal as a heap allocated string.
302 | iFMT_HEX | r1: value r2: pad size | Formats the integer value in hexdecimal padded with zeros to the pad size as a heap allocated string.
303 | iFMT_FLOAT | f1: value r1: precision | Formats the floating point value to the specified precision as a heap allocated string.
304 | iPARSE_INT | r1: string address | Parses a string as decimal, hexadecimal (0x or # prefix) or octal (0 prefix) integer.
305 | iPARSE_DEC | r1: string address | Parses a string as a decimal integer.
306 | iPARSE_HEX | r1: string address | Parses a string as a hexadecimal integer.
307 | iPARSE_FLOAT | r1: string address | Parses a string as a floating point value.
308 | iSPRINTF | Arg1: format string address Arg2: first value Arg3: second value ... | Stack-based interrupt that implements C-style sprintf(). Arguments are pushed in reverse order onto the stack. Return address and stack frame are expected to be pushed last which means this interrupt should only be used inside a called function like sprintf(). Returns a heap allocated string in r0.
309 | iFORMAT | Arg1: format string address Arg1: first value Arg2: second value ... | Stack-based interrupt that implements Python-style format(). Arguments are pushed in reverse order onto the stack. Return address and stack frame are expected to be pushed last which means this interrupt should only be used inside a called function like format(). Returns a heap allocated string in r0.
310 | iTO_LOWER | r1: character | Returns the lowercase version of the character.
311 | iTO_UPPER | r1: character | Returns the uppercase version of the character.
312 | iTO_LOWER_STR | r1: string address | Returns lowercase version of string as a heap allocated string.
313 | iTO_UPPER_STR | r1: string address | Returns uppercase version of string as a heap allocated string.
314 | iSTRCOPY | r1: string | Allocates a new string and copies the argument. Returns the new string pointer in r0.
315 | iSTRCMP | r1: string 1 r2: string 2 | Compares string 1 to string 2 and returns 0 if equal, <0 if string 1 is less than string 2, and >0 if string 1 is greater than string 2.
316 | iSTRICMP | r1: string 1 r2: string 2 | Ignoring case, compares string 1 to string 2 and returns 0 if equal, <0 if string 1 is less than string 2, and >0 if string 1 is greater than string 2.
317 | iSUBSTRING | r1: string r2: start index r3: length (-1 to end of string) | Returns a substring of a string as a heap allocated string.
318 | iPREFIX | r1: String r2: length | Returns length character prefix of the string as a heap allocated string.
319 | iSUFFIX | r1: String r2: length | Returns length character suffix of the string as a heap allocated string.
320 | iCHAR_SEARCH | r1: string r2: search char r3: start pos | Returns the index of the location of the character in the string or -1 if not found.
321 | iLAST_CHAR_SEARCH | r1: string r2: search char r3: start pos | Returns the index of the location of the character in the string searching from the end or -1 if not found.
322 | iSUBSTRING_SEARCH | r1: string to search r2: string to find r3: start pos | Searches a string for the specified substring and returns the index into the string if found or -1 if not found.
323 | iLAST_SUBSTRING_SEARCH | r1: string to search r2: string to find r3: start pos | Searches a string from the end for the specified substring and returns the index into the string if found or -1 if not found.
324 | iGET_CODEPOINTS | r1: string 1 | Returns a heap allocated array of the codepoints in the string.
325 | iFROM_CODEPOINTS | r1: array of codepoints | Returns a heap allocated string based on the passed array of codepoints.
326 | iCOUNT_GLPYHS | r1: string | Returns the number of glyphs (graphemes) in the string.
327 | iHASHCODE | r1: string | Returns the hashcode for the passed string.
328 | iTRIM | r1: string | Returns a heap allocatd string with the leading and trailing whitespace removed.
350 | iMATCHES | r1: string to search r2: regex to find | Searches a string for the specified regular expression and returns TRUE if found or FALSE if not found.
351 | iREPLACE_FIRST | r1: string to search r2: regex to find r3: replacement string | Searches a string for the specified regular expression and returns the heap allocated string that has the first occurance replaced by the replacement string.
352 | iREPLACE_ALL | r1: string to search r2: regex to find r3: replacement string | Searches a string for the specified regular expression and returns the heap allocated string that has all the occurances replaced by the replacement string.
353 | iSPLIT | r1: string to split r2: split regex r3: limit | Splits the string using the regex returning an array of strings capped with maximum elements specified by limit. If limit is -1 the splitting is not capped. Returns a heap allocated array of heap allocated strings.
354 | iJOIN | r1: list of strings r2: delimiter string | Joins a length prefixed list of strings using the delimiter string.
355 | iSTRCAT | r1: string 1 r2: string 2 r3: buffer or 0 | Concatenates the first string and second string. Result is put into buffer (might be reallocated) in r3.

### <system/system.def>

Interrupt | Pneumonic | Input Registers | Operation
--- | --- | --- | ---
1 | iINT_MIN | none | Returns largest negative integer.
2 | iINT_MAX | none | Returns largest negative positive integer.
3 | iFLOAT_MIN | none | Returns most negative floating point value.
4 | iFLOAT_LOWEST | none | Returns smallest floating point value greater than 0.
5 | iFLOAT_MAX | none | Returns largest poitive floating point value.
6 | iNEGATIVE_INFINITY | none | Returns negative infinity.
7 | iPOSITIVE_INFINITY | none | Returns positive infinity.
8 | iNAN | none | Returns Not A Number.
10 | iCYCLES | none | Returns user CPU time in cycles.
11 | iCLOCK | none | Returns current execution time in ns.
12 | iSAVE | none | Saves r1-r28 on the stack.
13 | iSAVE_FP | none | Saves f1-f31 on the stack.
14 | iRESTORE | none | Restores r1-r28 from the stack.
15 | iRESTORE_FP | none | Restores f1-f31 from the stack.
16 | iPrintCPUState | none | Prints a diagram of the current CPU state and stack.
20 | iALLOC | r1: allocation size | Returns a heap allocated block address.
21 | iREALLOC | r1: allocation address r2: new allocation size | Returns a new heap allocated block with data copied from the passed allocation address. The original allocation address is freed if it is in the heap.
22 | iFREE | r1: allocation address | Returns the heap allocated block address to the free list.
23 | iMEMMOVE | r1: dest address r2: src address r3: length | Moves contents of memory from src to dest. Can handle overlapping memory blocks.
24 | iMEMCLEAR | r1: dest address r2: length | Clears contents of memory from dest for r2 words.
25 | iALLOC_COUNT | none | Returns a count of heap allocated blocks.
26 | iFREE_COUNT | none | Returns a count of heap free blocks.
27 | iALLOC_SIZE | none | Returns total size of heap allocated blocks.
28 | iFREE_SIZE | none | Returns total size of heap free blocks.
29 | iWALK_HEAP | r1: port | Outputs the allocated blocks in the heap.
30 | iARGC | none | Returns the number of command line arguments.
31 | iARGS | r1: argument index | Returns address of of the command line argument specified by index or null. Index 0 returns the program name.
32 | iEXIT | r1: exit code | Exits process with specified code.
33 | iSYSTEM | r1: string address | Executes the system command contained in the string. Returns the exit code of the command.
34 | iGET_PID | none | Returns user process ID.
35 | iNEXT_PID | none | Returns the next available process ID.
36 | iGET_NUM_CORES | none | Returns user number of CPU cores.
37 | iFORK | none | Unix-style process fork. Zero is returned to the child process and positive PID of the child is returned to the parent. If the fork fails, -1 is returned.
38 | iWAIT |  | Waits for all child processes to complete.
39 | iWAIT_PID | r1: PID | Waits for the child process with PID to complete.
40 | iTHREAD | r1: function, r2: data | Starts a thread running the function passed in r1 and the data in r2. Returns the PID of the thread in r1.
41 | iJOIN_THREAD | r1: PID | Waits for the thread with PID to complete.
42 | iSLEEP | r1: delay in ms | Pauses execution for the specified milliseconds.
43 | iWAKE_THREAD | r1: PID | Wakes a thread from sleep.
44 | iALLOC_SHARED | r1: allocation size | Returns a shared block of memory.