Registers & Stack

Overview

The NCS/e CPU provides general-purpose integer and string registers, special-purpose registers, a value stack for temporary storage, and a dedicated call stack for subroutine execution.

Integer and string registers provide the primary working storage used by NCL instructions. The value stack provides temporary integer storage, while the call stack separately tracks return addresses for CALL and RET.

Integer registers

The CPU provides 32 general-purpose integer registers named r0 through r31.

Integer registers may be used as destinations for arithmetic, bit manipulation, branching, and peripheral operations.

Register Purpose
r0–r31 General-purpose integer registers.

MOVE — Copy Integer

MOVE <dst> <src>

Copies an integer value into the destination register.

Operands

Position Name Type Range Description
1 dst Integer register — Destination register.
2 src Integer value — Value to copy.

Modified registers

Register Description
dst Copied value.

Examples

-- Copy a literal.
MOVE r0 42
-- > r0 = 42

-- Copy a register.
MOVE r1 r0
-- > r1 = r0

SWAP — Swap Integers

SWAP <lhs> <rhs>

Exchanges the contents of two integer registers.

Operands

Position Name Type Range Description
1 lhs Integer register — First register.
2 rhs Integer register — Second register.

Modified registers

Register Description
lhs Swapped value.
rhs Swapped value.

Examples

-- Exchange two registers.
SWAP r0 r1
-- > r0 and r1 are exchanged

String registers

The CPU provides 16 general-purpose string registers named s0 through s15.

String registers store UTF-16 text and are used by string and peripheral instructions.

Register Purpose
s0–s15 General-purpose string registers.

SMOVE — Copy String

SMOVE <dst> <src>

Copies a string value into the destination register.

Operands

Position Name Type Range Description
1 dst String register — Destination register.
2 src String value — Value to copy.

Modified registers

Register Description
dst Copied value.

Examples

-- Copy a literal.
SMOVE s0 "Hello"
-- > s0 = "Hello"

-- Copy a register.
SMOVE s1 s0
-- > s1 = s0

SSWAP — Swap Strings

SSWAP <lhs> <rhs>

Exchanges the contents of two string registers.

Operands

Position Name Type Range Description
1 lhs String register — First register.
2 rhs String register — Second register.

Modified registers

Register Description
lhs Swapped value.
rhs Swapped value.

Examples

-- Exchange two registers.
SSWAP s0 s1
-- > s0 and s1 are exchanged

Special registers

The CPU provides four special-purpose registers.

Register Type Description
pc Integer Program counter.
sp Integer Value stack pointer.
sv Integer Top value on the stack.
er String Error register.

pc

Contains the index of the next program line to be executed. Control-flow instructions modify this register.

sp

Contains the index of the next free entry in the value stack.

sp is read-write. Programs may modify it directly to reposition the stack pointer.

Values written to sp are clamped to the valid stack range.

Property Value
Range 0–128
Write behavior Clamped

sv

Provides direct read-write access to the top value of the value stack without modifying sp.

Writing to sv replaces the current top value.

PUSH 10
MOVE sv 20
POP r0
-- > r0 = 20

If sp is 0, there is no current top value. Reading from or writing to sv causes a fatal stack underflow and immediately returns control to the shell.

er

Stores the most recent error generated by an instruction, peripheral, or program.

Fatal errors also set er, but immediately terminate execution and return control to the shell. The running program cannot inspect or handle a fatal error.

Value stack

The CPU provides a 128-entry LIFO (last-in, first-out) stack for temporary integer storage.

The stack pointer sp identifies the next free stack position. The special register sv provides direct access to the current top value without removing it.

Property Value
Capacity 128 entries
Stores Integers

Value pushed onto the stack are removed in the reversed order: the most recently pushed value is the first value returned by POP.

PUSH 10
PUSH 20
POP r0
POP r1

-- > r0 = 20
-- > r1 = 10

Stack registers

Register Description
sp Index of the next free stack position.
sv Value at the top of the value stack.

PUSH stores a value at sp and then increments sp. POP decrements sp and then retrieves the value at that position.

sv provides direct read-write access to the value immediately below sp:

sv = stack[sp - 1]

Because sp is writable, programs may reposition the stack pointer directly. Values written to sp are clamped to the range 0–128.

Reading or writing sv while sp is 0 is a fatal stack underflow.

Stack overflow and underflow are fatal errors. Execution is aborted and control returns to the shell.

PUSH — Stack Push

PUSH <val>

Pushes an integer value onto the value stack.

Operands

Position Name Type Range Description
1 val Integer value — Value to be pushed.

Modified registers

Register Description
sp Incremented by one.
sv References the pushed value.

Examples

-- Save a register.
PUSH r0
-- > r0 is pushed onto the stack

-- Push a literal.
PUSH 42
-- > 42 is pushed onto the stack

Notes

  • Stack overflow is a fatal error.
  • Execution is aborted and control returns to the shell.

POP — Stack Pop

POP <dst>

Removes the top value from the value stack and stores it in the destination register.

Operands

Position Name Type Range Description
1 dst Integer register — Destination register.

Modified registers

Register Description
dst Popped value.
sp Decremented by one.
sv References the new top value.

Examples

-- Restore a register.
POP r0
-- > r0 receives the top stack value

Notes

  • Stack underflow is a fatal error.
  • Execution is aborted and control returns to the shell.

Call stack

Subroutine return addresses are stored on a separate call stack. The call stack is not affected by PUSH, POP, sp and sv.

See Branching forCALL, RET, and call-stack behaviour.