Version 1.0.0-Alpha

The EXA Architecture Specification can be divided by the following sections:

Values

An EXA can handle two types of values:

  • Signed Integers: A normal four byte signed integer that wraps around when reaching its minimum or maximum number.
  • Strings: A normal string encoded in UTF-8.

Those data types are supported by everything that an EXA can use, from registers, files and even links, see the Binary values representations section for more details on the binary format representation for the datatypes.

Registers

An EXA has four registers:

  • The X register: This register is a general purpose register, it’s intended for arithmetic and temporal storage purposes.
  • The T register: This register is a test register, the register can be used as the X register, but, when some testing instruction is executed, this register will be the container for the instruction’s result, see the TEST instruction for more information.
  • The F register: This register is an special register, when an EXA is holding a file, this register will represent the currently pointing value of the file, if any read or write operation to this register occurs, this register will read or write the value to the file, by default, when some operation to a file occurs, the file pointer will jump one place forward.
  • The M register: This register is an special register, when an EXA writes a value to this register, it will be transmitted to the current host or network for other EXAs to be received, if no one reads the broadcasted value, the EXA that transmits the information will block until any EXA reads from it. The scope of this register can be controlled with the TMOD and FMOD instructions.

Files

A file is just an array of values stored in the network’s RAM, these arrays can be holded by an EXA for temporal storage purposes on a host, a file can have a name, but, this name is only within the scope of a network and an EXA, when the file is stored as a real file on some real host’s file system, this name is subjected by the file saving mechanism of the host.

Invalid Operations

An invalid operation is an operation that an EXA tries to perform, but, for whatever reason, is not possible to perform, such operations can be a file reading operation when the internal pointer of the file is pointing to the end of the file or trying to travel through a link that doesn’t exists, such invalid operations should be handled killing the EXA instantly.

Bytecode

List of assembly instructions, based on the original EXAPUNKS game with abbreviations:

  • R: Register
  • R/N: Register or Number
  • L: Address or Label inside the bytecode
  • O: Logical operator: ==, <, >, <=, >=, !=, MRD (M Ready), EOF (End of File)

Instructions:

  • COPY R/N R: Copy a value from the first operand to the second operand.
  • ADDI R/N R/N R: Add the two first operands and store the result in the third operand.
  • SUBI R/N R/N R: Substract the two first operands and store the result in the third operand.
  • MULI R/N R/N R: Multiply the two first operands and store the result in the third operand.
  • DIVI R/N R/N R: Divide the two first operands and store the result in the third operand.
  • SWIZ R/N R/N R: Swizzle the value of the first operand using the second operand as a mask and store the result in the third operand. The mask has to be a digit representing the positions of numbers in the first operand, examples: (6436 SWIZ 1234 = 6346), (7482 SWIZ 4231 = 7842), (720643 SWIZ 645312 = 702634).
  • MARK L: This instruction is only available in the assembler, this assembler directive will create a label that in assembly will be translated in the mark’s address wherever the label is called.
  • JUMP L: Jump to an address or a label.
  • TJMP L: If the T register equals to 1, this instruction will jump to the specified label or address.
  • FJMP L: If the T register equals to 0, this instruction will jump to the specified label or address.
  • TEST R/N O R/N: Compares the first and third operand using the second operand as a logical operator. This instruction will only work with normal operators and not with the MRD and EOF operators.
  • TEST O: Tests the given operand, this instruction will work only with the MRD and EOF operators.
  • REPL L: Replicate this EXA and point the program counter of the copy to the specified label or address. If the original EXA is holding a file, this file will not be replicated.
  • HALT: Kill the EXA that executes this instruction.
  • KILL R/N: Kill the EXA specified by the first operand. This instruction can work only inside of the scope of a network and cannot traverse external links.
  • EPID: Get this EXA’s process id.
  • LINK R/N: Traverse a link inside the network, if the link is an external link, the EXA will be stopped and sended across that external link, exiting the current network domain.
  • HOST R: Copy the current host’s name to the first operand.
  • TMOD: Enable global mode for the M register.
  • FMOD: Disable global mode for the M register.
  • VOID R: Discard the value from the specified register.
  • MAKE: Create a new file and hold it on the F register.
  • GRAB R/N: Grab a file from the current host.
  • FILE R: Copy the currently held file’s name.
  • RENM R/N: Rename the currently held file.
  • SEEK R/N: Change the currently held file’s pointer by the first operand.
  • DROP: Drop the currently held file.
  • WIPE: Wipe the currently held file.
  • NOTE: This is not an instruction, this assembler operand is used to write comments on the code.
  • NOOP: No operation.
  • RAND R/N R/N R: Generate a random number between the first two operands and store the result in the third operand.
  • CHTN R/N R: Converts a single character to its numerical representation. The conversion uses as the input, one UTF-8 character and the conversion output should be a four byte integer representation of said character.
  • NTCH R/N R: Converts a integer into the equivalent character in UTF-8. Like in the CHTN instruction, this instruction chould make a reverse conversion from a four byte integer to its UTF-8 representation.
  • EXCH R/N R/N R: Extracts a single character from the first operand using the second operand as the character index, then, the result will be saved into the third operand.
  • STCH R/N R/N R/N: Sets a character stored in the first operand, using the second operand as the index and the third operand as the destination string.

Bytecode list by instruction name

COPY

  • Representation: 0x01
  • Amount of arguments: 2 (Origin: R/N, Destination: R)

ADDI

  • Representation: 0x10
  • Amount of arguments: 3 (First Operand: R/N, Second Operand: R/N, Destination: R)

SUBI

  • Representation: 0x11
  • Amount of arguments: 3 (First Operand: R/N, Second Operand: R/N, Destination: R)

MULI

  • Representation: 0x12
  • Amount of arguments: 3 (First Operand: R/N, Second Operand: R/N, Destination: R)

DIVI

  • Representation: 0x13
  • Amount of arguments: 3 (First Operand: R/N, Second Operand: R/N, Destination: R)

SWIZ

  • Representation: 0x14
  • Amount of arguments: 3 (First Operand: R/N, Masking Operand: R/N, Destination: R)

JUMP

  • Representation: 0x20
  • Amount of arguments: 1 (Jump address: Four byte unsigned integer)

TJMP

  • Representation: 0x21
  • Amount of arguments: 1 (Jump address: Four byte unsigned integer)

FJMP

  • Representation: 0x22
  • Amount of arguments: 1 (Jump address: Four byte unsigned integer)

TEST

Normal mode
  • Representation: 0x23
  • Amount of arguments: 3 (First Operand: R/N, Condition: O, Second Operand: R/N)
Mono mode
  • Representation: 0x24
  • Amount of arguments: 1 (Condition: O)

REPL

  • Representation: 0x25
  • Amount of arguments: 1 (Duplicate jump address: Four byte unsigned integer)

HALT

  • Representation: 0xFF
  • Amount of arguments: 0

KILL

  • Representation: 0xFE
  • Amount of arguments: 1 (EPID Operand: R/N)

EPID

  • Representation: 0xFD
  • Amount of arguments: 0
  • Representation: 0x30
  • Amount of arguments: 1 (Link Operand: R/N)

HOST

  • Representation: 0x02
  • Amount of arguments: 1 (Destination Operand: R)

TMOD

  • Representation: 0x03
  • Amount of arguments: 0

FMOD

  • Representation: 0x04
  • Amount of arguments: 0

VOID

  • Representation: 0x05
  • Amount of arguments: 1 (Register Operand: R)

MAKE

  • Representation: 0x40
  • Amount of arguments: 0

GRAB

  • Representation: 0x41
  • Amount of arguments: 1 (File Name Operand: R/N)

FILE

  • Representation: 0x42
  • Amount of arguments: 1 (Register Operand: R)

RENM

  • Representation: 0x43
  • Amount of arguments: 1 (New File Name Operand: R/N)

SEEK

  • Representation: 0x44
  • Amount of arguments: 1 (Positions Operand: R/N)

DROP

  • Representation: 0x45
  • Amount of arguments: 0

WIPE

  • Representation: 0x46
  • Amount of arguments: 0

NOOP

  • Representation: 0x00
  • Amount of arguments: 0

RAND

  • Representation: 0x15
  • Amount of arguments: 3 (Minimum Operand: R/N, Maximum Operand: R/N, Destination Operand: R)

CHTN

  • Representation: 0x50
  • Amount of arguments: 2 (Source Character: R/N, Destination Register: R)

NTCH

  • Representation: 0x51
  • Amount of arguments: 2 (Source Number: R/N, Destination Register: R)

EXCH

  • Representation: 0x52
  • Amount of arguments: 3 (Source Text: R/N, Character Index: R/N, Destination Register: R)

STCH

  • Representation: 0x53
  • Amount of arguments: 3 (Source Character: R/N, Character Index: R/N, Destination Text: R/N)

Binary representations

The EXA architecture has some binary representations for storaging purposes.

Values binary representations

The internal values that an EXA can use, has to be represented as follows:

At the start of the data, there is a byte that if is set to 0xFF, this will mean that the value its a string, if it is 0x00, it will be a signed integer.

String

If the value its a string, the first four bytes will be the length of the string, the following bytes will be the actual string, the string has to be encoded in UTF-8.

Signed Integer

If the value its a signed integer, the following four bytes will be the actual integer.

Register binary representation

This is only used within the bytecode alone, the registers will be represented inside the bytecode as follows:

Logical operator binary representation

This is only used within the bytecode alone, the logical operators are used by the TEST instructions for computing a logical result based on the operator supplied in the second or first operand, the logical operators are represented as follows:

  • ==: 0x10
  • <: 0x11
  • >: 0x12
  • <=: 0x13
  • >=: 0x14
  • !=: 0x15
  • MRD: 0x16
  • EOF: 0x17

See the Bytecode section for more details.

File binary representation

A file is represented first by a header encoded in US-ASCII with the text ‘EXA-FILE’, then follows a four byte integer representing the number of values that the file has, and lastly, the following bytes will be the raw binary representation of the values stored in the file.

Compiled EXA binary representation

This format is used for storing a compiled EXA or for transmiting an EXA accross an external link, like the file binary representation, the header will be an 8 byte string encoded in US-ASCII with the text ‘EXA-CODE’, then, the default values for the X and T registers will be stored as a normal value, then, follows the M register default operation mode as a byte, 0xFF will mean that the global mode is enabled, and 0x00 will mean that the global mode is disabled, then, will follow the actual bytecode chunk, the first four bytes will represent the size of the bytecode, and then, the actual compiled bytecode will follow, if the EXA is holding a file, the next chunk of data will be the file’s binary representation.

Networks

The networks are an essential part of the EXA system, without this, the whole EXA system will have no sense, a network is a collection of interconnected hosts, those hosts are places that can contain objects like EXAs, files and external registers.

Hosts

The hosts are the building blocks for a network, a host can store objects like EXAs, files and external registers, unlike the EXAPUNKS game, a host has no size limitations.

Other EXAs

A network can have other EXAs that can be from the own network ro can be from another network, those EXAs like any other EXA, can execute instructions inside the network.

External Registers

A external register, is a register that is inside a host instead of an EXA, those registers are subjected to any kind of algorithm that the own network implements, these regfisters works exactly like a basic register, but, the binary representation for it on the bytecode has to be an eight byte US-ASCII encoded string, by this rule of thumb, the name of the register on the host has to follow that same rule.

A link is not exactly an object like a file or an EXA, the links are used for providing a path to pass over another host inside the network, to pass to another network, see the External Links section.

A external link works like a normal link, but, this link instead of providing a way to go to another host, this link can provide a custom gateway to transmit an EXA to another network, those networks can be another instance of an EXA virtual machine, an embedded device or a server located in a distant place, those links has to be implemented like the external registers to provide a mechanism to transmit correctly the said EXA to another network. Take into account that when an EXA travels to another network, there is not any guarantee that the EXA will be executed on the remote network or that the EXA will come back, also, the M register will not work accross networks, so, you cannot communicate from the remote network, this register only works inside the domain of a network.