Merge pull request #1195 from ethereum/memory-doc

Document memory layout

2 files changed, 23 insertions, 4 deletions

diff --git a/docs/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst
index 922056ec..ad0a9650 100644
--- a/docs/introduction-to-smart-contracts.rst
+++ b/docs/introduction-to-smart-contracts.rst
@@ -348,10 +348,12 @@ storage. A contract can neither read nor write to any storage apart
 from its own.
 
 The second memory area is called **memory**, of which a contract obtains
-a freshly cleared instance for each message call. Memory can be
-addressed at byte level, but read and written to in 32 byte (256-bit)
-chunks. Memory is more costly the larger it grows (it scales
-quadratically).
+a freshly cleared instance for each message call. Memory is linear and can be
+addressed at byte level, but reads are limited to a width of 256 bits, while writes
+can be either 8 bits or 256 bits wide. Memory is expanded by a word (256-bit), when
+accessing (either reading or writing) a previously untouched memory word (ie. any offset
+within a word). At the time of expansion, the cost in gas must be paid. Memory is more
+costly the larger it grows (it scales quadratically).
 
 The EVM is not a register machine but a stack machine, so all
 computations are performed on an area called the **stack**. It has a maximum size of
diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst
index d32186ca..72e32617 100644
--- a/docs/miscellaneous.rst
+++ b/docs/miscellaneous.rst
@@ -56,6 +56,23 @@ So for the following contract snippet::
 
 The position of ``data[4][9].b`` is at ``keccak256(uint256(9) . keccak256(uint256(4) . uint256(1))) + 1``.
 
+****************
+Layout in Memory
+****************
+
+Solidity reserves three 256-bit slots:
+-  0 - 64: scratch space for hashing methods
+- 64 - 96: currently allocated memory size (aka. free memory pointer)
+
+Scratch space can be used between statements (ie. within inline assembly).
+
+Solidity always places new objects at the free memory pointer and memory is never freed (this might change in the future).
+
+.. warning::
+  There are some operations in Solidity that need a temporary memory area larger than 64 bytes and therefore will not fit into the scratch space. They will be placed where the free memory points to, but given their short lifecycle, the pointer is not updated. The memory may or may not be zeroed out. Because of this, one shouldn't expect the free memory to be zeroed out.
+
+.. index: memory layout
+
 *****************
 Esoteric Features
 *****************