gistfile1.txt

diff --git a/docs/dev/format.rst b/docs/dev/format.rst
index 0c46984..25d663f 100644
--- a/docs/dev/format.rst
+++ b/docs/dev/format.rst
@@ -49,3 +49,72 @@ Unbuffered
 +------------+------------+------------+------------+-------------------+---------+
 
 The value field length = sizeof(type).
+
+Version 2 proposal
+==================
+
+Structure of version 1 mmstat's mmaps:
+
++-------------------+-----------+
+| version number    | fields... |
++===================+===========+
+| ``byte`` = ``02`` | ...       |
++-------------------+-----------+
+
+
+Fields
+------
+
+There are two types of field structures so far in mmstats:
+
+#. buffered
+#. unbuffered
+#. buffered array
+
+Buffered fields use multiple buffers for handling values which cannot be
+written atomically.
+
+Unbuffered structures have ``ff`` in the write buffer field.
+
+Unbuffered
+^^^^^^^^^^
+
++--------------------+------------+------------+------------+------------+-------------------+---------+
+| field type         | label size | label      | type size  | type       | write buffer      | value   |
++====================+============+============+============+============+===================+=========+
+| ``ushort`` = ``0`` | ``ushort`` | ``char[]`` | ``ushort`` | ``char[]`` | ``byte`` = ``ff`` | varies  |
++--------------------+------------+------------+------------+------------+-------------------+---------+
+
+The value field length = sizeof(type).
+
+Buffered
+^^^^^^^^
+
++--------------------+------------+------------+------------+------------+--------------+----------+----------+
+| field type         | label size | label      | type size  | type       | write buffer | buffer 1 | buffer 2 |
++====================+============+============+============+============+==============+==========+==========+
+| ``ushort`` = ``1`` | ``ushort`` | ``char[]`` | ``ushort`` | ``char[]`` | ``byte``     | varies   | varies   |
++--------------------+------------+------------+------------+------------+--------------+----------+----------+
+
+The buffers field length = sizeof(type) * buffers.
+
+The current write buffer is referenced by: write_buffer * sizeof(type)
+
+TODO: field for total number of buffers?
+
+Array
+~~~~~
+
++--------------------+------------+------------+------------+------------+---------------------+------------+--------+
+| field type         | label size | label      | type size  | type       | write buffer offset | array size | buffer |
++====================+============+============+============+============+=====================+============+========+
+| ``ushort`` = ``2`` | ``ushort`` | ``char[]`` | ``ushort`` | ``char[]`` | ``ushort``          | ``ushort`` | varies |
++--------------------+------------+------------+------------+------------+---------------------+------------+--------+
+
+An array is made up of ``array size`` + 1 individual buffers.
+
+The buffers field length = sizeof(type) * (array size + 1) * buffers.
+
+The current write buffer is referenced by: write_buffer * sizeof(type). Readers should ignore that subfield when reading values. The reader should present "beginning" of the array as the first subfield after the write buffer subfield, 
+
+TODO: field for total number of buffers?

Are buffer 1 and buffer 1 still relevant for the buffered field?

Perhaps the trick is we now have 3 distinct field formats and we can use the type indicator to let readers know which to expect:

• Lists (always buffered? the format you specify above but only has a single contiguous array field to hold all of the values instead of 2 buffer fields.
• Buffered scalars (like v1)
• Unbuffered scalars (like v1)

List field format:

• label size (ushort)
• label (char[])
• type size (ushort)
• type (char[])
• write buffer offset (ushort)
• array size (ushort)
• array (...)