isa

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 29, 2025 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package isa provides instruction set architecture

Index

Constants

View Source
const (
	// ErrBadInstruction is raised when a call to isa.New can't succeed due to
	// either missing or excessive operands
	ErrBadInstruction = "instruction operand mismatch: %s"

	// ErrExpectedOperand is raised when an Operand isn't represented by an
	// unsigned Word that will fit within the number of Operand bits
	ErrExpectedOperand = "expected unsigned operand: %d"
)
View Source
const (
	// OpcodeSize are the number of bits required for an Opcode value
	OpcodeSize = 7

	// OpcodeMask masks the bits for encoding an Opcode into an Instruction
	OpcodeMask = Opcode(1<<OpcodeSize - 1)

	// OperandMask masks the bits for encoding an Operand into an Instruction
	OperandMask = ^Operand(OpcodeMask) >> OpcodeSize
)
View Source
const ErrEffectNotDeclared = "effect not declared for opcode: %s"

ErrEffectNotDeclared is raised when an attempt to forcefully retrieve an Effect fails

Variables

View Source
var Effects = map[Opcode]*Effect{

	Label: {Ignore: true, Operand: Labels},
	NoOp:  {Ignore: true},

	Arg:        {Push: 1, Operand: Arguments},
	ArgsLen:    {Push: 1},
	ArgsPop:    {},
	ArgsPush:   {DPop: true, Operand: Arguments},
	ArgsRest:   {Push: 1, Operand: Arguments},
	Closure:    {Push: 1, Operand: Captured},
	EnvBind:    {Pop: 2},
	EnvPrivate: {Pop: 1},
	EnvPublic:  {Pop: 1},
	EnvValue:   {Pop: 1, Push: 1},

	Load:     {Push: 1, Operand: Locals},
	NewRef:   {Push: 1},
	RefBind:  {Pop: 2},
	RefValue: {Pop: 1, Push: 1},
	Store:    {Pop: 1, Operand: Locals},

	Const: {Push: 1, Operand: Constants},
	Dup:   {Pop: 1, Push: 2},
	False: {Push: 1},
	Null:  {Push: 1},
	Pop:   {Pop: 1},
	Swap:  {Pop: 2, Push: 2},
	True:  {Push: 1},
	Zero:  {Push: 1},

	Call:     {Pop: 1, Push: 1, DPop: true, Operand: Stack},
	Call0:    {Pop: 1, Push: 1},
	Call1:    {Pop: 2, Push: 1},
	Call2:    {Pop: 3, Push: 1},
	Call3:    {Pop: 4, Push: 1},
	CallSelf: {Push: 1, DPop: true, Operand: Stack},
	CallWith: {Pop: 2, Push: 1},
	TailCall: {Pop: 1, DPop: true, Operand: Stack},
	TailClos: {Pop: 1, DPop: true, Operand: Stack},
	TailSelf: {DPop: true, Operand: Stack},

	CondJump: {Pop: 1, Operand: Labels},
	Delay:    {Pop: 1, Push: 1},
	Jump:     {Operand: Labels},
	Panic:    {Pop: 1, Exit: true},
	RetFalse: {Exit: true},
	RetNull:  {Exit: true},
	RetTrue:  {Exit: true},
	Return:   {Pop: 1, Exit: true},

	Append:  {Pop: 2, Push: 1},
	Assoc:   {Pop: 2, Push: 1},
	Car:     {Pop: 1, Push: 1},
	Cdr:     {Pop: 1, Push: 1},
	Cons:    {Pop: 2, Push: 1},
	Dissoc:  {Pop: 2, Push: 1},
	Empty:   {Pop: 1, Push: 1},
	Get:     {Pop: 2, Push: 2},
	LazySeq: {Pop: 1, Push: 1},
	Length:  {Pop: 1, Push: 1},
	Nth:     {Pop: 2, Push: 2},
	Reverse: {Pop: 1, Push: 1},
	Vector:  {Push: 1, DPop: true, Operand: Stack},

	Eq:  {Pop: 2, Push: 1},
	Not: {Pop: 1, Push: 1},

	Add:    {Pop: 2, Push: 1},
	Div:    {Pop: 2, Push: 1},
	Mod:    {Pop: 2, Push: 1},
	Mul:    {Pop: 2, Push: 1},
	Neg:    {Pop: 1, Push: 1},
	NegInt: {Push: 1, Operand: Integer},
	NumEq:  {Pop: 2, Push: 1},
	NumGt:  {Pop: 2, Push: 1},
	NumGte: {Pop: 2, Push: 1},
	NumLt:  {Pop: 2, Push: 1},
	NumLte: {Pop: 2, Push: 1},
	PosInt: {Push: 1, Operand: Integer},
	Sub:    {Pop: 2, Push: 1},
}

Effects is a lookup table of instruction effects

Functions

func IsValidOperand

func IsValidOperand(i int) bool

IsValidOperand returns true if the int falls within the operand range

Types

type ActOn

type ActOn int
const (
	Nothing ActOn = iota
	Arguments
	Captured
	Constants
	Integer
	Labels
	Locals
	Stack
)

type Effect

type Effect struct {
	Operand ActOn // Describe element the operand acts on

	Pop  int // A fixed number of items to be popped from the stack
	Push int // A fixed number of items to be pushed onto the stack

	DPop   bool // Dynamic number of items to be popped (in operand)
	Ignore bool // Skip this instruction (ex: Labels and NoOps)
	Exit   bool // Results in a termination of the abstract machine
}

Effect captures how an Instruction impacts the state of the machine

func GetEffect added in v0.3.0

func GetEffect(oc Opcode) (*Effect, error)

func MustGetEffect

func MustGetEffect(oc Opcode) *Effect

MustGetEffect gives you effect information or explodes violently

type Instruction

type Instruction Word

Instruction represents a single instruction and its operand

func (Instruction) Equal

func (i Instruction) Equal(other ale.Value) bool

Equal compares this Instruction to another for equality

func (Instruction) Opcode

func (i Instruction) Opcode() Opcode

func (Instruction) Operand

func (i Instruction) Operand() Operand

func (Instruction) Split

func (i Instruction) Split() (Opcode, Operand)

func (Instruction) StackChange

func (i Instruction) StackChange() (int, error)

func (Instruction) String

func (i Instruction) String() string

type Instructions

type Instructions []Instruction

Instructions represent a set of Instructions

func (Instructions) String

func (i Instructions) String() string

type Opcode

type Opcode Word

Opcode represents an Instruction's operation

const (
	// Ignored Opcodes
	Label Opcode = iota // Marks a label (not executed)
	NoOp                // No operation

	// Argument, Environment and Closure Operations
	Arg        // Push the Nth argument (op = index)
	ArgsLen    // Push the number of arguments
	ArgsPop    // Pop argument stack, restore previous arguments
	ArgsPush   // Push argument stack, replace with popped values (op = count)
	ArgsRest   // Push remaining arguments as a vector (op = start index)
	Closure    // Push captured value (op = index)
	EnvBind    // Pop local and value, binds value to local in namespace
	EnvPrivate // Pop local, mark as private in namespace
	EnvPublic  // Pop local, mark as public in namespace
	EnvValue   // Pop local, resolve it from namespace

	// Reference and Register Operations
	Load     // Push local value (op = index)
	NewRef   // Push a new unbound Ref
	RefBind  // Pop ref and value, sets ref.Value to value
	RefValue // Pop ref, push ref.Value
	Store    // Pop value, store in local (op = index)

	// Stack and Constant Operations
	Const // Push constant (op = index)
	Dup   // Push a duplicate of the top of the stack
	False // Push the boolean false
	Null  // Push the null value
	Pop   // Pop (discard) the top of the stack
	Swap  // Swap the top two values on the stack
	True  // Push the boolean true
	Zero  // Push the integer zero

	// Call Operations
	Call     // Pop proc, pop N args, call proc, push result (op = count)
	Call0    // Pop proc, call with zero args, push result
	Call1    // Pop proc, pop 1 arg, call proc, push result
	Call2    // Pop proc, pop 2 args, call proc, push result
	Call3    // Pop proc, pop 3 args, call proc, push result
	CallSelf // Pop N args, call current closure (op = count)
	CallWith // Pop proc, pop sequence, call proc with seq values
	TailCall // Pop proc, pop N args, dynamic tail call (op = count)
	TailClos // Pop closure, pop N args, tail call (op = count)
	TailSelf // Pop N args, tail call (op = count)

	// Control Flow Operations
	CondJump // Pop value, if not false, jump to operand
	Delay    // Pop proc, wrap as promise, push promise
	Jump     // Jump to operand
	Panic    // Pop value, raise as error from VM
	RetFalse // Return the boolean false from VM
	RetNull  // Return the null value from VM
	RetTrue  // Return the boolean true from VM
	Return   // Pop value, return value from VM

	// Sequence Operations
	Append  // Pop value, pop sequence, append value to sequence, push result
	Assoc   // Pop pair, pop mapper, associate pair with mapper, push result
	Car     // Pop pair, push pair's Address (car) part
	Cdr     // Pop pair, push pair's Decrement (cdr) part
	Cons    // Pop car, pop cdr, push new cons cell
	Dissoc  // Pop key, pop mapper, dissociate key from mapper, push result
	Empty   // Pop sequence, push true if sequence is empty
	Get     // Pop key, pop mapper, push found status and value from mapper
	LazySeq // Pop proc, wrap as lazy sequence, push lazy sequence
	Length  // Pop sequence, push sequence length
	Nth     // Pop index, pop indexed, push from status and value from indexed
	Reverse // Pop sequence, push reversed sequence
	Vector  // Pop N values, push as a vector (op = count)

	// Boolean Operations
	Eq  // Pop two values, push true if equal
	Not // Pop value, push boolean negation of value

	// Numeric Operations
	Add    // Pop two numbers, push their sum
	Div    // Pop two numbers, push their quotient
	Mod    // Pop two numbers, push the remainder of division
	Mul    // Pop two numbers, push their product
	Neg    // Pop number, push negated value of number
	NegInt // Push negative integer (int = operand)
	NumEq  // Pop two numbers, push true if equal
	NumGt  // Pop two numbers, push true if second > first
	NumGte // Pop two numbers, push true if second >= first
	NumLt  // Pop two numbers, push true if second < first
	NumLte // Pop two numbers, push true if second <= first
	PosInt // Push positive integer (int = operand)
	Sub    // Pop two numbers, push their difference
)

func (Opcode) New

func (o Opcode) New(ops ...Operand) Instruction

New creates a new Instruction instance from an Opcode

func (Opcode) String

func (i Opcode) String() string

type Operand

type Operand Word

Operand allows an Instruction to be parameterized

type Runnable

type Runnable struct {
	Constants  data.Vector
	Globals    env.Namespace
	Code       Instructions
	LocalCount Operand
	StackSize  Operand
}

Runnable is a finalized representation of the Encoded state that can be executed by the abstract machine

type Word

type Word uintptr

Word represents the atomic unit of the ISA's Instruction stream. We've chosen a size that best aligns to the host architecture's standard word size for alignment reasons

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL