From 5783ebb93d12b50321ac8a75b128db514ae64b62 Mon Sep 17 00:00:00 2001
From: chriseth <chris@ethereum.org>
Date: Wed, 14 Nov 2018 17:33:02 +0100
Subject: Small changes to yul object specification.

---
 docs/yul.rst | 43 +++++++++++++++++++++++++++++++++++++------
 1 file changed, 37 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/yul.rst b/docs/yul.rst
index ea0a298b..2784078c 100644
--- a/docs/yul.rst
+++ b/docs/yul.rst
@@ -515,6 +515,16 @@ The following functions must be available:
 +---------------------------------------------+-----------------------------------------------------------------+
 | keccak256(p:u256, s:u256) -> v:u256         | keccak(mem[p...(p+s)))                                          |
 +---------------------------------------------+-----------------------------------------------------------------+
+| *Object access*                             |                                                                 |
++---------------------------------------------+-----------------------------------------------------------------+
+| datasize(name:string) -> size:u256          | size of the data object in bytes, name has to be string literal |
++---------------------------------------------+-----------------------------------------------------------------+
+| dataoffset(name:string) -> offset:u256      | offset of the data object inside the data area in bytes,        |
+|                                             | name has to be string literal                                   |
++---------------------------------------------+-----------------------------------------------------------------+
+| datacopy(dst:u256, src:u256, len:u256)      | copy len bytes from the data area starting at offset src bytes  |
+|                                             | to memory at position dst                                       |
++---------------------------------------------+-----------------------------------------------------------------+
 
 Backends
 --------
@@ -540,12 +550,19 @@ TBD
 Specification of Yul Object
 ===========================
 
+Yul objects are used to group named code and data sections.
+The functions ``datasize``, ``dataoffset`` and ``datacopy``
+can be used to access these sections from within code.
+Hex strings can be used to specify data in hex encoding,
+regular strings in native encoding. For code,
+``datacopy`` will access its assembled binary representation.
+
 Grammar::
 
     TopLevelObject = 'object' '{' Code? ( Object | Data )* '}'
     Object = 'object' StringLiteral '{' Code? ( Object | Data )* '}'
     Code = 'code' Block
-    Data = 'data' StringLiteral HexLiteral
+    Data = 'data' StringLiteral ( HexLiteral | StringLiteral )
     HexLiteral = 'hex' ('"' ([0-9a-fA-F]{2})* '"' | '\'' ([0-9a-fA-F]{2})* '\'')
     StringLiteral = '"' ([^"\r\n\\] | '\\' .)* '"'
 
@@ -558,14 +575,28 @@ An example Yul Object is shown below:
     // Code consists of a single object. A single "code" node is the code of the object.
     // Every (other) named object or data section is serialized and
     // made accessible to the special built-in functions datacopy / dataoffset / datasize
-    object {
+    // Access to nested objects can be performed by joining the names using ``.``.
+    // The current object and sub-objects and data items inside the current object
+    // are in scope without nested access.
+    object "Contract1" {
         code {
-            let size = datasize("runtime")
+            // first create "runtime.Contract2"
+            let size = datasize("runtime.Contract2")
             let offset = allocate(size)
             // This will turn into a memory->memory copy for eWASM and
             // a codecopy for EVM
-            datacopy(dataoffset("runtime"), offset, size)
-            // this is a constructor and the runtime code is returned
+            datacopy(offset, dataoffset("runtime.Contract2"), size)
+            // constructor parameter is a single number 0x1234
+            mstore(add(offset, size), 0x1234)
+            create(offset, add(size, 32))
+
+            // now return the runtime object (this is
+            // constructor code)
+            size := datasize("runtime")
+            offset := allocate(size)
+            // This will turn into a memory->memory copy for eWASM and
+            // a codecopy for EVM
+            datacopy(offset, dataoffset("runtime"), size)
             return(offset, size)
         }
 
@@ -579,7 +610,7 @@ An example Yul Object is shown below:
                 let offset = allocate(size)
                 // This will turn into a memory->memory copy for eWASM and
                 // a codecopy for EVM
-                datacopy(dataoffset("Contract2"), offset, size)
+                datacopy(offset, dataoffset("Contract2"), size)
                 // constructor parameter is a single number 0x1234
                 mstore(add(offset, size), 0x1234)
                 create(offset, add(size, 32))
-- 
cgit v1.2.3