Documentation Request: Core VM Operation Instructions in fift

doc/fiftbase.tex

@@ -1365,6 +1365,10 @@ \section*{Introduction}
 \item {\tt gasrunvmdict} (\dots $s$ $z$ -- \dots $x$ $z'$), a gas-aware version of {\tt runvmdict}.
 \item {\tt gasrunvm} (\dots $s$ $c$ $z$ -- \dots $x$ $c'$ $z'$), a gas-aware version of {\tt runvm}.
 \item {\tt gasrunvmctx} (\dots $s$ $c$ $t$ $z$ -- \dots $x$ $c'$ $z'$), a gas-aware version of {\tt runvmctx}.
+\item {\tt (vmopdump)} (\dots $s$ $cp$ -- \dots $s'$ $dump$), dumps detailed information about the VM instruction contained in the cell slice $s$ using the code page identifier $cp$. The instruction's string representation $dump$ is left on the stack along with the remaining cell slice $s'$ after the dumped instruction has been processed. The code page identifier $cp$ must be an integer within the range of $-0x80000000$ to $0x7fffffff$.
+\item {\tt (vmoplen)} (\dots $s$ $cp$ -- \dots $n$), determines the length of the VM instruction contained in the cell slice $s$ using the code page identifier $cp$. The length of the instruction, $n$, is an integer that is pushed onto the stack. The code page identifier $cp$ must be an integer within the range of $-0x80000000$ to $0x7fffffff$. If the code page is unknown, an $IntError$ is thrown with the message "unknown vm codepage".
+\item {\tt interpret\_store\_vm\_cont} (\dots -- \dots $cb$), serializes the virtual machine continuation $vmcont$ and stores it into the builder $cb$. If serialization fails, an $IntError$ is thrown with the message "cannot serialize vm continuation". The updated builder $cb$ is then pushed back onto the stack.
+\item {\tt interpret\_fetch\_vm\_cont} (\dots $cs$ -- \dots $vmcont$ $cs'$), deserializes the virtual machine continuation $vmcont$ from the cell slice $cs$. If deserialization fails, an $IntError$ is thrown with the message "cannot deserialize vm continuation". The remaining cell slice $cs'$ and the deserialized continuation $vmcont$ are then pushed back onto the stack.
 \end{itemize}
 For example, one can create an instance of TVM running some simple code as follows:
 \begin{verbatim}
@@ -2184,6 +2188,10 @@ \section*{Introduction}
 \item {\tt untriple} ($t$ -- $x$ $y$ $z$), unpacks a triple $t=(x,y,z)$, cf.~\ptref{p:tuples}. Equivalent to {\tt 3 untuple}.
 \item {\tt untuple} ($t$ $n$ -- $x_1$ \dots $x_n$), returns all components of a {\em Tuple\/}~$t=(x_1,\ldots,x_n)$, but only if its length is equal to~$n$, cf.~\ptref{p:tuples}. Otherwise throws an exception.
 \item {\tt variable} ( -- ), scans a blank-delimited word name $S$ from the remainder of the input, allocates an empty {\em Box}, and defines a new ordinary word $S$ as a constant, which will push the new {\em Box\/} when invoked, cf.~\ptref{p:variables}. Equivalent to {\tt hole constant}.
+\item {\tt (vmopdump)} (\dots $s$ $cp$ -- \dots $s'$ $dump$), dumps detailed information about the VM instruction contained in the cell slice $s$ using the code page identifier $cp$. The instruction's string representation $dump$ is left on the stack along with the remaining cell slice $s'$ after the dumped instruction has been processed. The code page identifier $cp$ must be an integer within the range of $-0x80000000$ to $0x7fffffff$.
+\item {\tt (vmoplen)} (\dots $s$ $cp$ -- \dots $n$), determines the length of the VM instruction contained in the cell slice $s$ using the code page identifier $cp$. The length of the instruction, $n$, is an integer that is pushed onto the stack. The code page identifier $cp$ must be an integer within the range of $-0x80000000$ to $0x7fffffff$. If the code page is unknown, an $IntError$ is thrown with the message "unknown vm codepage".
+\item {\tt interpret\_store\_vm\_cont} (\dots -- \dots $cb$), serializes the virtual machine continuation $vmcont$ and stores it into the builder $cb$. If serialization fails, an $IntError$ is thrown with the message "cannot serialize vm continuation". The updated builder $cb$ is then pushed back onto the stack.
+\item {\tt interpret\_fetch\_vm\_cont} (\dots $cs$ -- \dots $vmcont$ $cs'$), deserializes the virtual machine continuation $vmcont$ from the cell slice $cs$. If deserialization fails, an $IntError$ is thrown with the message "cannot deserialize vm continuation". The remaining cell slice $cs'$ and the deserialized continuation $vmcont$ are then pushed back onto the stack.
 \item {\tt while} ($e$ $e'$ -- ), a while loop, cf.~\ptref{p:loops}: executes {\em WordDef\/}~$e$, then removes and checks the top-of-stack integer. If it is zero, exits the loop. Otherwise executes {\em WordDef\/}~$e'$, then begins a new loop iteration by executing $e$ and checking the exit condition afterwards.
 \item {\tt word} ($x$ -- $s$), parses a word delimited by the character with the Unicode codepoint $x$ from the remainder of the current input line and pushes the result as a {\em String}, cf.~\ptref{p:string.ops}. For instance, {\tt bl word abracadabra type} will print the string ``{\tt abracadabra}''. If $x=0$, skips leading spaces, and then scans until the end of the current input line. If $x=32$, skips leading spaces before parsing the next word.
 \item {\tt words} ( -- ), prints the names of all words currently defined in the dictionary, cf.~\ptref{p:dict.lookup}.