From acf0a35f2cebb617e41520cbede56e8a1aef5021 Mon Sep 17 00:00:00 2001 From: Your Name Date: Wed, 30 Oct 2024 15:31:58 +0800 Subject: [PATCH 1/2] Documentation Request: Core VM Operation Instructions in fift --- doc/fiftbase.tex | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/fiftbase.tex b/doc/fiftbase.tex index c6131b2e2..ae6b904a8 100644 --- a/doc/fiftbase.tex +++ b/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}. From f7e94443c403781e81869be300534b460b308ee1 Mon Sep 17 00:00:00 2001 From: Your Name Date: Wed, 30 Oct 2024 16:45:11 +0800 Subject: [PATCH 2/2] TVM --- doc/fiftbase.tex | 8 -------- doc/tvm.tex | 2 +- 2 files changed, 1 insertion(+), 9 deletions(-) diff --git a/doc/fiftbase.tex b/doc/fiftbase.tex index ae6b904a8..c6131b2e2 100644 --- a/doc/fiftbase.tex +++ b/doc/fiftbase.tex @@ -1365,10 +1365,6 @@ \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} @@ -2188,10 +2184,6 @@ \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}. diff --git a/doc/tvm.tex b/doc/tvm.tex index f5067cc83..612495571 100644 --- a/doc/tvm.tex +++ b/doc/tvm.tex @@ -2162,7 +2162,7 @@ \section*{Introduction} \item {\tt F4A1} --- {\tt DICTUGETJMP} ($i$ $D$ $n$ -- ), similar to {\tt DICTIGETJMP}, but performs {\tt DICTUGET} instead of {\tt DICTIGET}. \item {\tt F4A2} --- {\tt DICTIGETEXEC} ($i$ $D$ $n$ -- ), similar to {\tt DICTIGETJMP}, but with {\tt EXECUTE} instead of {\tt JMPX}. \item {\tt F4A3} --- {\tt DICTUGETEXEC} ($i$ $D$ $n$ -- ), similar to {\tt DICTUGETJMP}, but with {\tt EXECUTE} instead of {\tt JMPX}. -\item {\tt F4A6\_$n$} --- {\tt DICTPUSHCONST $n$} ( -- $D$ $n$), pushes a non-empty constant dictionary $D$ (as a $\textit{Cell\/}^?$) along with its key length $0\leq n\leq 1023$, stored as a part of the instruction. The dictionary itself is created from the first of remaining references of the current continuation. In this way, the complete {\tt DICTPUSHCONST} instruction can be obtained by first serializing {\tt xF4A8\_}, then the non-empty dictionary itself (one {\tt 1} bit and a cell reference), and then the unsigned 10-bit integer $n$ (as if by a {\tt STU 10} instruction). An empty dictionary can be pushed by a {\tt NEWDICT} primitive (cf.~\ptref{sp:prim.dict.create}) instead. +\item {\tt F4A6\_$n$} --- {\tt DICTPUSHCONST $n$} ( -- $D$ $n$), pushes a non-empty constant dictionary $D$ (as a $\textit{Cell\/}^?$) along with its key length $0\leq n\leq 1023$, stored as a part of the instruction. The dictionary itself is created from the first of remaining references of the current continuation. In this way, the complete {\tt DICTPUSHCONST} instruction can be obtained by first serializing {\tt xF4A4\_}, then the non-empty dictionary itself (one {\tt 1} bit and a cell reference), and then the unsigned 10-bit integer $n$ (as if by a {\tt STU 10} instruction). An empty dictionary can be pushed by a {\tt NEWDICT} primitive (cf.~\ptref{sp:prim.dict.create}) instead. \item {\tt F4A8} --- {\tt PFXDICTGETQ} ($s$ $D$ $n$ -- $s'$ $x$ $s''$ $-1$ or $s$ $0$), looks up the unique prefix of {\em Slice} $s$ present in the prefix code dictionary (cf.~\ptref{sp:pfx.dict.tlb}) represented by $\textit{Cell\/}^?$ $D$ and $0\leq n\leq 1023$. If found, the prefix of $s$ is returned as $s'$, and the corresponding value (also a {\em Slice}) as $x$. The remainder of $s$ is returned as a {\em Slice\/} $s''$. If no prefix of $s$ is a key in prefix code dictionary $D$, returns the unchanged $s$ and a zero flag to indicate failure. \item {\tt F4A9} --- {\tt PFXDICTGET} ($s$ $D$ $n$ -- $s'$ $x$ $s''$), similar to {\tt PFXDICTGET}, but throws a cell deserialization failure exception on failure. \item {\tt F4AA} --- {\tt PFXDICTGETJMP} ($s$ $D$ $n$ -- $s'$ $s''$ or $s$), similar to {\tt PFXDICTGETQ}, but on success {\tt BLESS}es the value $x$ into a {\em Continuation\/} and transfers control to it as if by a {\tt JMPX}. On failure, returns $s$ unchanged and continues execution.