diff options
| -rw-r--r-- | docs/assembly.rst | 125 |
1 files changed, 114 insertions, 11 deletions
diff --git a/docs/assembly.rst b/docs/assembly.rst index f5abcdc8..ce45c55c 100644 --- a/docs/assembly.rst +++ b/docs/assembly.rst @@ -1,18 +1,116 @@ -################# -Solidity Assembly -################# +################################################# +Joyfully Universal Language for (Inline) Assembly +################################################# + +.. _julia: .. index:: ! assembly, ! asm, ! evmasm -Solidity defines an assembly language that can also be used without Solidity. -This assembly language can also be used as "inline assembly" inside Solidity -source code. We start with describing how to use inline assembly and how it -differs from standalone assembly and then specify assembly itself. +Julia is an intermediate language that can compile to various different backends +(EVM 1.0, EVM 1.5 and eWASM are planned). +Because of that, it is designed to be as featureless as possible. +It can already be used for "inline assembly" inside Solidity and +future versions of the Solidity compiler will even use Julia as intermediate +language. It should also be easy to build high-level optimizer stages for Julia. -.. note:: - TODO: Write about how scoping rules of inline assembly are a bit different - and the complications that arise when for example using internal functions - of libraries. Furthermore, write about the symbols defined by the compiler. +The core components of Julia are functions, blocks, variables, literals, +for-loops, switch-statements, expressions and assignments to variables. + +Julia in itself does not even provide operators. If the EVM is targeted, +opcodes will be available as built-in functions, but they can be reimplemented +if the backend changes. + +The following example program assumes that the EVM opcodes ``mul``, ``div`` +and ``mod`` are available either natively or as functions and computes exponentiation. + +.. code:: + { + function power(base, exponent) -> (result) + { + switch exponent + 0: { result := 1 } + 1: { result := base } + default: + { + result := power(mul(base, base), div(exponent, 2)) + switch mod(exponent, 2) + 1: { result := mul(base, result) } + } + } + } + +It is also possible to implement the same function using a for-loop +instead of recursion. Here, we need the EVM opcodes ``lt`` (less-than) +and ``add`` to be available. + +.. code:: + { + function power(base, exponent) -> (result) + { + result := 1 + for { let i := 0 } lt(i, exponent) { i := add(i, 1) } + { + result := mul(result, base) + } + } + } + +Specification of Julia +====================== + +Grammar:: + + Block = '{' Statement* '}' + Statement = + Block | + FunctionDefinition | + VariableDeclaration | + Assignment | + Expression | + Switch | + ForLoop | + 'break' | 'continue' + SubAssembly + FunctionDefinition = + 'function' Identifier '(' IdentifierList? ')' + ( '->' '(' IdentifierList ')' )? Block + VariableDeclaration = + 'let' IdentifierOrList ':=' Expression + Assignment = + IdentifierOrList ':=' Expression + Expression = + Identifier | Literal | FunctionCall + Switch = + 'switch' Expression Case* ( 'default' ':' Block )? + Case = + 'case' Expression ':' Block + ForLoop = + 'for' Block Expression Block Block + SubAssembly = + 'assembly' Identifier Block + FunctionCall = + Identifier '(' ( AssemblyItem ( ',' AssemblyItem )* )? ')' + IdentifierOrList = Identifier | '(' IdentifierList ')' + Identifier = [a-zA-Z_$] [a-zA-Z_0-9]* + IdentifierList = Identifier ( ',' Identifier)* + Literal = + NumberLiteral | StringLiteral | HexLiteral + NumberLiteral = HexNumber | DecimalNumber + HexLiteral = 'hex' ('"' ([0-9a-fA-F]{2})* '"' | '\'' ([0-9a-fA-F]{2})* '\'') + StringLiteral = '"' ([^"\r\n\\] | '\\' .)* '"' + HexNumber = '0x' [0-9a-fA-F]+ + DecimalNumber = [0-9]+ + + + + | 'dataSize' '(' Identifier ')' | + LinkerSymbol | + 'bytecodeSize' | + +Restriction for Expression: Functions can only return single item, +top level has to return nothing. +Restriction for VariableDeclaration and Assignment: Number of elements left and right needs to be the same +continue and break only in for loop .. _inline-assembly: @@ -41,6 +139,11 @@ We now want to describe the inline assembly language in detail. at a low level. This discards several important safety features of Solidity. +.. note:: + TODO: Write about how scoping rules of inline assembly are a bit different + and the complications that arise when for example using internal functions + of libraries. Furthermore, write about the symbols defined by the compiler. + Example ------- |