iverilog/vvp/opcodes.txt

/*
 * Copyright (c) 2001 Stephen Williams (steve@icarus.com)
 *
 *  $Id: opcodes.txt,v 1.38 2002/08/27 05:39:57 steve Exp $
 */



EXECUTABLE INSTRUCTION OPCODES

Instruction opcodes all start with a % character and have 0 or more
operands. In no case are there more then 3 operands. This chapter
describes the specific behavior of each opcode, in hopefully enough
detail that its complete effect can be predicted.

General principles of Arithmetic:

The binary arithmetic instruction in general take three parameters,
the left operand, the right operand, and the base. The left operand is
replaced with the result, which is the same width as the left and
right operands.


* %add <bit-l>, <bit-r>, <wid>

This instruction adds the right vector into the left vector, the
vectors having the width <wid>. If any of the bits of either vector
are x or z, the result is x. Otherwise, the result is the arithmetic
sum.

See also the %sub instruction.

* %addi <bit-l>, <imm>, <wid>

This instruction adds the immediate value (no x or z bits) into the
left vector. The imm value is limited to 16 significant bits, but it
is zero extended to match any width.

* %and <bit-l>, <bit-r>, <wid>

Perform the bitwise AND of the two vectors, and store the result in
the left vector. Each bit is calculated independent of other bits. AND
means the following:

	0 and ? --> 0
	? and 0 --> 0
	1 and 1 --> 1
	otherwise   x

* %assign <var-label>, <delay>, <bit>
* %assign/d <var-label>, <delay>, <bit>

This does a non-blocking assignment to a variable. The <label>
identifies the affected variable, and the <delay> gives the delay when
the assignment takes place. The delay may be 0. For blocking
assignments, see %set. The <bit> is the address of the thread register
that contains the bit value to assign.

The %assign/d instruction is exactly the same as the %assign
instruction, except that the <delay> specifies one of the index
registers, that contain a calculated delay.


* %assign/m <memory-label>, <delay>, <bit>

This instruction does a non-blocking assignment to a bit in a memory
from the specified thread register <bit>.  The memory bit is addressed
by index register 3.  Bit address zero is the LSB of the first memory
word.


* %assign/x0 <var-label>, <delay>, <bit>

This does a non-blocking assignment to a functor, similar to the
%assign instruction. The <var-label> identifies the base functor of
the affected variable, and the <delay> gives the delay when the
assignment takes place. The delay may be 0. The actual functor used is
calculated by using <var-label> as a base, and indexing with the
index[0] index register. This supports indexed assignment.

The <bit> is the address of the thread register that contains the bit
value to assign.


* %blend <bit-l>, <bit-r>, <wid>

This instruction blends the bits of a vector into the destination in a
manner like the expression (x ? <a> : <b>). The truth table is:

	1  1 --> 1
	0  0 --> 0
	z  z --> z
	x  x --> x
	.... --> x

In other words, if the bits are identical, then take that
value. Otherwise, the value is x.

* %breakpoint

This instruction unconditionally breaks the simulator into the
interactive debugger. The idea is to stop the simulator here and give
the user a chance to display the state of the simulation using
debugger commands.

This may not work on all platforms. If run-time debugging is compiled
out, then this function is a no-op.


* %cassign <var-label>, <expr-label>

Connect and active a procedural continuous assignment to a
variable. The <var-label> identifies the affected variable, and the
<expr-label> is the functor that drives the expression to the
variable.  This opcode affects only a single bit.


* %deassign <var-label>, <wid>

Deactive and disconnect a procedural continuous assignment to a
variable. The <var-label> identifies the affected variable.  <wid>
specifies the how many bits to deassign.


* %cmp/u <bit-l>, <bit-r>, <wid>
* %cmp/s <bit-l>, <bit-r>, <wid>

These instructions perform a generic comparison of two vectors of equal
size. The <bit-l> and <bit-r> numbers address the least-significant
bit of each vector, and <wid> is the width. If either operand is 0,
1, 2 or 3 then it is taken to be a constant replicated to the selected
width.

The results of the comparison go into bits 4, 5, 6 and 7:

	4: eq  (equal)
	5: lt  (less than)
	6: eeq (case equal)

The eeq bit is set to 1 if all the bits in the vectors are exactly the
same, or 0 otherwise. The eq bit is true if the values are logically
the same. That is, x and z are considered equal. In other words the eq
bit is the same as ``=='' and the eeq bit ``===''.

The lt bit is 1 if the left vector is less then the right vector, or 0
if greater then or equal to the right vector. It is the equivilent of
the Verilog < operator. Combinations of these three bits can be used
to implement all the Verilog comparison operators.

The %cmp/u and %cmp/s differ only in the handling of the lt bit. The
%cmp/u does an unsigned compare, whereas the %cmp/s does a signed
compare. In either case, if either operand constains x or z, then lt
bit gets the x value.

* %cmp/z <bit-l>, <bit-r>, <wid>
* %cmp/x <bit-l>, <bit-r>, <wid>

These instructions are for implementing the casez and casex
comparisons. These work similar to the %cmp/u instructions, except
only an eq bit is calculated. These comparisons both treat z values in
the left or right operand as don't care positions. The %cmp/x
instruction will also treat x values in either operand as don't care.

Only bit 4 is set by these instructions.

* %delay <delay>

This opcode pauses the thread, and causes it to be rescheduled for a
time in the future. The <amount> is the number of the ticks in the
future to reschedule, and is >= 0. If the %delay is zero, then the
thread yields the processor for another thread, but will be resumed in
the current time step.

* %delayx <idx>

This is similar to the %delay opcode, except that the parameter
selects an index register, which contains the actual delay. This
supports run-time calculated delays.

* %disable <scope-label>

This instruction terminates threads that are part of a specific
scope. The label identifies the scope in question, and the threads are
the threads that are currently within that scope.


* %div <bit-l>, <bit-r>, <wid>
* %div/s <bit-l>, <bit-r>, <wid>

This instruction arithmetically divides the <bit-l> vector by the
<bit-r> vector, and leaves the result in the <bit-l> vector. IF any of
the bits in either vector are x or z, the entire result is x.

The %div/s instruction is the same as %div, but does signed division.


* %force <fofu-label>, <width>

Activate a force represented by the force functors <fofu-label>, which
were created with a .force directive.  If any force was active on the
signal, that force is released first.  A vector of force functors may
be specified with <width> greater than 1.


* %fork <code-label>, <scope-label>

This instruction is similar to %jmp, except that it creates a new
thread to start executing at the specified address. The new thread is
created and pushed onto the child stack.  It is also marked runnable,
but is not necessarily started until the current thread yields.

The %fork instruction has no effect other then to push a child thread.

See also %join.


* %inv <bit>, <wid>

Perform a bitwise invert of the vector starting at <bit>. The result
replaces the input. Invert means the following, independently for each
bit:

	0  --> 1
	1  --> 0
	x  --> x
	z  --> x


* %ix/get <idx>, <bit>, <wid>

This instruction loads a thread vector starting at <bit>, size <wid>,
into the index register <idx>. The <bit> is the lsb of the value in
thread bit space, and <wid> is the width of the vector.

The function converts the 4-value bits into a binary number, without
sign extension. If any of the bits of the vector is x or z, then the
index register gets the value 0.

The function also writes into bit 4 a 1 if any of the bits of the
input vector are x or z. This is a flag that the 0 value written into
the index register is really the result of calculating from unknown
bits.

	4: unknown value
	5: (reserved)
	6: (reserved)


* %ix/load <idx>, <value>

This instruction loads an immediate value into the addressed index
register. The index register holds numeric values, so the <value> is a
number. The idx value selects the index register, and may be 0, 1, 2
or 3. This is different from %is/get, which loads the index register
from a value in the thread bit vector.


* %ix/add <idx>, <value>
* %ix/sub <idx>, <value>
* %ix/mul <idx>, <value>

This instruction adds, subtracts, or multiplies an immediate value to
the addressed index register. The index register holds numeric values,
so the <value> is a number. The <idx> value selects the index register,
and may be 0, 1, 2 or 3.


* %jmp <code-label>

The %jmp instruction performs an unconditional branch to a given
location. The parameter is the label of the destination instruction.

* %jmp/[01xz] <code-label>, <bit>

This is a conditional version of the %jmp instruction. In this case,
a single bit (addressed by <bit>) is tested. If it is one of the
values in the part after the /, the jump is taken. For example:

	%jmp/xz T_label, 8;

will jump to T_label if bit 8 is x or z.

* %join

This is the partner to %fork. This instruction causes the thread to
wait for the top thread in the child stack to terminate, then
continues. It has no effect in the current thread other then to wait
until the top child is cleared.

It is an error to execute %join if there are no children in the child
stack. Every %join in the thread must have a matching %fork that
spawned off a child thread.

If the matching child instruction is still running, a %join suspends
the calling thread until the child ends. If the child is already
ended, then the %join does not block or yield the thread.


* %load <bit>, <functor-label>

This instruction loads a value from the given functor output into the
specified thread register bit. The functor-label can refer to a .net,
a .var or a .functor, and may be indexed with array syntax to get at a
functor within a vector of functors. This instruction loads only a
single bit.


* %load/m <bit>, <memory-label>

This instruction loads a value from a memory bit into the specified
thread register bit. The memory bit is addressed by index register 3.
Bit address zero is the LSB of the first memory word.  This
instruction loads only a single bit.


* %load/x <bit>, <functor-label>, <idx>

This is an indexed load. It uses the contents of the specified index
register to select a bit from an array based at <functor-label>. The
bit is pulled from the addressed functor and loaded into the
destination bit. This function does not do any bounds checking.


* %mod <bit-l>, <bit-r>, <wid>

This instruction calculates the modulus %r of the left operand, and
replaces the left operand with the result. The <wid> gives the width
of the left and the right vectors, and the left vector is completely
replaced with the result.


* %mov <dst>, <src>, <wid>

This instruction copies a vector from one place in register space to
another. The destination and source vectors are assumed to be the same
width and non-overlapping. The <dst> may not be 0-3, but if the <src>
is one of the 4 constant bits, the effect is to replicate the value
into the destination vector. This is useful for filling a vector.


* %mul <bit-l>, <bit-r>, <wid>

This instruction multiplies the left vector by the right vector, the
vectors having the width <wid>. If any of the bits of either vector
are x or z, the result is x. Otherwise, the result is the arithmetic
product.


* %muli <bit-l>, <imm>, <wid>

This instruction is the same as %mul, but the second operand is an
immediate value that is padded to the width of the result.


* %nor/r <dst>, <src>, <wid>

The %nor/r instruction is a reduction nor. That is, the <src> is a
vector with width, but the result is a single bit. The <src> vector is
not affected by the operation unless the <dst> bit is within the
vector. The result is calculated before the <dst> bit is written, so
it is valid to place the <dst> within the <src>.

The actual operation performed is the inverted or of all the bits in
the vector.


* %or <dst>, <src>, <wid>

Perform the bitwise or of the vectors. Each bit in the <dst> is
combined with the corresponding bit in the source, according to the
truth table:

	1 or ? --> 1
	? or 1 --> 1
	0 or 0 --> 0
	otherwise  x


* %or/r <dst>, <src>, <wid>

This is a reduction version of the %or opcode. The <src> is a vector,
and the <dst> is a writeable scaler. The <dst> gets the value of the
or of all the bits of the src vector.


* %release <functor-label>

Release the force on the signal that is represented by the functor
<functor-label>.  The force was previously activated with a %force
statement.  If no force was active on this functor the statement does
nothing.  %release restores and propagates the normal value of the
previously forced functor.  In case of a forced Verilog register, the
current value of the force expression should be %set to the .var
functor before the force is released, to comply with Verilog release
semantics.  Like:

	%load	 <bit>, <functor-label> ; get the forced value
	%set	 <functor-label>, <bit> ; set the .var value
	%release <functor-label>	; remove the force


* %set <var-label>, <bit>

This sets a bit of a variable, and is used to implement blocking
assignments. The <label> identifies the variable to receive the new
value. Once the set completes, the value is immediately available to
be read out of the variable. The <bit> is the address of the thread
register that contains the bit value to assign.


* %set/m <memory-label>, <bit>

This instruction set a bit in a memory from the specified thread
register bit. The memory bit is addressed by index register 3.  Bit
address zero is the LSB of the first memory word.  This instruction
sets only a single bit.


* %set/x <var-label>, <bit>, <idx>

This sets the bit of a variable functor, the address calculated by
using the index register <idx> (0, 1, 2 or 3) to index the functor
address of <var-label>.

If the index value in index register <idx> is <0 (for example if
%ix/get converted an unknown value into the register) then the set is
not performed.


* %shiftl/i0 <bit>, <wid>

This instruction shifts the vector left (towards more significant
bits) by the amount in index register 0. The <bit> is the address of
the lsb of the vector, and <wid> the width of the vector. The shift is
done in place. Zero values are shifted in.

* %shiftr/i0 <bit>, <wid>

This instruction shifts the vector right (towards the less significant
bits) by the amount in the index register 0. The <bit> is the address
of the lsb of the vector, and <wid> is the width of the vector. The
shift is done in place.

This is an unsigned down shift, so zeros are shifted into the top bits.

* %sub <bit-l>, <bit-r>, <wid>

This instruction arithmetically subtracts the right vector out of the
left vector. It accomplishes this by adding to the left vector 1 plus
the 1s complement of the right vector. The carry value is dropped, and
the result, placed in <bit-l>, is the subtraction of <bit-r> from the
input <bit-l>. Both vectors have the same width. If any bits in either
operand are x, then the entire result is x.

See also the %add instruction.


* %vpi_call <name> [, ...]

This instruction makes a call to a system task that was declared using
VPI. The operands are compiled down to a vpiHandle for the call. The
instruction contains only the vpiHandle for the call. See the vpi.txt
file for more on system task/function calls.


* %vpi_func <name>, <dst>, <wid> [, ...]

This instruction is similar to %vpi_call, except that it is for
calling system functions. The difference here is the <dst> and <wid>
parameters that specify where the return value is to go. The normal
means that the VPI code uses to write the return value causes those
bits to go here.


* %wait <functor-label>

When a thread executes this instruction, it places itself in the
sensitive list for the addressed functor. The functor holds all the
threads that await the functor. When the defined sort of event occurs
on the functor, a thread schedule event is created for all the threads
in its list and the list is cleared.

* %xnor <dst>, <src>, <wid>

This does a bitwise exclusive nor (~^) of the <src> and <dst> vector,
and leaves the result in the <dst> vector. xnor is this:

	0 xnor 0 --> 1
	0 xnor 1 --> 0
	1 xnor 0 --> 0
	1 xnor 1 --> 1
	otherwise    x


* %xor <dst>, <src>, <wid>

This does a bitwise exclusive or (^) of the <src> and <dst> vector,
and leaves the result in the <dst> vector. xor is this:

	0 xnor 0 --> 0
	0 xnor 1 --> 1
	1 xnor 0 --> 1
	1 xnor 1 --> 0
	otherwise    x


/*
 * Copyright (c) 2001 Stephen Williams (steve@icarus.com)
 *
 *    This source code is free software; you can redistribute it
 *    and/or modify it in source code form under the terms of the GNU
 *    General Public License as published by the Free Software
 *    Foundation; either version 2 of the License, or (at your option)
 *    any later version.
 *
 *    This program is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *    GNU General Public License for more details.
 *
 *    You should have received a copy of the GNU General Public License
 *    along with this program; if not, write to the Free Software
 *    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 */