feat(docs): asm functions

[novusnota]

Rewrote the method ID collisions section to remove all logical jumps and make it much more streamlined :)

Also adjusted the structure a little towards the upcoming PR revamping this page. I'll push the draft of it right after we deal with asm functions here.

P.S.: I actually call argument to return position mappings "arrangements" and not "shuffle" as in grammar.ohm, because the latter kinda implies randomness, while those are actually deterministic. Hence, "asm arrangments".

Issue

• Closes Docs: describe asm functions #1011.
• Closes Describe how to use TVM assembly from Tact #1142 (old issue in tact-docs)

Also, resolved two teeny tiny issues from tact-docs — virtually 3-5 lines of fixes for each, no need in a separate CHANGELOG entry:

• Closes "Mutable functions" -> "Mutating functions" #1131
• Closes Wrong function signature for fromSlice #1092

Checklist

• I have updated CHANGELOG.md
• I have run the linter, formatter and spellchecker
• I did not do unrelated and/or undiscussed refactorings

[jeshecdom]

I agree that this is confusing, and I think that the cause is that we are mixing two mental models: a stack (low-level) and tuples (high-level).

We should pick only one and stick with it the entire explanation. It seems that describing everything in terms of tuples is more intuitive, but then we should not mention the stack (or mention how tuples are pushed and popped from a stack in a separate subsection, and only in that section mention the stack).

So, for example, I would start the examples saying something about the TVM instructions, something like this:

"
Even though TVM instructions work with a stack, TVM instructions can be seen, intuitively, as maps from tuples to tuples. To see how TVM instructions map tuples to tuples in the TVM stack, see [link: here]. Thinking in terms of tuples makes the explanation of asm functions much clearer, but for those who want to see an explanation using the stack directly, see [link: here].
"

Then, explaining the meaning of a declaration like:

asm(len self -> 1 0) fun testFun(self: Slice, len: Int): Result { TVM_INSTRUCTION }

struct Result {
   res1: Int;
   res2: Bool;
}

amounts to saying simply:

"
testFun passes the argument tuple (len, self) to instruction TVM_INSTRUCTION. Suppose (r0, r1) is the tuple result of TVM_INSTRUCTION, then testFun reorders the result according to the map -> 1 0, i.e., the 1-th index element (r1) has now index 0, and the 0-th index element (r0) has now index 1, producing the tuple (r1, r0). Finally, testFun assigns the tuple (r1, r0) into the Result struct one field at a time, producing Result {res1: r1, res2: r0}.
"

[novusnota]

@jeshecdom interesting note. The cases with multiple instructions should be covered too. And tuples on TON are denoted with square brackets [], so it's better to use those. Also, it's best for readability to remove parentheses as much as possible, so things like "and the 0-th index element (r0)" will be "and the 0-th index element r0" — no need to add indirection and visual pauses with parens :)

@anton-trunov wdyt about #1061 (comment)?

[anton-trunov]

TVM instructions can be seen, intuitively, as maps from tuples to tuples.

this is incorrect in a very specific technical sense: a tuple is a TVM data structure that occupy precisely one TVM stack position but can contain multiple other TVM primitives, including tuples

the term you probably intended to use is tensor

[anton-trunov]

testFun passes the argument tuple (len, self)

I find it confusing

[anton-trunov]

@novusnota just adapt the corresponding calling convention description from tvm.pdf

[anton-trunov]

@novusnota you also need to check how structures that are returned from a function are actually encoded

[anton-trunov]

To fully finish this section, #910 needs to be resolved too

[jeshecdom]

TVM instructions can be seen, intuitively, as maps from tuples to tuples.

this is incorrect in a very specific technical sense: a tuple is a TVM data structure that occupy precisely one TVM stack position but can contain multiple other TVM primitives, including tuples

the term you probably intended to use is tensor

I meant mathematical tuple, but now I see that this would introduce much more confusion because of the technical terms in TVM. So, the explanation should stick with the stack and use the technical terms in TVM.

[jeshecdom]

@jeshecdom interesting note. The cases with multiple instructions should be covered too. And tuples on TON are denoted with square brackets [], so it's better to use those. Also, it's best for readability to remove parentheses as much as possible, so things like "and the 0-th index element (r0)" will be "and the 0-th index element r0" — no need to add indirection and visual pauses with parens :)

@anton-trunov wdyt about #1061 (comment)?

Yeah, we should stick with the stack explanation and use the technical terms in TVM, because I see everyone is confused now :). But the way, a question:

In a function like this:

asm fun testFun(a: Int, b: Int): Result { 
 INS_1
 INS_2 
 .....
 INS_n   // Let us suppose that after INS_n finishes, 
         // there are 5 results in the stack
}

Does Tact know that after executing those instructions, there will be exactly 5 results in the stack?
What happens if struct Result has more than 5 fields? Will Tact pop more than 5 elements from the stack until it fills the struct, having as consequence the popping of elements that are not part of the intended result?

[anton-trunov]

Does Tact know that after executing those instructions, there will be exactly 5 results in the stack?

not in the current implementation

Will Tact pop more than 5 elements from the stack until it fills the struct

nope (the consequence of the previous answer)

This should be documented, of course, but an even more important question is "are returned structs actually represented as tensors (multiple TVM values)?"

[anton-trunov]

and, of course, the symmetrical question for input function parameters (including passing structs)

[novusnota]

1. Added description of the current Tact-flavored assembly from WIP feat: new asm parser #1064
2. Described everything from the stack point of view, including its "registers"
3. Refined the overall top-to-bottom reading flow

[novusnota]

All done here, @anton-trunov @jeshecdom.

I'll move to finilizing #1064 and then to other things

[anton-trunov]

Partially reviewed

[anton-trunov]

LGTM, let's merge this PR and request more edits with separate doc issues. @jeshecdom if you find anything that's worth further clarification please open new issues with docs.tact-lang.org tag