mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-16 21:36:35 +00:00
80f4716a61
Count how many mappings are currently active and also with what access pattern. Update the design doc with restrictions on the access patterns for nested mappings. Check if nested mappings obey the access mode restrictions of the design doc. Add various unit tests to check the desired behaviour.
156 lines
5.1 KiB
Text
156 lines
5.1 KiB
Text
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_allocator_alloc (const GstAllocator * 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 *offset, gsize *maxsize);
|
|
|
|
The offset and size can be changed with:
|
|
|
|
void gst_memory_resize (GstMemory *mem, gssize offset, gsize size);
|
|
|
|
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.
|
|
|
|
It is allowed to map multiple times with different access modes. for each of
|
|
the map calls, an corresponding unmap call needs to be made. WRITE-only memory
|
|
cannot be mapped in READ mode and READ-only memory cannot be mapped in WRITE
|
|
mode.
|
|
|
|
The memory pointer returned from the map call is guaranteed to remain valid in
|
|
the requested mapping mode until the corresponding unmap call is performed on
|
|
the pointer.
|
|
|
|
When multiple map operations are nested and return the same pointer, the pointer
|
|
is valid until the last unmap call is done.
|
|
|
|
When the final reference on a memory object is dropped, all outstanding
|
|
mappings are automatically unmapped.
|
|
|
|
Resizing a GstMemory does not influence any current mappings an any way. Note
|
|
however that the unmap call can resize the buffer again.
|
|
|
|
|
|
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.
|
|
|
|
|