Crate ternaria_isa 

The Ternaria instruction set (D-05, D-15).

Source of truth

The instruction set is declared once, in the isa! invocation below. The Opcode enum, the mnemonic table, the encoder, the decoder and the disassembler are generated from that declaration, so they cannot disagree.

Both a match and a table are generated. The interpreter uses the match, which compiles to a jump table. The assembler and disassembler use the table, which can be enumerated and searched.

Encoding

Fixed 27 trits, one word per instruction, no exceptions (D-05). Fields run from the least significant trit up:

  trit  0 ..  6   opcode    6 trits, +/-364
  trit  6 ..  9   rd        3 trits, +/-13
  trit  9 .. 12   rs1       3 trits, +/-13
  trit 12 .. 15   rs2       3 trits, +/-13
  trit 15 .. 27   imm      12 trits, +/-265,720

The 12-trit immediate covers +/-265,720. For comparison, RISC-V’s 12-bit immediate covers +/-2,048.

Registers

The register field is three balanced trits, so registers are numbered r-13 through r13, with r0 in the middle. r0 reads as zero and discards writes.

Undefined opcodes

Negative opcode values, 364 encodings, are reserved for future extension. Defined instructions occupy zero and up. Both reserved and undefined opcodes trap (D-15).

The immediate

Width is 12 trits in every format that uses one. There is no short form.

The value is a signed balanced integer covering +/-265,720. An unsigned immediate is not encodable, since a balanced ternary field carries sign in its digits.

Sign extension does not apply. Widening a 12-trit field to a 27-trit word sets the upper fifteen trits to zero, which is the only possible reading.

br3 uses its immediate in both directions: the positive branch adds it and the negative branch subtracts it, so the two targets are mirrored about the branch. Where the targets cannot be mirrored, use brn and brp, which take one target each over the full immediate range.

Units differ per instruction and are recorded in the table as ImmUnit:

Unit	Instructions	Meaning
ImmUnit::Instructions	jal, jalr, br3, brz	Whole instructions. The interpreter scales by 3 trytes, so branch targets are word-aligned by construction. Reach is +/-797,160 trytes.
ImmUnit::Trytes	lw, sw	Displacement from the base register, in addressable units.
ImmUnit::Trits	shl, shr	Shift distance, an exponent of three.
ImmUnit::Value	addi	A plain operand.
ImmUnit::None	everything else	Field unused; must be zero.

The program counter

pc is the tryte address of the instruction being executed. It advances by 3 trytes, one word, after every instruction that does not redirect it. Control-flow immediates count instructions, so pc += imm in a summary below means pc += 3 * imm trytes.

Modules

asm

A small text assembler.

Structs

Entry

One row of the instruction table.

Imm

A 12-trit immediate, +/-265,720.

Instruction

A decoded instruction.

Reg

An architectural register, numbered -13 through 13.

Enums

DecodeError

Why a word is not a valid instruction.

Format

Which fields an instruction actually uses.

ImmUnit

What an instruction’s immediate counts.

Opcode

Every defined operation.

Constants

IMM_MAX

Largest magnitude a 12-trit immediate can hold: (3^12-1)/2.

REG_COUNT

Number of architectural registers: 3^3.

REG_MAX

Largest magnitude a 3-trit register field can hold: (3^3-1)/2.

TABLE

The instruction table. Enumerable, unlike a match. Read by the assembler, the disassembler and the documentation.

WORD_TRYTES

Trytes per instruction. An instruction is one word and a word is three trytes, so a label’s address is its instruction index times this.