1 files changed, 140 insertions, 0 deletions
diff --git a/docs/design/part-memory.txt b/docs/design/part-memory.txt
new file mode 100644
index 0000000000..bcb61561c2
--- /dev/null
+++ b/docs/design/part-memory.txt
@@ -0,0 +1,140 @@
+GstMemory
+---------
+
+This document describes the design of the memory objects.
+
+GstMemory objects are usually added to GstBuffer objects and contain the
+multimedia data passed around in the pipeline.
+
+Requirements
+~~~~~~~~~~~~
+
+ - It must be possible to have different memory allocators
+ - It must be possible to efficiently share memory objects, copy, span
+   and trim.
+
+
+Allocators
+~~~~~~~~~~
+
+ GstMemory objects are created by allocators. Allocators are registered to the
+ memory system with a set of methods contained in a GstMemoryInfo structure.
+
+  struct _GstMemoryInfo {
+    GstMemoryAllocFunction    alloc;
+    GstMemoryGetSizesFunction get_sizes;
+    GstMemoryResizeFunction   resize;
+    GstMemoryMapFunction      map;
+    GstMemoryUnmapFunction    unmap;
+    GstMemoryFreeFunction     free;
+
+    GstMemoryCopyFunction     copy;
+    GstMemoryShareFunction    share;
+    GstMemoryIsSpanFunction   is_span;
+
+    gpointer user_data;
+  };
+
+ After an allocator is registerd, new GstMemory can be created with 
+
+   GstMemory * gst_memory_allocator_alloc (const GstMemoryAllocator * allocator,
+                                           gsize maxsize, gsize align);
+
+ The GstMemory object is a refcounted object that must be freed with
+ gst_memory_unref ().
+
+ It is also possible to create a new GstMemory object that wraps existing
+ memory with:
+  
+   GstMemory * gst_memory_new_wrapped  (GstMemoryFlags flags, gpointer data,
+                                        GFreeFunc free_func, gsize maxsize,
+                                        gsize offset, gsize size);
+
+Lifecycle
+~~~~~~~~~
+
+GstMemory objects are refcounted. When the GstMemory object is first created, it
+has a refcount of 1. 
+
+Each variable holding a reference to the GstMemory object is responsible for
+updating the refcount.
+
+The refcount determines the writability of the object. If the refcount > 1, it is
+by definition used by multipled objects and thus cannot be safely written to.
+
+When the refcount reaches 0, and thus no objects hold a reference anymore, we
+can free the memory. The GstMemoryFreeFunction of the allocator will be called
+to cleanup the memory.
+
+
+Memory layout
+~~~~~~~~~~~~~
+
+ GstMemory manages a memory region. The accesible part of the managed region is
+ defined by an offset relative to the start of the region and a size. This
+ means that the managed region can be larger than what is visible to the user of
+ GstMemory API.
+
+ Schematically, GstMemory has a pointer to a memory region of _maxsize_. The area
+ starting from _offset_ and _size_ is accessible.
+
+               memory
+    GstMemory  ->*----------------------------------------------------*
+                 ^----------------------------------------------------^ 
+                                   maxsize
+                      ^--------------------------------------^         
+                     offset            size
+
+ The current properties of the accessible memory can be retrieved with:
+
+   gsize       gst_memory_get_sizes  (GstMemory *mem, gsize *maxsize);
+
+ The offset and size can be changed with:
+
+   void        gst_memory_resize     (GstMemory *mem, gsize offset, gsize size);
+
+ The visible memory region can currently only be made smaller.
+
+ The memory object is always readable. The memory block is writable when:
+
+  - the refcount is exactly 1
+  - the memory object has no parent, or if it has a parent, the parent is
+    writable.
+  - the memory object is not marked as READONLY.
+
+
+Data Access
+~~~~~~~~~~~
+
+ Access to the memory region is always controlled with a map and unmap method
+ call. This allows the implementation to monitor the access patterns or set up
+ the required memory mappings when needed.
+
+ Mapping a memory region requires the caller to specify the access method: READ
+ and/or WRITE. For write access, the GstMemory object must be writable.
+
+ After the data has been accessed in the object, the unmap call must be
+ performed. The call will update the new memory size with the specified size.
+
+
+Copy
+~~~~
+
+ A GstMemory copy can be made with the gst_memory_copy() call. Normally,
+ allocators will implement a custom version of this function to make a copy of
+ the same kind of memory as the original one.
+
+ This is what the fallback version of the copy function will do, albeit slower
+ than what as custom implementation could do.
+
+ The copy operation is only required to copy the visible range of the memory
+ block.
+
+
+Share
+~~~~~
+
+ A memory region can be shared between GstMemory object with the
+ gst_memory_share() operation. 
+
+