Merge pull request #1195 from ethereum/memory-doc

Document memory layout

1 files changed, 17 insertions, 0 deletions

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
 *****************