feat: tolk asm-functions #1510
feat: tolk asm-functions #1510
Conversation
This comment has been minimized.
This comment has been minimized.
aigerimu
force-pushed
the
tolk-branch1
branch
from
c2e9f7a to
af6faf8
Compare
This comment has been minimized.
This comment has been minimized.
|
Thank you for the improvements in |
This comment has been minimized.
This comment has been minimized.
This comment was marked as outdated.
This comment was marked as outdated.
|
/review |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| Functions in Tolk may be defined using assembler code. | ||
| It's a low-level feature that requires deep understanding of stack layout, [Fift](/languages/fift/overview), and [TVM](/tvm/overview). | ||
|
|
||
| ## Standard functions are actually `asm` wrappers |
There was a problem hiding this comment.
[HIGH] Banned intensifier “actually” in heading
The H2 heading “Standard functions are actually asm wrappers” uses the intensifier “actually”, which the style guide lists as a banned hedge/intensifier. This weakens the neutral, factual tone required for technical documentation. The “Hedges and intensifiers” rule marks these terms as HIGH severity because they add emotional emphasis instead of information.
| ## Standard functions are actually `asm` wrappers | |
| ## Standard functions are `asm` wrappers |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| fun hashStateInit(code: cell, data: cell): uint256 asm """ | ||
| DUP2 | ||
| HASHCU | ||
| ... | ||
| ONE HASHEXT_SHA256 | ||
| """ | ||
| ``` | ||
|
|
||
| It is treated as a single string and inserted as-is into Fift output. | ||
| In particular, it may contain `//` comments inside (valid comments for Fift). | ||
|
|
||
| ## Stack order for multiple slots | ||
|
|
||
| When calling a function, arguments are pushed in a declared order. | ||
| The last parameter becomes the topmost stack element. | ||
|
|
||
| If an instruction results in several slots, the resulting type should be a tensor or a struct. | ||
|
|
||
| For example, write a function `abs2` that calculates `abs()` for two values at once: `abs2(-5, -10)` = `(5, 10)`. | ||
| Stack layout (the right is the top) is written in comments. | ||
|
|
||
| ```tolk | ||
| fun abs2(v1: int, v2: int): (int, int) | ||
| asm // v1 v2 | ||
| "ABS" // v1 v2_abs | ||
| "SWAP" // v2_abs v1 | ||
| "ABS" // v2_abs v1_abs | ||
| "SWAP" // v1_abs v2_abs |
There was a problem hiding this comment.
[HIGH] Ellipsis token and trailing inline comments in code examples
In the hashStateInit example, the line containing a bare ... inside the asm """ block is not valid assembler code and violates the rule against ellipses that change syntax, making the example non–copy‑pasteable. In the abs2 example, the stack layout descriptions are written as trailing // comments on the same lines as code, which the style guide forbids for code samples. Both issues are classified as HIGH severity because they reduce clarity and can cause confusion or errors when readers reuse the examples.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| For better understanding, let's look at regular functions first. | ||
| The compiler does all transformations automatically: | ||
|
|
||
| ```tolk | ||
| // transformed to: "returns (int, void)" | ||
| fun increment(mutate x: int): void { | ||
| x += 1; | ||
| // a hidden "return x" is inserted | ||
| } | ||
| fun demo() { | ||
| // transformed to: (newX, _) = increment(x); x = newX | ||
| increment(mutate x); | ||
| } | ||
| ``` | ||
|
|
||
| How to implement `increment()` via asm? | ||
|
|
||
| ```tolk | ||
| fun increment(mutate x: int): void | ||
| asm "INC" | ||
| ``` | ||
|
|
||
| The function still returns `void` (from the type system's perspective it does not return a value), | ||
| but `INC` leaves a number on the stack — that's a hidden "return x" from a manual variant. | ||
|
|
||
| Similarly, it works for `mutate self`. | ||
| An `asm` function should place `newSelf` onto the stack before the actual result: | ||
|
|
||
| ```tolk | ||
| // "TPUSH" pops (tuple) and pushes (newTuple); | ||
| // so, newSelf = newTuple, and return `void` (syn. "unit") | ||
| fun tuple.push<X>(mutate self, value: X): void | ||
| asm "TPUSH" | ||
| // "LDU" pops (slice) and pushes (int, newSlice); | ||
| // with `asm(-> 1 0)`, we make it (newSlice, int); | ||
| // so, newSelf = newSlice, and return `int` | ||
| fun slice.loadMessageFlags(mutate self): int | ||
| asm(-> 1 0) "4 LDU" | ||
| ``` | ||
|
|
||
| To return `self` for chaining, just specify a return type: | ||
|
|
||
| ```tolk | ||
| // "STU" pops (int, builder) and pushes (newBuilder); | ||
| // with `asm(op self)`, we put arguments to correct order; |
There was a problem hiding this comment.
[HIGH] First-person pronouns in prose and comments
The explanatory prose uses “let's” (“For better understanding, let's look at regular functions first.”) and code comments use “we” (“we make it (newSlice, int)”, “we put arguments to correct order”) to refer to authors and the reader. The style guide’s “Don't get personal” rule explicitly forbids first‑person plural pronouns for authors and inclusive phrasing that addresses the reader, marking such cases as HIGH severity. This wording shifts the tone from objective reference documentation to conversational narration, which the project aims to avoid.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
towards #1128