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 tact-docs#300 (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" tact-docs#374
• Closes Wrong function signature for fromSlice tact-docs#368

Checklist

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

[jeshecdom]

Probably we need to clarify this in a more detailed example (tutorial-like), because the connection with the stack is very vague and confusing. I can do such detailed example in a separate page, and then I can add a link in here to such page. I can work on that example as a separate PR, since now I am working on writing docs. What do you think? Do you suggest I should use the same TVM instructions you were using in these examples or should I use another TVM instruction that produces at least 3 or more results to exemplify the use of structs?

[novusnota]

I think that makes sense. If that's a tutorial-like example (for the Cookbook, I presume), then I'd use some other instruction with 3+ results to exemplify the use of Structs, exactly :)

UPD: Well, since my original answer I discovered that unused values are discarded only when the primitive type is specified as the return type. And now the idea of a tutorial makes much less sense to me — it's better that we improve descriptions here and now. But I may be totally wrong

[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)

[anton-trunov]

in any case, each such point should be accompanied by a concrete example of an asm-function

[novusnota]

just adapt the corresponding calling convention description from tvm.pdf

Sure, the -> 0 1 is much better explained in terms of s0..s255 stack registers.

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

Nope, at the moment it's all handled by FunC, which it turn just passes it to Fift, which does all the work. Neither Tact nor FunC check anything until it's too late and user hits exit code 5, 7, or whatever else.

Also, there could be more things in the stack, only the topmost 5 are of interest if we know that after all the instructions we need 5 values.

This should be documented, of course, but an even more important question is "are returned structs actually represented as tensors (multiple TVM values)?"
and, of course, the symmetrical question for input function parameters (including passing structs)
in any case, each such point should be accompanied by a concrete example of an asm-function

👍

[anton-trunov]

@jeshecdom when we have the grammar and AST for our embedded assembly language then we will be able to typecheck asm-functions and warn the user their stack discipline makes sense

[jeshecdom]

just adapt the corresponding calling convention description from tvm.pdf

Sure, the -> 0 1 is much better explained in terms of s0..s255 stack registers.

We could do the following with specific examples (previously, we should have explained how function arguments are pushed into the stack):

• First, explain how the result tensor is popped from the stack. Suppose after popping, you get some tensor (r0, r1, ..., rn).
• Explain how the notation -> n m l is just a re-arrangement of the result tensor.
• Explain how the re-arranged tensor is mapped into the result type of the function (this includes explaining how the tensor is mapped into a struct or a primitive type, or whatever).

[novusnota]

Eh, Structs are represented as tensors (...), but that's the doing of Tact+FunC. If we were to target TVM directly, we would've dealt with stack entries ourselves, all without tensors.

So I'm a bit hesitant on explaining things in tensors, and instead let's just properly describe stack and stack registers.

[jeshecdom]

Eh, Structs are represented as tensors (...), but that's the doing of Tact+FunC. If we were to target TVM directly, we would've dealt with stack entries ourselves, all without tensors.

So I'm a bit hesitant on explaining things in tensors, and instead let's just properly describe stack and stack registers.

Sounds good.

[anton-trunov]

So I'm a bit hesitant on explaining things in tensors, and instead let's just properly describe stack and stack registers.

sounds good to me too, since tvm.pdf does not even mention tensors, looks like it's a term coined by the FunC community

[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