summaryrefslogtreecommitdiffstats
path: root/src/gallium/drivers/nouveau/nouveau_heap.h
diff options
context:
space:
mode:
authorIlia Mirkin <[email protected]>2015-05-12 18:58:17 -0400
committerIlia Mirkin <[email protected]>2015-05-12 18:58:49 -0400
commitc696a318ef1eb58f65fb867d5616bbefd1def31e (patch)
tree7b34d2c6b700af7361f9eb08f262fc07c3e2d9de /src/gallium/drivers/nouveau/nouveau_heap.h
parentd06ce2f1df54edd234b1abde37bba524ed599acb (diff)
nouveau: document nouveau_heap
Signed-off-by: Ilia Mirkin <[email protected]>
Diffstat (limited to 'src/gallium/drivers/nouveau/nouveau_heap.h')
-rw-r--r--src/gallium/drivers/nouveau/nouveau_heap.h20
1 files changed, 20 insertions, 0 deletions
diff --git a/src/gallium/drivers/nouveau/nouveau_heap.h b/src/gallium/drivers/nouveau/nouveau_heap.h
index d0b22844ad0..a3d64a65623 100644
--- a/src/gallium/drivers/nouveau/nouveau_heap.h
+++ b/src/gallium/drivers/nouveau/nouveau_heap.h
@@ -23,6 +23,26 @@
#ifndef __NOUVEAU_HEAP_H__
#define __NOUVEAU_HEAP_H__
+/* This datastructure represents a memory allocation heap. Fundamentally, this
+ * is a doubly-linked list with a few properties, and a usage convention.
+ *
+ * On initial allocation, there is a single node with the full size that's
+ * marked as not in-use. As allocations are made, blocks are taken off the end
+ * of that first node, and inserted right after it. If the first node doesn't
+ * have enough free space, we look for free space down in the rest of the
+ * list. This can happen if an allocation is made and then freed.
+ *
+ * The first node will remain with in_use == 0 even if the whole heap is
+ * exhausted. Another invariant is that there will never be two sequential
+ * in_use == 0 nodes. If a node is freed and it has one (or both) adjacent
+ * free nodes, they are merged into one, and the relevant heap entries are
+ * freed.
+ *
+ * The pattern to free the whole heap is to start with the first node and then
+ * just free the "next" node, until there is no next node. This should assure
+ * that at the end the first (and only) node is not in use and contains the
+ * full size of the heap.
+ */
struct nouveau_heap {
struct nouveau_heap *prev;
struct nouveau_heap *next;