A wee educational programming environment.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
js
src
LICENSE
README.md
index.html
tests.html
tsconfig.json

README.md

Wee

Wee is a tiny educational programming environment. Wee is composed of:

  1. An instruction set architecture (ISA) with a corresponding virtual machine (Wee Machine).
  2. An assembly language plus assembler (Wee Assembly)
  3. A higher level language (Wee Lang) that is an extension of the assembly language making common tasks, like defining types, functions, locals, etc., more comfortable.
  4. A browser-based development environment with code editing, compilation and debugging tools (Wee DE).

Wee Machine

The Wee Machine resembles the architecture of real-world 32-bit machines like x86 and ARM. The Wee Machine is composed of the following components:

  1. The processor with
    1. 32-bit integer & float ALU
    2. 14 general purpose registers (r0-r13)
    3. A program counter register (pc)
    4. A stack pointer register (sp)
  2. Byte-addressable random access memory
  3. Memory mapped video memory (32-bit RGBA, 320x200)
  4. Ports to communicate with peripherals like
    1. Keyboard
    2. Mouse
    3. Graphics card
    4. Sound card
    5. Networking card
    6. Random number generator
    7. High precision timer
  5. A Basic Input/Output System (BIOS)

Wee Machine implements the Von Neumann architecture: code & data are stored to and read from the same memory. This allows self-modifying code. Wee Machine uses little endian, the word size is 32-bit.

Instruction Set

Instructions are 32-bit in size, with 0-3 operands encoded in the instruction. Memory access instructions allow the specification of byte-offsets. The opcode of an instruction is always encoded in the first 6 bits. Some instruction may be made up of an additional 32-bit value encoding data or an address.

Register encoding

Wee Machine has 16 registers, r0-r13, pc and sp. When encoding a register in an instruction, the register is referred to by an index. Registers r0 to r13 are indexed from 0 to 13. Register pc has index 14, and register sp has index 15.

Halting

Wee Machine can be halted via the instruction 0x00000000 or halt in assembly.

Arithmetic Operations

Wee Machine supports 32-bit integer and floating point arithmetic. All arithmetic instructions operate only on registers and have the following format:

bits 0-5 bits 6-9 bits 10-12 bits 14-17 bits 18-31
Opcode Register (op1) Register (op2) Register (op3) Unused

These instructions are supported:

Opcode Assembly Semantics
0x01 add op1, op2, op3 Adds the 32-bit integers in op1 and op2 and stores the result in op3.
0x02 sub op1, op2, op3 Subtracts the 32-bit integers in op1 and op2 and stores the result in op3.
0x03 mul op1, op2, op3 Multiplies the 32-bit integers in op1 and op2 and stores the result in op3.
0x04 div op1, op2, op3 Divides the 32-bit signed integer in op1 by op2 and stores the result in op3.
0x05 div_unsigned op1, op2, op3 Divides the 32-bit unsigned integer in op1 by op2 and stores the result in op3.
0x06 remainder op1, op2, op3 Divides the 32-bit signed integer in op1 by op2 and stores the remainder in op3. The remainder has the sign of the dividend op1
0x07 remainder_unsigned op1, op2, op3 Divides the 32-bit unsigned integer in op1 by op2 and stores the remainder in op3. The remainder has the sign of the dividend op1
0x08 add_float op1, op2, op3 Adds the 32-bit floats in op1 and op2 and stores the result in op3.
0x09 sub_float op1, op2, op3 Subtracts the 32-bit floats in op1 and op2 and stores the result in op3.
0x0a mul_float op1, op2, op3 Multiplies the 32-bit floats in op1 and op2 and stores the result in op3.
0x0b div_float op1, op2, op3 Divides the 32-bit float in op1 by op2 and stores the result in op3.
0x0c cos_float op1, op2 Calculates the cosine of the angle given in radians in op1 and stores the result in op2
0x0d sin_float op1, op2 Calculates the sine of the angle given in radians in op1 and stores the result in op2
0x0e atan2_float op1, op2, op2 Calculates the angle of the vector (x, y) stored in op1, op2 relative to the x-axis and stores the result in op3
0x0f sqrt_float op1, op2 Calculates the square root of the float in op1 and stores the result in op2
0x10 pow_float op1, op2 Calculates the value of op1 raised by the exponent in op2 and stores the result in r3
0x11 convert_int_float op1, op2 Converts the 32-bit signed integer in op1 to float and stores the result in op2
0x12 convert_float_int op1, op2 Converts the 32-bit float in op1 to a 32-bit signed integer, truncating the decimal portion, and stores the result in op2
0x13 cmp op1, op2, op3 Compares the 32-bit signed integer in op1 to op2 and stores the result in op3. The result will be 0 if op1 == op2, 1 if op1 > op2 and -1 (0xffffffff) if op1 < op2. The result can be used with the jump instructions.
0x14 cmp_unsigned op1, op2, op3 Compares the 32-bit unsigned integer in op1 to op2 and stores the result in op3. The result will be 0 if op1 == op2, 1 if op1 > op2 and -1 (0xffffffff) if op1 < op2. The result can be used with the jump instructions.
0x15 fcmp op1, op2, op3 Compares the 32-bit float in op1 to op2 and stores the result in op3. The result will be 0 if op1 == op2, 1 if op1 > op2 and -1 (0xffffffff) if op1 < op2. The result can be used with the jump instructions.

Note: Underflow, overflow and division by zero are not reported. Floating point operations should follow the IEEE 754 standard. Conversions between float and int may result in undefined values if the precision is exceeded. All the nastiness of NaNs and infinities apply. Rounding modes TBD.

Bit-wise Operations

Wee Machine supports a standard set of bit-wise operations. All bit-wise operation instructions operate only on registers and have the following format:

bits 0-5 bits 6-9 bits 10-12 bits 14-17 bits 18-31
Opcode Register (op1) Register (op2) Register (op3) Unused

The following instructions are supported:

Opcode Assembly Semantics
0x16 not op1, op2 Inverts the bits in op1 and stores the result in op2
0x17 and op1, op2, op3 Performs a bit-wise and of op1 and op2 and stores the result in op3
0x18 or op1, op2, op3 Performs a bit-wise or of op1 and op2 and stores the result in op3
0x19 xor op1, op2, op3 Performs a bit-wise exclusive or of op1 and op2 and stores the result in op3
0x1a shift_left op1, op2, op3 Shifts the bits in op1 to the left by the number of bits specified in op2 and stores the result in op3
0x1b shift_right op1, op2, op3 Shifts the bits in op1 to the right by number of bits specified in op2 and stores the result in op3

Jumps & Branching

Wee Machine supports a variety of jumps, either directly or based on the result of a cmp or fcmp instruction. All jump target addresses are absolute. Jump instructions have the following format:

bits 0-5 bits 6-9 bits 10-31 bits 32-64
Opcode Register (op1) Unused word2

The following instructions are supported:

Opcode Assembly Semantics
0x1c jump word2 Jumps to the specified address in word2
0x1d jump_equal op1, word2 Jumps to the specified relative address in word2 if the operands of the comparison, the result of which is stored in op1, were equal
0x1e jump_not_equal op1, word2 Jumps to the specified relative address in word2 if the operands of the comparison, the result of which is stored in op1, were not equal
0x1f jump_less op1, word2 Jumps to the specified relative address in word2 if the first operand of the comparison, the result of which is stored in op1, was less than the second operand
0x20 jump_greater op1, word2 Jumps to the specified relative address in word2 if the first operand of the comparison, the result of which is stored in op1, was greater than the second operand
0x21 jump_less_equal op1, word2 Jumps to the specified relative address in word2 if the first operand of the comparison, the result of which is stored in op1, was less or equal to the second operand
0x22 jump_greater_equal op1, word2 Jumps to the specified relative address in word2 if the first operand of the comparison, the result of which is stored in op1, was greater or equal to the second operand

Memory operations

Wee Machine has 16 megabytes of byte-addressable memory in which both code and data are stored, plus 16 registers that can hold data and addresses. Wee Machine provides instructions to load and store data from and to registers and memory.

Memory operations can be 1 or 2 words wide. 2-word memory operations encode a 32-bit value in the second word, which can represent data or an address. The format of the first word is as follows

bits 0-5 bits 6-9 bits 10-13 bits 14-31 bits 32-63
Opcode Register (op1) Register (op2) Offset in bytes (offset) Value (word)

The following memory operations are available:

Opcode Assembly Semantics
0x23 move op1, op2 Copies the value in op1 to op2
0x24 move word, op2 Copies the 32-bit value in word to op2
0x25 load word, offset, op2 Reads the 32-bit value at address word + offset from memory and stores it in op2
0x26 load op1, offset, op2 Reads the 32-bit value at address op1 + offset from memory and stores it in op2
0x27 store op1, word, offset Writes the 32-bit value in op1 to memory at address word + offset
0x28 store op1, op2, offset Writes the 32-bit value in op1 to memory at address op2 + offset
0x29 load_byte word, offset, op2 Reads the 8-bit value at address word + offset from memory and stores it in op1
0x2a load_byte op1, offset, op2 Reads the 8-bit value at address op1 + offset from memory and stores it in op2
0x2b store_byte op1, word, offset Writes the lowest 8 bits in op1 to memory at address word + offset
0x2c store_byte op1, op2, offset Writes the lowest 8 bits in op1 to memory at address op2 + offset
0x2d load_short word, offset, op2 Reads the 16-bit value at address word + offset from memory and stores it in op1
0x2e load_short op1, offset, op2 Reads the 16-bit value at address op1 + offset from memory and stores it in op2
0x2f store_short op1, word, offset Writes the lowest 16 bits in op1 to memory at address word + offset
0x30 store_short op1, op2, offset Writes the lowest 16 bits in op1 to memory at address op2 + offset

Stack & Call Operations

Wee Machine has a stack at the end of the available memory 0xffffff which grows "downwards". The register sp keeps track of the top of the stack in memory. Wee Machine provides instructions to make working with the stack easier, e.g. pushing and popping values.

The stack plays a pivotal role when implementing and calling functions in Wee Machine. A function can use the stack to store "local" values temporarily while the function is being executed. When calling another function, the parameters are passed to the function via the stack. Finally, the stack is also used to save the contents of registers, either because the function can not fit all local data into registers, or because another function is called that will itself modify registers.

Wee Machine's calling convention works as follows:

  1. The calling function (caller) saves all registers it uses to the stack, e.g. via push
  2. The caller pushes all arguments it wants to pass to the called function (callee) to the stack. The arguments are pushed to the stack in such an order, that the last argument becomes the top of the stack. All arguments are word sized.
  3. The caller calls the callee, via call, which will push the return address (the address of the the next instruction after call) onto the stack.
  4. The callee executes its instructions and eventually uses return <words to pop>, which will pop the specified number of words from the stack so the stack pointer points at the return address, then pops the return address of the stack, writes it to pc and resumes execution.
  5. The caller resumes at the instruction after call, with the stack pointer sp pointing to the location it pointed to after all arguments were pushed onto the stack. The caller pops the arguments from the stack. The callee may have returned a value in register r0.

Memory operations can be 1 or 2 words wide. 2-word memory operations encode a 32-bit value in the second word, which can represent data or an address. The format of the first word is as follows:

bits 0-5 bits 6-9 bits 10-31 bits 32-63
Opcode Register (op1) Number of words Value (word2)

The following stack & call operations are available:

Opcode Assembly Semantics
0x31 push word2 Decrease sp by 4, then write the 32-bit value word2 to the stack at address sp
0x32 push op1 decrease sp by 4, then write the 32-bit value in op1 to the stack at address sp
0x33 stackalloc <number of words> Decrease sp by 4 * <number of words>
0x34 pop op1 Reads the 32-bit value at address sp, stores it in op1, then increases sp by 4
0x35 pop <number of words> Pops the number of words from the stack by increasing sp by 4 * <words to pop>.
0x36 call word1 Pushes the address of the next instruction on the stack, sets pc to word1 which holds the address of the first instruction of the function, and resumes execution
0x37 call op1 Pushes the address of the next instruction on the stack, Sets pc to op1 which holds the address of the first instruction of the function, and resumes execution
0x38 return <number of words> Decreases sp by 4 * <number of words>, sets pc to the value at address sp, pops one more word from the stack, and finally resumes execution

Ports

Wee Machine supports peripherals like keyboard, mouse or graphics card. The processor communicate with these peripherals via ports. Each peripheral is assigned a port number through which the processor can read or write from and to the peripheral. Each peripheral has its own protocol through which it communicates with the processor.

Port operations are 1 or 2-words wide and have the following format:

bits 0-5 bits 6-9 bits 10-13 bits 14-31 bits 32-63
Opcode Register (op1) Register (op2) Port number Value (word2)

The following port operations are available:

Opcode Assembly Semantics
0x39 port_write op1, <port number> Write the 32-bit value in op1 to port <port number>
0x3a port_write word2, <port number> Write the 32-bit value word2 to port <port number>
0x3b port_write op2, op2 Write the 32-bit value in op1 to port op2
0x3c port_read <port number>, op1 Read the 32-bit value from port <port number> and store it in op1. The operation may block until the peripheral has completed its work.
0x3d port_read op1, op2 Read the 32-bit value from port op1 and store it in op2. The operation may block until the peripheral has completed its work.

Unused opcodes

All opcodes are encoded in the first 6 bits of an instruction. The instruction set ocupies opcodes 0x00 to 0x3d, leaving only opcode 0x3f unused. This opcode may be used in the future and is reserved.

Peripherals

Wee Machine simulates a system with a keyboard, mouse, graphics card, sound card and networking card. These peripherals are heavily simplified to make working with them simple enough for beginners. The following sections describe the peripheral capabilities and their respective port protocols.

Keyboard

TBD

Mouse

TBD

Graphics Card

TBD

Sound Card

TBD

Networking Card

TBD

Random number generator

TBD

High precision timer

TBD

BIOS

Wee Machine comes with a minimal BIOS that makes interacting with peripherals easier. The BIOS is composed of functions that are co-located in memory with the user code. The assembler knows the addresses of each BIOS function so a programmer can directly reference the function labels in their assembly program. The following sections describe the functions provided by the BIOS.

TBD

Bootup & Memory Layout

When Wee Machine boots up, it reserves the memory area 0xff0000 to 0xffffff for the stack, the area 0xfb1800 to 0xfeffff for the memory mapped video memory (320x200 pixels, 32-bit RGBA), and the area (0xfb1800 - BIOS code size) to 0xfb17ff for the BIOS code. Next, the program is loaded into memory at 0x000000 and executed. The BIOS can manage the unused memory between the program code & data and the BIOS code and provides functions to allocate and deallocate memory in this memory area. Programmers can choose to manage that memory themselves.