WHEATBYTECODE 1.0.0 DOCUMENTATION
This page was generated from https://github.com/ostracod/wheatsystem-spec at 10/5/2022, 5:09 PM EDT.
WheatBytecode is the programming language provided by WheatSystem for applications. This document describes the syntax and instructions of WheatBytecode.
DATA TYPES AND STRUCTURES
All integers in WheatBytecode are stored in little-endian order. All signed integers use two's complement to express negative values. All characters use ASCII encoding.
Integer data types are expressed in the following manner:
Each bytecode application file has the following structure:
Bytecode application file = [
u32 global frame size,
u32 function table length,
u32 application data file position,
Function table,
Instruction array,
Application data
]
The function table provides metadata for all functions in the application, while the instruction array contains bodies of bytecode instructions. Each function table entry references an instruction body. Instruction bodies in the instruction array must match the order of entries in the function table. Instruction bodies may not have unused space before or after their defined boundaries.
The application data region stores constant data which the application may read during runtime. Values in the application data region cannot be modified.
Each function table entry in a bytecode application file has the following structure:
Function table entry = [
s32 function ID,
u8 is guarded,
u32 argument frame size,
u32 local frame size,
u32 instruction body file position,
u32 instruction body size
]
File types have the following enumeration values:
Each heap allocation stores the following bitfield of attributes:
Allocation attributes = [
u1 x6 unused bits,
u1 is sentry,
u1 is guarded
]
Gate modes have the following enumeration values:
MEMORY LAYOUT
A "frame" is used by an application to store variable data. The size of each frame remains fixed after it is allocated.
Each frame has one of three types:
Each application has exactly one global frame. This frame is never removed.
One or more threads may be active in the system at a time. Each thread contains a stack, which in turn contains local frames and argument frames. When a thread calls a function, a local frame is added to the stack. When a thread returns from a function, the corresponding local frame is removed from the stack.
Argument values and return values are passed between functions through argument frames. If one function would like to call a function with arguments and read the return value, the calling function must perform these steps:
In the scenario described above, the invoked function would follow these steps:
If the expected argument frame size for a function is zero, the caller is not required to allocate an argument frame, and the invoked function cannot access any argument frame which may have been passed.
Every application has access to the unified system heap. Heap allocations have fixed size in the same manner as frames. If an application quits, the system will delete every heap allocation created by the application. Otherwise, applications must manually perform garbage collection.
Applications may reference heap allocations by using pointers. Each pointer is a 32-bit integer generated by the system. The pointer value of the null pointer is zero.
Every heap allocation may be marked as guarded or unguarded. The data in a guarded heap allocation may only be accessed by its creator or by applications with admin permission.
A heap allocation may also be marked as a sentry. A sentry allocation is intended to be referenced by multiple applications. The sentry attribute serves as a mechanism to help applications enforce type safety. All file handles and gates are sentry allocations created by the system.
Whenever a frame or a heap allocation is created, its contents are cleared so that every byte is zero. This ensures that one application cannot inspect memory which was freed by another application.
INSTRUCTION SYNTAX
Each bytecode instruction has the following structure:
Instruction = [
u8 opcode,
Array of arguments
]
Each argument is preceded by a prefix which has the following structure:
Argument prefix = [
u4 reference type,
u4 data type
]
Argument reference types have the following enumeration values:
Argument data types have the following enumeration values:
When reference type is 0x0, the argument will have the following structure:
Constant argument = [
Argument prefix,
Constant value
]
When reference type is 0x1, 0x2, 0x3, or 0x4, the argument will have the following structure:
Frame argument = [
Argument prefix,
Frame index as nested argument
]
When reference type is 0x5, the argument will have the following structure:
Application data argument = [
Argument prefix,
Application data index as nested argument
]
When reference type is 0x6, the argument will have the following structure:
Heap allocation argument = [
Argument prefix,
Pointer as nested argument,
Allocation index as nested argument
]
When reference type is 0x7, the argument will only consist of an argument prefix, and the data type in the prefix will be ignored.
ERROR CODES
Every error code must fit within a signed 8-bit integer. The sign of each error code holds special significance:
genericErr error code = 0x01
Thrown if a problem occurs which cannot be described by a more specific error code.
noImplErr error code = 0x02
Thrown if no implementation is available for the given operation. This includes the following circumstances:
typeErr error code = 0x03
Thrown if a value or resource has the wrong type. This includes the following circumstances:
numRangeErr error code = 0x04
Thrown if a number argument is not in an acceptable range.
indexErr error code = 0x05
Thrown if an index argument is out of bounds or refers to an invalid item. This includes the following circumstances:
lenErr error code = 0x06
Thrown if an argument representing a length or size is invalid. This includes the following circumstances:
ptrErr error code = 0x07
Thrown if a pointer argument has a malformed value, or if the pointer references a deleted heap allocation.
nullErr error code = 0x08
Thrown if a pointer argument has an unexpected null value.
dataErr error code = 0x09
Thrown if an argument data structure contains malformed data. This includes the following circumstances:
argFrameErr error code = 0x0A
Thrown when an argument frame is missing or has an invalid size. This includes the following circumstances:
missingErr error code = 0x0B
Thrown if a necessary resource does not exist. This includes the following circumstances:
stateErr error code = 0x0C
Thrown when trying to use a resource which is in an invalid state. This includes the following circumstances:
permErr error code = 0x0D
Thrown if the current application has insufficient permissions to perform an action. This includes the following circumstances:
capacityErr error code = 0x0E
Thrown if the system has insufficient hardware resources for the operation. This includes the following circumstances:
throttleErr error code = 0x0F
Thrown if the current function invocation should terminate prematurely. This includes the following circumstances:
MEMORY INSTRUCTIONS
wrt dest, value
Writes a value from one memory location to another.
wrtBuff dest, buff, size
Copies a sequence of bytes between memory locations. dest and buff may overlap each other in memory.
fillBuff buff, size, value
Fills a range of memory with a repeating value.
newArgFrame size
Creates a new argument frame to feed into the next function invocation. If an argument frame already exists, it will be deleted first.
newAlloc dest, attrs, size
Creates a new heap allocation.
delAlloc alloc
Deletes a heap allocation.
allocAttrs dest, alloc
Retrieves the attributes of a heap allocation.
allocSize dest, alloc
Retrieves the size of a heap allocation.
allocCreator dest, alloc
Retrieves the file handle of the application which created the given heap allocation. The result is null if the allocation was created by the system.
setAllocAttrs alloc, attrs
Modifies the attributes of the given heap allocation.
CONTROL FLOW INSTRUCTIONS
jmp instrOffset
Jumps control flow to another instruction within the current function.
jmpZ instrOffset, cond
Jumps control flow to another instruction if the given value is zero.
jmpNZ instrOffset, cond
Jumps control flow to another instruction if the given value is not zero.
jmpE instrOffset, value1, value2
Jumps control flow to another instruction if the given values are equal.
jmpNE instrOffset, value1, value2
Jumps control flow to another instruction if the given values are not equal.
jmpG instrOffset, value1, value2
Jumps control flow to another instruction if the first value is greater than the second value.
jmpNG instrOffset, value1, value2
Jumps control flow to another instruction if the first value is not greater than the second value.
GATE INSTRUCTIONS
newGate dest, mode
Creates a new gate to facilitate synchronization of function invocations within the current application. The new gate will initially be in an open state. The current application is considered to be the owner of the gate. If an application quits, all gates owned by the application will be deleted.
delGate gate
Deletes the given gate.
waitGate gate
Blocks execution of the current function invocation if the given gate is closed. If another thread in the current app calls openGate on the gate, execution will resume. If the gate mode is 1, the gate will close after calling waitGate.
openGate gate
Causes the given gate to open. If the gate mode is 0, then openGate will resume all threads blocked by waitGate. If the gate mode is 1, then openGate will resume only one thread blocked by waitGate, and waitGate will immediately close the gate again.
closeGate gate
Causes the given gate to close, so that waitGate will block thread execution.
ERROR INSTRUCTIONS
setErrJmp instrOffset
Configures an error handler within the current function. If an error is thrown, control flow will jump to the error handler.
clrErrJmp
Removes any error handler from the current function. If an error is thrown, it will be passed to the invoking function.
throw errCode
Throws an error which will be handled by the invoking function, or by the error handler in the current function. The error code must be in the range of s8.
err dest
Retrieves the code of the last error which was caught in the current function. The result will be 0 if no error has been caught by an error handler.
FUNCTION INSTRUCTIONS
findFunc dest, appHandle, funcId
Searches for a function having an ID in the given application. If such a function is not found, the result is -1.
call funcIndex
Invokes a function which is defined in the current application.
callRemote appHandle, funcIndex
Invokes a function which may be defined in another application.
ret
Exits the current function and returns control flow to the invoking function.
caller dest
Retrieves the file handle of the application which invoked the current function.
funcIsGuarded dest, appHandle, funcIndex
Retrieves whether the function defined in the given application is guarded.
BITWISE INSTRUCTIONS
bNot dest, value
Performs bitwise NOT with the given value.
bOr dest, value1, value2
Performs bitwise OR with the given values.
bAnd dest, value1, value2
Performs bitwise AND with the given values.
bXor dest, value1, value2
Performs bitwise XOR with the given values.
bLeft dest, value1, value2
Performs bitshift left with the given values.
bRight dest, value1, value2
Performs bitshift right with the given values. The leftmost bits will be filled with zeros.
ARITHMETIC INSTRUCTIONS
inc value
Increments the given value by one.
dec value
Decrements the given value by one.
add dest, value1, value2
Performs addition with the given values.
sub dest, value1, value2
Performs subtraction with the given values.
mul dest, value1, value2
Performs multiplication with the given values.
div dest, value1, value2
Performs division with the given values.
mod dest, value1, value2
Performs the modulo operation with the given values.
APPLICATION INSTRUCTIONS
launch appHandle
Launches the given application if it is not already running.
thisApp dest
Retrieves the file handle of the current application.
quitApp
Terminates the current application.
appIsRunning dest, appHandle
Retrieves whether the given application is running.
appInitErr dest, appHandle
Retrieves the code of the unhandled error which terminated the init function of the given application. The result will be 0 if the given application has no associated init error. The init error will persist until appHandle is deleted by the system, or until the application is launched again.
killApp appHandle
Requests for the given application to terminate.
FILE INSTRUCTIONS
newFile name, type, isGuarded, size
Creates a new file.
delFile fileHandle
Deletes the given file.
openFile dest, name
Retrieves a file handle for the given file. After the current application finishes using the file handle, the application should perform the closeFile instruction. Otherwise, the system may accumulate garbage.
closeFile fileHandle
Indicates to the system that the current application has finished using the given file handle. The system may delete fileHandle if all other applications have also closed the file handle.
readFile dest, fileHandle, pos, size
Reads a sequences of bytes from the given file into a buffer.
wrtFile fileHandle, pos, buff, size
Writes a sequences of bytes from the given buffer into a file.
FILE METADATA INSTRUCTIONS
allFileNames dest
Retrieves a list of all file names in the system volume.
fileExists dest, name
Retrieves whether a file with the given name exists.
fileName dest, fileHandle
Retrieves the name of the given file.
fileType dest, fileHandle
Retrieves the type of the given file.
fileIsGuarded dest, fileHandle
Retrieves whether the given file is guarded.
fileSize dest, fileHandle
Retrieves the size of the given file.
PERMISSION INSTRUCTIONS
hasAdminPerm dest, appHandle
Retrieves whether the given application holds admin permission.
giveAdminPerm appHandle
Grants admin permission to the given application.
delAdminPerm appHandle
Deletes admin permission from the given application.
RESOURCE INSTRUCTIONS
memSize dest
Retrieves the total amount of memory in the system.
appMemSize dest, appHandle
Retrieves the amount of memory used by the given application.
memSizeLeft dest
Retrieves the amount of unused memory remaining in the system.
volSize dest
Retrieves the total amount of storage in the system volume.
volSizeLeft dest
Retrieves the amount of unused storage remaining in the system volume.