@menu
* VM instructions::
* IOS related instructions::
* Function management instructions::
* Environment instructions::
* Printing Instructions::
* Format Instructions::
* Main stack manipulation instructions::
* Registers manipulation instructions::
* Return stack manipulation instructions::
* Arithmetic instructions::
* Relational instructions::
* Concatenation instructions::
* Logical instructions::
* Bitwise instructions::
* Shift instructions::
* Compare-and-swap instructions::
* Branch instructions::
* Conversion instructions::
* String instructions::
* Array instructions::
* Struct instructions::
* Offset Instructions::
* Instructions to handle mapped values::
* Type related instructions::
* IO instructions::
* Exceptions handling instructions::
* Debugging Instructions::
* System Interaction Instructions::
* Miscellaneous Instructions::
@end menu

@node VM instructions
@subsection VM instructions

@menu
* Instruction canary::
* Instruction exit::
* Instruction pushend::
* Instruction popend::
* Instruction pushob::
* Instruction popob::
* Instruction pushom::
* Instruction popom::
* Instruction pushoo::
* Instruction popoo::
* Instruction pushoi::
* Instruction popoi::
* Instruction pushod::
* Instruction popod::
* Instruction pushoac::
* Instruction popoac::
* Instruction pushopp::
* Instruction popopp::
* Instruction pushoc::
* Instruction popoc::
* Instruction pushobc::
* Instruction popobc::
* Instruction sync::
* Instruction pusharem::
* Instruction poparem::
@end menu

@node Instruction canary
@subsubsection Instruction canary
@pvindex canary

Synopsys:

@example
canary
@end example

This instruction installs a canary to mark the bottom of the stack,
which is checked by the `exit' instruction.  To be most effective
this should be executed before the stack is used for the first time.

Stack: @code{( -- )}

@node Instruction exit
@subsubsection Instruction exit
@pvindex exit

Synopsys:

@example
exit
@end example

Do some cleanup and finish execution of a PVM program.  This checks
the stack sentinel installed by the `canary' instruction.

Stack: @code{( -- )}

@node Instruction pushend
@subsubsection Instruction pushend
@pvindex pushend

Synopsys:

@example
pushend
@end example

Push the current endianness on the stack.  This endianness is part
of the global state of the PVM.

Stack: @code{( -- INT )}

@node Instruction popend
@subsubsection Instruction popend
@pvindex popend

Synopsys:

@example
popend
@end example

Pop a signed integer from the stack and make it the current
endianness in the PVM.  The possible values for endianness are
IOS_ENDIAN_LSB and IOS_ENDIAN_MSB.

Stack: @code{( INT -- )}

@node Instruction pushob
@subsubsection Instruction pushob
@pvindex pushob

Synopsys:

@example
pushob
@end example

Push output base.

This instruction pushes a signed integer value with the output base
that is used when printing PVM values.  Valid values are 2, 8, 10
and 16.

Stack: @code{( -- INT )}

@node Instruction popob
@subsubsection Instruction popob
@pvindex popob

Synopsys:

@example
popob
@end example

Pop and set output base.

This instructions pops a signed integer from the stack and uses it
to set the new output base to be used when printing PVM values.
Valid values are 2, 8, 10 and 16.

If an invalid obase is specified then this instruction raises
PVM_E_INVAL.

Stack: @code{( INT -- )}

Exceptions: @code{PVM_E_INVAL}

@node Instruction pushom
@subsubsection Instruction pushom
@pvindex pushom

Synopsys:

@example
pushom
@end example

Push output mode.

This instruction pushes a signed integer value with the output mode
that is used when printing PVM values.  Valid values are 0 for flat
mode, and 1 for tree mode.

Stack: @code{( -- INT )}

@node Instruction popom
@subsubsection Instruction popom
@pvindex popom

Synopsys:

@example
popom
@end example

Pop and set output mode.

This instructions pops a signed integer from the stack and uses it
to set the new output mode to be used when printing PVM values.
Valid values are 0 for flat mode and 1 for tree mode.

If an invalid omode is specified then this instruction raises
PVM_E_INVAL.

Stack: @code{( INT -- )}

Exceptions: @code{PVM_E_INVAL}

@node Instruction pushoo
@subsubsection Instruction pushoo
@pvindex pushoo

Synopsys:

@example
pushoo
@end example

Push output offsets mode.

This instruction pushes a boolean encoded in a signed integer value
indicating whether to show offsets when printing PVM values.

Stack: @code{( -- INT )}

@node Instruction popoo
@subsubsection Instruction popoo
@pvindex popoo

Synopsys:

@example
popoo
@end example

Pop and set output offsets mode.

This instructions pops a boolean encoded in a signed integer from
the stack and uses it to set the new output offset mode to be used
when printing PVM values.

Stack: @code{( INT -- )}

@node Instruction pushoi
@subsubsection Instruction pushoi
@pvindex pushoi

Synopsys:

@example
pushoi
@end example

Push output indentation mode.

This instructions pushes an integer to the stack with the current
indentation step configured in the VM.  The indentation step
determines how many white characters to use in each indentation
level when printing output.

Stack: @code{( -- INT )}

@node Instruction popoi
@subsubsection Instruction popoi
@pvindex popoi

Synopsys:

@example
popoi
@end example

Pop and set output indentation step mode.

This instructions pops an integer from the stack and uses it to
set the current indentation step in the VM.  The indentation step
determines how many white characters to use in each indentation
level when printing output.

Stack: @code{( INT -- )}

@node Instruction pushod
@subsubsection Instruction pushod
@pvindex pushod

Synopsys:

@example
pushod
@end example

Push output depth.

This instruction pushes a signed integer indicating the depth to use
when printing PVM values.

Stack: @code{( -- INT )}

@node Instruction popod
@subsubsection Instruction popod
@pvindex popod

Synopsys:

@example
popod
@end example

Pop and set output depth.

This instructions pops a signed integer indicating the maximum depth
included by the VM when printing values.

Stack: @code{( INT -- )}

@node Instruction pushoac
@subsubsection Instruction pushoac
@pvindex pushoac

Synopsys:

@example
pushoac
@end example

Push output array cutoff.

This instruction pushes a signed integer indicating the number of
elements that the VM includes in the printed representation of PVM
array values.

Stack: @code{( -- INT )}

@node Instruction popoac
@subsubsection Instruction popoac
@pvindex popoac

Synopsys:

@example
popoac
@end example

Pop and set output array cutoff.

This instructions pops a signed integer indicating the number of
elements that the VM includes in the printed representation of PVM
array values.

Stack: @code{( INT -- )}

@node Instruction pushopp
@subsubsection Instruction pushopp
@pvindex pushopp

Synopsys:

@example
pushopp
@end example

Push pretty-print usage.

This instruction pushes a signed integer indicating whether the VM
is configured to use pretty-printers.

Stack: @code{( -- INT )}

@node Instruction popopp
@subsubsection Instruction popopp
@pvindex popopp

Synopsys:

@example
popopp
@end example

Pop and set usage of pretty-printers.

This instructions pops a signed integer indicating whether to use
pretty-printers when printing values and sets it in the VM.

Stack: @code{( INT -- )}

@node Instruction pushoc
@subsubsection Instruction pushoc
@pvindex pushoc

Synopsys:

@example
pushoc
@end example

Push the current output color to the stack, encoded as a
RGB triplet.

Stack: @code{( -- INT INT INT )}

@node Instruction popoc
@subsubsection Instruction popoc
@pvindex popoc

Synopsys:

@example
popoc
@end example

Pop the RGB triplet at the top of the stack and use it to set
the new terminal output color.

Stack: @code{( INT INT INT -- )}

@node Instruction pushobc
@subsubsection Instruction pushobc
@pvindex pushobc

Synopsys:

@example
pushobc
@end example

Push the current output background color to the stack, encoded as a
RGB triplet.

Stack: @code{( -- INT INT INT )}

@node Instruction popobc
@subsubsection Instruction popobc
@pvindex popobc

Synopsys:

@example
popobc
@end example

Pop the RGB triplet at the top of the stack and use it to set
the new terminal output background color.

Stack: @code{( INT INT INT -- )}

@node Instruction sync
@subsubsection Instruction sync
@pvindex sync

Synopsys:

@example
sync
@end example

Handle pending signals, and raise exceptions accordingly.  This
instruction should be emitted in strategic places, such as before
backwards jumps and at function prolog, to assure signals are
eventually attended to.

Stack: @code{( -- )}

Exceptions: @code{PVM_E_SIGNAL}

@node Instruction pusharem
@subsubsection Instruction pusharem
@pvindex pusharem

Synopsys:

@example
pusharem
@end example

Push autoremap flag.

This instruction pushes a signed integer indicating whether the
VM is in `autoremap' mode.

Stack: @code{( -- INT )}

@node Instruction poparem
@subsubsection Instruction poparem
@pvindex poparem

Synopsys:

@example
poparem
@end example

Pop and set the autoremap flag.

This instruction pops a signed integer from the stack and sets
it as the new value of the `autoremap' flag.

Stack: @code{( INT -- )}

@node IOS related instructions
@subsection IOS related instructions

@menu
* Instruction open::
* Instruction close::
* Instruction flush::
* Instruction pushios::
* Instruction popios::
* Instruction ioflags::
* Instruction iosize::
* Instruction ionum::
* Instruction ioref::
* Instruction iohandler::
* Instruction iogetb::
* Instruction iosetb::
@end menu

@node Instruction open
@subsubsection Instruction open
@pvindex open

Synopsys:

@example
open
@end example

Open a new IO space.  The handler string and a set of flags are
passed on the stack.  The descriptor of the opened IOS is pushed to
the stack as a signed integer.

If there is no other IO space opened when this instruction is
executed, then the just opened space becomes the current IO space.

If there is an error condition opening the IO space, a negative
number indicating the condition is pushed on the stack.  Note that
valid IOS descriptors are non-negative.  The possible error
conditions are:

-1 for an unspecified error condition.
-3 invalid flags specified
-4 memory allocation failure.
-5 end of file
-6 invalid argument passed to open
-7 IO space already opened
-8 Insufficient permissions to perform the requested operation.

Stack: @code{( STR ULONG -- INT )}

@node Instruction close
@subsubsection Instruction close
@pvindex close

Synopsys:

@example
close
@end example

Close an IO space.  The descriptor of the space to close is provided
on the stack as a signed integer.

If the specified IO space doesn't exist, this instruction raises
PVM_E_NO_IOS. If the operation fails, it raises PVM_E_IO.

Stack: @code{( INT -- )}

Exceptions: @code{PVM_E_NO_IOS, PVM_E_IO}

@node Instruction flush
@subsubsection Instruction flush
@pvindex flush

Synopsys:

@example
flush
@end example

Flush an IO space.  The descriptor of the space to flush, and the
bit-offset up to which perform the flushing are provided on the stack.

If the specified IO space doesn't exist, this instruction raises
PVM_E_IO.

Stack: @code{( INT ULONG -- )}

Exceptions: @code{PVM_E_IO}

@node Instruction pushios
@subsubsection Instruction pushios
@pvindex pushios

Synopsys:

@example
pushios
@end example

Push the descriptor of the current IO space on the stack, as a
signed integer.  If no IO space is currently opened, push a negative
number.

Stack: @code{( -- INT )}

@node Instruction popios
@subsubsection Instruction popios
@pvindex popios

Synopsys:

@example
popios
@end example

Pop an IO space descriptor from the stack and set it as the current
IO space.  If the specified descriptor doesn't identify an IO space,
raise PVM_E_NO_IOS.

Stack: @code{( INT -- )}

Exceptions: @code{PVM_E_NO_IOS}

@node Instruction ioflags
@subsubsection Instruction ioflags
@pvindex ioflags

Synopsys:

@example
ioflags
@end example

Push an unsigned 64-bit integer with the flags of the given IO space
on the stack.  The IO space is identified by a descriptor, which is
a signed integer.  If the given IO space doesn't exist, raise
PVM_E_NO_IOS.

Stack: @code{( INT -- INT ULONG )}

Exceptions: @code{PVM_E_NO_IOS}

@node Instruction iosize
@subsubsection Instruction iosize
@pvindex iosize

Synopsys:

@example
iosize
@end example

Push the size of the given IO space on the stack, as an offset.  The
IO space is identified by a descriptor, which is a signed integer.
If the given IO space doesn't exist, raise PVM_E_NO_IOS.

Stack: @code{( INT -- INT OFF )}

Exceptions: @code{PVM_E_NO_IOS}

@node Instruction ionum
@subsubsection Instruction ionum
@pvindex ionum

Synopsys:

@example
ionum
@end example

Pushe the number of IO spaces on the stack.

Stack: @code{( -- ULONG )}

@node Instruction ioref
@subsubsection Instruction ioref
@pvindex ioref

Synopsys:

@example
ioref
@end example

Given an index ULONG, push the descriptor of the IO space on
the stack as a signed integer.

If the provided index is out of bounds, then raise
PVM_E_OUT_OF_BOUNDS.

Stack: @code{( ULONG -- ULONG IOS )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction iohandler
@subsubsection Instruction iohandler
@pvindex iohandler

Synopsys:

@example
iohandler
@end example

Push the handler of the given IO space on the stack, as a string.  The
IO space is identified by a descriptor, which is a signed integer.
If the given IO space doesn't exist, raise PVM_E_NO_IOS.

Stack: @code{( INT -- INT OFF )}

Exceptions: @code{PVM_E_NO_IOS}

@node Instruction iogetb
@subsubsection Instruction iogetb
@pvindex iogetb

Synopsys:

@example
iogetb
@end example

Each IO space has a bias associated with it, which by default is 0
bits.  This bias is applied to the offset given to every read/write
operation.

This instruction pushes the bias associated to the given IO space to
the stack, as an offset.  If the given IO space doesn't exist then
the exception PVM_E_NO_IOS is raised.

Stack: @code{( INT - INT OFF )}

Exceptions: @code{PVM_E_NO_IOS}

@node Instruction iosetb
@subsubsection Instruction iosetb
@pvindex iosetb

Synopsys:

@example
iosetb
@end example

Each IO space has a bias associated with it, which by default is 0
bits.  This bias is applied to the offset given to every read/write
operation.

This instruction sets the bias associated to the given IO space.
The bias is specified as an offset.  If the given IO space doesn't
exist, the exception PVM_E_NO_IOS is raised.

Stack: @code{( OFF INT -- OFF )}

Exceptions: @code{PVM_E_NO_IOS}

@node Function management instructions
@subsection Function management instructions

@menu
* Instruction call::
* Instruction prolog::
* Instruction return::
@end menu

@node Instruction call
@subsubsection Instruction call
@pvindex call

Synopsys:

@example
call
@end example

Call a closure on the stack, passing the specified arguments.  After
the execution of the closure, control is transferred to the
instruction immediately following the call instruction.

Stack: @code{( ARG1 ... ARGN CLOSURE -- RETVAL )}

@node Instruction prolog
@subsubsection Instruction prolog
@pvindex prolog

Synopsys:

@example
prolog
@end example

Prepare the PVM for the execution of a function.  This instruction
shall be the target of every `call' instruction and shall be the
first instruction in every function body.

Stack: @code{( -- )}

@node Instruction return
@subsubsection Instruction return
@pvindex return

Synopsys:

@example
return
@end example

Return from a function.  A function can have many `return'
instructions.

Stack: @code{( -- )}

@node Environment instructions
@subsection Environment instructions

@menu
* Instruction pushf::
* Instruction popf::
* Instruction pushvar::
* Instruction pushtopvar::
* Instruction popvar::
* Instruction regvar::
* Instruction duc::
* Instruction pec::
@end menu

@node Instruction pushf
@subsubsection Instruction pushf
@pvindex pushf

Synopsys:

@example
pushf N
@end example

Push a new lexical frame.  If the argument N is bigger than zero, it
indicates the number of entries in the frame.  If N is 0, it means
we don't know how many entries will be stored in the frame.

Stack: @code{( -- )}

@node Instruction popf
@subsubsection Instruction popf
@pvindex popf

Synopsys:

@example
popf N
@end example

Pop N lexical frames.

Stack: @code{( -- )}

@node Instruction pushvar
@subsubsection Instruction pushvar
@pvindex pushvar

Synopsys:

@example
pushvar BACK, OVER
@end example

Retrieve the value of a variable from the lexical environment and
push it on the stack.  The lexical address of the variable is
specified as arguments to the instruction.

Stack: @code{( -- VAL )}

@node Instruction pushtopvar
@subsubsection Instruction pushtopvar
@pvindex pushtopvar

Synopsys:

@example
pushtopvar OVER
@end example

Retrieve the value of a variable from the top-level frame of the
lexical environment and put it on the stack.  The OVER part of the
lexical address of the variable is specified as an argument to the
instruction.

If the variable is not found then raise E_INVAL.

Stack: @code{( -- VAL )}

@node Instruction popvar
@subsubsection Instruction popvar
@pvindex popvar

Synopsys:

@example
popvar BACK, OVER
@end example

Pop a value from the stack and set it as the value of a variable
having the lexical address specified in the arguments, in the
current lexical environment.

Stack: @code{( VAL -- )}

@node Instruction regvar
@subsubsection Instruction regvar
@pvindex regvar

Synopsys:

@example
regvar
@end example

Pop a value from the stack and use it as the value for a new
variable in the current lexical environment.

Stack: @code{( VAL -- )}

@node Instruction duc
@subsubsection Instruction duc
@pvindex duc

Synopsys:

@example
duc
@end example

Make a copy of the closure at the top of the stack, and
replace it.

Stack: @code{( CLS -- CLS )}

@node Instruction pec
@subsubsection Instruction pec
@pvindex pec

Synopsys:

@example
pec
@end example

Put the current lexical environment to the closure at the top of the
stack.

Stack: @code{( CLS -- CLS )}

@node Printing Instructions
@subsection Printing Instructions

@menu
* Instruction printi::
* Instruction printiu::
* Instruction printl::
* Instruction printlu::
* Instruction prints::
* Instruction beghl::
* Instruction endhl::
* Instruction begsc::
* Instruction endsc::
@end menu

In the following instructions the meaning of the argument BASE is
the following:

2 - print the number in binary.
8 - print the number in octal.
16 - print the number in hexadecimal.
Any other value - print the number in decimal.

@node Instruction printi
@subsubsection Instruction printi
@pvindex printi

Synopsys:

@example
printi BITS
@end example

Given a signed integer and a numeration base in the stack, print the
integer to the terminal.

Stack: @code{( INT INT -- )}

@node Instruction printiu
@subsubsection Instruction printiu
@pvindex printiu

Synopsys:

@example
printiu BITS
@end example

Given an unsigned integer and a numeration base in the stack, print
the integer to the terminal.

Stack: @code{( UINT INT -- )}

@node Instruction printl
@subsubsection Instruction printl
@pvindex printl

Synopsys:

@example
printl BITS
@end example

Given a long and a numeration base in the stack, print the integer
to the terminal.

Stack: @code{( LONG INT -- )}

@node Instruction printlu
@subsubsection Instruction printlu
@pvindex printlu

Synopsys:

@example
printlu BITS
@end example

Given an unsigned long and a numeration base in the stack, print the
integer to the terminal.

Stack: @code{( ULONG INT -- )}

@node Instruction prints
@subsubsection Instruction prints
@pvindex prints

Synopsys:

@example
prints
@end example

Print the string at the top of the stack.

Stack: @code{( STR -- )}

@node Instruction beghl
@subsubsection Instruction beghl
@pvindex beghl

Synopsys:

@example
beghl
@end example

Begin an hyperlink, using the URL and ID on the stack.

Stack: @code{( STR STR -- )}

@node Instruction endhl
@subsubsection Instruction endhl
@pvindex endhl

Synopsys:

@example
endhl
@end example

End the current hyperlink.

If no hyperlink is currently being generated, this instruction
raises an exception.

Stack: @code{( -- )}

Exceptions: @code{PVM_E_GENERIC}

@node Instruction begsc
@subsubsection Instruction begsc
@pvindex begsc

Synopsys:

@example
begsc
@end example

Begin the styling class whose name is found on the stack.  This
class will be in effect in subsequent print operations until it is
explicitly ended by a `endsc' instruction.

Stack: @code{( STR -- )}

@node Instruction endsc
@subsubsection Instruction endsc
@pvindex endsc

Synopsys:

@example
endsc
@end example

End the styling class whose name is found on the stack.  This class
should have been previously began by a `begsc' instruction.

Stack: @code{( STR -- )}

@node Format Instructions
@subsection Format Instructions

@menu
* Instruction formati::
* Instruction formatiu::
* Instruction formatl::
* Instruction formatlu::
* Instruction formatf32::
* Instruction formatf64::
@end menu

In the following instructions the meaning of the argument BASE is
the following:

2 - format the number in binary.
8 - format the number in octal.
16 - format the number in hexadecimal.
Any other value - format the number in decimal.

@node Instruction formati
@subsubsection Instruction formati
@pvindex formati

Synopsys:

@example
formati BITS
@end example

Given a signed integer and a numeration base in the stack, push the
string representation to the stack.

Stack: @code{( INT INT -- STR )}

@node Instruction formatiu
@subsubsection Instruction formatiu
@pvindex formatiu

Synopsys:

@example
formatiu BITS
@end example

Given an unsigned integer and a numeration base in the stack, push the
string representation to the stack.

Stack: @code{( UINT INT -- STR )}

@node Instruction formatl
@subsubsection Instruction formatl
@pvindex formatl

Synopsys:

@example
formatl BITS
@end example

Given a long and a numeration base in the stack, push the string
representation to the stack.

Stack: @code{( LONG INT -- STR )}

@node Instruction formatlu
@subsubsection Instruction formatlu
@pvindex formatlu

Synopsys:

@example
formatlu BITS
@end example

Given an unsigned long and a numeration base in the stack, push the
string representation to the stack.

Stack: @code{( ULONG INT -- STR )}

@node Instruction formatf32
@subsubsection Instruction formatf32
@pvindex formatf32

Synopsys:

@example
formatf32 STYLE
@end example

Given a UINT (that should be interpreted as a 32-bit floating-point
number), and a UINT (as the conversion precision), push the string
representation of the floating-point number with specified precision.

The formatting style is given by a literal parameters.
Style 0 corresponds to %f-tag which converts the number in the style
[-]ddd.ddd where the number of digits after the decimal-point character
is the equal to the precision.
Style 1 corresponds to %e-tag which converts the number in the style
[-]d.ddde+-dd (so called scientific notation).  Precision for this
style also means the number of digits after the decimal-point character.
Style 2 corresponds to %g-tag which choose either %f style or %e based
on the length of the repsentation.  For this style, precision specify
the number of significant numbers.

Stack: @code{( UINT UINT -- STR )}

@node Instruction formatf64
@subsubsection Instruction formatf64
@pvindex formatf64

Synopsys:

@example
formatf64 STYLE
@end example

Given a ULONG (that should be interpreted as a 64-bit floating-point
number), and a UINT (as the conversion precision), push the string
representation of the floating-point number with specified precision.
The formatting style is given by a literal parameters.

The formatting style is given by a literal parameters.
Style 0 corresponds to %f-tag which converts the number in the style
[-]ddd.ddd where the number of digits after the decimal-point character
is the equal to the precision.
Style 1 corresponds to %e-tag which converts the number in the style
[-]d.ddde+-dd (so called scientific notation).  Precision for this
style also means the number of digits after the decimal-point character.
Style 2 corresponds to %g-tag which choose either %f style or %e based
on the length of the repsentation.  For this style, precision specify
the number of significant numbers.

Stack: @code{( ULONG UINT -- STR )}

@node Main stack manipulation instructions
@subsection Main stack manipulation instructions

@menu
* Instruction push::
* Instruction drop::
* Instruction drop2::
* Instruction drop3::
* Instruction drop4::
* Instruction swap::
* Instruction nip::
* Instruction nip2::
* Instruction nip3::
* Instruction dup::
* Instruction over::
* Instruction oover::
* Instruction rot::
* Instruction nrot::
* Instruction tuck::
* Instruction quake::
* Instruction revn::
* Instruction pushhi::
* Instruction pushlo::
* Instruction push32::
@end menu

@node Instruction push
@subsubsection Instruction push
@pvindex push

Synopsys:

@example
push VAL
@end example

Push the value given as an argument to the main stack.

Stack: @code{( -- VAL )}

@node Instruction drop
@subsubsection Instruction drop
@pvindex drop

Synopsys:

@example
drop
@end example

Pop the value at the top of the main stack, and discard it.

Stack: @code{( VAL -- )}

@node Instruction drop2
@subsubsection Instruction drop2
@pvindex drop2

Synopsys:

@example
drop2
@end example

Pop the two values at the top of the main stack, and discard them.

Stack: @code{( VAL VAL -- )}

@node Instruction drop3
@subsubsection Instruction drop3
@pvindex drop3

Synopsys:

@example
drop3
@end example

Pop the three values at the top of the main stack, and discard them.

Stack: @code{( VAL VAL VAL -- )}

@node Instruction drop4
@subsubsection Instruction drop4
@pvindex drop4

Synopsys:

@example
drop4
@end example

Pop the four values at the top of the stack, and discard them.

Stack: @code{( VAL VAL VAL VAL -- )}

@node Instruction swap
@subsubsection Instruction swap
@pvindex swap

Synopsys:

@example
swap
@end example

Exchange the two elements at the top of the stack.

Stack: @code{( A B -- B A)}

@node Instruction nip
@subsubsection Instruction nip
@pvindex nip

Synopsys:

@example
nip
@end example

Discard the element at the under top of the main stack.

Stack: @code{( A B -- B )}

@node Instruction nip2
@subsubsection Instruction nip2
@pvindex nip2

Synopsys:

@example
nip2
@end example

Discard the two elements at the under top of the main stack.

Stack: @code{( A B C -- C )}

@node Instruction nip3
@subsubsection Instruction nip3
@pvindex nip3

Synopsys:

@example
nip3
@end example

Discard the three elements at the under top of the main stack.

Stack: @code{( A B C D -- D )}

@node Instruction dup
@subsubsection Instruction dup
@pvindex dup

Synopsys:

@example
dup
@end example

Push a copy of the element at the top of the main stack.

Stack: @code{( A -- A A )}

@node Instruction over
@subsubsection Instruction over
@pvindex over

Synopsys:

@example
over
@end example

Push a copy of the element at the under top of the main stack.

Stack: @code{( A B -- A B A )}

@node Instruction oover
@subsubsection Instruction oover
@pvindex oover

Synopsys:

@example
oover
@end example

Push a copy of the element under the under top of the main stack.

Stack: @code{( A B C -- A B C A )}

@node Instruction rot
@subsubsection Instruction rot
@pvindex rot

Synopsys:

@example
rot
@end example

Rotate the three elements at the top of the main stack, clock-wise.

Stack: @code{( A B C -- B C A )}

@node Instruction nrot
@subsubsection Instruction nrot
@pvindex nrot

Synopsys:

@example
nrot
@end example

Rotate the three elements at the top of the stack, counter
clock-wise.

Stack: @code{( A B C -- C A B )}

@node Instruction tuck
@subsubsection Instruction tuck
@pvindex tuck

Synopsys:

@example
tuck
@end example

Tuck a copy of the element at the top of the stack down two
positions.

Stack: @code{( A B -- B A B )}

@node Instruction quake
@subsubsection Instruction quake
@pvindex quake

Synopsys:

@example
quake
@end example

Swap the two elements at the under top of the stack.

Stack: @code{( A B C - B A C )}

@node Instruction revn
@subsubsection Instruction revn
@pvindex revn

Synopsys:

@example
revn N
@end example

Reverse the N elements at the top of the stack.

Stack: @code{( VAL... -- VAL... )}

@node Instruction pushhi
@subsubsection Instruction pushhi
@pvindex pushhi

Synopsys:

@example
pushhi VAL
@end example

Push the high 32 bits of the value passed as an argument to the main
stack.  This instruction shall be completed with a `pushlo'.

This instruction is a workaround to a limitation of Jitter.

Stack: @code{( -- HI32(VAL) )}

@node Instruction pushlo
@subsubsection Instruction pushlo
@pvindex pushlo

Synopsys:

@example
pushlo VAL
@end example

Push the low 32 bits of the value passed as an argument to the main
stack.  This instruction shall be preceded by a `pushhi'.

This instruction is a workaround to a limitation of Jitter.

Stack: @code{( -- LO32(VAL) )}

@node Instruction push32
@subsubsection Instruction push32
@pvindex push32

Synopsys:

@example
push32 VAL
@end example

Push the value passed as an argument on the stack.  This assumes
that the internal representation of VAL doesn't require more than
32-bit.

This instruction is a workaround to a limitation of Jitter.

Stack: @code{( -- VAL )}

@node Registers manipulation instructions
@subsection Registers manipulation instructions

@menu
* Instruction pushr::
* Instruction popr::
* Instruction setr::
@end menu

@node Instruction pushr
@subsubsection Instruction pushr
@pvindex pushr

Synopsys:

@example
pushr REGNO
@end example

Push the contents of the register REGNO on the stack.

Stack: @code{( -- VAL )}

@node Instruction popr
@subsubsection Instruction popr
@pvindex popr

Synopsys:

@example
popr REGNO
@end example

Pop the element at the top of the stack and put it in the
register REGNO.

Stack: @code{( VAL -- )}

@node Instruction setr
@subsubsection Instruction setr
@pvindex setr

Synopsys:

@example
setr REGNO
@end example

Set the element at the top of the stack to the value of the
register REGNO.

Stack: @code{( -- )}

@node Return stack manipulation instructions
@subsection Return stack manipulation instructions

@menu
* Instruction saver::
* Instruction restorer::
* Instruction tor::
* Instruction fromr::
* Instruction atr::
@end menu

@node Instruction saver
@subsubsection Instruction saver
@pvindex saver

Synopsys:

@example
saver REGNO
@end example

Push the contents of the register REGNO to the return stack.

Stack: @code{( -- )}
ReturnStack: ( -- VAL )

@node Instruction restorer
@subsubsection Instruction restorer
@pvindex restorer

Synopsys:

@example
restorer REGNO
@end example

Pop the element at the top of the return stack and put it in the
register REGNO.

Stack: @code{( -- )}
ReturnStack: ( VAL -- )

@node Instruction tor
@subsubsection Instruction tor
@pvindex tor

Synopsys:

@example
tor
@end example

Pop an element from the stack and push it in the return stack.

Stack: @code{( VAL -- )}
ReturnStack: ( -- VAL )

@node Instruction fromr
@subsubsection Instruction fromr
@pvindex fromr

Synopsys:

@example
fromr
@end example

Pop an element from the return stack and push it on the stack.

Stack: @code{( -- VAL)}
ReturnStack: ( VAL -- )

@node Instruction atr
@subsubsection Instruction atr
@pvindex atr

Synopsys:

@example
atr
@end example

Push a copy of the element at the top of the return stack into the
stack.

Stack: @code{( -- VAL )}

@node Arithmetic instructions
@subsection Arithmetic instructions

@menu
* Instruction addi::
* Instruction addiu::
* Instruction addlu::
* Instruction subi::
* Instruction subiu::
* Instruction subl::
* Instruction sublu::
* Instruction muli::
* Instruction muliu::
* Instruction mull::
* Instruction mullu::
* Instruction divi::
* Instruction diviu::
* Instruction divl::
* Instruction divlu::
* Instruction modi::
* Instruction modiu::
* Instruction modl::
* Instruction modlu::
* Instruction negi::
* Instruction negiu::
* Instruction negl::
* Instruction neglu::
* Instruction powi::
* Instruction powiu::
* Instruction powl::
* Instruction powlu::
@end menu

The following instructions assume that both operands have the same
size in bits.

@node Instruction addi
@subsubsection Instruction addi
@pvindex addi

Synopsys:

@example
addi
@end example

Push the result of adding the two integers at the top of the stack.
If the operation would result in overflow, raise PVM_E_OVERFLOW.

Stack: @code{( INT INT -- INT INT INT )}

Exceptions: @code{PVM_E_OVERFLOW}

@node Instruction addiu
@subsubsection Instruction addiu
@pvindex addiu

Synopsys:

@example
addiu
@end example

Push the result of adding the two unsigned integers at the top of
the stack.

Stack: @code{( UINT UINT -- UINT UINT UINT )}
Instruction addl

Push the result of adding the two longs at the top of the stack.
If the operation would result in overflow, raise PVM_E_OVERFLOW.

Stack: @code{( LONG LONG -- LONG LONG LONG )}

Exceptions: @code{PVM_E_OVERFLOW}

@node Instruction addlu
@subsubsection Instruction addlu
@pvindex addlu

Synopsys:

@example
addlu
@end example

Push the result of adding the two unsigned longs at the top of
the stack.

Stack: @code{( ULONG ULONG -- ULONG ULONG ULONG )}

@node Instruction subi
@subsubsection Instruction subi
@pvindex subi

Synopsys:

@example
subi
@end example

Push the result of subtracting the two integers at the top of
the stack.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction subiu
@subsubsection Instruction subiu
@pvindex subiu

Synopsys:

@example
subiu
@end example

Push the result of subtracting the two unsigned integers at the
top of the stack.

Stack: @code{( UINT UINT -- UINT UINT UINT )}

@node Instruction subl
@subsubsection Instruction subl
@pvindex subl

Synopsys:

@example
subl
@end example

Push the result of subtracting the two longs at the top
of the stack.

Stack: @code{( LONG LONG -- LONG LONG LONG )}

@node Instruction sublu
@subsubsection Instruction sublu
@pvindex sublu

Synopsys:

@example
sublu
@end example

Push the result of subtracting the two unsigned longs at the
top of the stack.

Stack: @code{( ULONG ULONG -- ULONG ULONG ULONG )}

@node Instruction muli
@subsubsection Instruction muli
@pvindex muli

Synopsys:

@example
muli
@end example

Push the result of multiplying the two integers at the top of the
stack.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction muliu
@subsubsection Instruction muliu
@pvindex muliu

Synopsys:

@example
muliu
@end example

Push the result of multiplying the two unsigned integers at the
top of the stack.

Stack: @code{( UINT UINT -- UINT UINT UINT )}

@node Instruction mull
@subsubsection Instruction mull
@pvindex mull

Synopsys:

@example
mull
@end example

Push the result of multiplying the two longs at the top of the
stack.

Stack: @code{( LONG LONG -- LONG LONG LONG )}

@node Instruction mullu
@subsubsection Instruction mullu
@pvindex mullu

Synopsys:

@example
mullu
@end example

Push the result of multiplying the two unsigned longs at the top
of the stack.

Stack: @code{( ULONG ULONG -- ULONG ULONG ULONG )}

@node Instruction divi
@subsubsection Instruction divi
@pvindex divi

Synopsys:

@example
divi
@end example

Push the result of the integer division of the two integers at the
top of the stack.  If the denominator is zero, raise
PVM_E_DIV_BY_ZERO.

Stack: @code{( INT INT -- INT INT INT )}

Exceptions: @code{PVM_E_DIV_BY_ZERO}

@node Instruction diviu
@subsubsection Instruction diviu
@pvindex diviu

Synopsys:

@example
diviu
@end example

Push the result of the integer division of the two unsigned integers
at the top of the stack.  If the denominator is zero, raise
PVM_E_DIV_BY_ZERO.

Stack: @code{( UINT UINT -- UINT UINT UINT )}

Exceptions: @code{PVM_E_DIV_BY_ZERO}

@node Instruction divl
@subsubsection Instruction divl
@pvindex divl

Synopsys:

@example
divl
@end example

Push the result of the integer division of the two longs at the top
of the stack.  If the denominator is zero, raise PVM_E_DIV_BY_ZERO.

Stack: @code{( LONG LONG -- LONG LONG LONG )}

Exceptions: @code{PVM_E_DIV_BY_ZERO}

@node Instruction divlu
@subsubsection Instruction divlu
@pvindex divlu

Synopsys:

@example
divlu
@end example

Push the result of the integer division of the two unsigned
longs at the top of the stack.  If the denominator is zero,
raise PVM_E_DIV_BY_ZERO.

Stack: @code{( ULONG ULONG -- ULONG ULONG ULONG )}

Exceptions: @code{PVM_E_DIV_BY_ZERO}

@node Instruction modi
@subsubsection Instruction modi
@pvindex modi

Synopsys:

@example
modi
@end example

Push the result of the modulus of the two integers at the top of the
stack.  If the denominator is zero, raise PVM_E_DIV_BY_ZERO.

Stack: @code{( INT INT -- INT INT INT )}

Exceptions: @code{PVM_E_DIV_BY_ZERO}

@node Instruction modiu
@subsubsection Instruction modiu
@pvindex modiu

Synopsys:

@example
modiu
@end example

Push the result of the modulus of the two unsigned integers at the
top of the stack.  If the denominator is zero, raise
PVM_E_DIV_BY_ZERO.

Stack: @code{( UINT UINT -- UINT UINT UINT )}

Exceptions: @code{PVM_E_DIV_BY_ZERO}

@node Instruction modl
@subsubsection Instruction modl
@pvindex modl

Synopsys:

@example
modl
@end example

Push the result of the modulus of the two longs at the top of the
stack.  If the denominator is zero, raise PVM_E_DIV_BY_ZERO.

Stack: @code{( LONG LONG -- LONG LONG LONG )}

Exceptions: @code{PVM_E_DIV_BY_ZERO}

@node Instruction modlu
@subsubsection Instruction modlu
@pvindex modlu

Synopsys:

@example
modlu
@end example

Push the result of the modulus of the two unsigned longs at the top
of the stack.  If the denominator is zero, raise PVM_E_DIV_BY_ZERO.

Stack: @code{( ULONG ULONG -- ULONG ULONG ULONG )}

Exceptions: @code{PVM_E_DIV_BY_ZERO}

@node Instruction negi
@subsubsection Instruction negi
@pvindex negi

Synopsys:

@example
negi
@end example

Push the result of the negation of the integer at the top of the
stack.

Stack: @code{( INT -- INT INT )}

@node Instruction negiu
@subsubsection Instruction negiu
@pvindex negiu

Synopsys:

@example
negiu
@end example

Push the result of the negation of the unsigned integer at the
top of the stack.

Stack: @code{( UINT -- UINT UINT UINT )}

@node Instruction negl
@subsubsection Instruction negl
@pvindex negl

Synopsys:

@example
negl
@end example

Push the result of the negation of the long at the top of the
stack.

Stack: @code{( LONG -- LONG LONG )}

@node Instruction neglu
@subsubsection Instruction neglu
@pvindex neglu

Synopsys:

@example
neglu
@end example

Push the result of the negation of the unsigned long at the top of
the stack.

Stack: @code{( ULONG -- ULONG ULONG )}

@node Instruction powi
@subsubsection Instruction powi
@pvindex powi

Synopsys:

@example
powi
@end example

Perform the exponentiation of the integer at the under top of the
stack.  The exponent is the unsigned integer at the top of the
stack.  If the exponent is 0, the result is 1.

Stack: @code{( INT UINT -- INT UINT INT )}

@node Instruction powiu
@subsubsection Instruction powiu
@pvindex powiu

Synopsys:

@example
powiu
@end example

Perform the exponentiation of the unsigned integer at the under top
of the stack.  The exponent is the unsigned integer at the top of
the stack.  If the exponent is 0, the result is 1.

Stack: @code{( UINT UINT -- UINT UINT UINT )}

@node Instruction powl
@subsubsection Instruction powl
@pvindex powl

Synopsys:

@example
powl
@end example

Perform the exponentiation of the long at the under top of the
stack.  The exponent is the unsigned integer at the top of the
stack.  If the exponent is 0, the result is 1.

Stack: @code{( LONG UINT -- LONG UINT LONG )}

@node Instruction powlu
@subsubsection Instruction powlu
@pvindex powlu

Synopsys:

@example
powlu
@end example

Perform the exponentiation of the unsigned long at the under top of
the stack.  The exponent is the unsigned integer at the top of the
stack.  If the exponent is 0, the result is 1.

Stack: @code{( ULONG UINT -- ULONG UINT ULONG )}

@node Relational instructions
@subsection Relational instructions

@menu
* Instruction eqi::
* Instruction eqiu::
* Instruction eql::
* Instruction eqlu::
* Instruction eqs::
* Instruction nei::
* Instruction neiu::
* Instruction nel::
* Instruction nelu::
* Instruction nes::
* Instruction nn::
* Instruction nnn::
* Instruction lti::
* Instruction ltiu::
* Instruction ltl::
* Instruction ltlu::
* Instruction lei::
* Instruction leiu::
* Instruction lel::
* Instruction lelu::
* Instruction gti::
* Instruction gtiu::
* Instruction gtl::
* Instruction gtlu::
* Instruction gei::
* Instruction geiu::
* Instruction gel::
* Instruction gelu::
* Instruction lts::
* Instruction gts::
* Instruction ges::
* Instruction les::
* Instruction eqc::
* Instruction nec::
@end menu

@node Instruction eqi
@subsubsection Instruction eqi
@pvindex eqi

Synopsys:

@example
eqi
@end example

Push 1 on the stack if the two integers at the top of the stack are
equal.  Otherwise push 0.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction eqiu
@subsubsection Instruction eqiu
@pvindex eqiu

Synopsys:

@example
eqiu
@end example

Push 1 on the stack if the two unsigned integers at the top of the
stack are equal.  Otherwise push 0.

Stack: @code{( UINT UINT -- UINT UINT UINT )}

@node Instruction eql
@subsubsection Instruction eql
@pvindex eql

Synopsys:

@example
eql
@end example

Push 1 on the stack if the two longs at the top of the stack are
equal.  Otherwise push 0.

Stack: @code{( LONG LONG -- LONG LONG INT )}

@node Instruction eqlu
@subsubsection Instruction eqlu
@pvindex eqlu

Synopsys:

@example
eqlu
@end example

Push 1 on the stack if the two unsigned longs at the top of the
stack are equal.  Otherwise push 0.

Stack: @code{( ULONG ULONG -- ULONG ULONG INT )}

@node Instruction eqs
@subsubsection Instruction eqs
@pvindex eqs

Synopsys:

@example
eqs
@end example

Push 1 on the stack if the two strings at the top of the stack are
equal.  Otherwise push 0.

Stack: @code{( STR STR -- STR STR INT )}

@node Instruction nei
@subsubsection Instruction nei
@pvindex nei

Synopsys:

@example
nei
@end example

Push 1 on the stack if the two integers at the top of the stack are
not equal.  Otherwise push 0.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction neiu
@subsubsection Instruction neiu
@pvindex neiu

Synopsys:

@example
neiu
@end example

Push 1 on the stack if the two unsigned integers at the top of the
stack are not equal.  Otherwise push 0.

Stack: @code{( UINT UINT -- UINT UINT INT )}

@node Instruction nel
@subsubsection Instruction nel
@pvindex nel

Synopsys:

@example
nel
@end example

Push 1 on the stack if the two longs at the top of the stack are not
equal.  Otherwise push 0.

Stack: @code{( LONG LONG -- LONG LONG INT )}

@node Instruction nelu
@subsubsection Instruction nelu
@pvindex nelu

Synopsys:

@example
nelu
@end example

Push 1 on the stack if the two unsigned longs at the top of the
stack are not equal.  Otherwise push 0.

Stack: @code{( ULONG ULONG -- ULONG ULONG INT )}

@node Instruction nes
@subsubsection Instruction nes
@pvindex nes

Synopsys:

@example
nes
@end example

Push 1 on the stack if the two strings at the top of the stack are
not equal.  Otherwise push 0.

Stack: @code{( STR STR -- STR STR INT )}

@node Instruction nn
@subsubsection Instruction nn
@pvindex nn

Synopsys:

@example
nn
@end example

Push 0 on the stack if the value at the top of the stack equals
PVM_NULL.  Otherwise push 1.

Stack: @code{( VAL -- VAL INT )}

@node Instruction nnn
@subsubsection Instruction nnn
@pvindex nnn

Synopsys:

@example
nnn
@end example

Push 1 on the stack if the value at the top of the stack equals
PVM_NULL.  Otherwise push 0.

Stack: @code{( VAL -- VAL INT )}

@node Instruction lti
@subsubsection Instruction lti
@pvindex lti

Synopsys:

@example
lti
@end example

Push 1 on the stack if the integer at the under top is less that the
integer at the top.  Otherwise push 0.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction ltiu
@subsubsection Instruction ltiu
@pvindex ltiu

Synopsys:

@example
ltiu
@end example

Push 1 on the stack if the unsigned integer at the under top is less
that the unsigned integer at the top.  Otherwise push 0.

Stack: @code{( UINT INT -- UINT UINT INT )}

@node Instruction ltl
@subsubsection Instruction ltl
@pvindex ltl

Synopsys:

@example
ltl
@end example

Push 1 on the stack if the long at the under top is less that the
long at the top.  Otherwise push 0.

Stack: @code{( LONG LONG -- LONG LONG INT )}

@node Instruction ltlu
@subsubsection Instruction ltlu
@pvindex ltlu

Synopsys:

@example
ltlu
@end example

Push 1 on the stack if the unsigned long at the under top is less
that the unsigned long at the top.  Otherwise push 0.

Stack: @code{( ULONG ULONG -- ULONG ULONG INT )}

@node Instruction lei
@subsubsection Instruction lei
@pvindex lei

Synopsys:

@example
lei
@end example

Push 1 on the stack if the integer at the under top is less or equal
that the integer at the top.  Otherwise push 0.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction leiu
@subsubsection Instruction leiu
@pvindex leiu

Synopsys:

@example
leiu
@end example

Push 1 on the stack if the unsigned integer at the under top is less
or equal that the unsigned integer at the top.  Otherwise push 0.

Stack: @code{( UINT UINT -- UINT UINT INT )}

@node Instruction lel
@subsubsection Instruction lel
@pvindex lel

Synopsys:

@example
lel
@end example

Push 1 on the stack if the long at the under top is less or equal
that the long at the top.  Otherwise push 0.

Stack: @code{( LONG LONG -- LONG LONG INT )}

@node Instruction lelu
@subsubsection Instruction lelu
@pvindex lelu

Synopsys:

@example
lelu
@end example

Push 1 on the stack if the unsigned long at the under top is less or
equal that the unsigned long at the top.  Otherwise push 0.

Stack: @code{( ULONG ULONG -- ULONG ULONG INT )}

@node Instruction gti
@subsubsection Instruction gti
@pvindex gti

Synopsys:

@example
gti
@end example

Push 1 on the stack if the integer at the under top is greater than
the integer at the top.  Otherwise push 0.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction gtiu
@subsubsection Instruction gtiu
@pvindex gtiu

Synopsys:

@example
gtiu
@end example

Push 1 on the stack if the unsigned integer at the under top is
greater than the unsigned integer at the top.  Otherwise push 0.

Stack: @code{( UINT UINT -- UINT UINT INT )}

@node Instruction gtl
@subsubsection Instruction gtl
@pvindex gtl

Synopsys:

@example
gtl
@end example

Push 1 on the stack if the long at the under top is greater than the
long at the top.  Otherwise push 0.

Stack: @code{( LONG LONG -- LONG LONG INT )}

@node Instruction gtlu
@subsubsection Instruction gtlu
@pvindex gtlu

Synopsys:

@example
gtlu
@end example

Push 1 on the stack if the unsigned long at the under top is greater
than the unsigned long at the top.  Otherwise push 0.

Stack: @code{( LONG LONG -- LONG LONG INT )}

@node Instruction gei
@subsubsection Instruction gei
@pvindex gei

Synopsys:

@example
gei
@end example

Push 1 on the stack if the integer at the under top is greater or
equal than the integer at the top.  Otherwise push 0.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction geiu
@subsubsection Instruction geiu
@pvindex geiu

Synopsys:

@example
geiu
@end example

Push 1 on the stack if the unsigned integer at the under top is
greater or equal than the unsigned integer at the top.  Otherwise
push 0.

Stack: @code{( UINT UINT -- UINT UINT INT )}

@node Instruction gel
@subsubsection Instruction gel
@pvindex gel

Synopsys:

@example
gel
@end example

Push 1 on the stack if the long at the under top is greater or equal
than the long at the top.  Otherwise push 0.

Stack: @code{( LONG LONG -- LONG LONG INT )}

@node Instruction gelu
@subsubsection Instruction gelu
@pvindex gelu

Synopsys:

@example
gelu
@end example

Push 1 on the stack if the unsigned long at the under top is greater
or equal than the unsigned long at the top.  Otherwise push 0.

Stack: @code{( ULONG ULONG -- ULONG ULONG INT )}

@node Instruction lts
@subsubsection Instruction lts
@pvindex lts

Synopsys:

@example
lts
@end example

Push 1 on the stack if the string at the under top is less than the
string at the top, in lexicographic order.  Otherwise push 0.

Stack: @code{( STR STR -- STR STR INT )}

@node Instruction gts
@subsubsection Instruction gts
@pvindex gts

Synopsys:

@example
gts
@end example

Push 1 on the stack if the string at the under top is greater than
the string at the top, in lexicographic order.  Otherwise push 0.

Stack: @code{( STR STR -- STR STR INT )}

@node Instruction ges
@subsubsection Instruction ges
@pvindex ges

Synopsys:

@example
ges
@end example

Push 1 on the stack if the string at the under top is greater or
equal than the string at the top, in lexicographic order.  Otherwise
push 0.

Stack: @code{( STR STR -- STR STR INT )}

@node Instruction les
@subsubsection Instruction les
@pvindex les

Synopsys:

@example
les
@end example

Push 1 on the stack if the string at the under top is less or equal
than the string at the top, in lexicographic order.  Otherwise push
0.

Stack: @code{( STR STR -- STR STR INT )}

@node Instruction eqc
@subsubsection Instruction eqc
@pvindex eqc

Synopsys:

@example
eqc
@end example

Push 1 on the stack if the two closures at the top of the stack are
equal.  Otherwise push 0.

Stack: @code{( CLS CLS -- CLS CLS INT )}

@node Instruction nec
@subsubsection Instruction nec
@pvindex nec

Synopsys:

@example
nec
@end example

Push 1 on the stack if the two closures at the top of the stack are
not equal.  Otherwise push 0.

Stack: @code{( CLS CLS -- CLS CLS INT )}

@node Concatenation instructions
@subsection Concatenation instructions

@menu
* Instruction sconc::
@end menu

@node Instruction sconc
@subsubsection Instruction sconc
@pvindex sconc

Synopsys:

@example
sconc
@end example

Push the concatenation of the two strings at the top of the stack.

Stack: @code{( STR STR -- STR STR STR )}

@node Logical instructions
@subsection Logical instructions

@menu
* Instruction and::
* Instruction or::
* Instruction not::
@end menu

@node Instruction and
@subsubsection Instruction and
@pvindex and

Synopsys:

@example
and
@end example

Push the logical and of the two elements at the top of the stack.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction or
@subsubsection Instruction or
@pvindex or

Synopsys:

@example
or
@end example

Push the logical or of the two elements at the top of the stack.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction not
@subsubsection Instruction not
@pvindex not

Synopsys:

@example
not
@end example

Push the logical not of the element at the top of the stack.

Stack: @code{( INT -- INT INT )}

@node Bitwise instructions
@subsection Bitwise instructions

@menu
* Instruction bxori::
* Instruction bxoriu::
* Instruction bxorl::
* Instruction bxorlu::
* Instruction bori::
* Instruction boriu::
* Instruction borl::
* Instruction borlu::
* Instruction bandi::
* Instruction bandiu::
* Instruction bandl::
* Instruction bandlu::
* Instruction bnoti::
* Instruction bnotiu::
* Instruction bnotl::
* Instruction bnotlu::
@end menu

@node Instruction bxori
@subsubsection Instruction bxori
@pvindex bxori

Synopsys:

@example
bxori
@end example

Push the bitwise exclusive or of the two integers at the top of the
stack.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction bxoriu
@subsubsection Instruction bxoriu
@pvindex bxoriu

Synopsys:

@example
bxoriu
@end example

Push the bitwise exclusive or of the two unsigned integers at the
top of the stack.

Stack: @code{( UINT UINT -- UINT UINT UINT )}

@node Instruction bxorl
@subsubsection Instruction bxorl
@pvindex bxorl

Synopsys:

@example
bxorl
@end example

Push the bitwise exclusive or of the two longs at the top of the
stack.

Stack: @code{( LONG LONG -- LONG LONG LONG )}

@node Instruction bxorlu
@subsubsection Instruction bxorlu
@pvindex bxorlu

Synopsys:

@example
bxorlu
@end example

Push the bitwise exclusive or of the two unsigned longs at the top
of the stack.

Stack: @code{( ULONG ULONG -- ULONG ULONG ULONG )}

@node Instruction bori
@subsubsection Instruction bori
@pvindex bori

Synopsys:

@example
bori
@end example

Push the bitwise or of the two integers at the top of the stack.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction boriu
@subsubsection Instruction boriu
@pvindex boriu

Synopsys:

@example
boriu
@end example

Push the bitwise or of the two unsigned integers at the top of the
stack.

Stack: @code{( UINT UINT -- UINT UINT UINT )}

@node Instruction borl
@subsubsection Instruction borl
@pvindex borl

Synopsys:

@example
borl
@end example

Push the bitwise or of the two longs at the top of the stack.

Stack: @code{( LONG LONG -- LONG LONG LONG )}

@node Instruction borlu
@subsubsection Instruction borlu
@pvindex borlu

Synopsys:

@example
borlu
@end example

Push the bitwise or of the two longs at the top of the stack.

Stack: @code{( ULONG ULONG  -- ULONG ULONG ULONG )}

@node Instruction bandi
@subsubsection Instruction bandi
@pvindex bandi

Synopsys:

@example
bandi
@end example

Push the bitwise and of the two integers at the top of the stack.

Stack: @code{( INT INT -- INT INT INT )}

@node Instruction bandiu
@subsubsection Instruction bandiu
@pvindex bandiu

Synopsys:

@example
bandiu
@end example

Push the bitwise and of the two unsigned integers at the top of the
stack.

Stack: @code{( UINT UINT -- UINT UINT UINT )}

@node Instruction bandl
@subsubsection Instruction bandl
@pvindex bandl

Synopsys:

@example
bandl
@end example

Push the bitwise and of the two longs at the top of the stack.

Stack: @code{( LONG LONG -- LONG LONG LONG )}

@node Instruction bandlu
@subsubsection Instruction bandlu
@pvindex bandlu

Synopsys:

@example
bandlu
@end example

Push the bitwise and of the two unsigned longs at the top of the
stack.

Stack: @code{( ULONG ULONG -- ULONG ULONG ULONG )}

@node Instruction bnoti
@subsubsection Instruction bnoti
@pvindex bnoti

Synopsys:

@example
bnoti
@end example

Push the bitwise not of the integer at the top of the stack.

Stack: @code{( INT -- INT INT INT )}

@node Instruction bnotiu
@subsubsection Instruction bnotiu
@pvindex bnotiu

Synopsys:

@example
bnotiu
@end example

Push the bitwise not of the unsigned integer at the top of the
stack.

Stack: @code{( UINT -- UINT UINT )}

@node Instruction bnotl
@subsubsection Instruction bnotl
@pvindex bnotl

Synopsys:

@example
bnotl
@end example

Push the bitwise not of the long at the top of the stack.

Stack: @code{( LONG -- LONG LONG )}

@node Instruction bnotlu
@subsubsection Instruction bnotlu
@pvindex bnotlu

Synopsys:

@example
bnotlu
@end example

Push the bitwise not of the unsigned long at the top of the stack.

Stack: @code{( ULONG -- ULONG ULONG )}

@node Shift instructions
@subsection Shift instructions

@menu
* Instruction bsli::
* Instruction bsliu::
* Instruction bsll::
* Instruction bsllu::
* Instruction bsri::
* Instruction bsriu::
* Instruction bsrl::
* Instruction bsrlu::
@end menu

@node Instruction bsli
@subsubsection Instruction bsli
@pvindex bsli

Synopsys:

@example
bsli
@end example

Left-shift the integer at the under top of the stack the number of
bits indicated by the unsigned int at the top of the stack.

If the bit count is equal or bigger than the size of the left
operand, then raise PVM_E_OUT_OF_BOUNDS.

Stack: @code{( INT UINT -- INT UINT INT )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction bsliu
@subsubsection Instruction bsliu
@pvindex bsliu

Synopsys:

@example
bsliu
@end example

Left-shift the unsigned integer at the under top of the stack the
number of bits indicated by the unsigned int at the top of the
stack.

If the bit count is equal or bigger than the size of the left
operand, then raise PVM_E_OUT_OF_BOUNDS.

Stack: @code{( UINT UINT -- UINT UINT UINT )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction bsll
@subsubsection Instruction bsll
@pvindex bsll

Synopsys:

@example
bsll
@end example

Left-shift the long at the under top of the stack the number of bits
indicated by the unsigned int at the top of the stack.

If the bit count is equal or bigger than the size of the left
operand, then raise PVM_E_OUT_OF_BOUNDS.

Stack: @code{( LONG UINT -- LONG UINT LONG )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction bsllu
@subsubsection Instruction bsllu
@pvindex bsllu

Synopsys:

@example
bsllu
@end example

Left-shift the unsigned long at the under top of the stack the
number of bits indicated by the unsigned int at the top of the
stack.

If the bit count is equal or bigger than the size of the left
operand, then raise PVM_E_OUT_OF_BOUNDS.

Stack: @code{( ULONG UINT -- ULONG UINT ULONG )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction bsri
@subsubsection Instruction bsri
@pvindex bsri

Synopsys:

@example
bsri
@end example

Right-shift the integer at the under top of the stack the number of
tis indicated by the unsigned int at the top of the stack.

Stack: @code{( INT UINT -- INT UINT INT )}

@node Instruction bsriu
@subsubsection Instruction bsriu
@pvindex bsriu

Synopsys:

@example
bsriu
@end example

Right-shift the unsigned integer at the under top of the stack the
number of tis indicated by the unsigned int at the top of the stack.

Stack: @code{( UINT UINT -- UINT UINT UINT )}

@node Instruction bsrl
@subsubsection Instruction bsrl
@pvindex bsrl

Synopsys:

@example
bsrl
@end example

Right-shift the long at the under top of the stack the number of tis
indicated by the unsigned int at the top of the stack.

Stack: @code{( LONG UINT -- LONG UINT LONG )}

@node Instruction bsrlu
@subsubsection Instruction bsrlu
@pvindex bsrlu

Synopsys:

@example
bsrlu
@end example

Right-shift the unsigned long at the under top of the stack the
number of tis indicated by the unsigned int at the top of the stack.

Stack: @code{( ULONG UINT -- ULONG UINT ULONG )}

@node Compare-and-swap instructions
@subsection Compare-and-swap instructions

@menu
* Instruction swapgti::
* Instruction swapgtiu::
* Instruction swapgtl::
* Instruction swapgtlu::
@end menu

@node Instruction swapgti
@subsubsection Instruction swapgti
@pvindex swapgti

Synopsys:

@example
swapgti
@end example

Swap the two integers at the top of the stack if the element at the
under-top is greater than the element at the top.

Stack: @code{( INT INT -- INT INT )}

@node Instruction swapgtiu
@subsubsection Instruction swapgtiu
@pvindex swapgtiu

Synopsys:

@example
swapgtiu
@end example

Swap the two unsigned integers at the top of the stack if the
element at the under-top is greater than the element at the top.

Stack: @code{( UINT UINT -- UINT UINT )}

@node Instruction swapgtl
@subsubsection Instruction swapgtl
@pvindex swapgtl

Synopsys:

@example
swapgtl
@end example

Swap the two longs at the top of the stack if the element at the
under-top is greater than the element at the top.

Stack: @code{( LONG LONG -- LONG LONG )}

@node Instruction swapgtlu
@subsubsection Instruction swapgtlu
@pvindex swapgtlu

Synopsys:

@example
swapgtlu
@end example

Swap the two unsigned longs at the top of the stack if the element
at the under-top is greater than the element at the top.

Stack: @code{( ULONG ULONG -- ULONG ULONG )}

@node Branch instructions
@subsection Branch instructions

@menu
* Instruction ba::
* Instruction bn::
* Instruction bnn::
* Instruction bzi::
* Instruction bziu::
* Instruction bzl::
* Instruction bzlu::
* Instruction bnzi::
* Instruction bnziu::
* Instruction bnzl::
* Instruction bnzlu::
@end menu

@node Instruction ba
@subsubsection Instruction ba
@pvindex ba

Synopsys:

@example
ba LABEL
@end example

Branch unconditionally to the given LABEL.

Stack: @code{( -- )}

@node Instruction bn
@subsubsection Instruction bn
@pvindex bn

Synopsys:

@example
bn LABEL
@end example

Branch to the given LABEL if the value at the top of the stack is
PVM_NULL.

Stack: @code{( VAL -- VAL )}

@node Instruction bnn
@subsubsection Instruction bnn
@pvindex bnn

Synopsys:

@example
bnn LABEL
@end example

Branch to the given LABEL if the value at the top of the stack is
not PVM_NULL.

Stack: @code{( VAL -- VAL )}

@node Instruction bzi
@subsubsection Instruction bzi
@pvindex bzi

Synopsys:

@example
bzi LABEL
@end example

Branch to the given LABEL if the integer at the top of the stack is
zero.

Stack: @code{( INT -- INT )}

@node Instruction bziu
@subsubsection Instruction bziu
@pvindex bziu

Synopsys:

@example
bziu LABEL
@end example

Branch to the given LABEL if the unsigned integer at the top of
the stack is zero.

Stack: @code{( UINT -- UINT )}

@node Instruction bzl
@subsubsection Instruction bzl
@pvindex bzl

Synopsys:

@example
bzl LABEL
@end example

Branch to the given LABEL if the long at the top of the stack
is zero.

Stack: @code{( LONG -- LONG )}

@node Instruction bzlu
@subsubsection Instruction bzlu
@pvindex bzlu

Synopsys:

@example
bzlu LABEL
@end example

Branch to the given LABEL if the unsigned long at the top of the
stack is zero.

Stack: @code{( ULONG -- ULONG )}

@node Instruction bnzi
@subsubsection Instruction bnzi
@pvindex bnzi

Synopsys:

@example
bnzi LABEL
@end example

Branch to the given LABEL if the integer at the top of the stack
is nonzero.

Stack: @code{( INT -- INT )}

@node Instruction bnziu
@subsubsection Instruction bnziu
@pvindex bnziu

Synopsys:

@example
bnziu LABEL
@end example

Branch to the given LABEL if the unsigned integer at the top of the
stack is nonzero.

Stack: @code{( UINT -- UINT )}

@node Instruction bnzl
@subsubsection Instruction bnzl
@pvindex bnzl

Synopsys:

@example
bnzl LABEL
@end example

Branch to the given LABEL if the long at the top of the stack is
nonzero.

Stack: @code{( LONG -- LONG )}

@node Instruction bnzlu
@subsubsection Instruction bnzlu
@pvindex bnzlu

Synopsys:

@example
bnzlu LABEL
@end example

Branch to the given LABEL if the unsigned long at the top of the
stack is nonzero.

Stack: @code{( ULONG -- ULONG )}

@node Conversion instructions
@subsection Conversion instructions

@menu
* Instruction ctos::
* Instruction itoi::
* Instruction itoiu::
* Instruction itol::
* Instruction itolu::
* Instruction iutoi::
* Instruction iutoiu::
* Instruction iutol::
* Instruction iutolu::
* Instruction ltoi::
* Instruction ltoiu::
* Instruction ltol::
* Instruction ltolu::
* Instruction lutoi::
* Instruction lutoiu::
* Instruction lutol::
* Instruction lutolu::
@end menu

@node Instruction ctos
@subsubsection Instruction ctos
@pvindex ctos

Synopsys:

@example
ctos
@end example

Convert the character encoded as an unsigned integer at the top of
the stack to a string that contains just that character.

Stack: @code{( UINT -- UINT STR )}

@node Instruction itoi
@subsubsection Instruction itoi
@pvindex itoi

Synopsys:

@example
itoi NBITS
@end example

Convert the integer at the top of the stack to an integer
featuring NBITS bits.

NBITS can be any number from 1 to 32.

Stack: @code{( INT -- INT INT )}

@node Instruction itoiu
@subsubsection Instruction itoiu
@pvindex itoiu

Synopsys:

@example
itoiu NBITS
@end example

Convert the integer at the top of the stack to an unsigned integer
featuring NBITS bits.

NBITS can be any number from 1 to 32.

Stack: @code{( INT -- INT UINT )}

@node Instruction itol
@subsubsection Instruction itol
@pvindex itol

Synopsys:

@example
itol NBITS
@end example

Convert the integer at the top of the stack to a long featuring
NBITS bits.

NBITS can be any number from 1 to 64.

Stack: @code{( INT -- INT LONG )}

@node Instruction itolu
@subsubsection Instruction itolu
@pvindex itolu

Synopsys:

@example
itolu NBITS
@end example

Convert the integer at the top of the stack to an unsigned long
featuring NBITS bits.

NBITS can be any number from 1 to 64.

Stack: @code{( INT -- INT ULONG )}

@node Instruction iutoi
@subsubsection Instruction iutoi
@pvindex iutoi

Synopsys:

@example
iutoi NBITS
@end example

Convert the unsigned integer at the top of the stack to an integer
featuring NBITS bits.

NBITS can be any number from 1 to 32.

Stack: @code{( UINT -- UINT INT )}

@node Instruction iutoiu
@subsubsection Instruction iutoiu
@pvindex iutoiu

Synopsys:

@example
iutoiu NBITS
@end example

Convert the unsigned integer at the top of the stack to an unsigned
integer featuring NBITS bits.

NBITS can be any number from 1 to 32.

Stack: @code{( UINT -- UINT UINT )}

@node Instruction iutol
@subsubsection Instruction iutol
@pvindex iutol

Synopsys:

@example
iutol NBITS
@end example

Convert the unsigned integer at the top of the stack to a long
featuring NBITS bits.

NBITS can be any number from 1 to 64.

Stack: @code{( UINT -- UINT LONG )}

@node Instruction iutolu
@subsubsection Instruction iutolu
@pvindex iutolu

Synopsys:

@example
iutolu NBITS
@end example

Convert the unsigned integer at the top of the stack to an
unsigned long featuring NBITS bits.

NBITS can be any number from 1 to 64.

Stack: @code{( UINT -- UINT ULONG )}

@node Instruction ltoi
@subsubsection Instruction ltoi
@pvindex ltoi

Synopsys:

@example
ltoi NBITS
@end example

Convert the long at the top of the stack to an integer
featuring NBITS bits.

NBITS can be any number from 1 to 32.

Stack: @code{( LONG -- LONG INT )}

@node Instruction ltoiu
@subsubsection Instruction ltoiu
@pvindex ltoiu

Synopsys:

@example
ltoiu NBITS
@end example

Convert the long at the top of the stack to an unsigned
integer featuring NBITS bits.

NBITS can be any number from 1 to 32.

Stack: @code{( LONG -- LONG UINT )}

@node Instruction ltol
@subsubsection Instruction ltol
@pvindex ltol

Synopsys:

@example
ltol NBITS
@end example

Convert the long at the top of the stack to a long featuring
NBITS bits.

NBITS can be any number from 1 to 64.

Stack: @code{( LONG -- LONG LONG )}

@node Instruction ltolu
@subsubsection Instruction ltolu
@pvindex ltolu

Synopsys:

@example
ltolu NBITS
@end example

Convert the long at the top of the stack to an unsigned long
featuring NBITS bits.

NBITS can be any number from 1 to 64.

Stack: @code{( LONG -- LONG ULONG )}

@node Instruction lutoi
@subsubsection Instruction lutoi
@pvindex lutoi

Synopsys:

@example
lutoi NBITS
@end example

Convert the unsigned long at the top of the stack to an integer
featuring NBITS bits.

NBITS can be any number from 1 to 32.

Stack: @code{( ULONG -- ULONG INT )}

@node Instruction lutoiu
@subsubsection Instruction lutoiu
@pvindex lutoiu

Synopsys:

@example
lutoiu NBITS
@end example

Convert the unsigned long at the top of the stack to an unsigned
integer featuring NBITS bits.

NBITS can be any number from 1 to 32.

Stack: @code{( ULONG -- ULONG UINT )}

@node Instruction lutol
@subsubsection Instruction lutol
@pvindex lutol

Synopsys:

@example
lutol NBITS
@end example

Convert the unsigned long at the top of the stack to a long
featuring NBITS bits.

Stack: @code{( ULONG -- ULONG LONG )}

@node Instruction lutolu
@subsubsection Instruction lutolu
@pvindex lutolu

Synopsys:

@example
lutolu NBITS
@end example

Convert the unsigned long at the top of the stack to an
unsigned long featuring NBITS bits.

Stack: @code{( ULONG -- ULONG ULONG )}

@node String instructions
@subsection String instructions

@menu
* Instruction strref::
* Instruction strset::
* Instruction substr::
* Instruction muls::
* Instruction sprops::
* Instruction sproph::
* Instruction spropc::
@end menu

@node Instruction strref
@subsubsection Instruction strref
@pvindex strref

Synopsys:

@example
strref
@end example

Given a string and an unsigned long at the top of the stack, push an
unsigned integer with the code of the character that occupies that
position in the string, on the stack.

The index is zero-based.  If it is less than 0 or exceeds the
length of the string, then PVM_E_OUT_OF_BOUNDS is raised.

Stack: @code{( STR ULONG -- STR ULONG UINT )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction strset
@subsubsection Instruction strset
@pvindex strset

Synopsys:

@example
strset
@end example

Given a string STR, an index FROM and a string NEWSTR, copy the content
of NEWSTR to STR at index FROM.

Index is zero-based.

If FROM >= the size of the string, or if FROM+len(NEWSTR) > the size
of the string, raise the PVM_E_OUT_OF_BOUNDS exception.

Stack: @code{( STR ULONG NEWSTR -- STR )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction substr
@subsubsection Instruction substr
@pvindex substr

Synopsys:

@example
substr
@end example

Given a string and two indices FROM and TO conforming a semi-open
interval [FROM,TO), push the substring enclosed by that interval.

Both indexes are zero-based.

If FROM >= the size of the string, or if TO > the size of the
string, or if FROM >= TO, raise the PVM_E_OUT_OF_BOUNDS exception.

Stack: @code{( STR ULONG(from) ULONG(to) -- STR ULONG(from) ULONG(to) STR )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction muls
@subsubsection Instruction muls
@pvindex muls

Synopsys:

@example
muls
@end example

Given a string and an unsigned long on the stack, push a new
string value whose value is the concatenation of the argument
string applied to itself as many times as the unsigned long.  If
the second argument to muls is 0 then the result of the operation
is the empty string.

Stack: @code{( STR ULONG -- STR ULONG STR )}

@node Instruction sprops
@subsubsection Instruction sprops
@pvindex sprops

Synopsys:

@example
sprops
@end example

Given a string STR, set the styling class of the substring with
length LEN from index IDX to CLASS.

Stack: @code{( STR IDX LEN CLASS -- STR )}

@node Instruction sproph
@subsubsection Instruction sproph
@pvindex sproph

Synopsys:

@example
sproph
@end example

Given a string STR, set the hyperlink property (which characterized
by a URL and an ID) of the substring with length LEN from index IDX.

Stack: @code{( STR IDX LEN URL ID -- STR )}

@node Instruction spropc
@subsubsection Instruction spropc
@pvindex spropc

Synopsys:

@example
spropc
@end example

Given a string on the stack, push the copy of the string with all
properties cleared.

Stack: @code{( STR -- STR )}

@node Array instructions
@subsection Array instructions

@menu
* Instruction mka::
* Instruction ains::
* Instruction arem::
* Instruction aset::
* Instruction aref::
* Instruction arefo::
* Instruction asettb::
@end menu

@node Instruction mka
@subsubsection Instruction mka
@pvindex mka

Synopsys:

@example
mka
@end example

Make a new empty array value.

TYP is the type of the new array.

NELEM is a hint on how many elements to use to initialize the array
value.  This is to avoid allocating memory that will never be used.
Use 0UL when the number of elements in the array are not known
in advance; this will make the PVM to choose a reasonable default.

Stack: @code{( TYP ULONG(nelem) -- ARR )}

@node Instruction ains
@subsubsection Instruction ains
@pvindex ains

Synopsys:

@example
ains
@end example

Insert a new element VAL, at the end of the array ARR, making it grow.

If IDX is less than the current size of the array, the value is
stored in the referred argument.

If IDX is equal or bigger than the current size of the array, the
same element is replicated in the previous elements.

Examples:

a = [a1, a2, a3]

[a1, a2, a3] 2 VAL ains -> INVAL exception
[a1, a2, a3] 3 VAL ains -> [a1, a2, a3, VAL]
[a1, a2, a3] 5 VAL ains -> [a1, a2, a3, VAL, VAL, VAL]

Stack: @code{( ARR IDX VAL -- ARR )}

Exceptions: @code{PVM_E_INVAL}

@node Instruction arem
@subsubsection Instruction arem
@pvindex arem

Synopsys:

@example
arem
@end example

Remove an element from an array at the specified index, making it
schrink.

If IDX doesn't correspond to an element in the array, raise
PVM_E_OUT_OF_BOUNDS.  This always happens if the array is empty.

Stack: @code{( ARR IDX -- ARR )}
Exception: PVM_E_OUT_OF_BOUNDS

@node Instruction aset
@subsubsection Instruction aset
@pvindex aset

Synopsys:

@example
aset
@end example

Set the value with index ULONG in the array ARR to have the value
VAL.  The index in ULONG should be in range, since this instruction
is not checked.

Stack: @code{( ARR ULONG VAL -- ARR )}

@node Instruction aref
@subsubsection Instruction aref
@pvindex aref

Synopsys:

@example
aref
@end example

Given an array ARR and an index ULONG, push the element of the array
occupying that position on the stack.

If the provided index is out of bounds, then raise
PVM_E_OUT_OF_BOUNDS.

Stack: @code{( ARR ULONG -- ARR ULONG VAL )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction arefo
@subsubsection Instruction arefo
@pvindex arefo

Synopsys:

@example
arefo
@end example

Given an array ARR and an index ULONG, push the offset of the
element occupying that position in the array.

If the provided index is out of bounds, then raise
PVM_E_OUT_OF_BOUNDS.

Stack: @code{( ARR ULONG -- ARR ULONG OFF )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction asettb
@subsubsection Instruction asettb
@pvindex asettb

Synopsys:

@example
asettb
@end example

Given an array ARR and a closure BOUND, set the later as the array's
bounder function.  This is a function that, once executed with no
arguments, returns the size of the array.

Stack: @code{( ARR BOUND -- ARR )}

@node Struct instructions
@subsection Struct instructions

@menu
* Instruction mksct::
* Instruction sset::
* Instruction sseti::
* Instruction sref::
* Instruction srefo::
* Instruction srefmnt::
* Instruction srefnt::
* Instruction srefi::
* Instruction srefia::
* Instruction srefio::
* Instruction srefin::
* Instruction smodi::
@end menu

@node Instruction mksct
@subsubsection Instruction mksct
@pvindex mksct

Synopsys:

@example
mksct
@end example

Given an offset, a list of fields, a list of methods and a struct
type, create a struct value and push it on the stack.

Each field is specified as a triplet [OFF STR VAL] where OFF is the
offset of field, STR the name of the field or PVM_NULL if the field
is anonymous, and VAL is a value.

Each method is specified as a tuple [STR VAL] where STR is the name
of the method and VAL is the closure value corresponding to the
method.

Stack: @code{( OFF [OFF STR VAL]... [STR VAL]... ULONG ULONG TYP -- SCT )}

@node Instruction sset
@subsubsection Instruction sset
@pvindex sset

Synopsys:

@example
sset
@end example

Given a struct, a field name and a value, replace the value of
the referred struct field with the given value.  If the struct
does not have a field with the given name, then raise PVM_E_ELEM.

Stack: @code{( SCT STR VAL -- SCT )}

Exceptions: @code{PVM_E_ELEM}

@node Instruction sseti
@subsubsection Instruction sseti
@pvindex sseti

Synopsys:

@example
sseti
@end example

Given a struct, a field index and a value, replace the value
of the referred struct field with the given value.  If the
given index does not refer to a struct field, then raise
PVM_E_ELEM.

Stack: @code{(SCT IDX VAL -- SCT)}

Exceptions: @code{PVM_E_ELEM}

@node Instruction sref
@subsubsection Instruction sref
@pvindex sref

Synopsys:

@example
sref
@end example

Given a struct and a field name, push the value contained in the
referred struct field on the stack.  If the struct does not have a
field with the given name, or if the field is absent from the struct
value then raise PVM_E_ELEM.

Stack: @code{( SCT STR -- SCT STR VAL )}

Exceptions: @code{PVM_E_ELEM}

@node Instruction srefo
@subsubsection Instruction srefo
@pvindex srefo

Synopsys:

@example
srefo
@end example

Given a struct and a field name, push the bit-offset of the referred
field on the stack.  If the struct does not have a field with the given
name, or if the field is absent from the struct value then raise
PVM_E_ELEM.

Stack: @code{( SCT STR -- SCT STR BOFF )}

Exceptions: @code{PVM_E_ELEM}

@node Instruction srefmnt
@subsubsection Instruction srefmnt
@pvindex srefmnt

Synopsys:

@example
srefmnt
@end example

Given a struct and a method name, push the closure value corresponding
to that method on the stack.  If the struct does not have a method with
the given name then push PVM_NULL.

Stack: @code{( SCT STR - SCT STR CLS )}

@node Instruction srefnt
@subsubsection Instruction srefnt
@pvindex srefnt

Synopsys:

@example
srefnt
@end example

Given a struct and a field name, push the value contained in the
struct field on the stack.  If the struct does not have a field with
the given name, or if the field is absent from the struct value then
push PVM_NULL.

Stack: @code{( SCT STR -- SCT STR VAL )}

@node Instruction srefi
@subsubsection Instruction srefi
@pvindex srefi

Synopsys:

@example
srefi
@end example

Given a struct and an index, push the value of the field occupying
the position specified by the index in the given struct.  If the
struct doesn't have that many fields, raise PVM_E_OUT_OF_BOUNDS.

Stack: @code{( SCT ULONG -- SCT ULONG VAL )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction srefia
@subsubsection Instruction srefia
@pvindex srefia

Synopsys:

@example
srefia
@end example

Given a struct and an index, push 1 if the field occupying the
position specified by the index in the given struct is absent.  Push
0 otherwise.  If the struct doesn't have that many fields, raise
PVM_E_OUT_OF_BOUNDS.

Stack: @code{( SCT ULONG -- SCT ULONG INT )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction srefio
@subsubsection Instruction srefio
@pvindex srefio

Synopsys:

@example
srefio
@end example

Given a struct and an index, push the offset of the field occupying
the position specified by the index in the given struct.  If the
struct doesn't have that many fields, raise PVM_E_OUT_OF_BOUNDS.

Stack: @code{( SCT ULONG -- SCT ULONG BOFF )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction srefin
@subsubsection Instruction srefin
@pvindex srefin

Synopsys:

@example
srefin
@end example

Given a struct and an index, push the name of the field occupying
the position specified by the index in the given struct.  If the
field is anonymous, push PVM_NULL.  If the struct doesn't have that
many fields, raise PVM_E_OUT_OF_BOUNDS.

Stack: @code{( SCT ULONG -- SCT ULONG STR )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Instruction smodi
@subsubsection Instruction smodi
@pvindex smodi

Synopsys:

@example
smodi
@end example

Given a struct and an index, push the modified flags of the field
occupying the position specified by the index in the given struct.
If the struct doesn't have that many fields, raise
PVM_E_OUT_OF_BOUNDS.

Stack: @code{( SCT ULONG -- SCT ULONG BOOL )}

Exceptions: @code{PVM_E_OUT_OF_BOUNDS}

@node Offset Instructions
@subsection Offset Instructions

@menu
* Instruction mko::
* Instruction ogetm::
* Instruction osetm::
* Instruction ogetu::
* Instruction ogetbt::
@end menu

@node Instruction mko
@subsubsection Instruction mko
@pvindex mko

Synopsys:

@example
mko
@end example

Given an integral magnitude VAL and an unit expressed in an ULONG,
make an offset value and push it on the stack.

Stack: @code{( VAL ULONG -- OFF )}

@node Instruction ogetm
@subsubsection Instruction ogetm
@pvindex ogetm

Synopsys:

@example
ogetm
@end example

Given an offset OFF, push its magnitude on the stack.

Stack: @code{( OFF -- OFF VAL )}

@node Instruction osetm
@subsubsection Instruction osetm
@pvindex osetm

Synopsys:

@example
osetm
@end example

Given an offset OFF and an integral value VAL, make it the
offset's magnitude.

Stack: @code{( OFF VAL -- OFF )}

@node Instruction ogetu
@subsubsection Instruction ogetu
@pvindex ogetu

Synopsys:

@example
ogetu
@end example

Given an offset OFF, push its unit on the stack.

Stack: @code{( OFF -- OFF ULONG )}

@node Instruction ogetbt
@subsubsection Instruction ogetbt
@pvindex ogetbt

Synopsys:

@example
ogetbt
@end example

Given an offset OFF, push its base type on the stack.

Stack: @code{( OFF -- OFF TYP )}

@node Instructions to handle mapped values
@subsection Instructions to handle mapped values

@menu
* Instruction mm::
* Instruction map::
* Instruction unmap::
* Instruction reloc::
* Instruction ureloc::
* Instruction mgets::
* Instruction msets::
* Instruction mgeto::
* Instruction mseto::
* Instruction mgetios::
* Instruction msetios::
* Instruction mgetm::
* Instruction msetm::
* Instruction mgetw::
* Instruction msetw::
* Instruction mgetsel::
* Instruction msetsel::
* Instruction mgetsiz::
* Instruction msetsiz::
@end menu

@node Instruction mm
@subsubsection Instruction mm
@pvindex mm

Synopsys:

@example
mm
@end example

Given a value, push 1 on the stack if the value is mapped.
Push 0 otherwise.

Stack: @code{( VAL -- VAL INT )}

@node Instruction map
@subsubsection Instruction map
@pvindex map

Synopsys:

@example
map
@end example

Given a value, mark it as as mapped.  If the value can't be
mapped then this is a no-operation.

Stack: @code{( VAL -- VAL )}

@node Instruction unmap
@subsubsection Instruction unmap
@pvindex unmap

Synopsys:

@example
unmap
@end example

Given a value, mark it as as not mapped.  If the value can't be
mapped then this is a no-operation.

Stack: @code{( VAL -- VAL )}

@node Instruction reloc
@subsubsection Instruction reloc
@pvindex reloc

Synopsys:

@example
reloc
@end example

Given a value, a IO space expressed in an ulong, and a bit-offset
expressed in an ulong, relocate the value to the given bit-offset at
the given IO space.

If the given value is not map-able then raise PVM_E_INVAL.

Stack: @code{( VAL ULONG ULONG -- VAL ULONG ULONG )}

Exceptions: @code{PVM_E_INVAL}

@node Instruction ureloc
@subsubsection Instruction ureloc
@pvindex ureloc

Synopsys:

@example
ureloc
@end example

Given a value, undo the last reloc performed on the value.

If the given value is not map-able then raise PVM_E_INVAL.

Stack: @code{( VAL -- VAL )}

Exceptions: @code{PVM_E_INVAL}

@node Instruction mgets
@subsubsection Instruction mgets
@pvindex mgets

Synopsys:

@example
mgets
@end example

Given a value, push a boolean indicating whether the
value is strict.  If the given value is not map-able then push
false, i.e. 0.

Stack: @code{( VAL -- VAL INT )}

@node Instruction msets
@subsubsection Instruction msets
@pvindex msets

Synopsys:

@example
msets
@end example

Given a value and a boolean, set the strictness of the value
to the given boolean.  If the value is not map-able this is
a no-operation.

Stack: @code{( VAL INT -- VAL )}

@node Instruction mgeto
@subsubsection Instruction mgeto
@pvindex mgeto

Synopsys:

@example
mgeto
@end example

Given a map-able value, push its bit-offset on the stack as an
unsigned long.  If the given value is not map-able then push
PVM_NULL.

Stack: @code{( VAL -- VAL ULONG )}

@node Instruction mseto
@subsubsection Instruction mseto
@pvindex mseto

Synopsys:

@example
mseto
@end example

Given a map-able value an a bit-offset, set its offset to the value.
If the given value is not map-able, then the offset is ignored.

Stack: @code{( VAL ULONG -- VAL )}

@node Instruction mgetios
@subsubsection Instruction mgetios
@pvindex mgetios

Synopsys:

@example
mgetios
@end example

Given a map-able value, push its associated IO space on the stack.
If the given value is not map-able, then push PVM_NULL.

Stack: @code{( VAL -- VAL INT )}

@node Instruction msetios
@subsubsection Instruction msetios
@pvindex msetios

Synopsys:

@example
msetios
@end example

Given a map-able value and an IOS descriptor, set it as its
associated IO space.  If the IOS descriptor is PVM_NULL then it uses
the current IO space.  If the given value is not map-able then the
IO space is ignored.

Stack: @code{( VAL INT -- VAL )}

@node Instruction mgetm
@subsubsection Instruction mgetm
@pvindex mgetm

Synopsys:

@example
mgetm
@end example

Given a map-able value, push its mapper closure on the stack.  If
the given value is not map-able, then push PVM_NULL.

Stack: @code{( VAL -- VAL CLS )}

@node Instruction msetm
@subsubsection Instruction msetm
@pvindex msetm

Synopsys:

@example
msetm
@end example

Given a map-able value and a closure, set it as its mapper.  If the
given value is not map-able then the closure is ignored.

Stack: @code{( VAL CLS -- VAL )}

@node Instruction mgetw
@subsubsection Instruction mgetw
@pvindex mgetw

Synopsys:

@example
mgetw
@end example

Given a map-able value, push its writer closure on the stack.  If
the given value is not map-able, then push PVM_NULL.

Stack: @code{( VAL -- VAL CLS )}

@node Instruction msetw
@subsubsection Instruction msetw
@pvindex msetw

Synopsys:

@example
msetw
@end example

Given a map-able value and a closure, set it as its writer.  If the
given value is not map-able then the closure is ignored.

Stack: @code{( VAL CLS -- VAL )}

@node Instruction mgetsel
@subsubsection Instruction mgetsel
@pvindex mgetsel

Synopsys:

@example
mgetsel
@end example

Given a map-able value in the TOS, push the number of elements to
which its mapping is bounded to.  If the value is not mapped, or
if it is not bounded by number of elements, push PVM_NULL.

Note that only array values can have mappings bounded by number of
elements.

Stack: @code{( VAL -- VAL ULONG )}

@node Instruction msetsel
@subsubsection Instruction msetsel
@pvindex msetsel

Synopsys:

@example
msetsel
@end example

Given a map-able value and an unsigned long, set it as the mapping
bound by number of elements.  If the value is not map-able the
unsigned long is ignored.

Note that only array values can have mappings bounded by number of
elements.

Stack: @code{( VAL ULONG -- VAL )}

@node Instruction mgetsiz
@subsubsection Instruction mgetsiz
@pvindex mgetsiz

Synopsys:

@example
mgetsiz
@end example

Given a map-able value in the TOS, push its mapping size-bound as a
bit-offset.  If the value is not map-able, or if it is not bounded
by size, push PVM_NULL.

Note that only array values can have mappings bounded by size.

Stack: @code{( VAL -- VAL ULONG )}

@node Instruction msetsiz
@subsubsection Instruction msetsiz
@pvindex msetsiz

Synopsys:

@example
msetsiz
@end example

Given a map-able value and a bit-offset, set it as the mapping
size-bound.  If the value is not map-able, the bit-offset is
ignored.

Note that only array values can have mappings bounded by size.

Stack: @code{( VAL ULONG -- VAL )}

@node Type related instructions
@subsection Type related instructions

@menu
* Instruction isa::
* Instruction typof::
* Instruction isty::
* Instruction tyisi::
* Instruction tyisiu::
* Instruction tyisl::
* Instruction tyislu::
* Instruction tyiso::
* Instruction tyiss::
* Instruction tyisa::
* Instruction tyisc::
* Instruction tyissct::
* Instruction tyisv::
* Instruction mktyv::
* Instruction mktyi::
* Instruction tyigetsz::
* Instruction tyigetsg::
* Instruction mktys::
* Instruction mktyo::
* Instruction tyogetm::
* Instruction tyogetu::
* Instruction mktya::
* Instruction tyagett::
* Instruction tyagetb::
* Instruction mktyc::
* Instruction mktysct::
* Instruction tysctgetn::
* Instruction tysctgetnf::
* Instruction tysctgetfn::
* Instruction tysctgetft::
@end menu

@node Instruction isa
@subsubsection Instruction isa
@pvindex isa

Synopsys:

@example
isa
@end example

Given a value and a type, push 1 on the stack if the value is of the
given type.  Push 0 otherwise.

Stack: @code{( VAL TYPE -- TYPE VAL INT )}

@node Instruction typof
@subsubsection Instruction typof
@pvindex typof

Synopsys:

@example
typof
@end example

Given a value that is not itself a type, push its type on the stack.
Given a value that is a type, push the value on the stack.

Stack: @code{( VAL -- VAL TYPE )}

@node Instruction isty
@subsubsection Instruction isty
@pvindex isty

Synopsys:

@example
isty
@end example

Given a value, push 1 on the stack if it is a PVM type.
Push 0 otherwise.

Stack: @code{( TYPE -- TYPE INT )}

@node Instruction tyisi
@subsubsection Instruction tyisi
@pvindex tyisi

Synopsys:

@example
tyisi
@end example

Given a type, push 1 on the stack if it is an int.
Push 0 otherwise.

Stack: @code{( TYPE -- TYPE INT )}

@node Instruction tyisiu
@subsubsection Instruction tyisiu
@pvindex tyisiu

Synopsys:

@example
tyisiu
@end example

Given a type, push 1 on the stack if it is an uint.
Push 0 otherwise.

Stack: @code{( TYPE -- TYPE INT )}

@node Instruction tyisl
@subsubsection Instruction tyisl
@pvindex tyisl

Synopsys:

@example
tyisl
@end example

Given a type, push 1 on the stack if it is a long.
Push 0 otherwise.

Stack: @code{( TYPE -- TYPE INT )}

@node Instruction tyislu
@subsubsection Instruction tyislu
@pvindex tyislu

Synopsys:

@example
tyislu
@end example

Given a type, push 1 on the stack if it is an ulong.
Push 0 otherwise.

Stack: @code{( TYPE -- TYPE INT )}

@node Instruction tyiso
@subsubsection Instruction tyiso
@pvindex tyiso

Synopsys:

@example
tyiso
@end example

Given a type, push 1 on the stack if it is an offset.  Push 0
otherwise.

Stack: @code{( TYPE -- TYPE INT )}

@node Instruction tyiss
@subsubsection Instruction tyiss
@pvindex tyiss

Synopsys:

@example
tyiss
@end example

Given a type, push 1 on the stack if it is a string.  Push 0
otherwise.

Stack: @code{( TYPE -- TYPE INT )}

@node Instruction tyisa
@subsubsection Instruction tyisa
@pvindex tyisa

Synopsys:

@example
tyisa
@end example

Given a type, push 1 on the stack if it is an array.  Push 0
otherwise.

Stack: @code{( TYPE -- TYPE INT )}

@node Instruction tyisc
@subsubsection Instruction tyisc
@pvindex tyisc

Synopsys:

@example
tyisc
@end example

Given a type, push 1 on the stack if it is a closure.  Push 0
otherwise.

Stack: @code{( TYPE -- TYPE INT )}

@node Instruction tyissct
@subsubsection Instruction tyissct
@pvindex tyissct

Synopsys:

@example
tyissct
@end example

Given a type, push 1 on the stack if it is a struct.  Push 0
otherwise.

Stack: @code{( TYPE -- TYPE INT )}

@node Instruction tyisv
@subsubsection Instruction tyisv
@pvindex tyisv

Synopsys:

@example
tyisv ()
@end example

Given a type, push 1 on the stack if it is a void.  Push 0
otherwise.

Stack: @code{( TYPE -- TYPE INT)}

@node Instruction mktyv
@subsubsection Instruction mktyv
@pvindex mktyv

Synopsys:

@example
mktyv
@end example

Build a "void" type and push it on the stack.

Stack: @code{( -- TYPE )}

@node Instruction mktyi
@subsubsection Instruction mktyi
@pvindex mktyi

Synopsys:

@example
mktyi
@end example

Given an unsigned long denoting a bit width, and an unsigned int
denoting signedness (0 is unsigned, 1 is signed), build a an
integral type with these features and push it on the stack.

Stack: @code{( ULONG UINT -- TYPE )}

@node Instruction tyigetsz
@subsubsection Instruction tyigetsz
@pvindex tyigetsz

Synopsys:

@example
tyigetsz
@end example

Given an integral type, push its size (in bits) to the stack.

Stack: @code{( ITYPE -- ITYPE ULONG )}

@node Instruction tyigetsg
@subsubsection Instruction tyigetsg
@pvindex tyigetsg

Synopsys:

@example
tyigetsg
@end example

Given an integral type, push its sign to the stack.  0 means
unsigned and 1 means signed.

Stack: @code{( ITYPE -- ITYPE INT )}

@node Instruction mktys
@subsubsection Instruction mktys
@pvindex mktys

Synopsys:

@example
mktys
@end example

Push a string type on the stack.

Stack: @code{( -- TYPE )}

@node Instruction mktyo
@subsubsection Instruction mktyo
@pvindex mktyo

Synopsys:

@example
mktyo
@end example

Given a base integral type and an integer denoting an offset unit
(multiple of the base unit) construct an offset type having these
features, and push it on the stack.

Stack: @code{( TYPE INT -- TYPE )}
define F(res, a, b) \
undef F

@node Instruction tyogetm
@subsubsection Instruction tyogetm
@pvindex tyogetm

Synopsys:

@example
tyogetm
@end example

Given an offset type, push type of magnitude to the stack.

Stack : ( OTYPE -- OTYPE ITYPE)

@node Instruction tyogetu
@subsubsection Instruction tyogetu
@pvindex tyogetu

Synopsys:

@example
tyogetu
@end example

Given an offset type, push unit value to the stack.

Stack : ( OTYPE -- OTYPE ULONG)

@node Instruction mktya
@subsubsection Instruction mktya
@pvindex mktya

Synopsys:

@example
mktya
@end example

Given an elements type and a bounder closure, build an array type
having these features and push it on the stack.  The bounder closure
can return either PVM_NULL, or an integer, or an offset as the boundary
of the array type.

Stack: @code{( TYPE BOUNDER -- TYPE )}

@node Instruction tyagett
@subsubsection Instruction tyagett
@pvindex tyagett

Synopsys:

@example
tyagett
@end example

Given an array type, push the type of its elements on the stack.

Stack: @code{( TYPE -- TYPE TYPE )}

@node Instruction tyagetb
@subsubsection Instruction tyagetb
@pvindex tyagetb

Synopsys:

@example
tyagetb
@end example

Given an array type, push its bound on the stack.

Stack: @code{( TYPE -- TYPE (ULONG|NULL) )}

@node Instruction mktyc
@subsubsection Instruction mktyc
@pvindex mktyc

Synopsys:

@example
mktyc
@end example

Given a list of argument types, a return type and a number of
arguments, build a closure type and push it on the stack.

Stack: @code{( TYPE... TYPE ULONG -- TYPE )}

@node Instruction mktysct
@subsubsection Instruction mktysct
@pvindex mktysct

Synopsys:

@example
mktysct
@end example

Given a list of field descriptors, a number of fields and a struct
type name, build a struct type and push it on the stack.

Each field descriptor has the form [STRING TYPE] and contains the
name of the field and its type.

Stack: @code{( [STRING TYPE]... ULONG STR -- TYPE )}

@node Instruction tysctgetn
@subsubsection Instruction tysctgetn
@pvindex tysctgetn

Synopsys:

@example
tysctgetn
@end example

Given a struct type, push its name to the stack.  If the struct
type is not named push PVM_NULL.

Stack: @code{( SCT -- SCT STR )}

@node Instruction tysctgetnf
@subsubsection Instruction tysctgetnf
@pvindex tysctgetnf

Synopsys:

@example
tysctgetnf
@end example

Given a struct type, push its number of fields to the stack.

Stack: @code{( SCT -- SCT ULONG )}

@node Instruction tysctgetfn
@subsubsection Instruction tysctgetfn
@pvindex tysctgetfn

Synopsys:

@example
tysctgetfn
@end example

Given a struct type and an index, push the field name to the stack.
If the field is not named push PVM_NULL.

Stack: @code{( SCT ULONG -- SCT ULONG STR )}

@node Instruction tysctgetft
@subsubsection Instruction tysctgetft
@pvindex tysctgetft

Synopsys:

@example
tysctgetft
@end example

Given a struct type and an index, push the field type to the stack.

Stack: @code{( SCT ULONG -- SCT ULONG TYP )}

@node IO instructions
@subsection IO instructions

@menu
* Instruction write::
* Instruction peeki::
* Instruction peekiu::
* Instruction peekl::
* Instruction peeklu::
* Instruction peekdi::
* Instruction peekdiu::
* Instruction peekdl::
* Instruction peekdlu::
* Instruction pokei::
* Instruction pokeiu::
* Instruction pokel::
* Instruction pokelu::
* Instruction pokedi::
* Instruction pokediu::
* Instruction pokedl::
* Instruction pokedlu::
* Instruction peeks::
* Instruction pokes::
@end menu

@node Instruction write
@subsubsection Instruction write
@pvindex write

Synopsys:

@example
write
@end example

If the value at the TOS is mapped, then write it to its associated
IO space.  Otherwise, this is a no-op.

Stack: @code{( VAL -- VAL )}

Exceptions: @code{PVM_E_IOS_FULL, PVM_E_CONSTRAINT_ERROR}

@node Instruction peeki
@subsubsection Instruction peeki
@pvindex peeki

Synopsys:

@example
peeki NENC,ENDIAN,BITS
@end example

Given an IOS descriptor and a bit-offset, peek an integer value of
width BITS bits.  The negative encoding and endianness to be used
are specified in the instruction arguments.

Stack: @code{( INT ULONG -- INT )}

@node Instruction peekiu
@subsubsection Instruction peekiu
@pvindex peekiu

Synopsys:

@example
peekiu ENDIAN,BITS
@end example

Given an IOS descriptor and a bit-offset, peek an unsigned integer
value of width BITS bits.  The endianness to be used is specified in
the instruction arguments.

Stack: @code{( INT ULONG -- INT )}

@node Instruction peekl
@subsubsection Instruction peekl
@pvindex peekl

Synopsys:

@example
peekl NENC,ENDIAN,BITS
@end example

Given an IOS descriptor and a bit-offset, peek a long value of width
BITS bits.  The negative encoding and endianness to be used are
specified in the instruction arguments.

Stack: @code{( INT ULONG -- LONG )}

@node Instruction peeklu
@subsubsection Instruction peeklu
@pvindex peeklu

Synopsys:

@example
peeklu ENDIAN,BITS
@end example

Given an IOS descriptor and a bit-offset, peek an unsigned long value
of width BITS bits.  The endianness to be used is specified in the
instruction arguments.

Stack: @code{( INT ULONG -- ULONG )}

@node Instruction peekdi
@subsubsection Instruction peekdi
@pvindex peekdi

Synopsys:

@example
peekdi BITS
@end example

Given an IOS descriptor and a bit-offset, peek an integer value of
width BITS bits.  Use the default endianness and negative encoding.

Stack: @code{( INT ULONG -- INT )}

@node Instruction peekdiu
@subsubsection Instruction peekdiu
@pvindex peekdiu

Synopsys:

@example
peekdiu BITS
@end example

Given an IOS descriptor and a bit-offset, peek an unsigned integer
value of width BITS bits.  Use the default endianness.

Stack: @code{( INT ULONG -- UINT )}

@node Instruction peekdl
@subsubsection Instruction peekdl
@pvindex peekdl

Synopsys:

@example
peekdl BITS
@end example

Given an IOS descriptor and a bit-offset, peek a long value of width
BITS bits.  Use the default endianness and negative encoding.

Stack: @code{( INT ULONG -- LONG )}

@node Instruction peekdlu
@subsubsection Instruction peekdlu
@pvindex peekdlu

Synopsys:

@example
peekdlu BITS
@end example

Given an IOS descriptor and a bit-offset, peek an unsigned long value
of width BITS bits.  Use the default endianness.

Stack: @code{( INT ULONG -- ULONG )}

@node Instruction pokei
@subsubsection Instruction pokei
@pvindex pokei

Synopsys:

@example
pokei NENC,ENDIAN,BITS
@end example

Given an IOS descriptor, a bit-offset and an integer value of BITS
bits, poke it.  Use the negative encoding and endianness specified
in the instruction arguments.

Stack: @code{( INT ULONG INT -- )}

@node Instruction pokeiu
@subsubsection Instruction pokeiu
@pvindex pokeiu

Synopsys:

@example
pokeiu ENDIAN,BITS
@end example

Given an IOS descriptor, a bit-offset and an unsigned integer value
of BITS bits, poke it.  Use the endianness specified in the
instruction arguments.

Stack: @code{( INT ULONG INT -- )}

@node Instruction pokel
@subsubsection Instruction pokel
@pvindex pokel

Synopsys:

@example
pokel NENC,ENDIAN,BITS
@end example

Given an IOS descriptor, a bit-offset and a long value of BITS bits,
poke it.  Use the negative encoding and endianness specified in the
instruction arguments.

Stack: @code{( INT ULONG LONG -- )}

@node Instruction pokelu
@subsubsection Instruction pokelu
@pvindex pokelu

Synopsys:

@example
pokelu ENDIAN,BITS
@end example

Given an IOS descriptor, a bit-offset and an unsigned long value of
BITS bits, poke it.  Use the endianness specified in the instruction
arguments.

Stack: @code{( INT ULONG ULONG -- )}

@node Instruction pokedi
@subsubsection Instruction pokedi
@pvindex pokedi

Synopsys:

@example
pokedi BITS
@end example

Given an IOS descriptor, a bit-offset and an integer of BITS bits,
poke it.  Use the default negative encoding and endianness.

Stack: @code{( INT ULONG INT -- )}

@node Instruction pokediu
@subsubsection Instruction pokediu
@pvindex pokediu

Synopsys:

@example
pokediu BITS
@end example

Given an IOS descriptor, a bit-offset and an unsigned integer of BITS
bits, poke it.  Use the default endianness.

Stack: @code{( INT ULONG UINT -- )}

@node Instruction pokedl
@subsubsection Instruction pokedl
@pvindex pokedl

Synopsys:

@example
pokedl BITS
@end example

Given an IOS descriptor, a bit-offset and a long of BITS bits, poke
it.  Use the default negative encoding and endianness.

Stack: @code{( INT ULONG LONG -- )}

@node Instruction pokedlu
@subsubsection Instruction pokedlu
@pvindex pokedlu

Synopsys:

@example
pokedlu BITS
@end example

Given an IOS descriptor, a bit-offset and an unsigned long of BITS
bits, poke it.  Use the default endianness.

Stack: @code{( INT ULONG ULONG -- )}

@node Instruction peeks
@subsubsection Instruction peeks
@pvindex peeks

Synopsys:

@example
peeks
@end example

Given an IOS descriptor and a bit-offset, peek a string.

Stack: @code{( INT ULONG -- STR )}

@node Instruction pokes
@subsubsection Instruction pokes
@pvindex pokes

Synopsys:

@example
pokes
@end example

Given an IOS descriptor, a bit-offset and a string, poke it.

Stack: @code{( INT ULONG STR -- )}

@node Exceptions handling instructions
@subsection Exceptions handling instructions

@menu
* Instruction pushe::
* Instruction pope::
* Instruction raise::
* Instruction popexite::
@end menu

@node Instruction pushe
@subsubsection Instruction pushe
@pvindex pushe

Synopsys:

@example
pushe LABEL
@end example

Given an Exception struct in the stack, push a handler for it on the
exceptions stack.  An exception code 0 means any exception.

Stack: @code{( EXCEPTION -- )}

Exception Stack: @code{( -- EXCEPTION_HANDLER )}

@node Instruction pope
@subsubsection Instruction pope
@pvindex pope

Synopsys:

@example
pope
@end example

Pop an exception handler from the exceptions stack.

Stack: @code{( -- )}

Exception Stack: @code{( EXCEPTION_HANDLER -- )}

@node Instruction raise
@subsubsection Instruction raise
@pvindex raise

Synopsys:

@example
raise
@end example

Raise the given exception.

Stack: @code{( EXCEPTION -- )}

Exception Stack: @code{( -- )}

@node Instruction popexite
@subsubsection Instruction popexite
@pvindex popexite

Synopsys:

@example
popexite
@end example

Pops the exception on the stack and sets it in the VM.

Stack: @code{( EXCEPTION  -- )}

Exception Stack: @code{( -- )}

@node Debugging Instructions
@subsection Debugging Instructions

@menu
* Instruction strace::
* Instruction disas::
* Instruction note::
* Instruction vmdisp::
@end menu

@node Instruction strace
@subsubsection Instruction strace
@pvindex strace

Synopsys:

@example
strace DEPTH
@end example

Print a debugging trace with the elements of the top of the stack.
The number of elements to print is specified in DEPTH.  A depth of
zero means to print the whole stack.

Stack: @code{( -- )}

@node Instruction disas
@subsubsection Instruction disas
@pvindex disas

Synopsys:

@example
disas
@end example

Print out the disassembling of the program executed by the
closure in the top of the stack.

Stack: @code{( CLS -- CLS )}

@node Instruction note
@subsubsection Instruction note
@pvindex note

Synopsys:

@example
note VALUE
@end example

This instruction is intended to be used to insert annotations that
help to understand disassemblies.  Most of the times VALUE is a
string.

Semantically, this instruction does nothing.

Stack: @code{( -- )}

@node Instruction vmdisp
@subsubsection Instruction vmdisp
@pvindex vmdisp

Synopsys:

@example
vmdisp
@end example

Pushes the current dispatching strategy of current VM to the stack.

Stack: @code{( -- STR )}

@node System Interaction Instructions
@subsection System Interaction Instructions

@menu
* Instruction getenv::
@end menu

@node Instruction getenv
@subsubsection Instruction getenv
@pvindex getenv

Synopsys:

@example
getenv
@end example

This instruction gets the name of an environment variable on the
stack and pushes the value of the corresponding environment
variable.  If no variable with the given name is defined on the
environment, then push PVM_NULL.

Stack: @code{( STR -- STR STR )}

@node Miscellaneous Instructions
@subsection Miscellaneous Instructions

@menu
* Instruction nop::
* Instruction rand::
* Instruction time::
* Instruction sleep::
* Instruction siz::
* Instruction sel::
@end menu

@node Instruction nop
@subsubsection Instruction nop
@pvindex nop

Synopsys:

@example
nop
@end example

Do nothing.

Stack: @code{( -- )}

@node Instruction rand
@subsubsection Instruction rand
@pvindex rand

Synopsys:

@example
rand
@end example

Push a pseudo-random integer to the stack.

If the argument is 0U then it is ignored.  Otherwise it is
used to set the seed for a new sequence of pseudo-random numbers.

Stack: @code{( UINT -- INT )}

@node Instruction time
@subsubsection Instruction time
@pvindex time

Synopsys:

@example
time
@end example

Push the current system time to the stack in the form of
two long elements containing the number of seconds
and nanoseconds since the epoch.

Stack: @code{( -- LONG(sec) LONG(nsec) )}

@node Instruction sleep
@subsubsection Instruction sleep
@pvindex sleep

Synopsys:

@example
sleep
@end example

Sleep for a given number of seconds and nanoseconds.

If the provided number of nanoseconds are not in the range 0 to
999999999 or the number of provided seconds is negative, pushes
-1.

If there is any other error performing the operation then push
-2.

EINTR is treated as no error currently.

Stack: @code{( LONG LONG -- LONG LONG INT )}

@node Instruction siz
@subsubsection Instruction siz
@pvindex siz

Synopsys:

@example
siz
@end example

Given a value, push its size as a bit-offset.
By convention, the following PVM values have size zero:
  type, closure, null

Stack: @code{( VAL -- VAL ULONG )}

@node Instruction sel
@subsubsection Instruction sel
@pvindex sel

Synopsys:

@example
sel
@end example

Given a value, push its length as an unsigned long.

The length of an array is the number of values contained in it.
The length of a struct is the number of fields contained in it.
The length of a string is the number of characters contained in it.
The length of any other value is 1.

Stack: @code{( VAL -- VAL ULONG )}
