From 9392f52163b6629160fdb840c3e69126651df6cc Mon Sep 17 00:00:00 2001
From: exegete <nikitf-97@mail.ru>
Date: Thu, 29 Oct 2020 15:26:21 +0300
Subject: SML language overview added.

---
 doc/sml_language.txt | 167 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 167 insertions(+)
 create mode 100644 doc/sml_language.txt

(limited to 'doc/sml_language.txt')

diff --git a/doc/sml_language.txt b/doc/sml_language.txt
new file mode 100644
index 0000000..e7d804e
--- /dev/null
+++ b/doc/sml_language.txt
@@ -0,0 +1,167 @@
+-= Overview
+
+This document describes language used by cryptrobber and encrypt programs.
+Further this language will be referenced as SML (Stack Machine Language).
+"Strans" binary stack translator and "Smack" macroprocessor are used for
+translating SML program into ELF executable file. This document DOES NOT
+describe low level realisation of SML programs. For more information about
+methods envolved into this process you can refer to the "Threaded code" and
+"Call stack" topics.
+
+SML is a standard stack language. Every word (SML function) is executed in
+postfix notation. Even SML numbers are treated as words. For example:
+
+    4 5 + sys_write
+
+"4", "5", "+", "sys_write" are SML words. First, executing "4" will push
+nubmer 4 into the stack. Executing "5" will push number 5 into stack.
+Executing "+" will pop two numbers from stack (4 and 5), summarize them
+and push the result into stack (9). Executing "sys_write" will pop number
+from the stack (9) and print it.
+
+Further text will describe all basic SML macros and words in details.
+" filename ", * macro *, / word / designations are used to distinguish
+between different entities.
+
+-= IA32 macros and words
+
+" macro.sts "
+
+* next *
+Finishes assembler word description.
+
+* defasm *
+Begins assembler word description.
+
+* defword *
+Begins standard SML word description.
+
+* defconst *
+Describes constant number SML word.
+
+* defarr *
+Describes number array SML word.
+
+* defvar *
+Describes number variable SML word.
+
+* as *
+Links the name with the top value from stack.
+
+* literal *
+Used for transparent translation of numbers. It is a part of
+"Smack" macroprocessor, so there is no need to call it expicitly.
+
+* set_entry *
+Defines ELF executable entry point.
+
+* if *, * fi *, * else *
+These macros are used to describe conditional block.
+
+* do *, * untilod *, * until *, * od *
+These macros are used to describe conditional loop block.
+
+" core.sts "
+
+/ docol /
+SML word interpreter. It is used by "defword" macro to include in every
+SML word header for it's execution.
+
+/ exit /
+Finishes SML word execution.
+
+/ lit /
+SML number interpreter. It is used by "literal" macro.
+
+" stack.sts "
+
+/ top /
+Pushes the address of top of stack.
+
+/ ref /
+Pops the number of chosen stack element and pushes the address
+of this element.
+
+/ get /
+Pops the number of chosen stack element and pushes its value.
+
+/ set /
+Pops the value and the number of chosen stack element and changes
+the value of this element.
+
+/ drop /
+Pops the top stack element.
+
+/ dup /
+Pushes the copy of the top stack element.
+
+/ over /
+Pushes the copy of stack element over the top stack element.
+
+/ swap /
+Swaps two top stack elements.
+
+" branch.sts "
+
+/ branch /
+Changes the execution flow to the chosen address.
+
+/ 0branch /
+Conditional branch. Changes the execution flow to the chosen address
+but only if the value of the top stack element is zero.
+
+" memory.sts "
+
+/ @ /
+Replaces the address on top of stack by its value in memory.
+
+/ ! /
+Pops the address and the value from stack. Assigns this value to memory
+referenced by the chosen address.
+
+" math.sts "
+
+/ + /
+Adds two numbers from stack and pushes the result.
+
+/ - /
+Subtracts two numbers from stack and pushes the result.
+
+/ mul /
+Multiplies two numbers from stack and pushes the result.
+
+/ div /
+Divides two numbers from stack and pushes the result.
+
+/ mod /
+Divides two numbers from stack and pushes the modulo.
+
+/ = /
+Compares two numbers from stack for equality and pushes the result.
+
+/ != /
+Compares two numbers from stack for inequality and pushes the result.
+
+/ < /
+Compares two numbers from stack. Pushes "1" if the first
+is less than the second.
+
+/ > /
+Compares two numbers from stack. Pushes "1" if the first
+is greater than the second.
+
+" bitwise.sts "
+
+/ xor /
+Pops two numbers, applies XOR operation to them and pushes the result.
+
+/ and /
+Pops two numbers, applies AND operation to them and pushes the result.
+
+/ shr /
+Pops the counter and the value. Shifts right the value with the counter and
+pushes the result.
+
+/ shl /
+Pops the counter and the value. Shifts left the value with the counter and
+pushes the result.
-- 
cgit v1.2.3