WHEATSYSTEM 1.0.0 ARCHITECTURE

WheatSystem is an operating system designed by Jack Eisenmann. This document describes the design elements of WheatSystem.

DESIGN GOALS

Minimalism: The system should have a simple design.
Flexibility: The system should accommodate many use-cases.
Portability: The system and its applications should work on a variety of hardware platforms.

GENERAL OVERVIEW

Features:

All user applications must be provided as hardware-neutral bytecode.
All applications operate in the same memory space with a unified heap.
Each application may expose functions for other applications to invoke.
Access to certain resources may be limited to applications holding admin permission.

Limitations:

The file system does not support directories or multiple volumes.
The application system does not have automatic garbage collection.
The application system does not verify dependencies or compatibility.
The bytecode runtime environment may only use a single CPU core.
The bytecode has no native instructions for floating point operations.
The permission system does not support granularity beyond admin permission.

FILE SYSTEM

The system maintains a single volume for non-volatile storage of files. The volume may store any number of uniquely named files at the top level. The system does not support directories or any kind of nested file structure. Each file name may be no longer than 127 characters.

If a file name begins with the prefix ws, the file is defined as part of the WheatSystem specification. This convention helps avoid name collisions with third-party files.

Upon start-up, the system will launch the application named wsBoot in the system volume. If no such application is found, the system will become inactive.

Every file has one of the following types:

Generic file
Bytecode application file
System application file

A generic file does not hold special significance in the system. A generic file can store any sort of data.

A bytecode application file contains WheatBytecode instructions for user applications. Please see this page for details about WheatBytecode:

WheatBytecode Documentation

A system application file is used to access hardware features of the machine. A system application file does not contain any bytecode or machine code. Instead, the file contains an enumeration value which is consumed by the operating system. This enumeration value indicates the set of functions which should be exposed. Enumeration values are specific to each system implementation, and are generally incompatible across machines.

Bytecode applications and system applications have the following similarities:

Both may expose functions which can be called by other applications
Both are subject to the constraints of the permission system
Both may be throttled by the resource system to free memory

APPLICATION SYSTEM

The system supports multiple applications running concurrently. However, only one running application instance may be launched from each application file. The bytecode runtime environment will interleave application execution so that each instruction is evaluated atomically.

Every application uses the same unified heap for dynamic memory allocation. Applications must manage garbage collection of their heap allocations. If an application quits, the system will delete every heap allocation created by the application.

Whenever an application uses a pointer, the bytecode runtime environment will verify that the pointer value is not malformed. This check ensures that the application does not access an invalid memory location.

Furthermore, heap allocation read and write operations are controlled by the permission system. If an application without admin permission tries to access a guarded heap allocation of another application, the system will throw an error.

Every application has a function table which defines all functions available in the application. Each function has a signed 32-bit integer ID to help preserve compatibility regardless of function table ordering. The sign of each function ID holds special significance:

If a function ID is zero, the function is not intended to be used externally.
If a function ID is positive, the function is defined as part of the WheatSystem specification.
If a function ID is negative, the function is defined as part of some third-party specification.

Please see this page for a list of functions in the WheatSystem specification:

WheatSystem Functions

PERMISSION SYSTEM

Every application may or may not hold admin permission. Applications holding admin permission may access all resources available in the system. Admin permission should be reserved for highly trusted applications.

A resource is "guarded" if the resource may only be accessed by its owner or an application holding admin permission. Operations which may be guarded include:

Reading or modifying a heap allocation of another application
Invoking a function of another application
Reading or modifying a file

If an application without admin permission tries to perform a guarded action, the system will throw permErr in the application.

Access to the killApp instruction is guarded. If an application which does not hold admin permission tries to perform killApp, the system will throw permErr.

An application which holds admin permission may give or remove admin permission to any other application. Ownership of admin permission is persisted in non-volatile storage.

RESOURCE SYSTEM

The resource system distributes hardware resources to applications, including memory and non-volatile storage.

If memory usage becomes high, the system will attempt to kill a running application to free memory. The system will attempt the following actions to kill an application, ordered from most favorable to least favorable:

If the application implements a kill function, call the kill function.
Throw throttleErr in threads which contain function invocations of the application.
Terminate the application in a dirty state.

When throttling applications to free memory, the system will favor the following applications:

Applications which do not hold admin permission
Applications which are using a lot of memory

If an application attempts to create a memory allocation when memory is full, the resource system will throw capacityErr. The application will not be able to create more memory allocations until memory is freed.

In an analagous fashion, the resource system will throw capacityErr when the system volume is full and an application tries to create a file. The application will not be able to create more files until volume space is freed.

ABBREVIATION GLOSSARY

These abbreviations are used throughout WheatSystem documentation.

arg = Argument

alloc = Allocation

app = Application

attr = Attribute

buff = Buffer

clr = Clear

cond = Condition

del = Delete

dest = Destination

equ = Equal

err = Error

func = Function

impl = Implementation

init = Initialize

instr = Instruction

jmp = Jump

len = Length

mem = Memory

num = Number

perm = Permission

pos = Position

ptr = Pointer

src = Source

term = Terminal

vol = Volume

wrt = Write

ws = WheatSystem