isa-insn.tex

\input _macros

\title{Instructions}

\def\ins{{\tt I}}
\def\rg#1,#2.{$[#1:#2]$}
\def\ix#1{$[#1]$}

\chapter{\ass\ 16}

The following is the encoding of \ass\ 16, a 16-bit instruction-symbol ISA.
Values are given in their natural (big-endian) representation, such that in
\code{0xABCD}, \code{A} is the most significant digit.

\bigskip
{
	\halign{#\qquad&&\hbox to2em{\hss#\hss}\cr
		Hex&A&&&&B&&&&C&&&&D&&&\cr
		Bit&a&a&a&a&b&b&b&b&c&c&c&c&d&d&d&d\cr
		Index&15&14&13&12&11&10&9&8&7&6&5&4&3&2&1&0\cr
	}
}
\bigskip

C syntax is used in explications; familiarity with it is assumed. Ranges
\rg a,b. are sorted with $a > b$, and such that it is inclusive on $b$ but
exclusive on $a$ (thus indices are in the interval $[b, a)$, equivalently for
index $i: b \le i < a$). This notation is {\it not} consistent with Verilog
(which uses both indices inclusive), but {\it is} consistent with Python
(albeit reversed), and conveniently means that the size of the extracted
bitstring is $a - b$.

The following sections assume that the instruction word is \ins.

\ass\ 16 has 16 General-Purpose Registers (GPRs). Where an instruction encodes
4 bits for a ``register'', and implicitly refers to its value within the
description, this should be taken to be the value stored {\it within} the
register so numbered. All registers can be accessed in this fashion, but
\reg{R0} is the Program Counter (\reg{PC}), so its value will be used to fetch
the next instruction---thus, programs with linear control flow should not use
this register. (It can be used, of course, to branch or jump.) See the calling
convention document for details.

The GPRs are not to be confused with the SRs, System Registers, which are far
less frequently accessed; see that section for details.

\vfil \break

\section{Distinguished Exception Generator}

\noindent\ins\rg 16,0. \code{== 0}

Enter the exception handling routine with cause \reg{SR 9} \code{== 1}, if
interrupts are enabled. Otherwise, do nothing.

\section{Exception Return}

\noindent\ins\rg 16,0. \code{== 1}

Reverse the architectural exception routine, atomically. Specifically, this:

\li Sets \reg{PC} to \reg{SR 8} (the Exception Continuation register); and
\li Clears \reg{SR 63}, enabling interrupts;

all in one instruction, thus preventing a race between either of these actions.

(Non-exceptional returns are better handled by either moving from the
ABI-defined Continuation Register, or ``popping'' from the ABI-defined stack,
into PC, using the \code{XF} Data Transfer instruction. See that instruction
and the calling convention for details.)

\section{Bitwise Instructions}

\noindent\ins\rg 16,12. \code{== 0b0001}

\li \ins\rg 4,0. (\reg{D}) Destination Register, LHS (0--15)
\li \ins\rg 8,4. (\reg{S}) Source Register, RHS (0--15)
\li \ins\rg 12,8. (\code{M}) Truth Table Number (0--15)

Cf. \underbar{https://en.wikipedia.org/wiki/Truth\_table\#Binary\_operations} .

The value \code{M} can be treated as a Look-Up Table (LUT), using a bit from
\reg{D} as the most-significant and a corresponding bit from \reg{S} as the
least-significant of an index into the 4-bit table. For convenience, the
functions are reproduced below:

\bigskip
{
	\tabskip=3pt
	\halign{&{\bf #}\hss&\hbox to4em{= #\hss}\cr
		False&0&NOR&1&Not-Conv Impl&2&Not D&3\cr
		Not Impl&4&Not S&5&XOR&6&NAND&7\cr
		AND&8&XNOR&9&S&10&Impl&11\cr
		D&12&Conv Impl&13&OR&14&True&15\cr
	}
}
\bigskip

Of these, the most useful are:

\li {\bf AND, OR, XOR, NAND, NOR, XNOR}: Traditional bitwise building blocks.

\li {\bf Not D, Not S}: Complement, either in-place or of \reg{S}.

\li {\bf S}: Implements \insn{MOV}, by copying \reg{S} to \reg{D}.

\li {\bf D}: No-op.

\li {\bf True, False}: Load all-ones or all-zeros.

The rest are variations on material implication, and useful in limited
settings.

\section{Arithmetic Instructions}

\noindent\ins\rg 16,12. \code{== 0b0010}

\li \ins\rg 4,0. (\reg{D}) Destination Register, LHS (0--15)
\li \ins\rg 8,4. (\reg{S}) Source Register, RHS (0--15)
\li \ins\rg 11,8. (\code{M}) Operation Number (0--7)
\li \ins\ix{11} (\code{Si}) Source Immediate

If \code{Si} is set, the literal 4-bit value of the \reg{S} field is to be used
as \reg{S} in the operation. Otherwise, as usual, the 4-bit field is a register
number, and that register's value is to be used as \reg{S}.

\bigskip
{
	\offinterlineskip
	\halign{&\vrule#&\strut\quad#\hfil\quad\cr
		\noalign{\hrule}
		height2pt&\omit&&\omit&&\omit&\cr
		&{\bf Mode}&&{\bf Operation}&&{\bf Note}&\cr
		height2pt&\omit&&\omit&&\omit&\cr
		\noalign{\hrule}
		height2pt&\omit&&\omit&&\omit&\cr
		&0&&Add ($D = D + S$)&&&\cr
		&1&&Sub ($D = D - S$)&&&\cr
		&2&&Shl ($D = D \ll S$, fill $0$)&&&\cr
		&3&&Shr ($D = D \gg S$, fill $0$)&&&\cr
		&4&&Asr ($D = D \gg S$, fill MSB of $D$)&&&\cr
		&5&&Rol ($D = D \triangleleft S$, rotate left)&&&\cr
		&6&&Ror ($D = D \triangleright S$, rotate right)&&&\cr
		&7&&Neg ($D = - S$, signed negation)&&&\cr
		height2pt&\omit&&\omit&&\omit&\cr
		\noalign{\hrule}
	}
}
\bigskip

\section{Comparison Instructions}

\noindent\ins\rg 16,12. \code{== 0b0011}

\li \ins\rg 4,0. (\reg{D}) Destination Register, LHS (0--15)
\li \ins\rg 8,4. (\reg{S}) Source Register, RHS (0--15)
\li \ins\ix{8} (\code{E}) Equality Test
\li \ins\ix{9} (\code{G}) Greater Test
\li \ins\ix{10} (\code{S}) Sign Flag
\li \ins\ix{11} (\code{I}) Invert Flag

The internal test is true if either:

\li \code{E} is set and $D = S$; or
\li \code{G} is set and $D > S$, where ``$>$'' is sign-respecting if \code{S}
is set.

The final test is the internal test, or its negation if \code{I} is set.

If the final test is false, $0$ is written to \reg{D}. A nonzero value is
written if the test is true, canonically $1$.

The resulting table of operations, with some redundancy, is as follows, with
``Above''/``Below'' being interpreted as unsigned comparison, and
``Greater''/``Less'' as signed:

\bigskip
{
	\tabskip=3pt
	\halign{&{\bf #}\hss&\hbox to4em{= #\hss}\cr
		False&0&Equal&1&Above&2&Above/Equal&3\cr
		False&4&Equal&5&Greater&6&Greater/Equal&7\cr
		True&8&Not Equal&9&Below/Equal&10&Below&11\cr
		True&12&Not Equal&13&Less&14&Less/Equal&15\cr
	}
}
\bigskip

\section{Medium-range Jump Not Zero}

\noindent\ins\rg 16,12. \code{== 0b1000}

\li \ins\rg 8,0. (\code{S}) Signed Offset, Instructions ($-128$--$127$)
\li \ins\rg 12,8. (\reg{C}) Comparison Register (0--15)

If the value of \reg{C} is nonzero, \reg{PC} is offset by \code{S}
(specifically, \code{S * \ist} addressable units) from the {\it next}
instruction. Thus, the value of \code{S} is interpreted to be in {\it
instruction words} (typically 2 bytes for \ass\ 16 over octets).

\section{Short-range Branches}

\noindent\ins\rg 16,11. \code{== 0b11101}

\li \ins\rg 4,0. (\reg{V}) Value Register
\li \ins\rg 8,4. (\reg{C}) Jump Offset
\li \ins\ix{8}. (\code{S}) Immediate Flag
\li \ins\ix{9}. (\code{I)} Invert Flag
\li \ins\ix{10}. (\code{G}) Greater Flag

Compare the \reg{V} register with zero. If the greater flag is set, perform a
signed magnitude comparison. If the greater flag is clear, perform an equality
test. The final outcome is inverted if \code{I} is set. If the outcome is true,
add the \reg{V} register to \reg{PC} if \code{S} is clear, otherwise multiply
the number encoded as \reg{V} by \ist\ and add it to \reg{PC}.

\section{Miscellaneous Two-register Functionality}

\noindent\ins\rg 16,11. \code{== 0b11100}

\li \ins\rg 4,0. (\reg{A}) Second Register (0--15)
\li \ins\rg 8,4. (\reg{B}) Second Register (0--15)
\li \ins\rg 11,8. (\code{M}) Operation Number (0--7)

\bigskip
{
	\offinterlineskip
	\halign{&\vrule#&\strut\quad#\hfil\quad\cr
		\noalign{\hrule}
		height2pt&\omit&&\omit&&\omit&&\omit&\cr
		&{\bf Mode}&&{\bf Operation}&&{\bf Description}&&{\bf Note}&\cr
		height2pt&\omit&&\omit&&\omit&&\omit&\cr
		\noalign{\hrule}
		height2pt&\omit&&\omit&&\omit&&\omit&\cr
		&0&&Swap&&{\tt A = B, B = A}&&&\cr
		&1&&Mul&&{\tt A = A * B}&&\hfil*&\cr
		&2&&Div&&{\tt A = A / B}, fractional part&&\hfil*&\cr
		&3&&Mod&&{\tt A = A \% B}, integer part&&\hfil*&\cr
		&4&&LoadReg&&{\tt A = regs[B]}&&&\cr
		&5&&StoreReg&&{\tt regs[B] = A}&&&\cr
		&6&&Loop Indirect&&{\tt A -= 1, if A != 0 \string{ PC += B \string}}&&&\cr
		&7&&Loop&&{\tt A -= 1, if A != 0 \string{ PC += B$_{imm}$ * \ist\ \string}}&&&\cr
		height2pt&\omit&&\omit&&\omit&&\omit&\cr
		\noalign{\hrule}
	}
}
\bigskip

Entries marked with ``*'' are available only on models with a hardware
multiplier (see \reg{SR 7}).

\section{Subword Operation}

\noindent\ins\rg 16,12. \code{== 0b1001}

\li \ins\rg 4,0. (\reg{D}) Destination Register (0--15)
\li \ins\rg 8,4. (\code{Bi}) Byte Index (0--15)
\li \ins\rg 11,8. (\code{B}) Bytes (0--7)
\li \ins\ix {11}. (\code{S}) Sign Extend Flag

Selects bytes out of a word-sized register. The lowest-order byte accessed in
\reg{D} is \code{Bi}, and \code{B} bytes are accessed from it, shifted right by
\code{Bi}. If $B = 0$, 8 bytes are selected instead. If \code{S} is set, the
result is sign-extended using the highest bit of the selected subword.

This is approximately equivalent to the following assembly, with \code{B} in
\reg{A0} and \code{Bi} in \reg{A1}:

\startblock
	XF *-\reg{SP}, \reg{T0}
	XF *-\reg{SP}, \reg{T1}
	\# If $B = 0$, set \code{B} to 8.
	BIT \reg{T0}, \reg{T0}, 0  \# Load zeros
	MOV \reg{T1}, \reg{A0}
	CMP.EI \reg{T1}, \reg{T0}
	JC \reg{T1}, .window
	SI \reg{A0}, 8
{\leftskip=2em.window:\par}
	MOV \reg{T0}, \reg{A0}
	SHL \reg{T0}, \$3  \# 8 bits to a byte
	SI \reg{T1}, 1
	SHL \reg{T1}, \reg{T0}
	SUB \reg{T1}, \$1
	SHL \reg{A1}, \$3
	SHL \reg{T1}, \reg{A1}
	BIT \reg{D}, \reg{T1}, 8  \# AND
	SHR \reg{D}, \reg{A1}
{\leftskip=2em.cleanup:\par}
	XF \reg{T1}, *\reg{SP}+
	XF \reg{T0}, *\reg{SP}+
\endblock

\section{System Registers}

\noindent\ins\rg 16,13. \code{== 0b101}

\li \ins\rg 8,0. (\reg{SR}) System Register (0--255)
\li \ins\rg 12,8. (\reg{R}) General Register (0--15)
\li \ins\ix{12} (\code{W}) Write Flag

Read from \reg{SR} to \reg{R}, or write from \reg{R} to \reg{SR}.

The System Registers have a separate namespace from the General-Purpose
Registers; some are architectural constants, while others have meaning specific
to the hardware. The defined ones are as follows:

\bigskip
{
	\offinterlineskip
	\long\def\tcell#1{\vtop{\baselineskip=12pt\lineskip=1pt\lineskiplimit=0pt\hsize=3.75in\noindent#1}}
	\def\tspace#1{height#1&\omit&&\omit&&\omit&&\omit&\cr}
	\def\trule#1{
		\tspace{#1}
		\noalign{\hrule}
		\tspace{#1}
	}
	\def\tpad{\hskip2pt\relax}
	\halign{&\vrule#&\strut\tpad#\hfil\tpad\cr
		\noalign{\hrule}
		\tspace{2pt}
		&{\bf SR}&&{\bf R/W}&&{\bf Name}&&{\bf Description}&\cr
		\trule{2pt}
		&0&&R&&Model/Stepping&&\tcell{%
			\li 0: Unknown or prototype
			\li Otherwise: reserved
		}&\cr
		\trule{2pt}
		&1&&R&&Word Size&&In bits.&\cr
		\trule{2pt}
		&2&&RW&&Exception Handling Routine&&\tcell{%
			Loaded into \reg{PC} when an exception or interrupt occurs. (See
			also \reg{SR 8}, \reg{SR 9}, \reg{SR 11}, and \reg{SR 63}.)
		}&\cr
		\trule{2pt}
		&3&&W&&Power State&&\tcell{%
			\li Bit 0: Halt
			\li All other bits: reserved, write 0
		}&\cr
		\trule{2pt}
		&4&&RW&&Instructions Retired&&\tcell{%
			Counts continuously, incremented when an instruction is retired.
			Writing simply sets the counter. Initialized to 0 on reset.
		}&\cr
		\trule{2pt}
		&5&&RW&&Cycles Elapsed&&\tcell{%
			Counts the number of clock cycles elapsed, starting at 0 on reset.
			Writing simply sets the counter.
		}&\cr
		\trule{2pt}
		&6&&R&&Core Frequency&&\tcell{%
			Real frequency in $s^{-1}$ of the clock used for \reg{SR 5},
			divided by 1024 to produce a value in kibiHertz.
		}&\cr
		\trule{2pt}
		&7&&R&&ISA Extensions&&\tcell{%
			\li Bit 0: Hardware multiplier available
			\li All other bits: reserved
		}&\cr
		\trule{2pt}
		&8&&RW&&Exception Continuation&&\tcell{%
			Contains the ``next \reg{PC}'' value before the Exception Handling
			Routine (\reg{SR 2}) was entered. In \insn{JAL} terms, \reg{SR 2}
			is the \reg{P} ``Program Register'', and this register is the
			\reg{L} ``Link Register''.
		}&\cr
		\trule{2pt}
		&9&&RW&&Exception Cause&&\tcell{%
			If this is a Registered Exception (see \reg{SR 11}), this has one
			of the predefined values:
			\par\vtop{ \advance\leftskip by\parindent\noindent
				\li 0: Divide by zero
				\li 1: Illegal instruction
				\li 2: Supervisor request
			}
			\noindent Otherwise (if not a Registered Exception), the entire register
			contains the physical MMIO address of the device responsible for
			raising a hardware interrupt.
		}&\cr
		\trule{2pt}
		&10&&W&&Unofficial Debug Port&&\tcell{%
			Writing a byte will write it to stdout in most current simulators.
			Hardware implementors are allowed to ignore writes to this
			register, but it may be of some use to expose them via an external
			debugging interface.
		}&\cr
		\trule{2pt}
		&11&&RW&&Exception Status&&\tcell{%
			\li Bit 0: External exceptions enabled. When clear, any external
			exception pins are ignored. The Distinguished Exception Generator
			still interrupts as usual.
			\li Bit 1: Registered exception. If set, the Exception Cause
			\reg{SR 9} is a predefined ISA exception; otherwise, it is the MMIO
			address of the causative hardware. See that SR for details.
		}&\cr
		&63&&RW&&Exceptions Enabled&&\tcell{%
			\li Bit 0: Exceptions enabled. When clear, no exception at all is
			handled, including by the Distinguished Exception Generator, which
			is ignored. 
			\li All other bits: ignored.
			\noindent This SR contains only one bit so as to guarantee that
			enabling/disabling interrupts is atomic at the instruction level.
			In general, manipulating or even reading the other exception
			registers should be guarded with this SR set, either by the
			architecture when an interrupt is handled, or by setting this SR
			manually.
		}&\cr
		\trule{2pt}
		\trule{2pt}
		&64 -- 255&&-&&Extensions&&Reserved for extenders.&\cr
		\tspace{2pt}
		\noalign{\hrule}
	}
}
\bigskip

\section{Small Immediate}

\noindent\ins\rg 16,12. \code{== 0b1100}

\li \ins\rg 4,0. (\reg{D}) Destination Register (0--15)
\li \ins\rg 12,4. (\code{I}) Immediate (0--255)

Stores the unsigned value \code{I} into the register \reg{D}.

\section{Data Transfer}

\noindent\ins\rg 16,14. \code{== 0b01}

\li \ins\rg 4,0. (\reg{D}) Destination Register (0--15)
\li \ins\rg 8,4. (\reg{S}) Source Register (0--15)
\li \ins\rg 10,8. (\code{Dm}) Destination Mode (0--3)
\li \ins\ix{10} (\code{Di}) Destination Indirect
\li \ins\rg 13,11. (\code{Sm}) Source Mode (0--3)
\li \ins\ix{13} (\code{Si}) Source Indirect

If the corresponding indirect bit is set, the register contents are used as a
memory address, and the appropriate load/store behavior is done.

The ``mode'' determines how the register is changed before and after the
operation:

\li 0b00: No change.
\li 0b01: Autoincrement; increment the register by the number of bytes in a
word after the operation.
\li 0b10: Autodecrement: decrement the register by the number of bytes in a
word before the operation.
\li 0b11: Autopostdecrement: decrement the register by the number of bytes in a
word after the operation.

The operations, in order, are a load from \reg{S} (which may be indirect), and
a store to \reg{D} (which also may be indirect). It is possible to use any of
the modes with non-indirect access, which (for example) may be used to
implement counting loops.

\section{Long Instructions}

\noindent\ins\rg 16,12. \code{== 0b1111}

\li \ins\rg 12,8. (\code{L}) Number of instruction symbols to follow

Instructions starting with this nibble are reserved for extensions that use more than
16 bits of space for their encodings. The encoded length preserves the ability
for disassemblers, linkers, and soforth to operate around their presence structurally
if not necessarily semantically. Currently, a 32-bit format is used, with other
lengths freely available. Ultra long instruction words longer than 15*16 bits should
include as many "long instruction" header packets in their coding as necessary.

\subsection{32-bit Format}

\medskip
{
	\offinterlineskip
	\halign{&\vrule#&\tt\quad#\hfil\quad\cr
		\noalign{\hrule}
		height2pt&\omit&&\omit&&\omit&&\omit&\cr
		&0b1111&&0b0001&&A&&B&\cr
		height2pt&\omit&&\omit&&\omit&&\omit&\cr
		\noalign{\hrule}
		height2pt&\omit&&\omit&&\omit&&\omit&\cr
		&E&&F&&H&&L&\cr
		height2pt&\omit&&\omit&&\omit&&\omit&\cr
		\noalign{\hrule}
	}
}
\medskip

\li \ins\rg 32,28. \code{== 0b1111}
\li \ins\rg 28,24. \code{== 0x1} (One additional 16-bit symbol to follow)
\li \ins\rg 24,20. (\code{A})
\li \ins\rg 20,16. (\code{B})
\li \ins\rg 16,12. (\code{E}) \code{== 0x0} (Extension ID)
\li \ins\rg 12,8. (\code{F}) Operation Number (0--3)
\li \ins\rg 8,4. (\code{H})
\li \ins\rg 4,0. (\code{L})

The \code{E} field, when nonzero, is reserved for extenders.

\bigskip
{
	\offinterlineskip
	\halign{&\vrule#&\strut\quad#\hfil\quad\cr
		\noalign{\hrule}
		height2pt&\omit&&\omit&&\omit&\cr
		&{\bf Mode}&&{\bf Operation}&&{\bf Note}&\cr
		height2pt&\omit&&\omit&&\omit&\cr
		\noalign{\hrule}
		height2pt&\omit&&\omit&&\omit&\cr
		&0&&Multiply ($(H, L) = A * B)$)&&&\cr
		height2pt&\omit&&\omit&&\omit&\cr
		&1&&Divmod ($A + (H, L) / A, B = (H, L) \% B$)&&&\cr
		height2pt&\omit&&\omit&&\omit&\cr
		&2&&LoadOff (\code{A = *(B + H:L)})&&*&\cr
		height2pt&\omit&&\omit&&\omit&\cr
		&3&&StoreOff (\code{*(B + H:L) = A})&&*&\cr
		height2pt&\omit&&\omit&&\omit&\cr
		\noalign{\hrule}
	}
}
\bigskip

Notes:
\item{*} \code{H:L} is the 8-bit concatenation of the low-order fields,
interpreted as a signed 8-bit integer, specified in address units.

\maybye