From 909ab7dc88cec0518d81d650d449105c7d2e9194 Mon Sep 17 00:00:00 2001
From: Joonas Lahtinen <joonas.lahtinen@linux.intel.com>
Date: Fri, 30 Aug 2019 13:50:53 +0300
Subject: drm/i915: Document locking guidelines
Git-commit: ca69a3c68e2150ffb73ff1ff7d2b5390d76b3eb9
Patch-mainline: v5.8-rc1
References: jsc#SLE-12680, jsc#SLE-12880, jsc#SLE-12882, jsc#SLE-12883, jsc#SLE-13496, jsc#SLE-15322
To ensure cross-driver locking compatibility, document the expected
guidelines for implementing the GEM locking in i915. Note that this
is a description of how things should end up after being reworked,
and does not reflect the current state of things.
v2: Use rst note:: tag (Rodrigo)
Signed-off-by: Joonas Lahtinen <joonas.lahtinen@linux.intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Chris Wilson <chris@chris-wilson.co.uk>
Cc: Dave Airlie <airlied@redhat.com>
Cc: Matthew Auld <matthew.auld@intel.com>
Cc: Abdiel Janulgue <abdiel.janulgue@linux.intel.com>
Cc: CQ Tang <cq.tang@intel.com>
Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Acked-by: Dave Airlie <airlied@redhat.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190830105053.17491-1-joonas.lahtinen@linux.intel.com
Signed-off-by: Patrik Jakobsson <pjakobsson@suse.de>
---
Documentation/gpu/i915.rst | 46 ++++++++++++++++++++++++++++++++++++++
1 file changed, 46 insertions(+)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 429b08aac797..33cc6ddf8f64 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -329,6 +329,52 @@ for execution also include a list of all locations within buffers that
refer to GPU-addresses so that the kernel can edit the buffer correctly.
This process is dubbed relocation.
+Locking Guidelines
+------------------
+
+.. note::
+ This is a description of how the locking should be after
+ refactoring is done. Does not necessarily reflect what the locking
+ looks like while WIP.
+
+#. All locking rules and interface contracts with cross-driver interfaces
+ (dma-buf, dma_fence) need to be followed.
+
+#. No struct_mutex anywhere in the code
+
+#. dma_resv will be the outermost lock (when needed) and ww_acquire_ctx
+ is to be hoisted at highest level and passed down within i915_gem_ctx
+ in the call chain
+
+#. While holding lru/memory manager (buddy, drm_mm, whatever) locks
+ system memory allocations are not allowed
+
+ * Enforce this by priming lockdep (with fs_reclaim). If we
+ allocate memory while holding these looks we get a rehash
+ of the shrinker vs. struct_mutex saga, and that would be
+ real bad.
+
+#. Do not nest different lru/memory manager locks within each other.
+ Take them in turn to update memory allocations, relying on the object’s
+ dma_resv ww_mutex to serialize against other operations.
+
+#. The suggestion for lru/memory managers locks is that they are small
+ enough to be spinlocks.
+
+#. All features need to come with exhaustive kernel selftests and/or
+ IGT tests when appropriate
+
+#. All LMEM uAPI paths need to be fully restartable (_interruptible()
+ for all locks/waits/sleeps)
+
+ * Error handling validation through signal injection.
+ Still the best strategy we have for validating GEM uAPI
+ corner cases.
+ Must be excessively used in the IGT, and we need to check
+ that we really have full path coverage of all error cases.
+
+ * -EDEADLK handling with ww_mutex
+
GEM BO Management Implementation Details
----------------------------------------
--
2.28.0