From 9ff0cc0b8bca1ce73ead8590c1de998c1dddff17 Mon Sep 17 00:00:00 2001 From: Daniel Kirchner Date: Mon, 13 Sep 2021 14:00:24 +0200 Subject: [PATCH] Update docs. --- docs/assembly.rst | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/docs/assembly.rst b/docs/assembly.rst index 7edffca81..232e77777 100644 --- a/docs/assembly.rst +++ b/docs/assembly.rst @@ -124,9 +124,22 @@ Access to External Variables, Functions and Libraries You can access Solidity variables and other identifiers by using their name. Local variables of value type are directly usable in inline assembly. +They can both be read and assigned to. -Local variables that refer to memory or calldata evaluate to the -address of the variable in memory, resp. calldata, not the value itself. +Local variables that refer to memory evaluate to the address of the variable in memory not the value itself. +Such variables can also be assigned to, but note that an assignment will only change the pointer and not the data +and that it is your responsibility to respect Solidity's memory management. +See :ref:`Conventions in Solidity `. + +Similarly, local variables that refer to statically-sized calldata arrays or calldata structs +evaluate to the address of the variable in calldata, not the value itself. +The variable can also be assigned a new offset, but note that no validation to ensure that +the variable will not point beyond ``calldatasize()`` is performed. + +For dynamic calldata arrays, you can access +their calldata offset (in bytes) and length (number of elements) using ``x.offset`` and ``x.length``. +Both expressions can also be assigned to, but as for the static case, no validation will be performed +to ensure that the resulting data area is within the bounds of ``calldatasize()``. For local storage variables or state variables, a single Yul identifier is not sufficient, since they do not necessarily occupy a single full storage slot. @@ -135,9 +148,10 @@ inside that slot. To retrieve the slot pointed to by the variable ``x``, you use ``x.slot``, and to retrieve the byte-offset you use ``x.offset``. Using ``x`` itself will result in an error. -For dynamic calldata arrays, you can access -their calldata offset (in bytes) and length (number of elements) using ``x.offset`` and ``x.length``. -Both expressions can also be assigned to. +You can also assign to the ``.slot`` part of a local storage variable pointer. +For these (structs, arrays or mappings), the ``.offset`` part is always zero. +It is not possible to assign to the ``.slot`` or ``.offset`` part of a state variable, +though. Local Solidity variables are available for assignments, for example: @@ -178,17 +192,6 @@ Since Solidity 0.7.0, variables and functions declared inside the inline assembly block may not contain ``.``, but using ``.`` is valid to access Solidity variables from outside the inline assembly block. -Assignments are possible to assembly-local variables and to function-local -variables. Take care that when you assign to variables that point to -memory or storage, you will only change the pointer and not the data. - -You can assign to the ``.slot`` part of a local storage variable pointer. -For these (structs, arrays or mappings), the ``.offset`` part is always zero. -It is not possible to assign to the ``.slot`` or ``.offset`` part of a state variable, -though. - - - Things to Avoid --------------- @@ -199,6 +202,8 @@ functional-style opcodes, counting stack height for variable access and removing stack slots for assembly-local variables when the end of their block is reached. +.. _conventions-in-solidity: + Conventions in Solidity -----------------------